Краткое руководство. Создание и публикация пакета NuGet с помощью Visual Studio (только Для Windows)

В этом кратком руководстве вы используете Microsoft Visual Studio для создания пакета NuGet из библиотеки классов .NET. Затем вы публикуете пакет в nuget.org с помощью средства интерфейса командной строки (CLI).

Это краткое руководство предназначено только для пользователей Windows. Если вы используете другую платформу, используйте интерфейс командной строки .NET.

Необходимые условия

• Visual Studio 2026 г. с рабочей нагрузкой, связанной с .NET.

  Вы можете установить выпуск Community 2026 бесплатно из visualstudio.microsoft.com или использовать выпуск Professional или Enterprise.

  Visual Studio 2017 и более поздних версий автоматически включают возможности NuGet при установке рабочей нагрузки, связанной с .NET.

• Интерфейс командной строки .NET.

  Для Visual Studio 2017 и более поздних версий интерфейс командной строки .NET автоматически устанавливается с любой рабочей нагрузкой, связанной с .NET. Вы также можете установить пакет SDK .NET, чтобы получить интерфейс командной строки .NET. Интерфейс командной строки .NET необходим для проектов .NET, использующих формат SDK (и атрибут пакета SDK). Шаблон библиотеки классов .NET по умолчанию в Visual Studio 2017 и более поздних версиях использует атрибут SDK.

  Важный

  Если вы работаете с проектом, отличным от пакета SDK, следуйте процедурам в Create и опубликуйте пакет с помощью Visual Studio (.NET Framework, Windows) вместо этого, чтобы создать и опубликовать пакет. В этой статье рекомендуется использовать интерфейс командной строки .NET. Несмотря на то, что вы можете опубликовать любой пакет NuGet с помощью интерфейса командной строки NuGet, некоторые действия, описанные в этой статье, относятся к проектам в стиле SDK и .NET CLI. Интерфейс командной строки NuGet используется для проектов не-SDK (обычно проектов .NET Framework).

• Бесплатная учетная запись в nuget.org. Перед отправкой пакета NuGet необходимо зарегистрировать и подтвердить ее.

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

Создание проекта библиотеки классов

Вы можете использовать существующий проект библиотеки классов .NET для кода, который требуется упаковать, или создать его, выполнив следующие действия.

1. В Visual Studio выберите File>New>Project/Solution.

2. В окне создания проекта перейдите в поле поиска и введите библиотеку классов.

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

   • Содержит описание проекта создания библиотеки классов, предназначенной для .NET или .NET Standard.
   • Имеет тег C#

   Нажмите кнопку Далее.

4. В окне Настройте ваш новый проект в поле Имя проекта введите AppLogger и выберите Далее.

5. В окне "Дополнительные сведения " выберите соответствующее значение для Платформы и нажмите кнопку "Создать".

   Если вы не уверены, какую платформу выбрать, последний вариант является хорошим выбором и может быть легко изменен позже. Дополнительную информацию о том, какую платформу использовать, смотрите в разделе "Когда следует использовать netx.0 и netstandard".

6. (Необязательно) В этом кратком руководстве вам не нужно писать дополнительный код для пакета NuGet, потому что библиотеки классов шаблонов вполне достаточно для создания пакета. Однако если вы хотите добавить в пакет некоторый функциональный код, добавьте следующий код:

   namespace AppLogger
   {
       public class Logger
       {
           public void Log(string text)
           {
               Console.WriteLine(text);
           }
       }
   }
   

Настройка свойств пакета

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

1. В Обозреватель решений выберите project, а затем выберите Project><project-name> Properties где <project-name> — это имя project.

2. Разверните узел пакета, а затем выберите Общие.

   Узел пакета отображается только для проектов в стиле SDK в Visual Studio. Если вы работаете с проектом, не использующим стиль SDK (как правило, .NET Framework), либо мигрируйте проект, или ознакомьтесь с Создание и публикация пакета с помощью Visual Studio (.NET Framework, Windows) для пошаговых инструкций.

   

