快速入门：使用 Visual Studio 创建和发布 NuGet 包（仅限 Windows）

使用 Microsoft Visual Studio，可以从 .NET 类库创建 NuGet 包，然后使用 CLI 工具将其发布到 nuget.org。

快速入门仅适用于 Windows 用户。 如果使用 Mac，请使用 .NET CLI。

先决条件

• 安装具有 .NET Core 相关工作负载的 Visual Studio 2022 for Windows。

  你可以从 visualstudio.microsoft.com免费安装 2022 社区版，也可以使用专业版或企业版。

  当你安装与 .NET 相关的工作负荷时，Visual Studio 2017 及更高版本会自动包含 NuGet 功能。

• 安装 .NET CLI（如果尚未安装）。

  对于 Visual Studio 2017 及更高版本，.NET CLI 会自动安装任何与 .NET Core 相关的工作负载。 否则，请安装 .NET Core SDK 以获取 .NET CLI。 使用 SDK 样式格式 （SDK 属性）的 .NET 项目需要 .NET CLI。 Visual Studio 2017 及更高版本中的默认 .NET 类库模板使用 SDK 属性。

  重要

  如果您使用非 SDK 样式的项目，请改为按照 创建和发布 .NET Framework 软件包（Visual Studio） 中的步骤来创建并发布软件包。 在本文中，建议使用 .NET CLI。 尽管可以使用 NuGet CLI 发布任何 NuGet 包，但本文中的一些步骤特定于 SDK 样式的项目和 .NET CLI。 NuGet CLI 用于非 SDK 样式项目 （通常是 .NET Framework）。

• 如果您还没有 nuget.org 的帐户，请注册一个免费帐户。 必须先注册并确认帐户，然后才能上传 NuGet 包。

• 通过从 nuget.org下载 NuGet CLI 来安装它。将 nuget.exe 文件添加到合适的文件夹，并将该文件夹添加到 PATH 环境变量。

创建类库项目

可以将现有 .NET 类库项目用于要打包的代码，也可以按如下所示创建一个项目：

1. 在 Visual Studio 中，选择“文件>新建>项目。

2. 在 创建新项目 窗口中，选择 C#、Windows，并在下拉列表中选择 库。

3. 在生成的项目模板列表中，选择 类库（说明 用于创建面向 .NET 或 .NET Standard的类库的项目），然后选择“下一步”。

4. 在 配置新项目 窗口中，输入 AppLogger 作为 项目名称，然后选择 下一步。

5. 在“其他信息 窗口中，选择适当的 框架，然后选择 创建。

   如果不确定要选择哪个框架，则最新框架是一个不错的选择，以后可以轻松更改。 有关要使用的框架的信息，请参阅 何时面向 .NET 5.0 或 .NET 6.0 与 .NET Standard。

6. 若要确保项目正确创建，请选择 生成>生成解决方案。 DLL 位于“调试”文件夹中（如果改为生成该配置，则位于“发布”文件夹中）。

7. （可选）对于本快速入门，无需为 NuGet 包编写任何其他代码，因为模板类库足以创建包。 但是，如果想要包的一些功能代码，请包括以下代码：

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

配置包属性

创建项目后，可以按照以下步骤配置 NuGet 包属性：

1. 在 解决方案资源管理器中选择项目，然后选择 项目><项目名称> 属性，其中 <项目名称> 是项目的名称。

2. 展开 包 节点，然后选择 常规。

   包 节点仅适用于 Visual Studio 中的 SDK 样式项目。 如果要面向非 SDK 样式项目（通常是 .NET Framework），迁移项目，或参阅 创建和发布 .NET Framework 包 以获取分步说明。

   

3. 对于为公共使用而构建的包，请特别注意 标签 属性，因为标签可以帮助其他人找到您的包并了解其功能。

4. 为包提供唯一的 包 ID 并填写任何其他所需属性。 要查看有关 MSBuild 属性（SDK 样式项目）如何映射到 .nuspec 文件属性的表，请参阅 打包目标。 有关 .nuspec 文件属性的说明，请参阅 .nuspec 文件引用。 所有这些属性都进入 Visual Studio 为项目创建的 .nuspec 清单。

   重要

   你必须为包提供一个在 nuget.org 或所使用的任何主机中唯一的标识符。 否则，将发生错误。 对于本快速入门，我们建议在名称中包含 示例 或 测试，因为发布步骤使包公开可见。

