Создание пакета NuGet с помощью dotnet CLI

Пакеты NuGet содержат код, который разработчики могут повторно использовать в своих проектах. Независимо от того, что делает или содержит ваш код, используйте средство командной строки либо nuget.exe, либо dotnet.exe, для создания пакета NuGet.

В этой статье описывается, как создать пакет с помощью dotnet CLI. Начиная с Visual Studio 2017, CLI dotnet включается во все среды разработки .NET и .NET Core. Если вам нужно установить dotnet CLI или другие клиентские средства NuGet, см. статью "Установка клиентских средств NuGet".

Этот раздел относится только к .NET и другим проектам, используюющим формат стиля ПАКЕТА SDK. Для этих проектов NuGet использует сведения из файла проекта для создания пакета. Краткие руководства см. в статье "Создание пакетов с помощью dotnet CLI " или "Создание пакетов с помощью Visual Studio".

Команда MSBuild msbuild -t:pack функционально эквивалентна пакету dotnet. Дополнительные сведения о создании пакета с помощью MSBuild см. в статье "Создание пакета NuGet с помощью MSBuild".

Установить свойства

Вы можете создать пример проекта библиотеки классов с помощью dotnet new classlib команды и упаковить проект с помощью dotnet packкоманды. Команда dotnet pack использует следующие свойства. Если значения в файле проекта не указаны, команда использует значения по умолчанию.

• PackageIdИдентификатор пакета должен быть уникальным в nuget.org и любых других целевых объектах, в которых размещен пакет. Если не указать значение, команда использует эту AssemblyNameкоманду.
• Version — это определенный номер версии в форме Major.Minor.Patch[-Suffix], где -Suffix определяются предварительные версии. Если не задано, по умолчанию используется значение 1.0.0.
• Authors являются авторами пакета. Если не указано, значение по умолчанию — это AssemblyNameзначение.
• Company — это сведения о компании. Если значение не указано, значение по умолчанию — Authors.
• Product — это сведения о продукте. Если не указано, значение по умолчанию — это AssemblyNameзначение.

В Visual Studio эти значения можно задать в свойствах проекта. Щелкните правой кнопкой мыши проект в обозревателе решений, выберите "Свойства" и выберите раздел "Пакет ". Вы также можете добавить свойства непосредственно в CSPROJ или другой файл проекта.

В следующем примере показан файл проекта с добавленными свойствами пакета.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>UniqueID</PackageId>
    <Version>1.0.0</Version>
    <Authors>Author Name</Authors>
    <Company>Company Name</Company>
    <Product>Product Name</Product>
  </PropertyGroup>
</Project>

Можно добавить другие необязательные свойства, например Title, PackageDescriptionи PackageTags.

Команда dotnet pack автоматически преобразует PackageReferenceфайлы проекта в зависимости в созданном пакете. Вы можете контролировать, какие ресурсы следует включить с помощью IncludeAssetsExcludeAssets тегов и PrivateAssets тегов. Дополнительные сведения см. в разделе "Управление ресурсами зависимостей".

Дополнительные сведения о зависимостях, необязательных свойствах и использовании версий см. в следующем разделе:

• ссылки на пакеты в файлах проекта
• Управление версиями пакетов
• Свойства метаданных NuGet
• Целевые объекты пакета MSBuild

Выберите уникальный идентификатор пакета и задайте номер версии

Идентификатор пакета и номер версии однозначно определяют точный код, содержащийся в пакете.

Чтобы создать идентификатор пакета, выполните следующие рекомендации.

• Идентификатор должен быть уникальным в nuget.org и во всех других расположениях, в которых размещен пакет. Чтобы избежать конфликтов, рекомендуется использовать имя вашей компании в качестве первой части идентификатора.

• Следуйте соглашению об именовании, подобному пространству имен .NET, используя точечную нотацию. Например, используйте Contoso.Utility.UsefulStuff, а не Contoso-Utility-UsefulStuff или Contoso_Utility_UsefulStuff. Также полезно для пользователей, если вы сопоставите идентификатор пакета с пространством имен, которое использует код.

• Если вы создаете пакет примера кода , демонстрирующий использование другого пакета, добавьте .Sample его к идентификатору, как показано в Contoso.Utility.UsefulStuff.Sample.

  Пример пакета зависит от исходного пакета. При создании пакета образца добавьте значение <IncludeAssets> с contentFiles. В папке содержимого расположите пример кода в папке под названием \Samples\<identifier>, например, \Samples\Contoso.Utility.UsefulStuff.Sample.

Чтобы задать версию пакета, выполните следующие рекомендации.

• Как правило, задайте версию пакета для соответствия версии проекта или сборки, хотя это не обязательно. Сопоставление версии просто при ограничении пакета на одну сборку. Сам NuGet работает с версиями пакетов при разрешении зависимостей, а не с версиями сборок.

• Если вы используете нестандартную схему версий, обязательно рассмотрите правила управления версиями NuGet , как описано в разделе "Управление версиями пакетов". NuGet в основном соответствует семантической версии 2.0.0.

Добавление необязательного поля описания

Необязательное описание пакета отображается на вкладке README страницы nuget.org пакета. Описание извлекается из <Description> в файле проекта или $description в файле .nuspec.

В следующем примере показан Description в файле .csproj для пакета .NET:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageId>Azure.Storage.Blobs</PackageId>
    <Version>12.4.0</Version>
    <PackageTags>Microsoft Azure Storage Blobs;Microsoft;Azure;Blobs;Blob;Storage;StorageScalable</PackageTags>
    <Description>
      This client library enables working with the Microsoft Azure Storage Blob service for storing binary and text data.
      For this release see notes - https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md and https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/CHANGELOG.md
      in addition to the breaking changes https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/BreakingChanges.txt
      Microsoft Azure Storage quickstarts and tutorials - https://learn.microsoft.com/azure/storage/
      Microsoft Azure Storage REST API Reference - https://learn.microsoft.com/rest/api/storageservices/
      REST API Reference for Blob Service - https://learn.microsoft.com/rest/api/storageservices/blob-service-rest-api
    </Description>
  </PropertyGroup>
</Project>

Выполните команду pack

Чтобы создать пакет NuGet или NUPKG-файл , выполните команду dotnet pack из папки проекта, которая также автоматически создает проект.

dotnet pack

В выходных данных показан путь к NUPKG-файлу :

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj (in 97 ms).
  Successfully created package 'D:\proj\AppLoggerNet\AppLogger\bin\Debug\AppLogger.1.0.0.nupkg'.

Автоматическое создание пакета при сборке

Чтобы dotnet pack автоматически запускалось каждый раз при запуске dotnet build, добавьте следующую строку в файл проекта внутри тега <PropertyGroup>.

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

При упаковке в решении dotnet pack все проекты в решении, которые могут быть упакованы, то есть имеют для свойства IsPackable значение true.

Установка тестового пакета

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

Протестируйте установку вручную в Visual Studio или в командной строке с помощью обычного процесса установки пакета.

Дальнейшие шаги

После создания пакета вы можете опубликовать NUPKG-файл в выбранном узле.

См. следующие статьи о способах расширения возможностей пакета или поддержки других сценариев:

• Управление версиями пакетов
• Поддержка нескольких целевых платформ
• Добавьте значок пакета
• Преобразования исходных и конфигурационных файлов
• Локализация
• Предварительные версии
• Установка типа пакета
• Реквизиты и целевые объекты MSBuild
• Создавайте пакеты с использованием сборок взаимодействия COM
• Создание собственных пакетов
• Создание пакетов символов (.snupkg)