3. Для идентификатора пакета присвойте пакету уникальный идентификатор.

   Важный

   Необходимо предоставить пакету уникальный идентификатор для используемого узла, например nuget.org. В противном случае возникает ошибка. В этом кратком руководстве рекомендуется включить пример или тест в идентификатор, так как шаг публикации делает пакет общедоступным. Дополнительные сведения о выборе идентификатора см. в рекомендациях по идентификатору пакета.

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

   Все свойства переходят в манифест .nuspec, который Visual Studio создает для проекта. Таблицу, показывающую, как свойства Microsoft Build (MSBuild) в проектах в стиле SDK сопоставляются с свойствами файла .nuspec, см. в разделе pack target. Описание свойств файла NUSPEC см. в справочнике по NUSPEC.

5. (Необязательно) Чтобы просмотреть свойства непосредственно в файле проекта AppLogger.csproj, выберите Проект>Изменить файл проекта.

   Файл AppLogger.csproj откроется на новой вкладке.

   Этот параметр доступен для проектов, использующих стиль SDK.

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

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

1. Выберите Build>Configuration Manager и установите значение Активная конфигурация решения на Release.

2. В Обозреватель решений щелкните проект AppLogger и выберите Pack.

   Visual Studio создает проект и создает файл .nupkg.

3. Просмотрите окно вывода для получения подробных сведений, включая путь к файлу пакета. В этом примере встроенная сборка находится в папке bin\Release\net8.0, которая подходит для целевого объекта .NET 8.0:

   1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------
   1>  AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\net8.0\AppLogger.dll
   1>  Successfully created package 'd:\proj\AppLogger\AppLogger\bin\Release\Contoso.App.Logger.Test.1.0.0.nupkg'.
   ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
   

Если команда "Пакет" отсутствует в меню, проект, вероятно, не является проектом в стиле пакета SDK. Выполните одно из следующих действий.

• Обновите проект, так чтобы вы могли использовать интерфейс командной строки .NET.
• Следуйте инструкциям в Создание и публикация пакета с помощью Visual Studio (.NET Framework, Windows), чтобы использовать NuGet CLI для создания и публикации пакета NuGet из вашего проекта.

(Необязательно) Создание пакета при сборке

Visual Studio можно настроить для автоматического создания пакета NuGet при сборке проекта:

1. Выберите project в Обозреватель решений а затем выберите Project><project-name> Properties, где <project-name> — это имя project (AppLogger в этом случае).

2. Разверните узел пакета, выберите Общие, а затем выберите Создать пакет NuGet для сборки.

   

(Необязательно) Упаковать с помощью MSBuild

В качестве альтернативы использованию команды меню "Пакет " можно использовать msbuild -t:pack команду для создания пакета NuGet из проекта. NuGet 4.x+ и MSBuild 15.1+ поддерживают целевой pack объект, если проект содержит необходимые данные пакета.

1. Откройте проект в Обозреватель решений откройте окно командной строки, выбрав Tools>Command Line>Developer Command Prompt.

   Откроется окно командной строки в каталоге проекта.

2. Выполните следующую команду: msbuild -t:pack.

Дополнительные сведения см. в статье "Создание пакета NuGet с помощью MSBuild".

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

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

Получение ключа API

Перед публикацией пакета NuGet создайте ключ API:

1. Войдите в учетную запись nuget.org или создайте учетную запись , если у вас еще нет учетной записи .

2. В правом верхнем углу выберите имя пользователя и выберите ключи API.

3. Нажмите кнопку "Создать", а затем введите имя ключа.

4. В разделе Выбор областейвыберите Push.

5. В разделе "Выбор пакетов" для шаблона glob введите звездочку (*).

6. Выберите Создать.

7. Выберите Копировать, чтобы скопировать новый ключ.

   

Определение области предоставляет способ создания отдельных ключей API для различных целей. Каждый ключ имеет интервал времени окончания срока действия, и вы можете ограничить ключ определенными пакетами или шаблонами glOB-объектов. Кроме того, каждый ключ применяется к определенным операциям: отправка новых пакетов и версий пакетов, отправка только новых версий пакетов или отмена списка.

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

Для получения дополнительной информации см. Область действия API ключей.

Публикация с помощью интерфейса командной строки .NET или Интерфейса командной строки NuGet

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

dotnet nuget push <package-file> --api-key <API-key> --source https://api.nuget.org/v3/index.json

