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 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 dos 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 sua biblioteca. Também é possível embed os símbolos no dll ou exe com a seguinte propriedade do projeto: <DebugType>embedded</DebugType>

Pré-requisitos

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

Criar um pacote de símbolos

Se você estiver usando a CLI do dotnet ou o MSBuild, precisará definir as propriedades IncludeSymbols 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 estas propriedades na linha de comando:

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

    or

    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ímbolos herdados será criado.

Observação

O formato herdado .symbols.nupkg ainda é aceito, mas apenas por razões 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

No momento, os Azure Devops Artifacts não oferecem suporte à depuração via arquivos .snupkg.

  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.

Restrições de pacotes de símbolos do NuGet.org

O 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 são compatíveis com o servidor de símbolos em NuGet.org.
  • Os PDBs e DLLs do nupkg associadas precisam ser compilados com o compilador no Visual Studio versão 15.9 ou superior (consulte Hash de criptografia de 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 em C++, produzem PDBs do Windows em vez de PDBs portáteis. Eles não são aceitos pelo servidor de símbolos do NuGet.org. Em vez disso, use Pacotes de símbolos herdados.

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

Os pacotes de símbolos publicados em NuGet.org passam por várias validações, incluindo 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 e-mail com instruções sobre como corrigir os problemas identificados.

Quando o pacote de símbolos passar em 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 estiver demorando mais do que o esperado, visite status.nuget.org para verificar se o NuGet.org está passando por alguma interrupção. 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 o mesmo ID e versão que seu pacote NuGet correspondente (.nupkg).

  2. O .snupkg tem a mesma a estrutura de pasta que o nupkg correspondente para todos os arquivos DLL ou EXE, com a diferença 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 tipo de pacote SymbolsPackage:

    <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, licenseUrl e icon.

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

Confira também

Considere o uso do Link de Origem para habilitar a depuração do código-fonte de assemblies .NET. Para obter mais informações, consulte as Diretrizes de links de origem.

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