Criando pacotes de símbolos (.snupkg)

  • Artigo

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

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

Pré-requisitos

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

Criar um pacote de símbolos

Se você estiver usando a CLI dotnet ou o MSBuild, precisará definir as IncludeSymbols propriedades e SymbolPackageFormat para criar um arquivo .snupkg além do arquivo .nupkg.

  • Adicione as seguintes propriedades ao arquivo .csproj:

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

  • Ou especifique essas propriedades na linha de comando:

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

    ou

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

Se estiver usando o NuGet.exe, use os seguintes comandos para criar um arquivo .snupkg além do arquivo .nupkg:

nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg

nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg

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

Observação

O formato .symbols.nupkg herdado ainda tem suporte, mas apenas por motivos de compatibilidade, como pacotes nativos (consulte Pacotes de Símbolos Herdados). O servidor de símbolos da NuGet.org aceita apenas o novo formato de pacote de símbolos – .snupkg.

Publicando um pacote de símbolos

Observação

Atualmente, o Azure Devops Artifacts não dá suporte à depuração por meio .snupkg de arquivos.

  1. Para sua conveniência, primeiro salve sua chave de API com o NuGet (veja Publicar um pacote).

    nuget SetApiKey Your-API-Key

  2. Depois de publicar o pacote principal para o nuget.org, envie por push o pacote de símbolos da seguinte maneira.

    nuget push MyPackage.snupkg

  3. Você também pode efetuar push nos pacotes primário e de símbolos simultaneamente usando o comando abaixo. Ambos os arquivos .nupkg e .snupkg precisam estar presentes na pasta atual.

    nuget push MyPackage.nupkg

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

Observação

Se o pacote de símbolos não for publicado, verifique se você configurou a fonte de NuGet.org como https://api.nuget.org/v3/index.json. A publicação de pacote de símbolos tem compatibilidade apenas na API do NuGet V3.

Servidor de símbolos de NuGet.org

O NuGet.org dá suporte a seu próprio repositório de servidor de símbolos e aceita apenas o novo formato de pacote de símbolos – .snupkg. Os consumidores de pacote podem usar os símbolos publicados no servidor de símbolos nuget.org adicionando https://symbols.nuget.org/download/symbols às suas origens de símbolos no Visual Studio, o que permite intervir no código do pacote no depurador do Visual Studio. Consulte Especificar símbolos (.pdb) e arquivos de origem no depurador do Visual Studio para obter mais detalhes sobre esse processo.

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

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

  • Somente as seguintes extensões de arquivo são permitidas em pacotes de símbolos: .pdb, .nuspec, .xml, .psmdcp, , , .rels.p7s
  • Somente PDBs portáteis gerenciados têm suporte no servidor de símbolos do NuGet.org.
  • Os PDBs e suas DLLs .nupkg associadas precisam ser criados com o compilador no Visual Studio versão 15.9 ou superior (consulte Hash de criptografia PDB)

Os pacotes de símbolos publicados no NuGet.org falharão na validação se essas restrições não forem atendidas.

Observação

Projetos nativos, como projetos C++, produzem PDBs do Windows em vez de PDBs portáteis. Eles não são compatíveis com o servidor de símbolos do NuGet.org. Em vez disso , use pacotes de símbolo herdados .

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

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

Quando o pacote de símbolos tiver passado 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 do pacote geralmente leva 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á enfrentando interrupções. Se todos os sistemas estiverem operacionais e o pacote não tiver sido publicado com êxito dentro de uma hora, faça logon no nuget.org e entre em contato conosco usando o link Entre em contato com o suporte na página de detalhes do pacote.

Estrutura do pacote de símbolos

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

  1. O .snupkg tem a mesma ID e versão que seu pacote NuGet correspondente (.nupkg).

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

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

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

  4. Se um autor decide usar um nuspec personalizado para compilar seus nupkg e snupkg, o snupkg deve ter a mesma hierarquia de pastas e arquivos detalhados em 2).

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

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

Confira também

Considere usar Source Link para habilitar a depuração de código-fonte de assemblies .NET. Para obter mais informações, consulte as diretrizes de Source Link.

Para obter mais informações sobre pacotes de símbolos, consulte a especificação de design Depuração de Símbolos de Depuração & do Pacote NuGet .