Краткое руководство. Создание и публикация пакета NuGet с помощью Visual Studio (.NET Standard, только для Windows)Quickstart: Create and publish a NuGet package using Visual Studio (.NET Standard, Windows only)

Создание пакета NuGet из библиотеки классов .NET Standard в Visual Studio в Windows и его публикация на сайте nuget.org с помощью средства интерфейса командной строки выполняются очень просто.It's a simple process to create a NuGet package from a .NET Standard Class Library in Visual Studio on Windows, and then publish it to nuget.org using a CLI tool.

Примечание

Если вы используете Visual Studio для Mac, ознакомьтесь с этими сведениями о создании пакета NuGet или примените средства CLI dotnet.If you are using Visual Studio for Mac, refer to this information on creating a NuGet package, or use the dotnet CLI tools.

предварительные требованияPrerequisites

  1. Установите любой выпуск Visual Studio 2019 со страницы visualstudio.com с помощью рабочей нагрузки, связанной с .NET Core.Install any edition of Visual Studio 2019 from visualstudio.com with a .NET Core related workload.

  2. При необходимости установите CLI dotnet.If it's not already installed, install the dotnet CLI.

    Для CLI dotnet начиная с версии Visual Studio 2017 CLI dotnet автоматически устанавливается вместе с любыми рабочими нагрузками, связанными с .NET Core.For the dotnet CLI, starting in Visual Studio 2017, the dotnet CLI is automatically installed with any .NET Core related workloads. При использовании другой версии установите пакет SDK для .NET Core, чтобы получить CLI dotnet.Otherwise, install the .NET Core SDK to get the dotnet CLI. CLI dotnet является обязательным для проектов .NET Standard с форматом в стиле пакета SDK (атрибут SDK).The dotnet CLI is required for .NET Standard projects that use the SDK-style format (SDK attribute). Шаблон библиотеки классов .NET Standard по умолчанию в Visual Studio 2017 и более поздних версий, который применяется в рамках этой статьи, использует атрибут пакета SDK.The default .NET Standard class library template in Visual Studio 2017 and higher, which is used in this article, uses the SDK attribute.

    Важно!

    Если вы работаете с проектом не в стиле SDK, выполните инструкции по созданию и публикации пакета .NET Framework (Visual Studio).If you are working with a non-SDK-style project, follow the procedures in Create and publish a .NET Framework package (Visual Studio) to create and publish the package instead. В рамках этой статьи рекомендуем использовать CLI dotnet.For this article, the dotnet CLI is recommended. Любой пакет NuGet можно опубликовать с помощью CLI nuget.exe. Но некоторые действия, описанные в этой статье, относятся к проектам в стиле пакета SDK и CLI dotnet.Although you can publish any NuGet package using the nuget.exe CLI, some of the steps in this article are specific to SDK-style projects and the dotnet CLI. CLI nuget.exe используется для проектов не в стиле пакета SDK (в основном для проектов .NET Framework).The nuget.exe CLI is used for non-SDK-style projects (typically .NET Framework).

  3. Зарегистрируйтесь для получения бесплатной учетной записи на nuget.org, если вы не сделали этого ранее.Register for a free account on nuget.org if you don't have one already. При создании учетной записи вам направляется сообщение электронной почты с подтверждением.Creating a new account sends a confirmation email. Перед отправкой пакета вам нужно подтвердить учетную запись.You must confirm the account before you can upload a package.

Создание проекта библиотеки классовCreate a class library project

Вы можете использовать имеющийся проект библиотеки классов .NET Standard для кода, который нужно упаковать, или же создать простой проект, как показано ниже.You can use an existing .NET Standard Class Library project for the code you want to package, or create a simple one as follows:

  1. В Visual Studio выберите Файл > Создать > Проект, разверните узел Visual C# > .NET Standard, выберите шаблон "Библиотека классов (.NET Standard)", назовите проект AppLogger и нажмите кнопку ОК.In Visual Studio, choose File > New > Project, expand the Visual C# > .NET Standard node, select the "Class Library (.NET Standard)" template, name the project AppLogger, and click OK.

    Совет

    Для пакетов NuGet мы рекомендуем использовать целевой объект .NET Standard (если нет причин использовать другое), так как он обеспечивает совместимость с рядом потребляющих проектов.Unless you have a reason to choose otherwise, .NET Standard is the preferred target for NuGet packages, as it provides compatibility with the widest range of consuming projects.

  2. Щелкните правой кнопкой мыши полученный файл проекта и выберите пункт Сборка, чтобы убедиться, что проект создан правильно.Right-click on the resulting project file and select Build to make sure the project was created properly. Библиотека DLL находится в папке Debug (или папке Release, если вы используете конфигурацию выпуска для сборки).The DLL is found within the Debug folder (or Release if you build that configuration instead).

