Поделиться через

Создание пакетов символов (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

    or

    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. Если значение этого свойства не указано, будет создан устаревший пакет символов.

Примечание.

Устаревший формат .symbols.nupkg все еще поддерживается, но только в целях совместимости как собственные пакеты (см. раздел Устаревшие пакеты символов). Сервер символов NuGet.org принимает только новый формат пакетов символов: .snupkg.

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

Примечание.

Azure Devops Artifacts в настоящее время не поддерживает отладку с помощью файлов .snupkg.

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

    nuget SetApiKey Your-API-Key

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

    nuget push MyPackage.snupkg

  3. Также можно выполнить принудительную отправку одновременно основного пакета и пакета символов, используя указанную ниже команду. Оба файла (.nupkg и .snupkg) должны находиться в текущей папке.

    nuget push MyPackage.nupkg

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

Примечание.

Если пакет символов не опубликован, убедитесь, что вы настроили источник NuGet.org в виде https://api.nuget.org/v3/index.json. Публикация пакетов символов поддерживается только в API NuGet версии 3.

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

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

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

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

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

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

Примечание.

Собственные проекты, например проекты C++, создают PDB-файлы Windows вместо переносимых 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- и EXE-файлов в ту же иерархию папок будут включены соответствующие PDB-файлы. Файлы и папки с расширениями, отличными от PDB, не войдут в пакет SNUPKG.

  3. Файл пакета символов NUSPEC имеет тип пакета SymbolsPackage:

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

  4. Если автор решит создать пакеты NUPKG и SNUPKG с помощью пользовательского NUSPEC-файла, пакет SNUPKG должен иметь иерархию папок и файлы, указанные в пункте 2).

  5. Следующие поля будут исключены из NUSPEC-файла пакета SNUPKG: authors, owners, requireLicenseAcceptance, license type, licenseUrl и icon.

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

См. также

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

Дополнительные сведения о пакетах символов см. в проектной спецификации по Отладка пакетов NuGet и улучшение символов.