5. （可选）若要直接在 AppLogger.csproj 项目文件中查看属性，请选择 Project>编辑项目文件。

   AppLogger.csproj 选项卡加载。

   此选项从 Visual Studio 2017 开始提供，适用于使用 SDK 样式属性的项目。 对于早期 Visual Studio 版本，必须先选择 Project>Unload Project，然后才能编辑项目文件。

运行 pack 命令

若要从项目创建 NuGet 包，请执行以下步骤：

1. 选择 生成>配置管理器，然后将 活动解决方案配置 设置为 发布。

2. 在解决方案资源管理器 中选择 AppLogger 项目，然后选择 Pack。

   Visual Studio 生成项目并创建 .nupkg 文件。

3. 检查 输出 窗口以获取详细信息，其中包含包文件的路径。 在此示例中，生成的程序集位于 bin\Release\net6.0 中，符合 .NET 6.0 目标：

   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. 如果未在菜单上看到 Pack 命令，则项目可能不是 SDK 样式的项目，并且需要使用 NuGet CLI。 迁移项目 并使用 .NET CLI，或参阅 创建和发布 .NET Framework 包 以获取分步说明。

（可选）在生成时生成包

可以在生成项目时将 Visual Studio 配置为自动生成 NuGet 包：

1. 在 解决方案资源管理器中选择项目，然后选择 项目><项目名称> 属性，其中 <项目名称> 是项目的名称（在本例中为 AppLogger）。

2. 展开 包 节点，选择 常规，然后在生成 上选择生成 NuGet 包。

   

注意

自动生成包时，打包的额外时间会增加项目的总体生成时间。

（可选）使用 MSBuild 打包

作为使用 Pack 菜单命令的替代方法，当项目包含必要的包数据时，NuGet 4.x+ 和 MSBuild 15.1+ 支持 pack 目标：

1. 在 解决方案资源管理器中打开项目后，选择 工具>命令行>开发人员命令提示符打开命令提示符。

   命令提示符将在项目目录中打开。

2. 运行以下命令：msbuild -t:pack。

有关详细信息，请参阅 使用 MSBuild创建包。

发布这个包

创建 .nupkg 文件后，使用 .NET CLI 或 NuGet CLI 以及从 nuget.org 获取的 API 密钥将其发布到 nuget.org。

注意

• NuGet.org 扫描所有上传的程序包以检测病毒，如果发现任何病毒，则会拒绝这些程序包。 Nuget.org 还会定期扫描所有现有列出的包。

• 发布到 nuget.org 的包对其他开发人员公开可见，除非取消列出它们。 若要私下托管包，请参阅 托管自己的 NuGet 源。

获取 API 密钥

在发布 NuGet 包之前，请创建 API 密钥：

1. 登录到 nuget.org 帐户 或 创建帐户（如果还没有帐户）。

2. 选择右上角的用户名，然后选择 API 密钥。

3. 选择 创建，并提供密钥的名称。

4. 在 “选择范围”下，选择 “推送”。

5. 在 选择包>的 Glob 模式下，输入 *。

6. 选择 创建。

7. 选择 复制 以复制新密钥。

   

重要

• 始终将 API 密钥保留为机密。 API 密钥类似于密码，允许任何人代表你管理包。 如果 API 密钥意外泄露，请将其删除或重新生成。
• 将密钥保存在安全的位置，因为以后无法再次复制密钥。 如果返回到 API 密钥页，则需要重新生成密钥以复制密钥。 如果不再需要推送包，还可以删除 API 密钥。

作用域 可以让您为不同目的创建单独的 API 密钥。 每个密钥都有到期时间范围，可以将密钥范围限定为特定包或 glob 模式。 还可以将每个密钥限定为特定操作：推送新包和包版本、仅推送新包版本或取消列表。

通过范围，可以为管理组织包的不同人员创建 API 密钥，以便他们仅具有所需的权限。

有关详细信息，请参阅 限定范围的 API 密钥。

使用 .NET CLI 或 NuGet CLI 进行发布