В реальном пакете NuGet вы можете реализовать множество полезных возможностей, с помощью которых другие пользователи могут создавать приложения.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:

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

Настройка свойств пакетаConfigure package properties

  1. Щелкните правой кнопкой мыши проект в обозреватель решений и выберите команду меню Свойства, а затем выберите вкладку Пакет.Right-click the project in Solution Explorer, and choose Properties menu command, then select the Package tab.

    Вкладка Пакет отображается только для проектов в стиле SDK в Visual Studio, в основном для проектов .NET Standard или библиотеки классов .NET Core. Если вы используете проект не в стиле SDK (например, проект .NET Framework), перенесите проект или ознакомьтесь с пошаговыми инструкциями по созданию и публикации пакета .NET Framework.The Package tab appears only for SDK-style projects in Visual Studio, typically .NET Standard or .NET Core class library projects; if you are targeting a non-SDK style project (typically .NET Framework), either migrate the project or see Create and publish a .NET Framework package instead for step-by-step instructions.

    Свойства пакета NuGet в проекте Visual Studio

    Примечание

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

  2. Присвойте пакету уникальный идентификатор и заполните нужные свойства.Give your package a unique identifier and fill out any other desired properties. Сведения о сопоставлении свойств MSBuild (проект в стиле SDK) со свойствами в NUSPEC-файле см. в разделе о целевых объектах пакета.For a mapping of MSBuild properties (SDK-style project) to properties in a .nuspec, see pack targets. Описание свойств см. в справочнике по NUSPEC-файлу.For descriptions of properties, see the .nuspec file reference. Все свойства добавляются в манифест .nuspec, который Visual Studio создает для проекта.All of the properties here go into the .nuspec manifest that Visual Studio creates for the project.

    Важно!

    Необходимо присвоить пакету идентификатор, который будет уникальным на сайте nuget.org или другом используемом узле.You must give the package an identifier that's unique across nuget.org or whatever host you're using. При работе с этим руководством мы рекомендуем добавить к имени слово "Sample" или "Test", так как позже, после публикации, пакет станет общедоступным (хотя маловероятно, что кто-то будет его использовать).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.

  3. Необязательно. Чтобы просматривать свойства непосредственно в файле проекта, щелкните правой кнопкой мыши проект в обозревателе решений и выберите Edit AppLogger.csproj (Изменить AppLogger.csproj).(Optional) To see the properties directly in the project file, right-click the project in Solution Explorer and select Edit AppLogger.csproj.

    Этот параметр доступен для проектов, использующих атрибут стиля пакета SDK, только в версиях начиная с Visual Studio 2017.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. Затем щелкните правой кнопкой мыши выгруженный проект и выберите команду изменения AppLogger.csproj.Then right-click the unloaded project and choose Edit AppLogger.csproj.

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

  1. Выберите конфигурацию Выпуск.Set the configuration to Release.

  2. Щелкните проект правой кнопкой мыши в окне обозревателя решений и выберите команду Паковать:Right click the project in Solution Explorer and select the Pack command:

    Команда "Паковать" для NuGet в контекстном меню проекта Visual Studio

    Если команда Pack не отображается, проект, скорее всего, не разработан в стиле SDK. В таком случае нужно использовать CLI nuget.exe.If you don't see the Pack command, your project is probably not an SDK-style project and you need to use the nuget.exe CLI. Перенесите проект и используйте CLI dotnet, или ознакомьтесь с пошаговыми инструкциями по созданию и публикации пакета .NET Framework.Either migrate the project and use dotnet CLI, or see Create and publish a .NET Framework package instead for step-by-step instructions.

  3. Visual Studio создаст проект и файл .nupkg.Visual Studio builds the project and creates the .nupkg file. Ознакомьтесь с результатами в окне выходных данных (пример приведен ниже), где содержится путь к файлу пакета.Examine the Output window for details (similar to the following), which contains the path to the package file. Обратите внимание, что созданная сборка находится в папке bin\Release\netstandard2.0, которая является целевой для .NET Standard 2.0.Note also that the built assembly is in bin\Release\netstandard2.0 as befits the .NET Standard 2.0 target.

    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

