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