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

  • Статья

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

В этой статье описывается, как создать пакет с помощью dotnet CLI. Начиная с Visual Studio 2017, интерфейс командной строки 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.

Примечание.

Для пакетов, которые вы создаете для общедоступного потребления, обратите особое внимание на PackageTags свойство. Теги помогают другим пользователям найти пакет и понять, что это делает.

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

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

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

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

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

  • Идентификатор должен быть уникальным в 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.

Примечание.

Дополнительные сведения о разрешении зависимостей см. в разделе "Разрешение зависимостей" с помощью PackageReference. Сведения, которые помогут вам понять управление версиями, см. в этой серии записей блога:

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

Необязательное описание пакета отображается на вкладке 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 packdotnet build, добавьте следующую строку в файл проекта в <PropertyGroup> теге:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Примечание.

При автоматическом создании пакета упаковка увеличивает время сборки проекта.

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

Тестирование установки пакета

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

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

Внимание

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

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

Следующие шаги

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

Публикация пакета

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