Вы можете настроить в Visual Studio автоматическое создание пакета NuGet при сборке проекта.You can configure Visual Studio to automatically generate the NuGet package when you build the project.

  1. В обозревателе решений щелкните правой кнопкой мыши проект и выберите пункт Свойства.In Solution Explorer, right-click the project and choose Properties.

  2. На вкладке Пакет выберите Создать пакет NuGet при сборке.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.

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

В качестве альтернативы команде меню Pack в NuGet 4.x+ и MSBuild 15.1+ можно использовать целевой объект pack, когда проект содержит необходимые данные о пакете.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. (В общем случае следует запустить Командную строку разработчика для Visual Studio из меню "Пуск", так как в этом случае настраиваются все необходимые пути для MSBuild.)(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.)

Дополнительные сведения см. в разделе Создание пакета с помощью MSBuild.For more information, see Create a package using MSBuild.

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

Получив файл .nupkg, опубликуйте его на сайте nuget.org, используя интерфейс командной строки nuget.exe или dotnet.exe, а также ключ API, полученный на этом сайте.Once you have a .nupkg file, you publish it to nuget.org using either the nuget.exe CLI or the dotnet.exe CLI along with an API key acquired from nuget.org.

Примечание

Проверка на вирусы: перед публикацией все пакеты, загружаемые на веб-сайт nuget.org, проверяются на вирусы, и в случае обнаружения вирусов отклоняются.Virus scanning: All packages uploaded to nuget.org are scanned for viruses and rejected if any viruses are found. Кроме того, периодическую проверку проходят все пакеты, представленные на веб-сайте nuget.org.All packages listed on nuget.org are also scanned periodically.

Пакеты, опубликованные на сайте nuget.org, доступны и для других разработчиков (пока вы не исключите их из списка).Packages published to nuget.org are also publicly visible to other developers unless you unlist them. Чтобы разместить пакеты частным образом, см. раздел Размещение пакетов.To host packages privately, see Hosting packages.

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

  1. Войдите в учетную запись nuget.org или создайте учетную запись (если ее еще нет).Sign into your nuget.org account or create an account if you don't have one already.

    См. подробнее о создании индивидуальной учетной записи.For more information on creating your account, see Individual accounts.

  2. Выберите свое имя пользователя (в правом верхнем углу), а затем щелкните Ключи API.Select your user name (on the upper right), then select API Keys.

  3. Щелкните Create (Создать), введите имя ключа, а затем выберите Select Scopes (Выбрать области) > Push (Отправить) .Select Create, provide a name for your key, select Select Scopes > Push. Введите * в поле Glob pattern (Стандартная маска), а затем выберите Create (Создать).Enter * for Glob pattern, then select Create. (Дополнительные сведения об областях см. ниже.)(See below for more about scopes.)

  4. После создания ключа выберите Копировать для получения ключа доступа, который требуется в интерфейсе командной строки:Once the key is created, select Copy to retrieve the access key you need in the CLI:

    Копирование ключа API в буфер обмена

  5. Важно. Сохраните ключ в безопасном расположении, так как позже вы не сможете скопировать его.Important: Save your key in a secure location because you cannot copy the key again later on. Если вы вернетесь на страницу ключа API, вам понадобится повторно создать ключ, чтобы скопировать его.If you return to the API key page, you need to regenerate the key to copy it. Вы также можете удалить ключ API, если больше не хотите отправлять пакеты через интерфейс командной строки.You can also remove the API key if you no longer want to push packages via the CLI.

Определение области позволяет создавать отдельные ключи API для разных целей.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. Используя определение области, вы можете создавать ключи API разным пользователям, которые управляют пакетами организации. Это позволит предоставлять им только нужные разрешения.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. См. подробнее о ключах API в определении области.For more information, see scoped API keys.

Публикация с помощью CLI dotnet или CLI nuget.exePublish with the dotnet CLI or nuget.exe CLI

Выберите вкладку для своего инструмента CLI: .NET Core CLI (для CLI dotnet) или NuGet (для CLI nuget.exe).Select the tab for your CLI tool, either .NET Core CLI (dotnet CLI) or NuGet (nuget.exe CLI).

