Краткое руководство. Создание и публикация пакета с помощью dotnet CLI

  • Статья

В этом кратком руководстве показано, как быстро создать пакет NuGet из библиотеки классов .NET и опубликовать его в nuget.org с помощью интерфейса командной строки .NET или dotnet CLI.

Необходимые компоненты

  • Пакет SDK для .NET, предоставляющий средство командной строки dotnet. Начиная с Visual Studio 2017, dotnet CLI автоматически устанавливается с любыми связанными рабочими нагрузками .NET или .NET Core.

  • Бесплатная учетная запись на nuget.org. Следуйте инструкциям по добавлению новой отдельной учетной записи.

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

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

  1. Создайте папку с именем AppLogger.
  2. Откройте командную строку и перейдите в папку AppLogger . Все команды dotnet CLI в этом кратком руководстве запускаются в текущей папке по умолчанию.
  3. Введите dotnet new classlib, который создает проект с текущим именем папки.

Дополнительные сведения см. в разделе dotnet new.

Добавление метаданных пакета в файл проекта

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

Откройте файл проекта CSPROJ, FPROJ или VBPROJ и добавьте следующие свойства в существующий <PropertyGroup> тег. Используйте собственные значения для имени и компании и замените идентификатор пакета уникальным значением.

<PackageId>Contoso.08.28.22.001.Test</PackageId>
<Version>1.0.0</Version>
<Authors>your_name</Authors>
<Company>your_company</Company>

Внимание

Идентификатор пакета должен быть уникальным в nuget.org и других источниках пакетов. Публикация делает пакет общедоступным, поэтому если вы используете пример библиотеки AppLogger или другой тестовой библиотеки, используйте уникальное имя, включающее Sample или Test.

Вы можете добавить любые необязательные свойства, описанные в свойствах метаданных NuGet.

Примечание.

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

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

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

dotnet pack

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

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored C:\Users\myname\source\repos\AppLogger\AppLogger.csproj (in 64 ms).
  AppLogger -> C:\Users\myname\source\repos\AppLogger\bin\Debug\net6.0\AppLogger.dll
  Successfully created package 'C:\Users\myname\source\repos\AppLogger\bin\Debug\Contoso.08.28.22.001.Test.1.0.0.nupkg'.

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

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

    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>

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

Опубликуйте NUPKG-файл в nuget.org с помощью команды push-отправки dotnet nuget с ключом API, полученным из nuget.org.

Примечание.

  • Nuget.org проверяет все отправленные пакеты для вирусов и отклоняет пакеты, если он находит вирусы. Nuget.org также периодически сканирует все существующие перечисленные пакеты.

  • Пакеты, которые вы публикуете в nuget.org, общедоступны для других разработчиков, если вы не заметите их. Сведения о частном размещении пакетов см. в разделе "Размещение собственных веб-каналов NuGet".

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

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

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

  3. Выберите " Создать" и укажите имя ключа.

  4. В разделе "Выбор областей" выберите "Отправить".

  5. В разделе "Выбор пакетов>" введите *.

  6. Нажмите кнопку создания.

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

    Screenshot that shows the new API key with the Copy link.

Внимание

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

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

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

См. подробнее о ключах API в определении области.

Публикация с помощью команды dotnet nuget push

В папке, содержащей NUPKG-файл , выполните следующую команду. Укажите имя файла .nupkg и замените значение ключа ключом API.

dotnet nuget push Contoso.08.28.22.001.Test.1.0.0.nupkg --api-key qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 --source https://api.nuget.org/v3/index.json

Выходные данные показывают результаты процесса публикации:

Pushing Contoso.08.28.22.001.Test.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
  PUT https://www.nuget.org/api/v2/package/
warn : All published packages should have license information specified. Learn more: https://aka.ms/nuget/authoring-best-practices#licensing.
  Created https://www.nuget.org/api/v2/package/ 1221ms
Your package was pushed.

Дополнительные сведения см. в статье dotnet nuget push.

Примечание.

Если вы хотите избежать активного использования тестового пакета на nuget.org, вы можете отправить на nuget.org тестовый сайт https://int.nugettest.org. Обратите внимание, что пакеты, отправленные в int.nugettest.org, могут не сохраняться.

Ошибки публикации

Ошибки в результатах выполнения команды push обычно указывают на неполадку. Например, возможно, вы забыли обновить номер версии в проекте, поэтому вы пытаетесь опубликовать уже существующий пакет.

Вы также увидите ошибки, если ключ API недопустим или истек, или если вы пытаетесь опубликовать пакет с помощью идентификатора, уже существующего на узле. Предположим, например, идентификатор AppLogger-test уже существует в nuget.org. Если вы попытаетесь опубликовать пакет с этим идентификатором, push команда выдает следующую ошибку:

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 выберите имя пользователя в правом верхнем углу и нажмите кнопку "Управление пакетами".

Примечание.

Может потребоваться некоторое время для индексирования пакета и отображения в результатах поиска, где другие пользователи могут найти его. В течение этого времени пакет отображается в разделе "Неподписанные пакеты", а на странице пакета отображается следующее сообщение:

Screenshot showing the publishing message that's displayed when you upload a package to nuget.org.

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

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

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

    Screenshot that shows the Edit icon for a package listing on nuget.org.

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

    Screenshot that shows clearing the List checkbox for a package on nuget.org.

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

Примечание.

Чтобы избежать трансляции тестового пакета на nuget.org, вы можете отправиться на сайт https://int.nugettest.orgтестирования nuget.org. Обратите внимание, что пакеты, отправленные в int.nugettest.org, могут не сохраняться.

Поздравляем с созданием и публикацией первого пакета NuGet!

Другие видео о NuGet см. на Channel 9 и YouTube.

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

Дополнительные сведения о создании пакетов с помощью dotnet CLI:

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

Дополнительные сведения о создании и публикации пакетов NuGet: