Επεξεργασία

Κοινή χρήση μέσω

Quickstart: Create and publish a NuGet package using Visual Studio (Windows only)

  • Άρθρο

With Microsoft Visual Studio, you can create a NuGet package from a .NET class library, and then publish it to nuget.org using a CLI tool.

The quickstart is for Windows users only. If you're using Visual Studio for Mac, see Create a NuGet package from existing library projects or use the .NET CLI.

Prerequisites

  • Install Visual Studio 2022 for Windows with a .NET Core-related workload.

    You can install the 2022 Community edition for free from visualstudio.microsoft.com, or use the Professional or Enterprise edition.

    Visual Studio 2017 and later automatically includes NuGet capabilities when you install a .NET-related workload.

  • Install the .NET CLI, if it's not already installed.

    For Visual Studio 2017 and later, the .NET CLI is automatically installed with any .NET Core-related workload. Otherwise, install the .NET Core SDK to get the .NET CLI. The .NET CLI is required for .NET projects that use the SDK-style format (SDK attribute). The default .NET class library template in Visual Studio 2017 and later uses the SDK attribute.

    Important

    If you're working with a non-SDK-style project, follow the procedures in Create and publish a .NET Framework package (Visual Studio) instead to create and publish the package. For this article, the .NET CLI is recommended. Although you can publish any NuGet package using the NuGet CLI, some of the steps in this article are specific to SDK-style projects and the .NET CLI. The NuGet CLI is used for non-SDK-style projects (typically .NET Framework).

  • Register for a free account on nuget.org if you don't have one already. You must register and confirm the account before you can upload a NuGet package.

  • Install the NuGet CLI by downloading it from nuget.org. Add the nuget.exe file to a suitable folder, and add that folder to your PATH environment variable.

Create a class library project

You can use an existing .NET Class Library project for the code you want to package, or create one as follows:

  1. In Visual Studio, select File > New > Project.

  2. In the Create a new project window, select C#, Windows, and Library in the dropdown lists.

  3. In the resulting list of project templates, select Class Library (with the description, A project for creating a class library that targets .NET or .NET Standard), and then select Next.

  4. In the Configure your new project window, enter AppLogger for the Project name, and then select Next.

  5. In the Additional information window, select an appropriate Framework, and then select Create.

    If you're unsure which framework to select, the latest is a good choice, and can be easily changed later. For information about which framework to use, see When to target .NET 5.0 or .NET 6.0 vs. .NET Standard.

  6. To ensure the project was created properly, select Build > Build Solution. The DLL is found within the Debug folder (or Release if you build that configuration instead).

  7. (Optional) For this quickstart, you don't need to write any additional code for the NuGet package because the template class library is sufficient to create a package. However, if you'd like some functional code for the package, include the following code:

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

Configure package properties

After you've created your project, you can configure the NuGet package properties by following these steps:

  1. Select your project in Solution Explorer, and then select Project > <project name> Properties, where <project name> is the name of your project.

  2. Expand the Package node, and then select General.

    The Package node appears only for SDK-style projects in Visual Studio. If you're' targeting a non-SDK style project (typically .NET Framework), either migrate the project, or see Create and publish a .NET Framework package for step-by-step instructions.

    Screenshot showing NuGet package properties in a Visual Studio project.

  3. 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.

  4. Give your package a unique Package ID and fill out any other desired properties. For a table that shows how MSBuild properties (SDK-style projects) map to .nuspec file properties, see pack targets. For a description of .nuspec file properties, see the .nuspec file reference. All of these properties 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. Otherwise, an error occurs. For this quickstart we recommend including Sample or Test in the name because the publishing step makes the package publicly visible.

  5. (Optional) To see the properties directly in the AppLogger.csproj project file, select Project > Edit Project File.

    The AppLogger.csproj tab loads.

    This option is available starting in Visual Studio 2017 for projects that use the SDK-style attribute. For earlier Visual Studio versions, you must select Project > Unload Project before you can edit the project file.

Run the pack command

To create a NuGet package from your project, follow these steps:

  1. Select Build > Configuration Manager, and then set the Active solution configuration to Release.

  2. Select the AppLogger project in Solution Explorer, then select Pack.

    Visual Studio builds the project and creates the .nupkg file.

  3. Examine the Output window for details, which contains the path to the package file. In this example, the built assembly is in bin\Release\net6.0 as befits a .NET 6.0 target:

    1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------
1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\net6.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 ==========

  4. If you don't see the Pack command on the menu, your project is probably not an SDK-style project, and you need to use the NuGet CLI. Either migrate the project and use .NET CLI, or see Create and publish a .NET Framework package for step-by-step instructions.

(Optional) Generate package on build

You can configure Visual Studio to automatically generate the NuGet package when you build the project:

  1. Select your project in Solution Explorer, and then select Project > <project name> Properties, where <project name> is the name of your project (AppLogger in this case).

  2. Expand the Package node, select General, and then select Generate NuGet package on build.

    Screenshot showing package properties with Generate NuGet package on build selected.

Note

When you automatically generate the package, the extra time to pack increases the overall build time for your project.

(Optional) Pack with MSBuild

