通过

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

  • 项目

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

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

先决条件

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

    可以从 visualstudio.microsoft.com 免费安装 2022 Community 版，或者使用 Professional 或 Enterprise 版。

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

  • 如果尚未安装，则安装 .NET CLI。

    对于 Visual Studio 2017 及更高版本，.NET CLI 将自动随任何与 .NET Core 相关的工作负载一起安装。 否则，请安装 .NET Core SDK 以获取 .NET CLI。 .NET CLI 是使用 SDK 样式格式（SDK 属性）的 .NET Standard 项目所必需的。 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 CLI，从 nuget.org 下载它，将 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 框架），请迁移项目，或参阅创建并发布 .NET 框架包以获取分步说明。

    Screenshot showing NuGet package properties in a Visual Studio project.

  3. 对于面向公共使用而生成的包，请特别注意 Tags 属性，因为这些标记可帮助其他人查找包并了解其用途。

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

    重要

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

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

    AppLogger.csproj 选项卡加载。

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

运行 pack 命令

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

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

  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 包”。

    Screenshot showing package properties with Generate NuGet package on build selected.

注意

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

（可选）使用 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. 选择“复制”以复制新秘钥。

    Screenshot that shows the new API key with the Copy link.

重要

  • 始终将 API 密钥保留为机密。 API 密钥就像一个密码，允许任何人代表你管理软件包。 如果 API 密钥意外显示，则删除或重新生成密钥。
  • 请将密钥保存在安全位置，因为以后无法再次复制密钥。 如果返回到 API 密钥页，则需要重新生成密钥以对其进行复制。 如果你不再希望推送包，还可以删除 API 密钥。

设定范围允许创建针对不同用途的单独 API 密钥。 每个密钥都有过期时间，并且可以将秘钥范围限定为特定包（或 glob 模式）。 还可以将每个密钥限定为特定操作：推送新包和包版本、仅推送新包版本或取消列出。

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

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

使用 .NET CLI 或 NuGet CLI 发布

以下每个 CLI 工具都允许将包推送到服务器并发布。 选择 CLI 工具的选项卡， 即 .NET CLI 或 NuGet 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 的包可能不会保留。

发布错误

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 右上角选择用户名，然后选择“管理包”。

注意

包可能需要一些时间才能编入索引并显示在可供他人查看的搜索结果中。 在此期间，包显示在“未列出的包”下，包页面显示以下消息：

Screenshot showing the publishing message that's displayed when you upload a package to nuget.org.

现已将一个 NuGet 包发布到 nuget.org，其他开发人员可在自己的项目中使用它。

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

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

    Screenshot that shows the Edit icon for a package listing on nuget.org.

  2. 在下一页，选择“列出”，取消选择“在搜索结果中列出”复选框，然后选择“保存”。

    Screenshot that shows clearing the List checkbox for a package on nuget.org.

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

注意

若要避免测试包在 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 框架创建 NuGet 包。

使用 NuGet CLI 创建包

若要详细了解 NuGet 必须提供的详细信息，请参阅以下文章：