Criando pacotes de símbolos (.snupkg)

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 de sua biblioteca. Também é possível para embed eles na 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.

Criando um pacote de símbolos

Se você estiver usando a CLI do dotnet ou o MSBuild, será necessário definir as propriedades e SymbolPackageFormat as IncludeSymbols propriedades 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

    ou

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

Se você estiver usando NuGet.exe, poderá usar 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 SymbolPackageFormat propriedade pode ter um dos dois valores: symbols.nupkg (o padrão) ou snupkg. Se essa propriedade não for especificada, um pacote de símbolo herdado será criado.

Note

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 do NuGet.org aceita apenas o novo formato de pacote de símbolos – .snupkg.

Publicando um pacote de símbolos

Note

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

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

    nuget SetApiKey Your-API-Key

    Dica

    A partir do NuGet 7.6, você pode definir as NUGET_API_KEY variáveis de ambiente e NUGET_SYMBOL_API_KEY em vez de usar SetApiKey. Para obter mais informações, consulte variáveis de ambiente.

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

    nuget push MyPackage.snupkg

  3. Você também pode enviar por push pacotes primários e de símbolos ao mesmo tempo usando o comando abaixo. Os arquivos .nupkg e .snupkg precisam estar presentes na pasta atual.

    nuget push MyPackage.nupkg

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

Note

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

servidor de símbolos NuGet.org

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 pacotes podem usar os símbolos publicados para nuget.org servidor de símbolos adicionando https://symbols.nuget.org/download/symbols às fontes de símbolo em Visual Studio, o que permite entrar no código do pacote no depurador Visual Studio. Consulte Specify symbol (.pdb) e arquivos de origem no Visual Studio depurador para obter detalhes sobre esse processo.

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

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 PDB crypto hash)

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

Note

Projetos nativos, como projetos C++, produzem Windows PDBs 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 herdado .

Validação e indexação do 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, a 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 por 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 a indexação do pacote geralmente levam 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 em uma hora, faça logon no nuget.org e entre em contato conosco usando o link de Suporte de Contato 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 do pacote NuGet correspondente (.nupkg).

  2. O .snupkg tem a mesma estrutura de pastas que seu .nupkg correspondente para qualquer arquivo 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 diferentes do PDB serão deixados de fora do snupkg.

  3. O arquivo .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 criar seus nupkg e snupkg, o snupkg deverá ter a mesma hierarquia de pastas e arquivos detalhados em 2).

  5. Os campos a seguir serão excluídos do nuspec do snupkg: authors, , owners, requireLicenseAcceptance, , license typee licenseUrlicon.

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

Consulte também

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

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

  • Last updated on