Muokkaa

Jaa

Quickstart: Create and publish a package with the dotnet CLI

  • Artikkeli

This quickstart shows you how to quickly create a NuGet package from a .NET class library and publish it to nuget.org by using the .NET command-line interface, or dotnet CLI.

Prerequisites

  • The .NET SDK, which provides the dotnet command-line tool. Starting in Visual Studio 2017, the dotnet CLI automatically installs with any .NET or .NET Core related workloads.

  • A free account on nuget.org. Follow the instructions at Add a new individual account.

Create a class library project

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

  1. Create a folder named AppLogger.
  2. Open a command prompt and switch to the AppLogger folder. All the dotnet CLI commands in this quickstart run on the current folder by default.
  3. Enter dotnet new classlib, which creates a project with the current folder name.

For more information, see dotnet new.

Add package metadata to the project file

Every NuGet package has a manifest that describes the package's contents and dependencies. In the final package, the manifest is a .nuspec file, which uses the NuGet metadata properties you include in the project file.

Open the .csproj, .fsproj, or .vbproj project file, and add the following properties inside the existing <PropertyGroup> tag. Use your own values for name and company, and replace the package identifier with a unique value.

<PackageId>Contoso.08.28.22.001.Test</PackageId>
<Version>1.0.0</Version>
<Authors>your_name</Authors>
<Company>your_company</Company>

Important

The package identifier must be unique across nuget.org and other package sources. Publishing makes the package publicly visible, so if you use the example AppLogger library or other test library, use a unique name that includes Sample or Test.

You can add any optional properties described in NuGet metadata properties.

Note

For packages you build for public consumption, pay special attention to the PackageTags property. Tags help others find your package and understand what it does.

Run the pack command

To build a NuGet package or .nupkg file from the project, run the dotnet pack command, which also builds the project automatically.

dotnet pack

The output shows the path to the .nupkg file:

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored C:\Users\myname\source\repos\AppLogger\AppLogger.csproj (in 64 ms).
  AppLogger -> C:\Users\myname\source\repos\AppLogger\bin\Debug\net6.0\AppLogger.dll
  Successfully created package 'C:\Users\myname\source\repos\AppLogger\bin\Debug\Contoso.08.28.22.001.Test.1.0.0.nupkg'.

Automatically generate package on build

To automatically run dotnet pack whenever you run dotnet build, add the following line to your project file within <PropertyGroup>:

    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Publish the package

Publish your .nupkg file to nuget.org by using the dotnet nuget push command with an API key you get 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.

Get your 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 dotnet nuget push

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.

Congratulations on creating and publishing your first NuGet package!

Find more NuGet videos on Channel 9 and YouTube.

Next steps

See more details about how to create packages with the dotnet CLI:

Create a NuGet package with the dotnet CLI

Get more information about creating and publishing NuGet packages: