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

При создании пакета NuGet из кода вы упаковываете эту функцию в компонент, который можно совместно использовать с любым количеством других разработчиков. В этой статье описывается, как создать пакет с помощью MSBuild. MSBuild поставляется предварительно установленной с каждой рабочей нагрузкой Visual Studio, содержащей NuGet. Кроме того, вы можете использовать MSBuild с помощью dotnet CLI, выполнив команду dotnet msbuild.

Для проектов .NET Core и .NET Standard, использующих формат пакета SDK и любые другие проекты в стиле SDK, NuGet использует сведения в файле проекта непосредственно для создания пакета. Для проекта не в стиле SDK, который использует <PackageReference>, NuGet также использует файл проекта для создания пакета.

Проекты SDK-типа имеют функциональность упаковки, доступную по умолчанию. Для проектов PackageReference, отличных от пакета SDK, он также доступен по умолчанию начиная с Visual Studio 2026. В более ранних версиях Visual Studio необходимо добавить пакет NuGet.Build.Tasks.Pack в зависимости проекта и рекомендуется удалить эту ссылку на пакет при обновлении до Visual Studio 2026. Подробные сведения о целевых объектах пакета MSBuild см. в статье Об пакете NuGet и восстановлении в качестве целевых объектов MSBuild.

Для проектов в стиле SDK msbuild -t:pack функционально аналогичен dotnet pack.

Это важно

Этот раздел относится к проектам в стиле ПАКЕТА SDK , как правило, проектам .NET Core и .NET Standard, а также к проектам, не используюющим PackageReference.

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

Для создания пакета требуются следующие свойства.

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

Кроме того, если вы упаковаете проекты, не относящиеся к пакету SDK, которые используют PackageReference, требуется следующее:

• PackageOutputPath— выходная папка пакета, созданная при вызове пакета.

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

<PropertyGroup>
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>your_name</Authors>
  <Company>your_company</Company>
</PropertyGroup>

Это важно

Присвойте пакету уникальный идентификатор в nuget.org или любом используемом источнике пакета.

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

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>ClassLibDotNetStandard</PackageId>
    <Version>1.0.0</Version>
    <Authors>your_name</Authors>
    <Company>your_company</Company>
  </PropertyGroup>
</Project>

Можно также задать необязательные свойства, такие как Title, PackageDescriptionи PackageTags, как описано в целевых объектах пакета MSBuild, управлении ресурсами зависимостей и свойствами метаданных NuGet.

Замечание

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

Дополнительные сведения об объявлении зависимостей и указании номеров версий см. в справочнике по пакетам в файлах проекта и использовании версий пакета. Также можно непосредственно получить доступ к ресурсам из зависимостей в пакете, используя атрибуты <IncludeAssets> и <ExcludeAssets>. Дополнительные сведения см. в разделе "Управление ресурсами зависимостей".

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

Необязательное описание пакета отображается на вкладке 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>

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

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

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

• Идентификатор должен быть уникальным в 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. Сведения, которые помогут вам понять управление версиями, см. в этой серии записей блога:

• Часть 1. Борьба с DLL Hell
• Часть 2. Основной алгоритм
• Часть 3. Унификация посредством перенаправлений привязки

Настройка проекта для пакета

Проекты в стиле SDK не требуют дополнительной настройки.

Для проектов без стиля SDK требуется установить хотя бы один пакет (через PackageReference, а не packages.config), или проект должен явно указать NuGet, чтобы тот рассматривал проект как проект PackageReference через свойство RestoreProjectStyle.

Visual Studio 2022 и более ранних версий не имеет встроенного пакета, поэтому также необходимо установить пакет NuGet.Build.Tasks.Pack. При обновлении до Visual Studio 2026 или более поздней версии рекомендуется удалить пакет, чтобы воспользоваться новыми функциями и исправлениями ошибок.

1. Измените файл проекта.

   Если вы хотите, чтобы NuGet явно рассматривал проект как PackageReference (в проекте нет установленных пакетов), найдите или добавьте элемент <PropertyGroup>, который не содержит элемента Condition, и добавьте:

   <PropertyGroup>
     <!-- other properties -->
     <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
     <!-- more properties are allowed -->
   </PropertyGroup>
   

   Если вы используете Visual Studio 2022 или более ранних версий, добавьте следующее <PropertyGroup> после элемента:

   <ItemGroup>
     <!-- ... -->
     <PackageReference Include="NuGet.Build.Tasks.Pack" Version="6.14.0" PrivateAssets="all" />
     <!-- ... -->
   </ItemGroup>
   

   Замечание

   Рассмотрите возможность использования последней версии этого пакета.

2. Откройте командную строку разработчика (в поле поиска введите командную строку разработчика).

   Как правило, вы хотите запустить командную строку разработчика для Visual Studio из меню "Пуск ", так как она будет настроена со всеми необходимыми путями для MSBuild.

3. Перейдите в папку, содержащую файл проекта, и введите следующую команду, чтобы восстановить пакет NuGet.Build.Tasks.Pack.

   # Uses the project file in the current folder by default
   msbuild -t:restore
   

   Убедитесь, что выходные данные MSBuild указывают на успешное завершение сборки.

Выполните команду msbuild -t:pack

Чтобы создать пакет NuGet ( .nupkg файл) из проекта, выполните msbuild -t:pack команду, которая также автоматически создает проект:

В командной строке разработчика для Visual Studio введите следующую команду:

# Uses the project file in the current folder by default
msbuild -t:pack

В выходных данных показан путь к файлу .nupkg .

Microsoft (R) Build Engine version 16.1.76+g14b0a930a7 for .NET Framework
Copyright (C) Microsoft Corporation. All rights reserved.

Build started 8/5/2019 3:09:15 PM.
Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" on node 1 (pack target(s)).
GenerateTargetFrameworkMonikerAttribute:
Skipping target "GenerateTargetFrameworkMonikerAttribute" because all output files are up-to-date with respect to the input files.
CoreCompile:
  ...
CopyFilesToOutputDirectory:
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.dll" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll".
  ClassLib_DotNetStandard -> C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb".
GenerateNuspec:
  Successfully created package 'C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\AppLogger.1.0.0.nupkg'.
Done Building Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" (pack target(s)).

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:01.21

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

Чтобы автоматически запустить msbuild -t:pack при сборке или восстановлении проекта, добавьте следующую строку в файл проекта в <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

При запуске msbuild -t:pack в решении упаковываются все проекты, которые могут быть упакованы в решение, если свойству <IsPackable> присвоено значение true.

Замечание

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

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

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

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

Это важно

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

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

После создания пакета, который представлен файлом .nupkg, вы можете опубликовать его в галерее по вашему выбору, как описано в разделе «Публикация пакета».

Вы также можете расширить возможности пакета или поддерживать другие сценарии, как описано в следующих разделах:

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

Наконец, существуют дополнительные типы пакетов, которые следует учитывать:

• Нативные пакеты
• Пакеты символов