NuGet

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.

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

См. сведения о зависимостях пакета NuGet.

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

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

Имя свойства MSBuild	Имя Nuspec	Description
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.

✔️ СЛЕДУЕТ использовать атрибут href для определения HTTPS-ссылки, указывающей на значок пакета.

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

✔️ СЛЕДУЕТ использовать для значка пакета изображение размером 64 × 64 с прозрачным фоном, чтобы обеспечить оптимальную видимость.

✔ РЕКОМЕНДУЕТСЯ настроить Source Link, чтобы добавить метаданные системы управления версиями в сборки и пакет NuGet.

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

Пакеты предварительного выпуска

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

<PackageVersion>1.0.1-beta1</PackageVersion>

Примечание.

В пакетах стабильных выпусков нельзя указывать зависимости от пакетов предварительной версии. В таком случае переведите используемый пакет в режим предварительной версии или укажите зависимость от более ранней стабильной версии.

✔️ СЛЕДУЕТ опубликовать пакет в режиме предварительной версии для тестирования, предварительного просмотра или экспериментов.

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

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

Файлы символов (*.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 добавлен в список серверов символов по умолчанию.

НазадДалее