快速入门：使用 dotnet CLI 创建和发布包

  • 项目

本快速入门介绍如何从 .NET 类库快速创建 NuGet 包，并使用 .NET 命令行接口或 dotnet CLI 将其发布到 nuget.org。

先决条件

  • .NET SDK，提供 dotnet 命令行工具。 从 Visual Studio 2017 开始，dotnet CLI 将自动随任何 .NET 或 .NET Core 相关工作负荷一起安装。

  • nuget.org 的免费帐户。按照“添加新个人帐户”中的说明操作。

创建类库项目

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

  1. 创建一个名为 AppLogger 的文件夹。
  2. 打开命令提示符并切换到 AppLogger 文件夹。 本快速入门中的所有 dotnet CLI 命令默认在当前文件夹中运行。
  3. 输入 dotnet new classlib，用于创建具有当前文件夹名称的项目。

有关详细信息，请查看 dotnet new。

将包元数据添加到项目文件

每个 NuGet 包都有一个清单，用以描述包的内容和依赖项。 在最终包中，清单是一个 .nuspec 文件，使用你在项目文件中包含的 NuGet 元数据属性。

打开.csproj、.fproj 或 .vbproj 项目文件，并在现有 <PropertyGroup> 标记中添加以下属性。 对名称和公司使用自己的值，并将包标识符替换为唯一值。

<PackageId>Contoso.08.28.22.001.Test</PackageId>
<Version>1.0.0</Version>
<Authors>your_name</Authors>
<Company>your_company</Company>

重要

包标识符在 nuget.org 和其他包源中必须是唯一的。 发布会使包公开可见，因此如果使用 AppLogger 示例库或其他测试库，请使用包含 Sample 或 Test 的唯一名称。

你可以在 NuGet 元数据属性中添加描述的任何可选属性。

注意

对于为公共消耗而生成的包，请特别注意该 PackageTags 属性。 标记可帮助其他人找到你的包并了解它的作用。

运行 pack 命令

若要从项目中生成 NuGet 包或 .nupkg 文件，请运行 dotnet pack 命令，该命令也会自动生成项目。

dotnet pack

输出将显示 .nupkg 文件的路径：

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored C:\Users\myname\source\repos\AppLogger\AppLogger.csproj (in 64 ms).
  AppLogger -> C:\Users\myname\source\repos\AppLogger\bin\Debug\net6.0\AppLogger.dll
  Successfully created package 'C:\Users\myname\source\repos\AppLogger\bin\Debug\Contoso.08.28.22.001.Test.1.0.0.nupkg'.

在生成期间自动生成包

若要在运行 dotnet build 时都自动运行 dotnet pack，请将以下行添加到 <PropertyGroup> 中的项目文件内：

    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>

发布包

将 .nupkg 文件发布到 nuget.org，方法是将 dotnet nuget push 命令与从 nuget.org 获取的 API 密钥配合使用。

注意

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

  • 你发布到 nuget.org 的包对其他开发者公开可见，除非你取消列出它们。 若要私下托管包，请参阅托管自己的 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 密钥。

用 dotnet nuget push 发布

从包含 .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 的包可能不会保留。

祝贺你创建并发布第一个 NuGet 包！

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

后续步骤

请参阅有关如何使用 dotnet CLI 创建包的更多详细信息：

使用 dotnet CLI 创建 NuGet 包

获取有关创建和发布 NuGet 包的详细信息：