快速入门：仅使用 Visual Studio (Windows 创建和发布 NuGet 包)

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

本快速入门仅适用于 Windows 用户。 如果使用 Visual Studio for Mac，请参阅从现有库项目创建 NuGet 包或使用 .NET CLI。

先决条件

• 使用与 .NET Core 相关的工作负载安装 Visual Studio 2022 for Windows。

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

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

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

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

  重要

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

• 如果你还没有帐户，请在 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. 对于面向公共使用而生成的包，请特别注意 Tags 属性，因为这些标记可帮助其他人查找包并了解其用途。

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

   重要

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

5. (可选) 若要直接在 AppLogger.csproj 项目文件中查看属性，请选择“ 项目>编辑项目文件”。

   AppLogger.csproj 选项卡加载。

   从 Visual Studio 2017 开始，此选项可用于使用 SDK 样式属性的项目。 对于早期 Visual Studio 版本，必须先选择“ 项目>卸载项目” ，然后才能编辑项目文件。

运行 pack 命令

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

1. 选择“生成>Configuration Manager”，然后将“活动解决方案配置”设置为“发布”。

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

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

（可选）在生成期间生成包

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

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

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

   

注意

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

使用 MSBuild (可选) 包

作为使用 “包 ”菜单命令的替代方法，当项目包含必要的包数据时，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 密钥。

通过范围确定 ，可以创建用于不同用途的单独 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 push。

注意

如果要避免测试包在 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. 在下一页上，选择“ 列表”，取消选中“ 在搜索结果中列出 ”复选框，然后选择“ 保存”。

   

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

注意

若要避免测试包在 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