Criação de pacotes de símbolos (.snupkg)

Uma boa experiência de depuração depende da presença de símbolos de depuração, pois fornecem informações críticas como a associação entre o código compilado e o código-fonte, nomes de variáveis locais, trilhos de pilha e mais. Pode usar pacotes de símbolos (.snupkg) para distribuir estes símbolos e melhorar a experiência de depuração dos seus pacotes NuGet.

Note que o pacote de símbolos não é a única estratégia para tornar os símbolos de depuração disponíveis para os consumidores da sua biblioteca. Também é possível para embed eles no dll ou exe com a seguinte propriedade do projeto: <DebugType>embedded</DebugType>

Pré-requisitos

nuget.exe v4.9.0 ou superior ou dotnet CLI v2.2.0 ou superior, que implementam os protocolos NuGet necessários.

Criação de um pacote de símbolos

Se estiveres a usar dotnet CLI ou MSBuild, precisas de definir as IncludeSymbols propriedades e SymbolPackageFormat para criar um ficheiro .snupkg além do ficheiro .nupkg.

• Ou adicione as seguintes propriedades ao seu ficheiro .csproj:

  <PropertyGroup>
      <IncludeSymbols>true</IncludeSymbols>
      <SymbolPackageFormat>snupkg</SymbolPackageFormat>
  </PropertyGroup>
  

• Ou especificar estas propriedades na linha de comandos:

  dotnet pack MyPackage.csproj -p:IncludeSymbols=true -p:SymbolPackageFormat=snupkg
  

  ou

  msbuild MyPackage.csproj /t:pack /p:IncludeSymbols=true /p:SymbolPackageFormat=snupkg
  

Se estiveres a usar NuGet.exe, podes usar os seguintes comandos para criar um ficheiro .snupkg além do ficheiro .nupkg:

nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg

nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg

A SymbolPackageFormat propriedade pode ter um de dois valores: symbols.nupkg (o padrão) ou snupkg. Se esta propriedade não for especificada, será criado um pacote de símbolos legado.

Publicar um pacote de símbolos

1. Para conveniência, guarde primeiro a sua chave API com o NuGet ( veja publicar um pacote).

   nuget SetApiKey Your-API-Key
   

   Sugestão

   A partir do NuGet 7.6, podes definir as NUGET_API_KEY variáveis de ambiente e NUGET_SYMBOL_API_KEY em vez de usar SetApiKey. Para mais informações, veja variáveis de ambiente.

2. Depois de publicar o seu pacote principal no nuget.org, envie o pacote de símbolos da seguinte forma.

   nuget push MyPackage.snupkg
   

3. Também podes empurrar tanto os pacotes primários como os de símbolos ao mesmo tempo usando o comando abaixo. Tanto os ficheiros .nupkg como .snupkg têm de estar presentes na pasta atual.

   nuget push MyPackage.nupkg
   

O NuGet publicará ambos os pacotes para nuget.org. MyPackage.nupkg será publicado primeiro, seguido de MyPackage.snupkg.

NuGet.org servidor de símbolos

NuGet.org suporta o seu próprio repositório de servidores de símbolos e só aceita o novo formato de pacote de símbolos - .snupkg. Os consumidores de pacotes podem usar os símbolos publicados para nuget.org servidor de símbolos adicionando https://symbols.nuget.org/download/symbols às suas fontes de símbolos em Visual Studio, o que permite introduzir o código do pacote no depurador Visual Studio. Consulte Specify symbol (.pdb) e ficheiros de origem no depurador de Visual Studio para detalhes sobre esse processo.

NuGet.org restrições do pacote de símbolos

NuGet.org tem as seguintes restrições para pacotes de símbolos:

• Apenas as seguintes extensões de ficheiro são permitidas nos pacotes de símbolos: .pdb, .nuspec, , .psmdcp.rels.xml.p7s
• Apenas os PDBs Portáteis Geridos são suportados no servidor de símbolos do NuGet.org.
• Os PDBs e as suas DLLs .nupkg associadas precisam de ser construídos com o compilador na versão 15.9 ou superior Visual Studio (ver PDB cripto-hash)

Pacotes de símbolos publicados para NuGet.org falharão na validação se estas restrições não forem cumpridas.

Validação e indexação de pacotes de símbolos

Os pacotes de símbolos publicados para NuGet.org passam por várias validações, incluindo análise de malware. Se um pacote falhar numa verificação de validação, a sua página de detalhes do pacote mostrará uma mensagem de erro. Além disso, os proprietários do pacote receberão um email com instruções sobre como resolver os problemas identificados.

Quando o pacote de símbolos passar todas as validações, os símbolos serão indexados pelos servidores de símbolos do NuGet.org e estarão disponíveis para consumo.

A validação e indexação de pacotes normalmente demora menos de 15 minutos. Se a publicação do pacote demorar mais do que o esperado, visite status.nuget.org para verificar se NuGet.org está a sofrer alguma interrupção. Se todos os sistemas estiverem operacionais e o pacote não tiver sido publicado com sucesso dentro de uma hora, por favor inicie sessão no nuget.org e contacte-nos através do link de Suporte de Contacto na página de detalhes do pacote.

Estrutura do pacote de símbolos

O pacote de símbolos (.snupkg) apresenta as seguintes características:

1. O .snupkg tem o mesmo id e versão do seu correspondente pacote NuGet (.nupkg).

2. O .snupkg tem a mesma estrutura de pastas que o .nupkg correspondente para quaisquer ficheiros DLL ou EXE, com a distinção de que, em vez de DLLs/EXEs, os seus PDBs correspondentes serão incluídos na mesma hierarquia de pastas. Ficheiros e pastas com extensões diferentes do PDB serão deixados de fora do snupkg.

3. O ficheiro .nuspec do pacote de símbolos tem o tipo de SymbolsPackage pacote:

   <packageTypes>
      <packageType name="SymbolsPackage"/>
   </packageTypes>
   

4. Se um autor decidir usar um nuspec personalizado para construir o seu nupkg e snupkg, o snupkg deve ter a mesma hierarquia de pastas e ficheiros detalhados em 2).

5. Os seguintes campos serão excluídos do nuspec do snupkg: authors, owners, requireLicenseAcceptance, license type, licenseUrl, e icon.

6. Não uses o <license> elemento. Um .snupkg está coberto pela mesma licença que o correspondente .nupkg.

Ver também

Considere usar o Source Link para permitir a depuração do código-fonte de assemblies .NET. Para mais informações, consulte a orientação do Link de Fonte.

Para mais informações sobre pacotes de símbolos, consulte a especificação de design NuGet Package Debugging & Symbols Improvements .