Этот шаг — рекомендуемая альтернатива использования nuget.exe.This step is the recommended alternative to using nuget.exe.

Перед публикацией пакета сначала нужно открыть командную строку.Before you can publish the package, you must first open a command line.

  1. Перейдите в папку, содержащую файл .nupkg.Change to the folder containing the .nupkg file.

  2. Выполните следующую команду, указав имя пакета (уникальный идентификатор пакета) и заменив значение ключа ключом API:Run the following command, specifying your package name (unique package ID) and replacing the key value with your API key:

    dotnet nuget push AppLogger.1.0.0.nupkg --api-key qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 --source https://api.nuget.org/v3/index.json
    
  3. dotnet отображает результаты публикации:dotnet displays the results of the publishing process:

    info : Pushing AppLogger.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
    info :   PUT https://www.nuget.org/api/v2/package/
    info :   Created https://www.nuget.org/api/v2/package/ 12620ms
    info : Your package was pushed.
    

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

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

Ошибки в результатах выполнения команды push обычно указывают на неполадку.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. Например, имя AppLogger уже существует.The name "AppLogger", for example, already exists. В этом случае команда push выдает следующую ошибку:In such a case, the push command gives the following error:

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, это сообщение означает, что возник конфликт имен, что не совсем понятно из части касательно разрешения в ошибке.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. Измените идентификатор пакета, перестройте проект, повторно создайте файл .nupkg, а затем повторите команду push.Change the package identifier, rebuild the project, recreate the .nupkg file, and retry the push command.

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

В своем профиле на сайте nuget.org выберите Manage Packages (Управление пакетами), чтобы просмотреть опубликованный вами пакет.From your profile on nuget.org, select Manage Packages to see the one you just published. Вы также получите подтверждение по электронной почте.You also receive a confirmation email. Обратите внимание, что пакет индексируется и будет появляться в результатах поиска для других пользователей спустя определенное время.Note that it might take a while for your package to be indexed and appear in search results where others can find it. В этот период на странице вашего пакета отображается следующее сообщение:During that time your package page shows the message below:

This package has not been indexed yet.

Вот и все!And that's it! Вы только что опубликовали на сайте nuget.org свой первый пакет NuGet, который другие разработчики могут использовать в своих собственных проектах.You've just published your first NuGet package to nuget.org that other developers can use in their own projects.

Если при работе с этим пошаговым руководством был создан пакет, который не представляет пользы (например, пакет, созданный с использованием пустой библиотеки классов), следует исключить его из списка, чтобы он не отображался в результатах поиска: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:

  1. На сайте nuget.org выберите имя пользователя (в верхнем правом углу страницы), а затем Manage Packages (Управление пакетами).On nuget.org, select your user name (upper right of the page), then select Manage Packages.

  2. Найдите пакет, который требуется исключить из списка, в разделе Published (Опубликованное) и щелкните значок корзины справа:Locate the package you want to unlist under Published and select the trash can icon on the right:

    Значок корзины, отображаемый в списке пакетов на сайте nuget.org

  3. На следующей странице снимите флажок List (package-name) in search results (Вывести (имя пакета) в результатах поиска) и щелкните Save (Сохранить).On the subsequent page, clear the box labeled List (package-name) in search results and select Save:

    Снятие флажка List (Вывести) для пакета на сайте nuget.org

Добавление файла сведений и других файловAdding a readme and other files

Чтобы напрямую указать файлы, включаемые в пакет, измените файл проекта и используйте свойство content:To directly specify files to include in the package, edit the project file and use the content property:

<ItemGroup>
  <Content Include="readme.txt">
    <Pack>true</Pack>
    <PackagePath>\</PackagePath>
  </Content>
</ItemGroup>

В корень пакета будет включен файл с именем readme.txt.This will include a file named readme.txt in the package root. Visual Studio отображает содержимое этого файла в виде обычного текста сразу после установки пакета напрямую.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). Например, вот как выглядит файл сведений для пакета HtmlAgilityPack:For example, here's how the readme for the HtmlAgilityPack package appears:

Отображение файла сведений для пакета NuGet при установке

Примечание

Обычное добавление файла readme.txt в корень проекта не приведет к включению его в итоговый пакет.Merely adding the readme.txt at the project root will not result in it being included in the resulting package.

Другие видео о NuGet см. на Channel 9 и YouTube.Find more NuGet videos on Channel 9 and YouTube.