As an alternative 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:

  1. With your project open in Solution Explorer, open a command prompt by selecting Tools > Command Line > Developer Command Prompt.

    The command prompt opens in your project directory.

  2. Run the following command: msbuild -t:pack.

For more information, see Create a package using MSBuild.

Publish the package

After you've created a .nupkg file, publish it to nuget.org by using either the .NET CLI or the NuGet CLI, along with an API key acquired from nuget.org.

Note

  • Nuget.org scans all uploaded packages for viruses and rejects the packages if it finds any viruses. Nuget.org also scans all existing listed packages periodically.

  • Packages you publish to nuget.org are publicly visible to other developers unless you unlist them. To host packages privately, see Host your own NuGet feeds.

Acquire your API key

Before you publish your NuGet package, create an API key:

  1. Sign into your nuget.org account or create an account if you don't have one already.

  2. Select your user name at upper right, and then select API Keys.

  3. Select Create, and provide a name for your key.

  4. Under Select Scopes, select Push.

  5. Under Select Packages > Glob Pattern, enter *.

  6. Select Create.

  7. Select Copy to copy the new key.

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

Important

  • Always keep your API key a secret. The API key is like a password that allows anyone to manage packages on your behalf. Delete or regenerate your API key if it's accidentally revealed.
  • Save your key in a secure location, because you can't copy the key again later. 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 lets you create separate API keys for different purposes. Each key has an expiration timeframe, and you can scope the key to specific packages or glob patterns. You also scope each key to specific operations: Push new packages and package versions, push only new package versions, or unlist.

Through scoping, you can create API keys for different people who manage packages for your organization so they have only the permissions they need.

For more information, see scoped API keys.

Publish with the .NET CLI or NuGet CLI

Each of the following CLI tools allows you to push a package to the server and publish it. Select the tab for your CLI tool, either .NET CLI or NuGet CLI.

Using the .NET CLI (dotnet.exe) is the recommended alternative to using the NuGet CLI.

From the folder that contains the .nupkg file, run the following command. Specify your .nupkg filename, and replace the key value with your API key.

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

The output shows the results of the publishing process:

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.

For more information, see dotnet nuget push.

Note

If you want to avoid your test package being live on nuget.org, you can push to the nuget.org test site at https://int.nugettest.org. Note that packages uploaded to int.nugettest.org might not be preserved.

Publish errors

Errors from the push command typically indicate the problem. For example, you might have forgotten to update the version number in your project, so you're trying to publish a package that already exists.

You also see errors if your API key is invalid or expired, or if you try to publish a package using an identifier that already exists on the host. Suppose, for example, the identifier AppLogger-test already exists on nuget.org. If you try to publish a package with that identifier, 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.).

If you get this error, check that you're using a valid API key that hasn't expired. If you are, the error indicates the package identifier already exists on the host. To fix the error, change the package identifier to be unique, rebuild the project, recreate the .nupkg file, and retry the push command.

Manage the published package

When your package successfully publishes, you receive a confirmation email. To see the package you just published, on nuget.org, select your user name at upper right, and then select Manage Packages.

Note

It might take awhile for your package to be indexed and appear in search results where others can find it. During that time, your package appears under Unlisted Packages, and the package page shows the following message:

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

You've now published a NuGet package to nuget.org that other developers can use in their projects.

If you've created a package that isn't useful (such as this sample package that was created with an empty class library), or you decide you don't want the package to be visible, you can unlist the package to hide it from search results:

  1. After the package appears under Published Packages on the Manage Packages page, select the pencil icon next to the package listing.

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

  2. On the next page, select Listing, deselect the List in search results checkbox, and then select Save.

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

The package now appears under Unlisted Packages in Manage Packages and no longer appears in search results.

Note

To avoid your test package being live on nuget.org, you can push to the nuget.org test site at https://int.nugettest.org. Note that packages uploaded to int.nugettest.org might not be preserved.

Add a readme or another file

To directly specify files to include in the package, edit the project file and add the content property:

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

In this example, the property specifies a file named readme.txt in the project root. Visual Studio displays the contents of that file as plain text immediately after it installs the package. Readme files aren't displayed for packages installed as dependencies. For example, here's the readme for the HtmlAgilityPack package:

1 ----------------------------------------------------
2 ---------- Html Agility Pack Nuget Readme ----------
3 ----------------------------------------------------
4
5 ----Silverlight 4 and Windows Phone 7.1+ projects-----
6 To use XPATH features: System.Xml.Xpath.dll from the 3 Silverlight 4 SDK must be referenced. 
7 This is normally found at 
8 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client 
9 or 
10 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client
11
12 ----Silverlight 5 projects-----
13 To use XPATH features: System.Xml.Xpath.dll from the Silverlight 5 SDK must be referenced. 
14 This is normally found at 
15 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client 
16 or 
17 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client

Note

If you only add readme.txt at the project root without including it in the content property of the project file, it won't be included in the package.

Find more NuGet videos on Channel 9 and YouTube.

Congratulations on creating a NuGet package by using a Visual Studio .NET class library. Advance to the next article to learn how to create a NuGet package with the Visual Studio .NET Framework.

Create a package using the NuGet CLI

To explore more that NuGet has to offer, see the following articles: