Создание пакетов символов (SNUPKG)

Хороший интерфейс отладки зависит от наличия отладочных символов, так как они предоставляют критически важные сведения, такие как связь между компилируемым и исходным кодом, имена локальных переменных, трассировки стека и многое другое. Пакеты символов (SNUPKG) можно использовать для распространения этих символов и улучшения отладки пакетов NuGet.

Обратите внимание, что пакет символов не является единственной стратегией, чтобы сделать отладочные символы доступными для потребителей библиотеки. Их также можно использовать embed в dll следующем свойстве проекта.exe<DebugType>embedded</DebugType>

Необходимые условия

nuget.exe версии 4.9.0 или более поздней версии илиdotnet CLI версии 2.2.0 или более поздней версии, реализующей необходимые протоколы NuGet.

Создание пакета символов

Если вы используете dotnet CLI или MSBuild, необходимо задать IncludeSymbols и SymbolPackageFormat свойства для создания SNUPKG-файла в дополнение к NUPKG-файлу.

• Добавьте следующие свойства в CSPROJ-файл:

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

• Или укажите эти свойства в командной строке:

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

  или

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

Если вы используете NuGet.exe, вы можете использовать следующие команды для создания snupkg-файла в дополнение к Nupkg-файлу:

nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg

nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg

Свойство SymbolPackageFormat может иметь одно из двух значений: symbols.nupkg (по умолчанию) или snupkg. Если это свойство не указано, будет создан устаревший пакет символов.

Публикация пакета символов

1. Для удобства сначала сохраните ключ API с помощью NuGet (см. статью о публикации пакета).

   nuget SetApiKey Your-API-Key
   

   Tip

   Начиная с NuGet 7.6, можно задать NUGET_API_KEY переменные среды и NUGET_SYMBOL_API_KEY переменные среды вместо использования SetApiKey. Дополнительные сведения см. в разделе переменных среды.

2. После публикации основного пакета в nuget.org отправьте пакет символов следующим образом.

   nuget push MyPackage.snupkg
   

3. Вы также можете отправлять как основные, так и пакеты символов одновременно с помощью следующей команды. Файлы NUPKG и SNUPKG должны присутствовать в текущей папке.

   nuget push MyPackage.nupkg
   

NuGet публикует оба пакета в nuget.org. MyPackage.nupkg сначала будет опубликовано MyPackage.snupkg, за которым следует.

сервер символов NuGet.org

NuGet.org поддерживает собственный репозиторий сервера символов и принимает только новый формат пакета символов . .snupkg Потребители пакетов могут использовать символы, опубликованные на сервере символов nuget.org, добавив https://symbols.nuget.org/download/symbols в их источники символов в Visual Studio, что позволяет перейти к коду пакета в отладчике Visual Studio. Дополнительные сведения об этом процессе см. в разделе Specify symbol (PDB) и исходных файлов в отладчике Visual Studio.

ограничения пакета символов NuGet.org

NuGet.org имеет следующие ограничения для пакетов символов:

• В пакетах символов разрешены только следующие расширения файлов: .pdb, , , .psmdcp.xml.rels.nuspec.p7s
• На сервере символов NuGet.org поддерживаются только управляемые переносимые PDF-файлы .
• Файлы PDF и связанные библиотеки DLL nupkg должны быть созданы с помощью компилятора в Visual Studio версии 15.9 или выше (см. хэш шифрования PDB)

Пакеты символов, опубликованные в NuGet.org, завершаются ошибкой проверки, если эти ограничения не выполнены.

Проверка пакета символов и индексирование

Пакеты символов, опубликованные в NuGet.org , проходят несколько проверок, включая сканирование вредоносных программ. Если сбой проверки пакета, страница сведений о пакете отобразит сообщение об ошибке. Кроме того, владельцы пакета получат электронное письмо с инструкциями по устранению выявленных проблем.

Когда пакет символов прошел все проверки, символы будут индексированы серверами символов NuGet.org и будут доступны для использования.

Проверка и индексирование пакетов обычно занимает менее 15 минут. Если публикация пакетов занимает больше времени, посетите status.nuget.org , чтобы проверить, возникают ли прерывания NuGet.org. Если все системы работают и пакет не был успешно опубликован в течение часа, войдите в nuget.org и обратитесь к нам с помощью ссылки "Обратиться в службу поддержки" на странице сведений о пакете.

Структура пакета символов

Пакет символов (SNUPKG) имеет следующие характеристики:

1. Snupkg имеет тот же идентификатор и версию, что и соответствующий пакет NuGet (Nupkg).

2. Snupkg имеет ту же структуру папок, что и соответствующий Nupkg для любых DLL-файлов или EXE с различием, что вместо БИБЛИОТЕК DLL/EXEs соответствующие PDF-файлы будут включены в ту же иерархию папок. Файлы и папки с расширениями, отличными от PDB, будут оставлены вне snupkg.

3. Nuspec-файл пакета символов имеет SymbolsPackage тип пакета:

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

4. Если автор решит использовать пользовательский nuspec для сборки nupkg и snupkg, snupkg должен иметь ту же иерархию папок и файлы, которые подробно описаны в 2).

5. Следующие поля будут исключены из nuspec snupkg: authors, owners, requireLicenseAcceptance, license type, licenseUrlи icon.

6. Не используйте <license> элемент. Snupkg охватывается той же лицензией, что и соответствующий NUPKG.

См. также

Рассмотрите возможность использования source Link для включения отладки исходного кода .NET сборок. Дополнительные сведения см. в руководстве по исходному каналу.

Дополнительные сведения о пакетах символов см. в спецификации конструктора nuGet Package Debugging и Symbols Improvements .