使用 Visual Studio 创建和发布 NuGet 包（仅限 .NET Standard 和 Windows）

从 Windows 上 Visual Studio 中的 .NET Standard 类库创建 NuGet 包，然后使用 CLI 工具将其发布到 nuget.org，这是一个很简单的过程。

先决条件

通过与 .NET Core 相关的工作负载从 visualstudio.com 安装任意版本的 Visual Studio 2019。

如果尚未安装，则安装 dotnet CLI。

对于 dotnet CLI，从 Visual Studio 2017 开始，dotnet CLI 将自动随任何与 .NET Core 相关的工作负载一起安装。 否则，请安装 .NET Core SDK 以获取 dotnet CLI。 dotnet CLI 是使用 SDK 样式格式（SDK 属性）的 .NET Standard 项目所必需的。 Visual Studio 2017 及更高版本中的默认 .NET Standard 类库模板（本文所用模板）使用 SDK 属性。 

重要

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

如果你还没有帐户，请在 nuget.org 上注册一个免费帐户。 创建新帐户会发送确认电子邮件。 必须先确认该帐户，才能上传包。

创建类库项目

可以使用现有的 .NET Standard 类库项目用于要打包的代码，或者创建一个简单的项目，如下所示：

在 Visual Studio 中，选择“文件”>“新建”>“项目”，展开“Visual C#”>“.NET Standard”节点，选择“类库(.NET Standard)”模板，将项目命名为“AppLogger”，然后单击“确定”。 

提示

除非你有其他选择理由，否则 .NET Standard 是 NuGet 包的首选目标，因为它提供了与最广泛的使用项目的兼容性。

右键单击生成的项目文件并选择“生成”，确保已正确创建项目。 DLL 位于调试文件夹中（或发布中，如果生成的是该配置）。

当然，在实际的 NuGet 包中，可实现许多有用的功能，让其他人可通过这些功能生成应用程序。 但是对于本演练，无需编写其他任何代码，因为模板的类库足以创建包。 但是，如果你需要此程序包的某个功能代码，请使用以下命令：

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

配置包属性

在解决方案资源管理器中右键单击该项目，然后选择“属性”菜单命令，然后选择“包”选项卡。“包”选项卡仅在 Visual Studio 的 SDK 样式项目中显示，通常是 .NET Standard 或 .NET Core 类库项目；

备注

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

为包提供一个唯一标识符，并填写任何其他所需的属性。 若要将 MSBuild 属性（SDK 样式项目）映射到 .nuspec 中的属性。 这里的所有属性都列入 Visual Studio 为项目创建的 .nuspec 清单。 

重要

你必须为包提供一个在 nuget.org 中唯一或你使用的任何主机的标识符。 对于本次演练，我们建议在名称中包含“Sample”或“Test”，因为稍后的发布步骤确实会使该包公开显示（尽管实际上不太可能有人会使用它）。如果你尝试发布名称已存在的包，则会看到一个错误。

（可选）若要直接查看项目文件中的属性，请右键单击“解决方案资源管理器”中的“项目”，然后选择“编辑 AppLogger.csproj”。此选项从 Visual Studio 2017 开始仅对使用 SDK 样式属性的项目可用。 否则，右键单击项目，并选择“卸载项目”。 然后右键单击卸载的项目并选择“编辑 AppLogger.csproj”。

运行 pack 命令

将此配置设置为“发布”。

请在“解决方案资源管理器”中右键单击该项目，然后选择“Pack”命令：

如果没有看到“Pack”nuget.exe命令，那么项目可能不是 SDK 样式的项目，需要使用 CLI。

Visual Studio 构建项目并创建 .nupkg 文件。 检查“输出”窗口以查看详细信息（类似于以下内容），其中包含包文件的路径。 另请注意，生成的程序集位于适合 .NET Standard 2.0 目标的 bin\Release\netstandard2.0 中。

1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------
1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\netstandard2.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 ==========

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

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

1. 在“解决方案资源管理器”中，右键单击项目，然后选择“属性”。
2. 在“包”选项卡中，选择“在生成期间生成 NuGet 包”。

备注

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

（可选）使用 MSBuild 打包