以下每个 CLI 工具都允许将包推送到服务器并发布它。 选择 CLI 工具的选项卡，.NET CLI 或 NuGet CLI。

.NET CLI

使用 .NET CLI（dotnet.exe）是使用 NuGet CLI 的建议替代方法。

从包含 .nupkg 文件的文件夹运行以下命令。 指定 .nupkg 文件名，并将密钥值替换为 API 密钥。

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

输出显示发布过程的结果：

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.

有关详细信息，请参阅 dotnet nuget 推送。

注意

如果要避免测试包在 nuget.org 上实时运行，可以在 https://int.nugettest.org推送到 nuget.org 测试站点。请注意，上载到 int.nugettest.org 的包可能不会保留。

NuGet 命令行界面 (CLI)

使用 NuGet CLI（nuget.exe）是使用 .NET CLI 的替代方法：

1. 打开命令提示符并更改为包含 .nupkg 文件的文件夹。

2. 运行以下命令。 将 <包文件名> 替换为包的文件名，并将 <api 密钥值替换为 API 密钥>。

   NuGet CLI 以 包 ID-version.nupkg的形式生成 .nupkg 文件。 例如，AppLogger.1.0.0.nupkg：

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

   发布过程的结果如下所示：

   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.
   

有关详细信息，请参阅 NuGet 推送。

发布错误

push 命令中的错误通常指示问题。 例如，你可能忘记更新项目中的版本号，因此你正尝试发布已存在的包。

如果 API 密钥无效或已过期，或者尝试使用主机上已存在的标识符发布包，则还会看到错误。 例如，假设标识符 AppLogger-test 已存在于 nuget.org 上。如果尝试发布具有该标识符的包，push 命令会提供以下错误：

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 密钥。 如果是，则错误指示主机上已存在包标识符。 若要修复此错误，请将包标识符更改为唯一，重新生成项目，重新创建 .nupkg 文件，然后重试 push 命令。

管理已发布的包

成功发布包后，会收到确认电子邮件。 若要查看您刚发布的包，请在 nuget.org上点击右上角的用户名，然后选择 管理包。

注意

您的包可能需要一段时间才能被编制索引，并在搜索结果中显示，以便其他人可以找到它。 在此期间，您的包裹会列在 未列出的包裹下，包裹页面显示以下消息：

现在，你已发布一个 NuGet 包，nuget.org 其他开发人员可以在其项目中使用。

如果你创建了一个无效的包（例如，此示例包是使用空类库创建的），或者你决定不希望该包可见，则可以 取消列出 该包，从而将其从搜索结果中隐藏。

1. 在软件包显示在“管理包”页面的“已发布包”下后，选择软件包列表旁边的铅笔图标。

   

2. 在下一页中，选择 Listing，取消选中搜索结果中的 列表选项 的复选框，然后选择 保存。

   

包现在显示在 管理包 中 未列出的包 下，不再显示在搜索结果中。

注意

为了避免测试包在 nuget.org 上实时运行，可以在 https://int.nugettest.org推送到 nuget.org 测试站点。请注意，上载到 int.nugettest.org 的包可能不会保留。

添加自述文件或其他文件

若要直接指定要包含在包中的文件，请编辑项目文件并添加 content 属性：

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

在此示例中，该属性指定项目根目录中名为 readme.txt 的文件。 Visual Studio 在安装包后立即将该文件的内容显示为纯文本。 对于作为依赖项安装的包，不显示自述文件。 例如，下面是 HtmlAgilityPack 包的自述文件：

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

注意

如果仅在项目根目录中添加 readme.txt 而不将其包含在项目文件的 content 属性中，则它不会包含在包中。

相关视频

在 第 9 频道 和 YouTube上查找 NuGet 视频。

恭喜使用 Visual Studio .NET 类库创建 NuGet 包。 转到下一篇文章，了解如何使用 Visual Studio .NET Framework 创建 NuGet 包。

使用 NuGet CLI 创建包

要了解 NuGet 提供的更多内容，请参阅以下文章：

• 创建 NuGet 包
• 发布一个软件包
• 生成预发行版包
• 支持多个 .NET Framework 版本
• 包版本控制
• 创建本地化的 NuGet 包
• 从 .NET Framework 向 .NET Core 移植