Quickstart: Create and publish a package using Visual Studio (.NET Framework, Windows)

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

The quickstart is for Windows users only. If you're using Visual Studio for Mac, see dotnet CLI tools instead.

Prerequisites

• Install Visual Studio 2022 for Windows with any .NET-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 higher automatically includes NuGet capabilities when a .NET workload is installed.

• 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

To create a class library project, follow these steps:

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 (.NET Framework), and then select Next.

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

5. 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).

6. (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 this sample package, include the following code:

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

   Within a real-world NuGet package, you'd likely implement many useful features with which others can build applications. You can also set the target frameworks. For an example, see UWP.

Configure project properties for the package

A NuGet package includes a manifest (a .nuspec file), that contains relevant metadata such as the package identifier, version number, description, and more. Some of this metadata can be drawn from the project properties directly, which avoids having to separately update them in both the project and the manifest. The following steps describe how to set the applicable properties:

1. Select Project > Properties, and then select the Application tab.

2. For Assembly name, give your package a unique identifier. If you attempt to publish a package with a name that already exists, you see an error.

   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.

3. Select Assembly Information, which displays a dialog box in which you can enter other properties that carry into the manifest (see Replacement tokens). The most commonly used fields are Title, Description, Company, Copyright, and Assembly version. Because these properties appear with your package on a host like nuget.org after you publish it, make sure they're fully descriptive.

   

4. (Optional) To see and edit the properties directly, open the Properties/AssemblyInfo.cs file in the project by selecting select Project > Edit Project File.

5. After you've set these properties, set the Active solution configuration in Build > Configuration Manager to Release and rebuild the project to generate the updated DLL.

Generate the initial manifest

After you've set the project properties and created the DLL, you can now generate an initial .nuspec file from the project. This step includes the relevant replacement tokens to draw information from the project file.

Run nuget spec only once to generate the initial manifest. If you update the package, either change values in your project, or edit the manifest directly:

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 where the AppLogger.csproj file is located.

2. Run the following command: nuget spec AppLogger.csproj.

   NuGet creates a manifest that matches the name of the project, in this case AppLogger.nuspec. It also includes replacement tokens in the manifest.

3. Open AppLogger.nuspec in a text editor to examine its contents, which will be similar to the following code:

   <?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>
   

Edit the manifest

1. Edit the following properties before proceeding. Otherwise, if you try to create a NuGet package with the default values in your .nuspec file, an error occurs. For information about these properties, see Optional metadata elements:

   • licenseUrl
   • projectUrl
   • releaseNotes
   • tags

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

3. You can also add any other elements to the manifest at this time, as described in .nuspec file reference.

4. Save the file before proceeding.

Run the pack command

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: nuget pack.

   NuGet generates a .nupkg file in the form of identifier.version.nupkg in the current folder.

Publish the package

After you've created a .nupkg file, publish it to nuget.org by using the NuGet CLI with an API key acquired from nuget.org. For nuget.org, you must use nuget.exe 4.1.0 or higher.

If you'd like to test and validate your package before publishing it a public gallery, you can upload it to a test environment like int.nugettest.org instead of nuget.org. Note that packages uploaded to int.nugettest.org may not be preserved.

Acquire your API key

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

2. In the upper-right corner, select your user name, and then select API Keys.

3. Select Create, and then enter a name for your key.

4. Under Select Scopes, select Push.

5. Under Select Packages, for Glob Pattern, enter an asterisk (*).

6. Select Create.

7. Select Copy to copy the new key.

   

Scoping provides a way to create separate API keys for different purposes. Each key has an expiration time frame, 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 NuGet CLI

Using the NuGet CLI (nuget.exe) is an alternative to using the .NET CLI:

1. Open a command prompt and change to the folder containing the .nupkg file.

2. Run the following command. Replace <package filename> with the file name of your package and replace <api key value> with your API key. The package filename is a concatenation of your package ID and version number with a .nupkg extension. For example, AppLogger.1.0.0.nupkg:

   nuget push <package filename> <api key value> -Source https://api.nuget.org/v3/index.json
   

   The result of the publishing process is displayed as follows:

   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.
   

For more information, see nuget push.

Publish errors

When you run the push command, you sometimes encounter an error. For instance, you might get an error in the following situations:

• Your API key is invalid or expired.
• You try to publish a package that has an identifier that already exists on the host.
• You make changes to a published package, but you forget to update the version number before you try to publish it again.

The error message typically indicates the source of the problem.

For example, suppose the identifier Contoso.App.Logger.Test exists on nuget.org. If you try to publish a package with that identifier, you get 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.).

To address this situation, check the scope, expiration date, and value of your API key. If the key is valid, the error indicates that the package identifier already exists on the host. To overcome the problem, change the package identifier to be unique, rebuild the project, re-create the .nupkg file, and retry the push command.

Manage the published package

When your package is successfully published, you receive a confirmation email. To see the published package, go to nuget.org, select your user name in the upper-right corner, and then select Manage Packages.

Now that your NuGet package is published at nuget.org, other developers can use it in their projects.

If you create a package that isn't useful (such as this sample package from an empty class library), or if 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.

   

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

   

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

Next steps

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

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

• Publish a package
• Build a prerelease package
• Support multiple target frameworks
• Package versioning
• Creating a localized package