Как создать nuget пакет visual studio
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
12 contributors
Users who have contributed to this file
- Open with Desktop
- View raw
- Copy raw contents Copy raw contents
Copy raw contents
Copy raw contents
[!Note] If you are using Visual Studio for Mac, refer to this information on creating a NuGet package, or use the dotnet CLI tools.
If it's not already installed, install the dotnet CLI.
Create a class library project
Right-click on the resulting project file and select Build to make sure the project was created properly. The DLL is found within the Debug folder (or Release if you build that configuration instead).
Within a real NuGet package, of course, you implement many useful features with which others can build applications. For this walkthrough, however, you won't write any additional code because a class library from the template is sufficient to create a package. Still, if you'd like some functional code for the package, use the following:
Configure package properties
Right-click the project in Solution Explorer, and choose Properties menu command, then select the Package tab.
[!Note] For packages built for public consumption, pay special attention to the Tags property, as tags help others find your package and understand what it does.
Give your package a unique identifier and fill out any other desired properties. For a mapping of MSBuild properties (SDK-style project) to properties in a .nuspec, see pack targets. For descriptions of properties, see the .nuspec file reference. All of the properties here go into the .nuspec manifest that Visual Studio creates for the project.
[!Important] You must give the package an identifier that's unique across nuget.org or whatever host you're using. For this walkthrough we recommend including "Sample" or "Test" in the name as the later publishing step does make the package publicly visible (though it's unlikely anyone will actually use it).
If you attempt to publish a package with a name that already exists, you see an error.
(Optional) To see the properties directly in the project file, right-click the project in Solution Explorer and select Edit AppLogger.csproj.
This option is only available starting in Visual Studio 2017 for projects that use the SDK-style attribute. Otherwise, right-click the project and choose Unload Project. Then right-click the unloaded project and choose Edit AppLogger.csproj.
Run the pack command
Set the configuration to Release.
Right click the project in Solution Explorer and select the Pack command:
1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------ 1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\netstandard2.0\AppLogger.dll 1>Successfully created package 'd:\proj\AppLogger\AppLogger\bin\Release\AppLogger.1.0.0.nupkg'. ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
(Optional) Generate package on build
You can configure Visual Studio to automatically generate the NuGet package when you build the project.
In Solution Explorer, right-click the project and choose Properties.
In the Package tab, select Generate NuGet package on build.
[!NOTE] When you automatically generate the package, the time to pack increases the build time for your project.
(Optional) pack with MSBuild
As an alternate to using the Pack menu command, NuGet 4.x+ and MSBuild 15.1+ supports a pack target when the project contains the necessary package data. Open a command prompt, navigate to your project folder and run the following command. (You typically want to start the "Developer Command Prompt for Visual Studio" from the Start menu, as it will be configured with all the necessary paths for MSBuild.)
Publish the package
Acquire your API key
Publish with the dotnet CLI or nuget.exe CLI
This step is the recommended alternative to using nuget.exe .
Before you can publish the package, you must first open a command line.
This step is an alternative to using dotnet.exe .
Open a command line and change to the folder containing the .nupkg file.
Run the following command, specifying your package name (unique package ID) and replacing the key value with your API key:
nuget.exe displays the results of the publishing process:
Manage the published package
Adding a readme and other files
To directly specify files to include in the package, edit the project file and use the content property:
This will include a file named readme.txt in the package root. Visual Studio displays the contents of that file as plain text immediately after installing the package directly. (Readme files are not displayed for packages installed as dependencies). For example, here's how the readme for the HtmlAgilityPack package appears:
[!Note] Merely adding the readme.txt at the project root will not result in it being included in the resulting package.
Если вы используете Visual Studio для Mac, ознакомьтесь с этими сведениями о создании пакета NuGet или примените средства CLI dotnet.
Предварительные требования
При необходимости установите CLI dotnet .
Создание проекта библиотеки классов
В Visual Studio выберите Файл Создать > Проект, разверните узел >, выберите шаблон "Библиотека классов (.NET Standard)", присвойте проекту имя AppLogger и нажмите кнопку >.
Щелкните правой кнопкой мыши полученный файл проекта и выберите пункт Сборка, чтобы убедиться, что проект создан правильно. Библиотека DLL находится в папке Debug (или папке Release, если вы используете конфигурацию выпуска для сборки).
В реальном пакете NuGet вы можете реализовать множество полезных возможностей, с помощью которых другие пользователи могут создавать приложения. Однако в этом пошаговом руководстве вы не будете писать дополнительный код, так как библиотеки классов из шаблона достаточно для создания пакета. Тем не менее, вы можете использовать функциональный код для пакета:
Настройка свойств пакета
Щелкните правой кнопкой мыши проект в обозреватель решений и выберите команду меню Свойства, а затем выберите вкладку Пакет.
Если пакет будет общедоступным, обратите особое внимание на свойство Теги, так как они помогают найти ваш пакет и понять его назначение.
Присвойте пакету уникальный идентификатор и заполните нужные свойства. Сведения о сопоставлении свойств MSBuild (проект в стиле SDK) со свойствами в NUSPEC-файле см. в разделе о целевых объектах пакета. Описание свойств см. в справочнике по NUSPEC-файлу. Все свойства добавляются в манифест .nuspec , который Visual Studio создает для проекта.
Необходимо присвоить пакету идентификатор, который будет уникальным на сайте nuget.org или другом используемом узле. При работе с этим руководством мы рекомендуем добавить к имени слово "Sample" или "Test", так как позже, после публикации, пакет станет общедоступным (хотя маловероятно, что кто-то будет его использовать).
Необязательно. Чтобы просматривать свойства непосредственно в файле проекта, щелкните правой кнопкой мыши проект в обозревателе решений и выберите Edit AppLogger.csproj (Изменить AppLogger.csproj).
Этот параметр доступен для проектов, использующих атрибут стиля пакета SDK, только в версиях начиная с Visual Studio 2017. Если у вас другой сценарий, щелкните проект правой кнопкой мыши и выберите пункт Выгрузить проект. Затем щелкните правой кнопкой мыши выгруженный проект и выберите команду изменения AppLogger.csproj.
Выполнение команды pack
Выберите конфигурацию Выпуск.
Щелкните проект правой кнопкой мыши в окне обозревателя решений и выберите команду Паковать:
(Необязательно) Создание пакета при сборке
Вы можете настроить в Visual Studio автоматическое создание пакета NuGet при сборке проекта.
В обозревателе решений щелкните правой кнопкой мыши проект и выберите пункт Свойства.
На вкладке Пакет выберите Создать пакет NuGet при сборке.
При автоматическом создании пакета время на упаковку увеличивает время сборки проекта.
(Необязательно) Упаковка с помощью MSBuild
В качестве альтернативы команде меню Pack в NuGet 4.x+ и MSBuild 15.1+ можно использовать целевой объект , когда проект содержит необходимые данные о пакете. Откройте командную строку, перейдите в папку проекта и запустите приведенную ниже команду. (В общем случае следует запустить Командную строку разработчика для Visual Studio из меню "Пуск", так как в этом случае настраиваются все необходимые пути для MSBuild.)
Дополнительные сведения см. в разделе Создание пакета с помощью MSBuild.
Публикация пакета
Получение ключа API
Выберите свое имя пользователя (в правом верхнем углу), а затем щелкните Ключи API.
После создания ключа выберите Копировать для получения ключа доступа, который требуется в интерфейсе командной строки:
Всегда держите свой ключ API в секрете! Рассматривайте свой ключ API как пароль, позволяющий любому пользователю управлять пакетами от вашего имени. Вам следует удалить или повторно создать свой ключ API, если он был случайно раскрыт.
Сохраните ключ в безопасном расположении, так как у вас больше не будет возможности скопировать ключ. Если вы вернетесь на страницу ключа API, вам понадобится повторно создать ключ, чтобы скопировать его. Кроме того, вы можете удалить ключ API, если больше не хотите отправлять пакеты.
Определение области позволяет создавать отдельные ключи API для разных целей. Ключи имеют срок действия. Кроме того, их можно привязать к определенным пакетам (или стандартным маскам). Каждый ключ также привязан к конкретным операциям: отправка новых пакетов и обновлений, отправка только обновлений или удаление из списка. Используя определение области, вы можете создавать ключи API разным пользователям, которые управляют пакетами организации. Это позволит предоставлять им только нужные разрешения. См. подробнее о ключах API в определении области.
Публикация с помощью CLI dotnet или CLI nuget.exe
Этот шаг — рекомендуемая альтернатива использования nuget.exe .
Перед публикацией пакета сначала нужно открыть командную строку.
Перейдите в папку, содержащую файл .nupkg .
Выполните следующую команду, указав имя пакета (уникальный идентификатор пакета) и заменив значение ключа ключом API:
dotnet отображает результаты публикации:
Дополнительные сведения см. в статье о команде dotnet nuget push.
Эту команду можно использовать вместо dotnet.exe .
Откройте командную строку и перейдите к папке с файлом .nupkg .
Выполните следующую команду, указав имя пакета (уникальный идентификатор пакета) и заменив значение ключа ключом API:
nuget.exe отображает результаты публикации:
Ознакомьтесь со сведениями о команде nuget push.
Ошибки публикации
Ошибки в результатах выполнения команды push обычно указывают на неполадку. Например, вы забыли обновить номер версии проекта и пытаетесь опубликовать пакет, который уже существует.
Ошибки также возникают при попытке опубликовать пакет с использованием идентификатора, который уже имеется на узле. Например, имя AppLogger уже существует. В этом случае команда push выдает следующую ошибку:
Управление опубликованным пакетом
Если при работе с этим пошаговым руководством был создан пакет, который не представляет пользы (например, пакет, созданный с использованием пустой библиотеки классов), следует исключить его из списка, чтобы он не отображался в результатах поиска:
Найдите пакет, который требуется исключить из списка, в разделе Published (Опубликованное) и щелкните значок корзины справа:
На следующей странице снимите флажок List (package-name) in search results (Вывести (имя пакета) в результатах поиска) и щелкните Save (Сохранить).
Добавление файла сведений и других файлов
Чтобы напрямую указать файлы, включаемые в пакет, измените файл проекта и используйте свойство content :
В корень пакета будет включен файл с именем readme.txt . Visual Studio отображает содержимое этого файла в виде обычного текста сразу после установки пакета напрямую. (Файлы сведений не отображаются для пакетов, устанавливаемых как зависимости.) Например, вот как выглядит файл сведений для пакета HtmlAgilityPack:
Обычное добавление файла readme.txt в корень проекта не приведет к включению его в итоговый пакет.
Независимо от назначения вашего пакета или содержащегося в нем кода, с помощью одного из средств CLI ( nuget.exe или dotnet.exe ) вы можете создать компонент, которым можно поделиться с любым количеством разработчиков для совместного использования. Инструкции по установке средств CLI для NuGet см. в статье Установка клиентских средств NuGet. Обратите внимание на то, что средство CLI не входит в состав Visual Studio по умолчанию.
Для проектов, перенесенных из packages.config в packages.config , используйте msbuild -t:pack.
С технической точки зрения, пакет NuGet — это просто ZIP-файл, расширение которого изменено на .nupkg и содержимое которого соответствует определенным соглашениям. В этом разделе подробно описывается создание пакета, в котором соблюдаются эти соглашения.
Создание пакета начинается с подготовки скомпилированного кода (сборок), символов и других файлов, которые должны быть включены в пакет (см. раздел Процесс создания пакета). Этот процесс не зависит от компиляции и других задач по созданию файлов для пакета, хотя вы можете использовать информацию из файла проекта для синхронизации скомпилированных сборок и пакетов.
Выбор сборок для добавления в пакет
Большинство пакетов общего назначения содержат одну или несколько сборок, которые другие разработчики могут использовать в собственных проектах.
Как правило, для каждой сборки лучше создавать собственный пакет NuGet, если эти сборки используются независимо. Например, если есть сборка Utilities.dll , которая зависит от сборки Parser.dll , но сборка Parser.dll также полезна сама по себе, создайте для каждой из этих сборок отдельный пакет. Это позволит разработчикам использовать Parser.dll независимо от Utilities.dll .
Если библиотека состоит из нескольких сборок, которые не используются сами по себе, то их предпочтительнее объединить в одном пакете. В продолжение предыдущего примера, если сборка Parser.dll содержит код, который используется только сборкой Utilities.dll , то сборку Parser.dll лучше включить в тот же пакет.
Аналогичным образом, если сборка Utilities.dll зависит от сборки Utilities.resources.dll , которая не используется сама по себе, включите их в один пакет.
Ресурсы представляют собой особый случай. Когда пакет устанавливается в проекте, NuGet автоматически добавляет ссылки на библиотеки DLL сборок в пакете, кроме тех из них, в именах которых есть , так как они считаются локализованными вспомогательными сборками (см. раздел Создание локализованных пакетов). По этой причине следует избегать использования .resources.dll в именах файлов пакета, которые содержат важный код.
Если библиотека содержит сборки COM-взаимодействия, следуйте дополнительным указаниям в разделе Создание пакетов, содержащих сборки COM-взаимодействия.
Назначение и структура файла NUSPEC
После того как вы решите, какие файлы нужно включить в пакет, следует создать манифест пакета в XML-файле .nuspec .
Манифест служит следующим целям:
- Описывает содержимое пакета и сам включается в него.
- Управляет созданием пакета и предоставляет диспетчеру NuGet указания по установке пакета в проекте. Например, в манифесте определяются другие зависимости пакета, чтобы диспетчер NuGet мог также установить их при установке основного пакета.
- Содержит обязательные и необязательные свойства, как описано ниже. Полные сведения, включая описание свойств, которые не упомянуты в этом разделе, см. в справочнике по файлам NUSPEC.
Часто используемые необязательные свойства:
- заметки о выпуске;
- сведения об авторских правах;
- краткое описание для пользовательского интерфейса диспетчера пакетов в Visual Studio;
- код языка;
- URL проекта
- лицензия в виде выражения или файла ( licenseUrl больше не рекомендуется, используйте вместо него licenseUrl );
- файл значка ( iconUrl больше не рекомендуется, используйте вместо него iconUrl );
- список зависимостей и ссылок;
- теги, упрощающие поиск в коллекции.
Ниже приведен типичный (но вымышленный) файл .nuspec с комментариями, описывающими свойства.
Подробные сведения об объявлении зависимостей и указании номеров версий см. в разделе packages.config и Управление версиями пакета. Доступ к ресурсам зависимостей в пакете можно также предоставлять напрямую с помощью атрибутов include и exclude элемента dependency . См. подраздел "Зависимости" в разделе Справочник по файлам NUSPEC.
Так как манифест включается в пакет, создаваемый на его основе, вы можете получить дополнительные примеры, изучив существующие пакеты. Хорошим их источником может служить папка global-packages на компьютере, расположение которой можно получить с помощью следующей команды:
Перейдите в любую папку пакет\версия, скопируйте файл в файл .zip , затем откройте этот файл .zip и изучите содержимое файла .nuspec в нем.
При создании файла .nuspec из проекта Visual Studio манифест содержит токены, которые заменяются сведениями из проекта при сборке пакета. См. раздел Создание файла NUSPEC на основе проекта Visual Studio.
Создание NUSPEC-файла
Создание полного манифеста, как правило, начинается с базового файла .nuspec , который создается одним из следующих способов на основе:
Затем нужно отредактировать файл вручную так, чтобы он описывал содержимое итогового пакета.
Автоматически формируемые файлы .nuspec содержат заполнители, которые нужно изменить перед созданием пакета с помощью команды nuget pack . Если файл .nuspec содержит заполнители, эта команда завершается сбоем.
На основе рабочего каталога, соответствующего соглашениям
Так как пакет NuGet — это просто ZIP-файл, расширение которого изменено на .nupkg , зачастую проще всего создать нужную структуру папок в локальной файловой системе, а затем создать файл .nuspec на основе этой структуры. Команда nuget pack автоматически добавляет все файлы, имеющиеся в этой структуре папок (кроме папок, начинающихся с . , что позволяет иметь закрытые файлы в этой же структуре).
Преимущество такого подхода в том, что вам не нужно указывать в манифесте файлы, которые требуется включить в пакет (как описано далее в этом разделе). В процессе сборки можно создать структуру папок, которая будет в точности перенесена в пакет, и легко включить в него другие файлы, которые в противном случае не были бы добавлены в проект:
- содержимое и исходный код, которые следует внедрить в конечный проект;
- Сценарии PowerShell
- преобразования существующих файлов конфигурации и исходного кода в проекте.
Ниже представлены соглашения в отношении папок.
Папка | Описание | Действие при установке пакета |
---|---|---|
(корневая) | Расположение файла readme.txt | При установке пакета в Visual Studio отображается файл readme.txt в корневой папке проекта. |
lib/ | Файлы сборки ( .dll ), документации ( .xml ) и символов ( .pdb ) для данного моникера целевой платформы (TFM) | Сборки добавляются как ссылки для использования во время компиляции или выполнения. Файлы .xml и .pdb копируются в папки проекта. Сведения о создании вложенных папок для определенных целевых платформ см. в разделе Поддержка нескольких целевых платформ. |
ref/ | Файлы сборки ( .dll ) и символов ( .pdb ) для определенного моникера целевой платформы (TFM) | Сборки добавляются как ссылки для использования только во время компиляции. Поэтому в папку bin проекта ничего не копируется. |
runtimes | Файлы сборки ( .dll ), символов ( .pdb ) и машинных ресурсов ( .pri ) для определенной архитектуры | Сборки добавляются как ссылки для использования только во время выполнения. Остальные файлы копируются в папки проекта. В папке /ref/ всегда должна быть соответствующая сборка (TFM) для AnyCPU , чтобы предоставить соответствующие сборки, используемые во время компиляции. См. раздел Поддержка нескольких целевых платформ. |
содержание | Произвольные файлы | Содержимое копируется в корневую папку проекта. Папку content можно представить как корневую папку целевого приложения, которое будет использовать пакет. Чтобы пакет добавил изображение в папку /images приложения, поместите это изображение в папку content/images пакета. |
выполнить сборку | Файлы MSBuild и .props (3.x+). | Автоматическое добавление в проект. |
buildMultiTargeting | Файлы MSBuild и .props (4.0+) для кроссплатформенного определения. | Автоматическое добавление в проект. |
buildTransitive | Файлы MSBuild и .props (5.0+), которые можно транзитивно передавать в любой соответствующий проект. См. об этой функции. | Автоматическое добавление в проект. |
средства | Скрипты и программы PowerShell, доступные из консоли диспетчера пакетов | Папка tools добавляется в переменную среды PATH только для консоли диспетчера пакетов (в частности, она tools добавляется в переменную PATH для среды MSBuild при сборке проекта). |
Так как в структуре папок может быть сколько угодно сборок для любого числа целевых платформ, этот метод обязателен при создании пакетов, поддерживающих несколько платформ.
После того как вы подготовите нужную структуру папок, выполните в ней следующую команду, чтобы создать файл .nuspec :
Созданный файл .nuspec не содержит явных ссылок на файлы в структуре папок. NuGet автоматически включает все файлы при создании пакета. Однако вам необходимо отредактировать значения-заполнители в других частях манифеста.
На основе библиотеки DLL сборки
В такой простой ситуации, как создание пакета на основе сборки, вы можете создать файл .nuspec из содержащихся в сборке метаданных с помощью следующей команды:
При использовании такого формата ряд заполнителей в манифесте заменяется конкретными значениями из сборки. Например, свойству присваивается имя сборки, а свойству — ее версия. Однако остальные свойства в манифесте не имеют соответствующих значений в сборке и поэтому по-прежнему содержат заполнители.
На основе проекта Visual Studio
Создавать файл .nuspec на основе файла .csproj или .vbproj удобно, так как ссылки на другие пакеты, установленные в проекте, как и на зависимости, создаются автоматически. Просто выполните следующую команду в папке, в которой находится файл проекта:
Получившийся файл .nuspec содержит .nuspec , которые заменяются во время создания пакета значениями их проекта, включая ссылки на другие пакеты, которые уже установлены.
Если у вас есть зависимости пакетов для включения в файл .nuspec, используйте вместо этого и получите файл .nuspec из созданного файла .nupkg. Например, используйте следующую команду.
Токен отделяется символами $ с обеих сторон свойства проекта. Например, значение в созданном таким образом манифесте, как правило, имеет следующий вид:
Этот токен заменяется значением AssemblyName из файла проекта во время упаковки. Точные сведения о том, как значения из проекта сопоставляются с токенами .nuspec , см. в .nuspec .
Токены избавляют от необходимости изменять критически важные значения, такие как номер версии, в файле .nuspec при обновлении пакета. (При необходимости токены всегда можно заменить на конкретные значения.)
Обратите внимание на то, что при работе с проектом Visual Studio доступно несколько дополнительных параметров создания пакета, которые описываются далее в подразделе Выполнение команды nuget pack для создания файла NUPKG.
Пакеты на уровне решения
Только в NuGet 2.x. Недоступно в NuGet 3.0 и более поздних версиях.
В NuGet 2.x поддерживалась концепция пакетов на уровне решения, которые устанавливают средства или дополнительные команды для консоли диспетчера команд (содержимое папки tools ), но не добавляют ссылки, содержимое или настройки сборки в проекты решения. Такие пакеты не содержат файлов непосредственно в папках lib , content или build , а их зависимости не содержат файлов в соответствующих папках lib , content или build .
NuGet отслеживает установленные пакеты уровня решения в файле packages.config в папке .nuget , а не в файле packages.config проекта.
Новый файл со значениями по умолчанию
Следующая команда создает манифест по умолчанию с заполнителями, формируя надлежащую структуру файлов:
Полученный файл .nuspec содержит заполнители для значений, например projectUrl . Прежде чем использовать этот файл для создания итогового файла .nupkg , его необходимо отредактировать.
Выбор уникального идентификатора пакета и задание номера версии
Идентификатор пакета (элемент ) и номер версии (элемент ) — два самых важных значения в манифесте, так как они однозначно определяют код, содержащийся в пакете.
Рекомендации в отношении идентификатора пакета
Рекомендации в отношении версии пакета
- Как правило, версия пакета должна соответствовать версии библиотеки, хотя это не строгое требование. Это легко реализовать, если пакет ограничен единственной сборкой, как было описано выше в подразделе Выбор сборок для добавления в пакет. В целом помните, что при разрешении зависимостей диспетчер NuGet ориентируется на версии пакетов, а не на версии сборок.
- При применении нестандартной схемы версий обязательно учитывайте правила управления версиями в NuGet, которые изложены в разделе Управление версиями пакета.
Добавление файла сведений и других файлов
Чтобы явным образом указать файлы, которые следует включить в пакет, используйте узел в файле .nuspec , который находится тега :
При использовании подхода на основе рабочего каталога, соответствующего соглашениям, файл readme.txt можно поместить в корневую папку пакета, а другое содержимое — в папку content . Элементы в манифесте не требуются.
Если в корневую папку пакета добавлен файл с именем readme.txt , Visual Studio отображает содержимое этого файла в виде обычного текста сразу после установки пакета напрямую. (Файлы сведений не отображаются для пакетов, устанавливаемых как зависимости.) Например, вот как выглядит файл сведений для пакета HtmlAgilityPack:
Если узел в файле .nuspec пуст, NuGet включает в пакет только содержимое из папки lib .
Включение в пакет свойств и целей MSBuild
Файлы в корневой папке \build считаются пригодными для всех целевых платформ. Чтобы предоставить файлы для определенных платформ, сначала поместите их в соответствующие вложенные папки, например следующие:
Затем в файле .nuspec укажите ссылки на эти файлы в узле :
Включение свойств и целевых объектов MSBuild в пакет появилось в NuGet 2.5, поэтому рекомендуется добавить атрибут в элемент metadata , чтобы указать минимальную версию клиента NuGet, необходимую для использования пакета.
В NuGet 3.x целевые объекты не добавляются в проект, а предоставляются через .nuget.g.targets и .nuget.g.props .
Выполнение команды nuget pack для создания файла NUPKG
Чтобы создать пакет на основе сборки или рабочего каталога, соответствующего соглашениям, выполните команду nuget pack , указав файл .nuspec , где необходимо заменить на имя файла:
При использовании проекта Visual Studio выполните команду nuget pack , указав файл проекта. В результате автоматически загрузится файл .nuspec проекта, и все токены в нем будут заменены значениями из файла проекта.
Использование файла проекта напрямую является необходимым для замены токенов, так как проект является источником значений токенов. Замена токенов не производится при использовании команды nuget pack с файлом .nuspec .
В любом случае команда nuget pack исключает папки, начинающиеся с точки, например .git или .hg .
NuGet указывает, есть ли в файле .nuspec ошибки, требующие исправления, например, если вы забыли изменить значения-заполнители в манифесте.
После успешного выполнения команды nuget pack вы получаете файл .nupkg , который можно опубликовать в подходящей коллекции, как описано в разделе nuget pack .
После создания пакета его полезно просмотреть, открыв в средстве Обозреватель пакетов. В нем в графической форме представлено содержимое пакета и его манифест. Вы также можете переименовать полученный файл .nupkg в файл .zip и просмотреть его содержимое напрямую.
Дополнительные параметры
С командой nuget pack можно использовать различные параметры командной строки для исключения файлов, переопределения номера версии в манифесте, изменения папки выходных данных и совершения других действий. Полный список параметров см. в справочнике по команде pack.
Ниже приводятся некоторые часто используемые с проектами Visual Studio параметры.
Проекты, на которые указывают ссылки. Если проект ссылается на другие проекты, вы можете включить их в пакет или добавить в качестве зависимостей с помощью параметра :
Включение является рекурсивным, поэтому если MyProject.csproj ссылается на проекты B и C, а они ссылаются на проекты D, E и F, в пакет включаются файлы из проектов B, C, D, E и F.
Если в проекте, на который указывает ссылка, есть собственный файл .nuspec , NuGet вместо этого добавляет проект как зависимость. Такой проект необходимо упаковать и опубликовать отдельно.
Конфигурация сборки. По умолчанию NuGet использует стандартную конфигурацию сборки, указанную в файле проекта. Обычно это конфигурация Debug. Чтобы упаковать файлы из другой конфигурации сборки, например Release, используйте параметр , указав конфигурацию:
Символы. Чтобы включить символы, позволяющие пользователям осуществлять пошаговое выполнение кода в пакете, используйте параметр :
Тестирование установки пакета
Перед публикацией пакета, как правило, необходимо протестировать процесс его установки в проекте. Это позволяет убедиться в том, что все необходимые файлы помещаются в нужные места.
Установку можно протестировать вручную в Visual Studio или в командной строке, выполнив стандартную процедуру установки пакета.
Для автоматического тестирования выполните указанные ниже основные действия.
- Скопируйте файл .nupkg в локальную папку.
- Добавьте эту папку в источники пакета с помощью команды nuget sources add -name -source (см. описание nuget sources add -name -source ). Обратите внимание на то, что на каждом компьютере этот локальный источник необходимо задать только один раз.
- Установите пакет из источника с помощью команды nuget install -source , где соответствует имени источника, предоставленному команде nuget sources . Указание источника позволяет гарантировать, что пакет будет устанавливаться только из него.
- В файловой системе проверьте, правильно ли установились файлы.
Следующие шаги
Создав пакет, то есть файл .nupkg , вы можете опубликовать его в любой коллекции на ваш выбор, как описано в разделе .nupkg .
Вы также можете расширить возможности пакета или обеспечить поддержку других сценариев, как описано в следующих разделах:
If you are using Visual Studio for Mac, refer to this information on creating a NuGet package, or use the dotnet CLI tools.
Prerequisites
If it's not already installed, install the dotnet CLI.
Create a class library project
Right-click on the resulting project file and select Build to make sure the project was created properly. The DLL is found within the Debug folder (or Release if you build that configuration instead).
Within a real NuGet package, of course, you implement many useful features with which others can build applications. For this walkthrough, however, you won't write any additional code because a class library from the template is sufficient to create a package. Still, if you'd like some functional code for the package, use the following:
Configure package properties
Right-click the project in Solution Explorer, and choose Properties menu command, then select the Package tab.
For packages built for public consumption, pay special attention to the Tags property, as tags help others find your package and understand what it does.
Give your package a unique identifier and fill out any other desired properties. For a mapping of MSBuild properties (SDK-style project) to properties in a .nuspec, see pack targets. For descriptions of properties, see the .nuspec file reference. All of the properties here go into the .nuspec manifest that Visual Studio creates for the project.
You must give the package an identifier that's unique across nuget.org or whatever host you're using. For this walkthrough we recommend including "Sample" or "Test" in the name as the later publishing step does make the package publicly visible (though it's unlikely anyone will actually use it).
If you attempt to publish a package with a name that already exists, you see an error.
(Optional) To see the properties directly in the project file, right-click the project in Solution Explorer and select Edit AppLogger.csproj.
This option is only available starting in Visual Studio 2017 for projects that use the SDK-style attribute. Otherwise, right-click the project and choose Unload Project. Then right-click the unloaded project and choose Edit AppLogger.csproj.
Run the pack command
Set the configuration to Release.
Right click the project in Solution Explorer and select the Pack command:
(Optional) Generate package on build
You can configure Visual Studio to automatically generate the NuGet package when you build the project.
In Solution Explorer, right-click the project and choose Properties.
In the Package tab, select Generate NuGet package on build.
When you automatically generate the package, the time to pack increases the build time for your project.
(Optional) pack with MSBuild
As an alternate to using the Pack menu command, NuGet 4.x+ and MSBuild 15.1+ supports a pack target when the project contains the necessary package data. Open a command prompt, navigate to your project folder and run the following command. (You typically want to start the "Developer Command Prompt for Visual Studio" from the Start menu, as it will be configured with all the necessary paths for MSBuild.)
Publish the package
Acquire your API key
For more information on creating your account, see Individual accounts.
Select your user name (on the upper right), then select API Keys.
Select Create, provide a name for your key, select Select Scopes > Push. Enter * for Glob pattern, then select Create. (See below for more about scopes.)
Once the key is created, select Copy to retrieve the access key you need in the CLI:
Always keep your API key a secret! Treat your API key as a password that allows anyone to manage packages on your behalf. You should delete or regenerate your API key if it is accidentally revealed.
Save your key in a secure location because you cannot copy the key again later on. If you return to the API key page, you need to regenerate the key to copy it. You can also remove the API key if you no longer want to push packages.
Scoping allows you to create separate API keys for different purposes. Each key has its expiration timeframe and can be scoped to specific packages (or glob patterns). Each key is also scoped to specific operations: push of new packages and updates, push of updates only, or delisting. Through scoping, you can create API keys for different people who manage packages for your organization such that they have only the permissions they need. For more information, see scoped API keys.
Publish with the dotnet CLI or nuget.exe CLI
This step is the recommended alternative to using nuget.exe .
Before you can publish the package, you must first open a command line.
Change to the folder containing the .nupkg file.
Run the following command, specifying your package name (unique package ID) and replacing the key value with your API key:
dotnet displays the results of the publishing process:
This step is an alternative to using dotnet.exe .
Open a command line and change to the folder containing the .nupkg file.
Run the following command, specifying your package name (unique package ID) and replacing the key value with your API key:
nuget.exe displays the results of the publishing process:
Publish errors
Errors from the push command typically indicate the problem. For example, you may have forgotten to update the version number in your project and are therefore trying to publish a package that already exists.
You also see errors when trying to publish a package using an identifier that already exists on the host. The name "AppLogger", for example, already exists. In such a case, the push command gives the following error:
If you're using a valid API key that you just created, then this message indicates a naming conflict, which isn't entirely clear from the "permission" part of the error. Change the package identifier, rebuild the project, recreate the .nupkg file, and retry the push command.
Manage the published package
If in this walkthrough you created a package that isn't actually useful (such as a package created with an empty class library), you should unlist the package to hide it from search results:
Locate the package you want to unlist under Published and select the trash can icon on the right:
On the subsequent page, clear the box labeled List (package-name) in search results and select Save:
Adding a readme and other files
To directly specify files to include in the package, edit the project file and use the content property:
This will include a file named readme.txt in the package root. Visual Studio displays the contents of that file as plain text immediately after installing the package directly. (Readme files are not displayed for packages installed as dependencies). For example, here's how the readme for the HtmlAgilityPack package appears:
Merely adding the readme.txt at the project root will not result in it being included in the resulting package.
Это краткое руководство относится только к Visual Studio 2017 для Windows и более поздним версиям. Visual Studio для Mac не поддерживает описанные здесь функции. Используйте вместо этого средства интерфейса командной строки dotnet.
Предварительные требования
Установите интерфейс командной строки nuget.exe , скачав его на сайте nuget.exe , и сохраните этот файл .exe в подходящую папку. Добавьте эту папку в переменную среды PATH.
Создание проекта библиотеки классов
В Visual Studio выберите Файл Создать > Проект, разверните узел >, выберите шаблон "Библиотека классов (.NET Framework)", присвойте проекту имя AppLogger и нажмите кнопку ОК.
Щелкните правой кнопкой мыши полученный файл проекта и выберите пункт Сборка, чтобы убедиться, что проект создан правильно. Библиотека DLL находится в папке Debug (или папке Release, если вы используете конфигурацию выпуска для сборки).
Однако в этом пошаговом руководстве вы не будете писать дополнительный код, так как библиотеки классов из шаблона достаточно для создания пакета. Тем не менее, вы можете использовать функциональный код для пакета:
Настройка свойств проекта для пакета
Пакет NuGet содержит манифест (файл .nuspec ) с соответствующими метаданными, такими как идентификатор пакета, номер версии, описание и многое другое. Некоторые из них могут поступать напрямую из свойств проекта, в результате чего исчезает необходимость изменять их как в проекте, так и в манифесте. Этот раздел описывает, где можно задать соответствующие свойства.
Выберите команду меню Проект Свойства, а затем щелкните вкладку Приложение.
В поле Имя сборки укажите уникальный идентификатор пакета.
Необходимо присвоить пакету идентификатор, который будет уникальным на сайте nuget.org или другом используемом узле. При работе с этим руководством мы рекомендуем добавить к имени слово "Sample" или "Test", так как позже, после публикации, пакет станет общедоступным (хотя маловероятно, что кто-то будет его использовать).
Необязательно. Чтобы просмотреть или изменить свойства напрямую, откройте файл Properties/AssemblyInfo.cs в проекте.
Задав свойства, укажите для конфигурацию проекта значение Выпуск и перестройте проект для создания обновленной библиотеки DLL.
Создание начального манифеста
Получив библиотеку DLL и задав свойства проекта, вы можете использовать команду nuget spec , чтобы создать начальный файл .nuspec из проекта. Этот шаг включает в себя соответствующие токены замены для получения сведений из файла проекта.
Запускать nuget spec для создания начального манифеста потребуется всего один раз. При обновлении пакета нужно либо изменить значения в проекте, либо отредактировать сам файл манифеста.
Откройте командную строку и перейдите в папку проекта, содержащую файл AppLogger.csproj .
Выполните следующую команду: nuget spec AppLogger.csproj . После указания проекта NuGet создает манифест с тем же именем, что и проект, в данном случае это AppLogger.nuspec . Он также включает в себя токены замены из манифеста.
Откройте файл AppLogger.nuspec в текстовом редакторе для просмотра его содержимого, которое должно иметь следующий вид.
Изменение манифеста
NuGet выдает ошибку при попытке создать пакет со значениями по умолчанию в вашем файле .nuspec , поэтому перед продолжением нужно изменить следующие поля. Их использование описано в разделе о необязательных элементах метаданных в справочнике по файлу NUSPEC.
- licenseUrl
- projectUrl
- iconUrl
- releaseNotes
- tags
Кроме того, сейчас можно добавить в манифест любые другие элементы, как описано в разделе Справочник по файлу NUSPEC.
Сохраните файл, прежде чем продолжить.
Выполнение команды pack
Из командной строки перейдите в папку, содержащую файл .nuspec , и выполните команду nuget pack .
NuGet создает в текущей папке файл .nupkg формата .nupkg .
Публикация пакета
Получение ключа API
Выберите свое имя пользователя (в правом верхнем углу), а затем щелкните Ключи API.
После создания ключа выберите Копировать для получения ключа доступа, который требуется в интерфейсе командной строки:
Всегда держите свой ключ API в секрете! Рассматривайте свой ключ API как пароль, позволяющий любому пользователю управлять пакетами от вашего имени. Вам следует удалить или повторно создать свой ключ API, если он был случайно раскрыт.
Сохраните ключ в безопасном расположении, так как у вас больше не будет возможности скопировать ключ. Если вы вернетесь на страницу ключа API, вам понадобится повторно создать ключ, чтобы скопировать его. Кроме того, вы можете удалить ключ API, если больше не хотите отправлять пакеты.
Определение области позволяет создавать отдельные ключи API для разных целей. Ключи имеют срок действия. Кроме того, их можно привязать к определенным пакетам (или стандартным маскам). Каждый ключ также привязан к конкретным операциям: отправка новых пакетов и обновлений, отправка только обновлений или удаление из списка. Используя определение области, вы можете создавать ключи API разным пользователям, которые управляют пакетами организации. Это позволит предоставлять им только нужные разрешения. См. подробнее о ключах API в определении области.
Публикация с помощью команды nuget push
Откройте командную строку и перейдите к папке с файлом .nupkg .
Выполните следующую команду, указав имя пакета и заменив значение ключа на ключ API:
nuget.exe отображает результаты публикации:
Ознакомьтесь со сведениями о команде nuget push.
Ошибки публикации
Ошибки в результатах выполнения команды push обычно указывают на неполадку. Например, вы забыли обновить номер версии проекта и пытаетесь опубликовать пакет, который уже существует.
Ошибки также возникают при попытке опубликовать пакет с использованием идентификатора, который уже имеется на узле. Например, имя AppLogger уже существует. В этом случае команда push выдает следующую ошибку:
Управление опубликованным пакетом
Если при работе с этим пошаговым руководством был создан пакет, который не представляет пользы (например, пакет, созданный с использованием пустой библиотеки классов), следует исключить его из списка, чтобы он не отображался в результатах поиска:
Найдите пакет, который требуется исключить из списка, в разделе Published (Опубликованное) и щелкните значок корзины справа:
На следующей странице снимите флажок List (package-name) in search results (Вывести (имя пакета) в результатах поиска) и щелкните Save (Сохранить).
Читайте также: