diff --git a/docs/nuget-org/Publish-a-package.md b/docs/nuget-org/Publish-a-package.md index 3dfe32091..b72c7b87e 100644 --- a/docs/nuget-org/Publish-a-package.md +++ b/docs/nuget-org/Publish-a-package.md @@ -22,6 +22,9 @@ To publish on nuget.org, sign in to nuget.org with a Microsoft account, and use Once you have an account, you can publish a package to nuget.org by using the nuget.org web portal, the dotnet CLI, or the NuGet CLI version 4.1.0 or above. You can also publish packages through Azure Pipelines. +> [!NOTE] +> If you want to publish your package on a test site before publishing it on nuget.org, you can use [https://int.nugettest.org](https://int.nugettest.org). Note that packages uploaded to int.nugettest.org might not be preserved. + ### Upload to the nuget.org web portal To upload a package to the nuget.org website: diff --git a/docs/quickstart/create-and-publish-a-package-using-visual-studio.md b/docs/quickstart/create-and-publish-a-package-using-visual-studio.md index dd1169c71..7e67bf359 100644 --- a/docs/quickstart/create-and-publish-a-package-using-visual-studio.md +++ b/docs/quickstart/create-and-publish-a-package-using-visual-studio.md @@ -1,56 +1,61 @@ --- -title: "Quickstart: Create and publish a NuGet package using Visual Studio (Windows only)" -description: A quickstart that shows how to create and publish a .NET NuGet package using Visual Studio for Windows. +title: "Quickstart: Create and Publish a NuGet Package Using Visual Studio (Windows Only)" +description: In this quickstart, find out how to use Visual Studio to create a basic NuGet package and then use the command line to publish the package to nuget.org. author: JonDouglas ms.author: jodou -ms.date: 03/03/2025 +ms.date: 04/15/2026 ms.topic: quickstart +# customer intent: As a developer, I want to find out how to create and publish a NuGet package so that I can make my code available to other developers. --- # 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. +In this quickstart, you use Microsoft Visual Studio to create a NuGet package from a .NET class library. Then you publish the package to nuget.org by using a command-line interface (CLI) tool. -The quickstart is for Windows users only. If you're using a Mac, use the [.NET CLI](create-and-publish-a-package-using-the-dotnet-cli.md). +This quickstart is for Windows users only. If you're using a Mac, use the [.NET CLI](create-and-publish-a-package-using-the-dotnet-cli.md). ## Prerequisites -- Install Visual Studio 2022 for Windows with a .NET Core-related workload. +- Visual Studio 2026 with a .NET-related workload. - You can install the 2022 Community edition for free from [visualstudio.microsoft.com](https://visualstudio.microsoft.com/), or use the Professional or Enterprise edition. + You can install the 2026 Community edition for free from [visualstudio.microsoft.com](https://visualstudio.microsoft.com/), or you can use the Professional or Enterprise edition. - Visual Studio 2017 and later automatically includes NuGet capabilities when you install a .NET-related workload. + Visual Studio 2017 and later automatically include NuGet capabilities when you install a .NET-related workload. -- Install the .NET CLI, if it's not already installed. +- The .NET CLI. - For Visual Studio 2017 and later, the .NET CLI is automatically installed with any .NET Core-related workload. Otherwise, install the [.NET Core SDK](https://www.microsoft.com/net/download/) to get the .NET CLI. The .NET CLI is required for .NET projects that use the [SDK-style format](../resources/check-project-format.md) (SDK attribute). The default .NET class library template in Visual Studio 2017 and later uses the SDK attribute. + For Visual Studio 2017 and later, the .NET CLI is automatically installed with any .NET-related workload. You can also install the [.NET SDK](https://dotnet.microsoft.com/download) to get the .NET CLI. The .NET CLI is required for .NET projects that use the [SDK-style format](../resources/check-project-format.md) (and an 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)](create-and-publish-a-package-using-visual-studio-net-framework.md) 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](../resources/check-project-format.md) (typically .NET Framework). + > [!IMPORTANT] + > If you're working with a non-SDK-style project, follow the procedures in [Create and publish a package using Visual Studio (.NET Framework, Windows)](create-and-publish-a-package-using-visual-studio-net-framework.md) instead to create and publish the package. For this article, the .NET CLI is recommended. Although you can publish any NuGet package by 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](../resources/check-project-format.md) (typically .NET Framework projects). -- [Register for a free account on nuget.org](../nuget-org/individual-accounts.md#add-a-new-individual-account) if you don't have one already. You must register and confirm the account before you can upload a NuGet package. +- A [free account on nuget.org](../nuget-org/individual-accounts.md#add-a-new-individual-account). You must register and confirm the account before you can upload a NuGet package. -- Install the NuGet CLI by downloading it from [nuget.org](https://dist.nuget.org/win-x86-commandline/latest/nuget.exe). Add the *nuget.exe* file to a suitable folder, and add that folder to your PATH environment variable. +- The NuGet CLI. You can install it by downloading it from [nuget.org](https://dist.nuget.org/win-x86-commandline/latest/nuget.exe). 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: +You can use an existing .NET class library project for the code you want to package, or you can create one by taking the following steps: + +1. In Visual Studio, select **File** > **New** > **Project/Solution**. -1. In Visual Studio, select **File** > **New** > **Project**. +1. In the **Create a new project** window, go to the search box and enter **class library**. -1. In the **Create a new project** window, select **C#**, **Windows**, and **Library** in the dropdown lists. +1. In the resulting list of project templates, select the **Class Library** template that meets the following criteria: + - Has the description *A project for creating a class library that targets .NET or .NET Standard* + - Has a **C\#** tag -1. 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**. + Select **Next**. -1. In the **Configure your new project** window, enter *AppLogger* for the **Project name**, and then select **Next**. +1. In the **Configure your new project** window, for **Project name**, enter **AppLogger**, and then select **Next**. -1. In the **Additional information** window, select an appropriate **Framework**, and then select **Create**. +1. In the **Additional information** window, select an appropriate value for **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](/dotnet/standard/net-standard#when-to-target-net50-or-net60-vs-netstandard). + 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 `netx.0` vs. `netstandard`](/dotnet/standard/net-standard#when-to-target-netx0-vs-netstandard). -1. 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). +1. To check whether the project is created properly, select **Build** > **Build Solution**. Then check the *Debug* folder for the DLL. If your project is configured to build a release configuration, check the *Release* folder instead. -1. (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: +1. (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 want to add some functional code to the package, include the following code: ```csharp namespace AppLogger @@ -67,78 +72,83 @@ You can use an existing .NET Class Library project for the code you want to pack ## Configure package properties -After you've created your project, you can configure the NuGet package properties by following these steps: +After you create your project, you can configure the NuGet package properties by following these steps: -1. Select your project in **Solution Explorer**, and then select **Project** > **\ Properties**, where \ is the name of your project. +1. In **Solution Explorer**, select your project, and then select **Project** > **\ Properties**, where \ is the name of your project. 1. 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](../consume-packages/migrate-packages-config-to-package-reference.md), or see [Create and publish a .NET Framework package](create-and-publish-a-package-using-visual-studio-net-framework.md) for step-by-step instructions. + The **Package** node appears only for SDK-style projects in Visual Studio. If you're targeting a non-SDK style project (typically .NET Framework projects), either [migrate the project](../consume-packages/migrate-packages-config-to-package-reference.md), or see [Create and publish a package using Visual Studio (.NET Framework, Windows)](create-and-publish-a-package-using-visual-studio-net-framework.md) for step-by-step instructions. - :::image type="content" source="media/qs-create-vs-project-properties.png" alt-text="Screenshot showing NuGet package properties in a Visual Studio project."::: + :::image type="content" source="media/qs-create-vs-project-properties.png" alt-text="Screenshot of a project properties window in Visual Studio. General properties for a NuGet package are visible, such as the package ID and title." lightbox="media/qs-create-vs-project-properties.png"::: -1. 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. +1. For **Package ID**, give your package a unique ID. + + > [!IMPORTANT] + > You must give the package an identifier that's unique across the host that you use, such as nuget.org. Otherwise, an error occurs. For this quickstart, we recommend including *Sample* or *Test* in the ID, because the publishing step makes the package publicly visible. For more information about selecting an ID, see [Best practices for the package identifier](../create-packages/Creating-a-Package.md#best-practices-for-the-package-identifier). -1. 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](../reference/msbuild-targets.md#pack-target). For a description of *.nuspec* file properties, see the [.nuspec file reference](../reference/nuspec.md). All of these properties go into the `.nuspec` manifest that Visual Studio creates for the project. +1. Fill out any other desired properties. For packages built for public consumption, pay special attention to the **Tags** property, because tags help others find your package and understand what it does. - > [!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. + All the properties go into the *.nuspec* manifest that Visual Studio creates for the project. For a table that shows how Microsoft Build (MSBuild) properties in SDK-style projects map to *.nuspec* file properties, see [pack target](../reference/msbuild-targets.md#pack-target). For a description of *.nuspec* file properties, see [.nuspec reference](../reference/nuspec.md). 1. (Optional) To see the properties directly in the *AppLogger.csproj* project file, select **Project** > **Edit Project File**. - The **AppLogger.csproj** tab loads. + The *AppLogger.csproj* file opens in a new tab. - 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. + This option is available for projects that use the SDK-style attribute. ## 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**. +1. Select **Build** > **Configuration Manager**, and then set the **Active solution configuration** value to **Release**. -1. Select the AppLogger project in **Solution Explorer**, then select **Pack**. +1. In **Solution Explorer**, right-click the **AppLogger** project, and then select **Pack**. - Visual Studio builds the project and creates the *.nupkg* file. + Visual Studio builds the project and creates the *.nupkg* file. -1. 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. Examine the **Output** window for detailed information, including the path to the package file. In this example, the built assembly is in the *bin\Release\net8.0* folder, which is appropriate for a .NET 8.0 target: - ```output - 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 ========== - ``` + ```output + 1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------ + 1> AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\net8.0\AppLogger.dll + 1> Successfully created package 'd:\proj\AppLogger\AppLogger\bin\Release\Contoso.App.Logger.Test.1.0.0.nupkg'. + ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ========== + ``` + +If the **Pack** command is missing from the menu, your project probably isn't an SDK-style project. Take one of the following steps: -1. 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](../consume-packages/migrate-packages-config-to-package-reference.md) and use .NET CLI, or see [Create and publish a .NET Framework package](create-and-publish-a-package-using-visual-studio-net-framework.md) for step-by-step instructions. +- [Migrate the project](../consume-packages/migrate-packages-config-to-package-reference.md) from the `packages.config` format to the `PackageReference` format so that you can use the .NET CLI. +- Follow the instructions in [Create and publish a package using Visual Studio (.NET Framework, Windows)](create-and-publish-a-package-using-visual-studio-net-framework.md) to use the NuGet CLI to create and publish a NuGet package from your project. ### (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** > **\ Properties**, where \ is the name of your project (AppLogger in this case). +1. Select your project in **Solution Explorer**, and then select **Project** > **\ Properties**, where \ is the name of your project (**AppLogger** in this case). 1. Expand the **Package** node, select **General**, and then select **Generate NuGet package on build**. - :::image type="content" source="media/qs-create-vs-generate-on-build.png" alt-text="Screenshot showing package properties with Generate NuGet package on build selected."::: + :::image type="content" source="media/qs-create-vs-generate-on-build.png" alt-text="Screenshot of a project properties window in Visual Studio. In the General properties section, the Generate NuGet package on build option is selected." lightbox="media/qs-create-vs-generate-on-build.png"::: > [!NOTE] -> When you automatically generate the package, the extra time to pack increases the overall build time for your project. +> When you select this option, the extra time that's needed to generate the package 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: +As an alternative to using the **Pack** menu command, you can use the `msbuild -t:pack` command to build a NuGet package from your project. NuGet 4.x+ and MSBuild 15.1+ support a `pack` target when your 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**. +1. With your project open in **Solution Explorer**, open a command prompt window by selecting **Tools** > **Command Line** > **Developer Command Prompt**. - The command prompt opens in your project directory. + The command prompt window opens in your project directory. 1. Run the following command: `msbuild -t:pack`. -For more information, see [Create a package using MSBuild](../create-packages/creating-a-package-msbuild.md). +For more information, see [Create a NuGet package using MSBuild](../create-packages/creating-a-package-msbuild.md). ## 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. +After you create a *.nupkg* file, take the steps in the following sections to publish it to nuget.org. You can use the .NET CLI or the NuGet CLI for publishing. You also use an API key that you acquire from nuget.org. [!INCLUDE [publish-notes](includes/publish-notes.md)] @@ -148,44 +158,42 @@ Before you publish your NuGet package, create an API key: [!INCLUDE [publish-api-key](includes/publish-api-key-with-link.md)] -### Publish with the .NET CLI or NuGet CLI +### Publish by using 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**. +You can use the .NET CLI or the NuGet CLI to push a package to the server and publish it. Go to the tab for the tool that you want to use. #### [.NET CLI](#tab/netcore-cli) -Using the .NET CLI (*dotnet.exe*) is the recommended alternative to using the NuGet CLI. +The .NET CLI (`dotnet.exe`) is the recommended alternative to the NuGet CLI. [!INCLUDE [publish-dotnet](includes/publish-dotnet.md)] #### [NuGet CLI](#tab/nuget) -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. +For publishing, you can use the NuGet CLI (`nuget.exe`) as an alternative to the .NET CLI: -1. Run the following command. Replace \ with the file name of your package and replace \ with your API key. +1. Open a command prompt window, and then go to the folder that contains the *.nupkg* file. - The NuGet CLI generates a *.nupkg* file in the form of *package ID-version.nupkg*. For example, *AppLogger.1.0.0.nupkg*: +1. Run the following command. Replace `` with the name of your *.nupkg* file, and replace `` with your API key. The package file has the format *\.\.nupkg*, for example, *Contoso.App.Logger.Test.1.0.0.nupkg*. - ```nuget - nuget push -Source https://api.nuget.org/v3/index.json - ``` + ```nuget + nuget push -Source https://api.nuget.org/v3/index.json + ``` - The result of the publishing process is displayed as follows: + The output shows the results of the publishing process: - ```output - Pushing 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. - ``` + ```output + Pushing to 'https://www.nuget.org/api/v2/package'... + PUT https://www.nuget.org/api/v2/package/ + Created https://www.nuget.org/api/v2/package/ 950ms + Your package was pushed. + ``` -For more information, see [nuget push](../reference/cli-reference/cli-ref-push.md). +For more information, see [push command (NuGet CLI)](../reference/cli-reference/cli-ref-push.md). --- -### Publish errors +### Errors during publishing [!INCLUDE [publish-errors](includes/publish-errors.md)] @@ -193,59 +201,78 @@ For more information, see [nuget push](../reference/cli-reference/cli-ref-push.m [!INCLUDE [publish-manage](includes/publish-manage.md)] -## Add a readme or another file +## Add a read-me or another file + +You can include a read-me file or other files in your package. + +### Add a read-me file + +To add a read-me file to the package, take the following steps: + +1. In **Solution Explorer**, select your project, and then select **Project** > **\ Properties**, where \ is the name of your project. -To directly specify files to include in the package, edit the project file and add the `content` property: +1. Expand the **Package** node, select **General**, and then scroll to the **README** section. + +1. Select **Browse**, and then select your read-me file. + + Visual Studio adds information about your read-me file to the project file: + - A `PackageReadmeFile` child element is added to the `PropertyGroup` element. + - A `None` child element is added to the `ItemGroup` element. + + ```xml + + + ... + read-me.md + ... + + + + ... + + True + \ + + ... + + + ``` + +In the preceding example, the property specifies a file named *read-me.md* in the project root. After you build, pack, and publish your package, nuget.org displays the contents of the read-me file on the package page. Visual Studio also displays the contents of that file in the Package Manager UI. + +For example, the following screenshot shows the read-me file for the `HtmlAgilityPack` package: + +:::image type="content" source="media/package-read-me-file.png" alt-text="Screenshot of the Visual Studio Package Manager UI that shows a package details pane. The README tab describes HTML parsing abilities of the package." lightbox="media/package-read-me-file.png"::: + +### Add other files + +To add other files to a package, open the project file by selecting **Project** > **Edit Project File**. Then add a `Content` child element to the `ItemGroup` element: ```xml - + true \ ``` -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: - -```output -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. +For more information, see [Including content in a package](../reference/msbuild-targets.md#including-content-in-a-package). -## Related video +## Related videos -Find NuGet videos on [Channel 9](/shows/NuGet-101/) and [YouTube](https://www.youtube.com/playlist?list=PLdo4fOcmZ0oVLvfkFk8O9h6v2Dcdh2bh_). +For videos about using NuGet for package management, see [.NET Package Management with NuGet for Beginners](/shows/dotnet-package-management-with-nuget-for-beginners) and [NuGet for Beginners](https://www.youtube.com/playlist?list=PLdo4fOcmZ0oVLvfkFk8O9h6v2Dcdh2bh_). -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. +## Related content -> [!div class="nextstepaction"] -> [Create a package using the NuGet CLI](../create-packages/creating-a-package.md) +To find out how to create a NuGet package with the Visual Studio .NET Framework, see [Create a package using the nuget.exe CLI](../create-packages/Creating-a-Package.md). -To explore more that NuGet has to offer, see the following articles: +For more information about NuGet, see the following articles: -- [Create a NuGet package](../create-packages/creating-a-package-dotnet-cli.md) -- [Publish a package](../nuget-org/publish-a-package.md) -- [Build a prerelease package](../create-packages/Prerelease-Packages.md) -- [Support multiple .NET Framework versions](../create-packages/multiple-target-frameworks-project-file.md) +- [Create a NuGet package with the dotnet CLI](../create-packages/creating-a-package-dotnet-cli.md) +- [Publish NuGet packages](../nuget-org/Publish-a-package.md) +- [Building pre-release packages](../create-packages/Prerelease-Packages.md) +- [Support multiple .NET frameworks in your project file](../create-packages/multiple-target-frameworks-project-file.md) - [Package versioning](../concepts/package-versioning.md) -- [Create localized NuGet packages](../create-packages/creating-localized-packages.md) -- [Porting to .NET Core from .NET Framework](/dotnet/articles/core/porting/index) +- [Creating localized NuGet packages](../create-packages/Creating-Localized-Packages.md) +- [Overview of upgrading .NET apps](/dotnet/core/porting/) diff --git a/docs/quickstart/includes/publish-api-key-with-link.md b/docs/quickstart/includes/publish-api-key-with-link.md index b0162ee05..847593ea4 100644 --- a/docs/quickstart/includes/publish-api-key-with-link.md +++ b/docs/quickstart/includes/publish-api-key-with-link.md @@ -1,3 +1,3 @@ [!INCLUDE [publish-api-key](publish-api-key.md)] -For more information, see [scoped API keys](../../nuget-org/scoped-api-keys.md). +For more information, see [Scoped API keys](../../nuget-org/scoped-api-keys.md). diff --git a/docs/quickstart/includes/publish-api-key.md b/docs/quickstart/includes/publish-api-key.md index b2588b6be..2a036d3d2 100644 --- a/docs/quickstart/includes/publish-api-key.md +++ b/docs/quickstart/includes/publish-api-key.md @@ -1,24 +1,24 @@ -1. [Sign into your nuget.org account](https://www.nuget.org/users/account/LogOn?returnUrl=%2F) or [create an account](../../nuget-org/individual-accounts.md#add-a-new-individual-account) if you don't have one already. +1. [Sign in to your nuget.org account](https://www.nuget.org/users/account/LogOn?returnUrl=%2F) or [create an account](../../nuget-org/individual-accounts.md#add-a-new-individual-account) if you don't have one already. -1. Select your user name at upper right, and then select **API Keys**. +1. In the upper-right corner, select your user name, and then select **API Keys**. -1. Select **Create**, and provide a name for your key. +1. Select **Create**, and then enter a name for your key. 1. Under **Select Scopes**, select **Push**. -1. Under **Select Packages** > **Glob Pattern**, enter \*. +1. Under **Select Packages**, for **Glob Pattern**, enter an asterisk (**\***). 1. Select **Create**. 1. Select **Copy** to copy the new key. - ![Screenshot that shows the new API key with the Copy link.](../media/qs-create-api-key.png) + :::image type="content" source="../media/qs-create-api-key.png" alt-text="Screenshot of a nuget.org page that shows the new API key, a message about copying the key now, and the Copy button, which is highlighted."::: > [!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. +> - Always keep your API key a secret. The API key is like a password that anyone can use 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. +*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. \ No newline at end of file diff --git a/docs/quickstart/includes/publish-dotnet.md b/docs/quickstart/includes/publish-dotnet.md index eead5986d..d0ccbb8c7 100644 --- a/docs/quickstart/includes/publish-dotnet.md +++ b/docs/quickstart/includes/publish-dotnet.md @@ -1,20 +1,16 @@ -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. +From the folder that contains the *.nupkg* file, run the following command. Replace `` with the name of your *.nupkg* file, and replace `` with your API key. ```dotnetcli -dotnet nuget push Contoso.08.28.22.001.Test.1.0.0.nupkg --api-key qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 --source https://api.nuget.org/v3/index.json +dotnet nuget push --api-key --source https://api.nuget.org/v3/index.json ``` The output shows the results of the publishing process: ```output -Pushing Contoso.08.28.22.001.Test.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'... +Pushing 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 + Created https://www.nuget.org/api/v2/package/ 2891ms Your package was pushed. ``` For more information, see [dotnet nuget push](/dotnet/core/tools/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](https://int.nugettest.org). Note that packages uploaded to int.nugettest.org might not be preserved. \ No newline at end of file diff --git a/docs/quickstart/includes/publish-errors.md b/docs/quickstart/includes/publish-errors.md index a6afe8686..3aee9a504 100644 --- a/docs/quickstart/includes/publish-errors.md +++ b/docs/quickstart/includes/publish-errors.md @@ -1,10 +1,15 @@ -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. +When you run the `push` command, you sometimes encounter an error. For instance, you might get an error in the following situations: -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: +- 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. - ```output - 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.). - ``` +The error message typically indicates the source of the problem. -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. +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: + +```output +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. diff --git a/docs/quickstart/includes/publish-manage.md b/docs/quickstart/includes/publish-manage.md index bf1b8c8e6..44fcbd4d0 100644 --- a/docs/quickstart/includes/publish-manage.md +++ b/docs/quickstart/includes/publish-manage.md @@ -1,21 +1,21 @@ -When your package successfully publishes, you receive a confirmation email. To see the package you just published, on [nuget.org](https://www.nuget.org/), select your user name at upper right, and then select **Manage Packages**. +When your package is successfully published, you receive a confirmation email. To see the published package, go to [nuget.org](https://www.nuget.org/), select your user name in the upper-right corner, 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: +> It might take a while for your package to be indexed and to 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.](../media/qs-create-not-indexed.png) +> :::image type="content" source="../media/qs-create-not-indexed.png" alt-text="Screenshot of a nuget.org warning message about the package not being published yet. The text states that validation and indexing can take an hour."::: -You've now published a NuGet package to nuget.org that other developers can use in their projects. +Now that your NuGet package is published at nuget.org, other developers can use it 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: +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. - ![Screenshot that shows the Edit icon for a package listing on nuget.org.](../media/qs-create-vs-edit-package.png) + :::image type="content" source="../media/qs-create-vs-edit-package.png" alt-text="Screenshot of the nuget.org Packages page. The Published Packages section lists one package. Its edit icon is highlighted."::: -1. On the next page, select **Listing**, deselect the **List in search results** checkbox, and then select **Save**. +1. On the next page, select **Listing**, clear the **List in search results** checkbox, and then select **Save**. - ![Screenshot that shows clearing the List checkbox for a package on nuget.org.](../media/qs-create-vs-unlist-package.png) + :::image type="content" source="../media/qs-create-vs-unlist-package.png" alt-text="Screenshot of a nuget.org page. In the Listing section, the option for listing the package in search results is highlighted."::: The package now appears under **Unlisted Packages** in **Manage Packages** and no longer appears in search results. diff --git a/docs/quickstart/includes/publish-notes.md b/docs/quickstart/includes/publish-notes.md index 78007281b..f34483fc6 100644 --- a/docs/quickstart/includes/publish-notes.md +++ b/docs/quickstart/includes/publish-notes.md @@ -1,5 +1,5 @@ > [!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. +> - Nuget.org scans all uploaded packages for viruses and rejects any packages that contain 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](../../hosting-packages/overview.md). +> - Packages you publish to nuget.org are publicly visible to other developers unless you unlist them. To host packages privately, see [Hosting your own NuGet feeds](../../hosting-packages/Overview.md). diff --git a/docs/quickstart/media/package-read-me-file.png b/docs/quickstart/media/package-read-me-file.png new file mode 100644 index 000000000..2603cd697 Binary files /dev/null and b/docs/quickstart/media/package-read-me-file.png differ diff --git a/docs/quickstart/media/qs-create-api-key.png b/docs/quickstart/media/qs-create-api-key.png index 9e0d1045b..5d575c4a8 100644 Binary files a/docs/quickstart/media/qs-create-api-key.png and b/docs/quickstart/media/qs-create-api-key.png differ diff --git a/docs/quickstart/media/qs-create-not-indexed.png b/docs/quickstart/media/qs-create-not-indexed.png index b5af2bc4f..84185ae0c 100644 Binary files a/docs/quickstart/media/qs-create-not-indexed.png and b/docs/quickstart/media/qs-create-not-indexed.png differ diff --git a/docs/quickstart/media/qs-create-vs-edit-package.png b/docs/quickstart/media/qs-create-vs-edit-package.png index 57bab2cb5..fb8a3864f 100644 Binary files a/docs/quickstart/media/qs-create-vs-edit-package.png and b/docs/quickstart/media/qs-create-vs-edit-package.png differ diff --git a/docs/quickstart/media/qs-create-vs-generate-on-build.png b/docs/quickstart/media/qs-create-vs-generate-on-build.png index f0b741899..411980f8b 100644 Binary files a/docs/quickstart/media/qs-create-vs-generate-on-build.png and b/docs/quickstart/media/qs-create-vs-generate-on-build.png differ diff --git a/docs/quickstart/media/qs-create-vs-project-properties.png b/docs/quickstart/media/qs-create-vs-project-properties.png index d7d5264c3..58d51dfd7 100644 Binary files a/docs/quickstart/media/qs-create-vs-project-properties.png and b/docs/quickstart/media/qs-create-vs-project-properties.png differ diff --git a/docs/quickstart/media/qs-create-vs-unlist-package.png b/docs/quickstart/media/qs-create-vs-unlist-package.png index 0b2b1e8d7..35e4a60f7 100644 Binary files a/docs/quickstart/media/qs-create-vs-unlist-package.png and b/docs/quickstart/media/qs-create-vs-unlist-package.png differ