作为使用“打包”菜单命令的备选项，当项目包含必要的包数据时，NuGet 4.x+ 和 MSBuild 15.1+ 支持 pack 目标。 打开命令提示符，导航到项目文件夹并运行以下命令。 （用户通常习惯从“开始”菜单中启动“适用于 Visual Studio 的开发人员命令提示符”，因为它将使用 MSBuild 的所有必需路径进行配置。）

发布包

有了 .nupkg 文件后，可以使用 nuget.exe CLI 或 dotnet.exe CLI 以及从 nuget.org 获取的 API 密钥将其发布到 nuget.org。

备注

病毒扫描：所有上传到 nuget.org 的包都会进行病毒扫描，如果发现任何病毒，将拒绝包。 此外，还会定期扫描 nuget.org 上列出的所有包。

发布到 nuget.org 的包也对其他开发者公开可见，除非你取消列出它们。

获取 API 密钥

1. 登录你的 nuget.org 帐户，或创建一个帐户（如果你还没有帐户）。
2. 选择用户名（在右上角），然后选择“API 密钥”。
3. 选择“创建”，提供密钥名称，选择“选择范围”>“推送”。 输入“Glob 模式”*，然后选择“创建”。 （请参阅下面有关范围的详细信息。）
4. 创建密钥后，选择“复制”，检索需要在 CLI 中使用的访问密钥：

警告

始终将 API 密钥保留为机密！ 将 API 密钥视为密码，使任何人都可以代表你管理包。 如果 API 密钥意外显示，则应删除或重新生成密钥。

重要

将密钥保存在安全位置，因为以后无法再次复制密钥。 如果返回到 API 密钥页，则需要重新生成密钥以对其进行复制。 如果你不再希望推送包，还可以删除 API 密钥。

范围允许创建针对不同用途的单独 API 密钥。 每个密钥都有其过期时间，并且可以将范围限定为特定包（或 glob 模式）。 每个密钥还将范围限定为特定操作：新包和更新推送、仅更新推送，或者从列表中删除。 通过范围限定，可以为管理组织不同包的不同人员创建 API 密钥，这样他们就只有所需的权限。

使用 dotnet CLI 或 nuget.exe CLI 发布

选择 CLI 工具（.NET Core CLI (dotnet CLI) 或 NuGet (nuget.exe CLI)）对应的选项卡。

.NET Core CLI

此步骤是使用 nuget.exe 的推荐替代方法。

在发布包之前，必须先打开命令行。

更改到包含 .nupkg 文件的文件夹。

运行以下命令，指定包名称（唯一包 ID）并使用你的 API 密钥替换密钥值：

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

dotnet 会显示发布过程的结果：

info : Pushing AppLogger.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
info :   PUT https://www.nuget.org/api/v2/package/
info :   Created https://www.nuget.org/api/v2/package/ 12620ms
info : Your package was pushed.

NuGet

该步骤是使用 dotnet.exe 的替代方法。

打开命令行并更改到包含 .nupkg 文件的文件夹。

运行以下命令，指定包名称（唯一包 ID）并使用你的 API 密钥替换密钥值：

nuget push AppLogger.1.0.0.nupkg qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 -Source https://api.nuget.org/v3/index.json

nuget.exe 会显示发布过程的结果：

Pushing AppLogger.1.0.0.nupkg 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.

发布错误

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

尝试使用主机上已存在的标识符发布包时，你也会看到错误。 例如，名称“AppLogger”已经存在。 在这种情况下，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. 在 nuget.org 上，选择用户名（在该页的右上角），然后选择“管理包”。
2. 找到你需要在“已发布”下取消列出的包，然后选择右侧的回收站图标：

1. 在随后的页面上，清除标记有“在搜索结果中列出(包名)”的框，然后选择“保存”：

添加自述文件和其他文件

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

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

这将在包根目录中包含一个名为 readme.txt 的文件。 Visual Studio 在直接安装包之后立即将该文件的内容显示为纯文本。 （对于安装为依赖项的包，不会显示自述文件）。 例如，下面是 HtmlAgilityPack 包的自述文件的显示方式：

 备注

只在项目根目录添加 readme.txt 不会导致它被包含在生成的包中。