NuGet

Статья
01/29/2025

NuGet — это диспетчер пакетов для экосистемы .NET, который является основным способом, который разработчики могут обнаруживать и получать библиотеки с открытым кодом .NET. NuGet.org, бесплатная служба, предоставляемая корпорацией Майкрософт для размещения пакетов NuGet, является основным узлом для общедоступных пакетов NuGet, но вы можете опубликовать в пользовательских службах NuGet, таких как MyGet и Azure Artifacts.

Создание пакета NuGet

Пакет NuGet (*.nupkg) — это ZIP-файл, содержащий сборки .NET и связанные метаданные.

Существует два основных способа создания пакета NuGet. Более новый и рекомендуемый способ создать пакет из проекта в стиле SDK (файл проекта, содержимое которого начинается с <Project Sdk="Microsoft.NET.Sdk">). Сборки и целевые объекты автоматически добавляются в пакет и остальные метаданные добавляются в ФАЙЛ MSBuild, например имя пакета и номер версии. Компиляция с помощью команды dotnet pack выводит файл *.nupkg вместо сборок.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <AssemblyName>Contoso.Api</AssemblyName>
    <PackageVersion>1.1.0</PackageVersion>
    <Authors>John Doe</Authors>
  </PropertyGroup>
</Project>

Старый способ создания пакета NuGet — с помощью файла *.nuspec и средства командной строки nuget.exe. Nuspec-файл обеспечивает большой контроль, но необходимо тщательно указать, какие сборки и целевые объекты необходимо включить в окончательный пакет NuGet. Легко допустить ошибку или забыть обновить nuspec при внесении изменений. Преимущество nuspec заключается в том, что его можно использовать для создания пакетов NuGet для фреймворков, которые еще не поддерживают файл проекта в стиле SDK.

✔️ Рекомендуется использовать файл проекта в стиле SDK для создания пакета NuGet.

Зависимости пакетов

В статье Dependencies подробно рассматриваются зависимости пакетов NuGet.

Важные метаданные пакета NuGet

Пакет NuGet поддерживает множество свойств метаданных . В следующей таблице содержатся основные метаданные, которые должны предоставляться каждому пакету NuGet.org:

Имя свойства MSBuild	Имя Nuspec	Описание
`PackageId`	`id`	Идентификатор пакета. Префикс из идентификатора можно зарезервировать, если он соответствует условиям .
`PackageVersion`	`version`	Версия пакета NuGet. Дополнительные сведения см. в версии пакета NuGet.
`Title`	`title`	Понятное для пользователя название пакета. По умолчанию используется `PackageId`.
`Description`	`description`	Длинное описание пакета, отображаемого в пользовательском интерфейсе.
`Authors`	`authors`	Разделенный запятыми список авторов пакетов, соответствующий именам профилей в nuget.org.
`PackageTags`	`tags`	Список тегов и ключевых слов, описывающих пакет, разделенный пробелами или точками с запятой. Теги используются при поиске пакетов.
`PackageIcon`	`icon`	Путь к изображению в пакете для использования в качестве значка пакета. Дополнительные сведения о `icon` метаданных.
`PackageProjectUrl`	`projectUrl`	URL-адрес домашней страницы проекта или исходного репозитория.
`PackageLicenseExpression`	`license`	Идентификатор SPDX лицензии проекта. Только утвержденные лицензии OSI и FSF могут использовать идентификатор. Другие лицензии должны использовать `PackageLicenseFile`. Дополнительные сведения о `license` метаданных.

Важный

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

✔️ Рассмотрите возможность выбрать имя пакета NuGet с префиксом, который соответствует критериям резервирования префикса NuGet .

✔️ Обязательно используйте в значке пакета ссылку с протоколом HTTPS.

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

✔️ Используйте изображение значка пакета, равное 64x64, и имеет прозрачный фон для лучшего просмотра результатов.

✔️ Рассмотрите возможность настройки ссылки на источник, чтобы добавить метаданные системы управления версиями в сборки и пакет NuGet.

Source Link автоматически добавляет RepositoryUrl и RepositoryType метаданные в пакет NuGet. Source Link также добавляет сведения о точном исходном коде, из который был создан пакет. Например, в пакет, созданный из репозитория Git, будет добавлен хэш фиксации в качестве метаданных.

Предрелизные пакеты

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

<PackageVersion>1.0.1-beta1</PackageVersion>

Заметка

Стабильный пакет не может зависеть от пререлизного пакета. Необходимо либо выпустить собственный пакет как предварительную версию, либо использовать старую стабильную версию.

предварительная зависимость пакета NuGet

✔️ Опубликуйте пакет предварительной версии при тестировании или эксперименте.

✔️ Опубликуйте стабильный пакет, когда он готов, чтобы другие стабильные пакеты могли ссылаться на него.

Пакеты символов

Файлы символов (*.pdb) создаются компилятором .NET вместе со сборками. Файлы символов соотносят места выполнения с исходным кодом, что позволяет вам пошагово выполнять исходный код в процессе его работы, используя отладчик. NuGet поддерживает создание отдельного пакета символов (*.snupkg), содержащего файлы символов вместе с основным пакетом, содержащим сборки .NET. Идея пакетов символов заключается в том, что они размещаются на сервере символов и загружаются только средством, например Visual Studio по запросу.

NuGet.org размещает репозиторий с собственным сервером символов . Разработчики могут использовать символы, опубликованные на сервере символов NuGet.org, добавив https://symbols.nuget.org/download/symbols в источники символов в Visual Studio.

Важный

Сервер символов NuGet.org поддерживает только новые портативные файлы символов (*.pdb), созданные проектами в стиле SDK.

Чтобы использовать сервер символов NuGet.org при отладке библиотеки .NET, разработчики должны иметь Visual Studio 2017 версии 15.9 или более поздней.

Альтернативой созданию пакета символов является внедрение файлов символов в основной пакет NuGet. Основной пакет NuGet будет больше, но внедренные файлы символов означает, что разработчикам не нужно настраивать сервер символов NuGet.org. Если вы создаете пакет NuGet с помощью проекта в стиле SDK, вы можете встроить файлы символов, задав свойство AllowedOutputExtensionsInPackageBuildOutputFolder:

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
    <!-- Include symbol files (*.pdb) in the built .nupkg -->
    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
  </PropertyGroup>
</Project>

Недостатком внедрения файлов символов является увеличение размера пакета примерно на 30% для библиотек .NET, скомпилированных с помощью проектов в стиле SDK. Если размер пакета является проблемой, вместо этого следует публиковать символы в пакете символов.

✔️ РАССМОТРИТЕ возможность публикации символов в виде пакета символов (*.snupkg) для NuGet.org

Пакеты символов (*.snupkg) предоставляют разработчикам удобный способ отладки по мере необходимости, не увеличивая размер основного пакета и не влияя на производительность их восстановления для тех, кто не намерен отлаживать пакет NuGet.

Предостережение заключается в том, что пользователям может потребоваться найти и настроить сервер символов NuGet в интегрированной среде разработки (как однократная настройка), чтобы получить файлы символов. Visual Studio 2019 версии 16.1 добавил сервер символов NuGet.org в список серверов символов по умолчанию.

предыдущий следующий

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