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

Статья
08/21/2023

С помощью Microsoft Visual Studio можно создать пакет NuGet из библиотеки классов платформа .NET Framework, а затем опубликовать его в nuget.org с помощью средства командной строки NuGet.

Краткое руководство предназначено только для пользователей Windows. Если вы используете Visual Studio для Mac, ознакомьтесь с инструментами dotnet CLI.

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

Установите Visual Studio 2022 для Windows с любым. Рабочая нагрузка, связанная с NET.

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

Visual Studio 2017 и выше автоматически включает возможности NuGet при установке рабочей нагрузки .NET.
Зарегистрируйтесь для получения бесплатной учетной записи на nuget.org, если вы не сделали этого ранее. Перед отправкой пакета NuGet необходимо зарегистрировать и подтвердить ее.
Установите интерфейс командной строки NuGet, скачав его из nuget.org. Добавьте файл nuget.exe в подходящую папку и добавьте ее в переменную среды PATH.

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

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

В Visual Studio выберите Файл>Создать>Проект.
В окне создания проекта выберите C#, Windows и Библиотека в раскрывающихся списках.
В результирующем списке шаблонов проектов выберите библиотеку классов (платформа .NET Framework), а затем нажмите кнопку "Далее".
В окне "Настройка нового проекта" введите AppLogger для имени проекта и нажмите кнопку "Создать".
Чтобы убедиться, что проект был создан правильно, выберите "Сборка решения сборки>". Библиотека DLL находится в папке Debug (или папке Release, если вы используете конфигурацию выпуска для сборки).
(Необязательно) Для этого краткого руководства вам не нужно писать дополнительный код для пакета NuGet, так как библиотека классов шаблонов достаточно для создания пакета. Однако если для этого примера пакета требуется некоторый функциональный код, включите следующий код:
```
namespace AppLogger
{
    public class Logger
    {
        public void Log(string text)
        {
            Console.WriteLine(text);
        }
    }
}
```
В реальном мире пакет NuGet, вероятно, будет реализовано множество полезных функций, с помощью которых другие пользователи могут создавать приложения. Вы также можете задать целевые платформы. Примеры см. в разделе UWP и Xamarin.

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

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

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

Внимание

Необходимо присвоить пакету идентификатор, который будет уникальным на сайте nuget.org или другом используемом узле. В противном случае возникает ошибка. В этом кратком руководстве мы рекомендуем включить пример или тест в имя, так как шаг публикации делает пакет общедоступным.
Выберите сведения о сборке, в котором отображается диалоговое окно, в котором можно ввести другие свойства, которые несут в манифест (см . маркеры замены). Чаще всего используются поля Заголовок, Описание, Компания, Авторские права и Версия сборки. Так как эти свойства отображаются вместе с пакетом на узле, например nuget.org после публикации, убедитесь, что они полностью описательны.
(Необязательно) Чтобы просмотреть и изменить свойства напрямую, откройте файл properties/AssemblyInfo.cs в проекте, выбрав команду "Изменить файл проекта>".
После установки этих свойств задайте конфигурацию активного решения в Build>Configuration Manager, чтобы освободить и перестроить проект, чтобы создать обновленную библиотеку DLL.

Создание начального манифеста

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

Выполните nuget spec только один раз, чтобы создать начальный манифест. Если вы обновляете пакет, измените значения в проекте или измените манифест напрямую:

Открыв проект в Обозреватель решений, откройте командную строку, выбрав командную строку разработчика командной строки> инструментов.>

Командная строка открывается в каталоге проекта, где AppLogger.csproj находится файл.
Выполните следующую команду: nuget spec AppLogger.csproj.

NuGet создает манифест, соответствующий имени проекта.AppLogger.nuspec Он также содержит маркеры замены в манифесте.

Откройте AppLogger.nuspec в текстовом редакторе, чтобы проверить его содержимое, которое будет аналогично следующему коду:

<?xml version="1.0"?>
<package >
  <metadata>
    <id>Package</id>
    <version>1.0.0</version>
    <authors>Your username</authors>
    <owners>Your username</owners>
    <license type="expression">MIT</license>
    <!-- <icon>icon.png</icon> -->
    <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Package description</description>
    <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
    <copyright>Copyright 2022</copyright>
    <tags>Tag1 Tag2</tags>
  </metadata>
</package>

Изменение манифеста

Перед продолжением измените следующие свойства. В противном случае при попытке создать пакет NuGet со значениями по умолчанию в .nuspec файле возникает ошибка. Дополнительные сведения об этих свойствах см. в разделе Необязательные элементы метаданных:
- licenseUrl
- projectUrl
- releaseNotes
- tags
Если пакет будет общедоступным, обратите особое внимание на свойство Теги, так как они помогают найти ваш пакет и понять его назначение.
Вы также можете добавить любые другие элементы в манифест в настоящее время, как описано в справочнике по nuspec-файлу.
Сохраните файл, прежде чем продолжить.

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

Открыв проект в Обозреватель решений, откройте командную строку, выбрав командную строку разработчика командной строки> инструментов.>

Командная строка открывается в каталоге проекта.
Выполните следующую команду: nuget pack.

NuGet создает nupkg-файл в виде идентификатора.version.nupkg в текущей папке.

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

После создания NUPKG-файла опубликуйте его в nuget.org с помощью интерфейса командной строки NuGet с ключом API, полученным из nuget.org. Для nuget.org необходимо использовать nuget.exe версию 4.1.0 или более позднюю версию.

Если вы хотите протестировать и проверить пакет перед публикацией общедоступной коллекции, его можно отправить в тестовую среду, например int.nugettest.org вместо nuget.org. Обратите внимание, что пакеты, отправленные в int.nugettest.org, могут не сохраняться.

Примечание.

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

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

Войдите в учетную запись nuget.org или создайте учетную запись, если у вас еще нет учетной записи.
Выберите имя пользователя в правом верхнем углу и выберите ключи API.
Выберите " Создать" и укажите имя ключа.
В разделе "Выбор областей" выберите "Отправить".
В разделе "Выбор пакетов>" введите *.
Нажмите кнопку создания.
Выберите "Копировать", чтобы скопировать новый ключ.

Внимание

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

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

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

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

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

Использование интерфейса командной строки NuGet (nuget.exe) является альтернативой использованию .NET CLI:

Откройте командную строку и перейдите в папку, содержащую NUPKG-файл .
Выполните следующую команду. Замените <имя> файла пакета именем пакета и замените <значение> ключа API ключом API. Имя файла пакета — это объединение идентификатора пакета и номера версии с расширением NUPKG . Например, AppLogger.1.0.0.nupkg:
```
nuget push <package filename> <api key value> -Source https://api.nuget.org/v3/index.json
```
Результат процесса публикации отображается следующим образом:
```
Pushing <package filename> to 'https://www.nuget.org/api/v2/package'...
    PUT https://www.nuget.org/api/v2/package/
    Created https://www.nuget.org/api/v2/package/ 6829ms
Your package was pushed.
```

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

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

Ошибки в результатах выполнения команды 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, что другие разработчики могут использовать в своих проектах.

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

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

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

Примечание.

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

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

Поздравляем с созданием пакета NuGet с помощью платформа .NET Framework Visual Studio. Перейдите к следующей статье, чтобы узнать, как создать пакет NuGet с помощью интерфейса командной строки NuGet.

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

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

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

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

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

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

Создание начального манифеста

Изменение манифеста

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

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

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

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

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

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

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

Обратная связь

Обратная связь

Дополнительные ресурсы