Pushing <package-file> to 'https://www.nuget.org/api/v2/package'...
  PUT https://www.nuget.org/api/v2/package/
  Created https://www.nuget.org/api/v2/package/ 2891ms
Your package was pushed.

Ошибки во время публикации

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

• Ключ API недопустим или истек.
• Вы пытаетесь опубликовать пакет с идентификатором, который уже существует на узле.
• Вы вносите изменения в опубликованный пакет, но вы забыли обновить номер версии перед попыткой повторной публикации.

Сообщение об ошибке обычно указывает источник проблемы.

Например, предположим, что идентификатор Contoso.App.Logger.Test существует в nuget.org. Если вы попытаетесь опубликовать пакет с этим идентификатором, вы получите следующую ошибку:

Response status code does not indicate success: 403 (The specified API key is invalid, has expired, or does not have permission to access the specified package.).

Чтобы устранить эту ситуацию, проверьте область, дату окончания срока действия и значение ключа API. Если ключ действителен, ошибка указывает, что идентификатор пакета уже существует на узле. Чтобы устранить проблему, измените идентификатор пакета, чтобы он был уникальным, перестроите проект, повторно создайте NUPKG-файл и повторите push команду.

Управление опубликованным пакетом

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

Теперь, когда пакет NuGet опубликован в nuget.org, другие разработчики могут использовать его в своих проектах.

Если вы создаете пакет, который не полезен (например, этот пример пакета из пустой библиотеки классов) или если вы не хотите, чтобы пакет был видимым, вы можете отменить список пакета, чтобы скрыть его из результатов поиска:

1. После появления пакета в разделе опубликованных пакетов на странице Управление пакетами выберите значок карандаша рядом с списком пакетов.

   

2. На следующей странице выберите " Список", снимите флажок "Список" в результатах поиска и нажмите кнопку "Сохранить".

   

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

Добавление файла read-me или другого файла

В пакет можно включить файл read-me или другие файлы.

Добавьте файл read-me

Чтобы добавить файл read-me в пакет, сделайте следующее:

1. Откройте файл project, выбрав Project>Edit Project File.

2. В файле проекта перейдите к PropertyGroup элементу и добавьте дочерний PackageReadmeFile элемент:

   <Project Sdk="Microsoft.NET.Sdk">
       <PropertyGroup>
           ...
           <PackageReadmeFile>readme.md</PackageReadmeFile>
           ...
       </PropertyGroup>
   </Project>
   

3. Перейдите к элементу ItemGroup и добавьте дочерний None элемент:

   <Project Sdk="Microsoft.NET.Sdk">
       <PropertyGroup>
           ...
           <PackageReadmeFile>readme.md</PackageReadmeFile>
           ...
       </PropertyGroup>
   
       <ItemGroup>
           ...
           <None Include="readme.md" Pack="true" PackagePath="\" />
           ...
       </ItemGroup>
   </Project>
   

В предыдущем примере свойство указывает файл с именем readme.md в корневом каталоге проекта. После сборки, упаковки и публикации пакета nuget.org отображает содержимое файла read-me на странице пакета. Visual Studio также отображает содержимое этого файла в пользовательском интерфейсе диспетчер пакетов.

Например, на следующем снимке экрана показан файл README для HtmlAgilityPack пакета.

Добавление других файлов

Чтобы добавить другие файлы в пакет, откройте файл project, выбрав Project>Edit Project File. Затем добавьте дочерний Content элемент в ItemGroup элемент:

<ItemGroup>
  <Content Include="other-content.md">
    <Pack>true</Pack>
    <PackagePath>\</PackagePath>
  </Content>
</ItemGroup>

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

Связанные видео

Видео об использовании NuGet для управления пакетами см. в статье .NET Управление пакетами с помощью NuGet для начинающих и NuGet для начинающих.

Связанный контент

Сведения о создании пакета NuGet с помощью платформы Visual Studio .NET см. в статье Create a package using the nuget.exe CLI.

Дополнительные сведения о NuGet см. в следующих статьях:

• Создание пакета NuGet с помощью dotnet CLI
• Публикация пакетов NuGet
• Создание пакетов предварительной версии
• Поддержка нескольких фреймворков .NET в вашем файле проекта
• управление версиями пакетов
• Создание локализованных пакетов NuGet
• Обзор обновления приложений .NET