通过

快速入门：使用 Visual Studio 创建和发布包（.NET Framework、Windows）

  • 项目

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

本快速入门仅适用于 Windows 用户。 如果使用的是 Visual Studio for Mac，请改为查看 dotnet CLI 工具。

先决条件

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

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

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

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

  • 要安装 NuGet CLI，从 nuget.org 下载它，将 nuget.exe 文件添加到合适的文件夹，然后将该文件夹添加到 PATH 环境变量中。

创建类库项目

若要创建类库项目，请按照下列步骤操作：

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

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

  3. 在生成的项目模板列表中，选择“类库”（.NET 框架），然后选择“下一步”。

  4. 在“配置新项目”窗口中，输入“AppLogger”作为“项目名称”，然后选择“创建”。

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

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

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

    当然，在实际的 NuGet 包中，你很可能实现许多有用的功能，让其他人可通过这些功能生成应用程序。 还可以设置目标框架。 有关示例，请参阅 UWP 和 Xamarin。

配置包的项目属性

NuGet 包中包括清单（.nuspec 文件），其中包含相关的元数据，例如包标识符、版本号和描述等。 其中一些元数据可以直接从项目属性中获取，避免在项目和清单中对其进行单独更新。 以下步骤介绍如何设置适用的属性：

  1. 选择“项目 > 属性”，然后选择“应用程序”选项卡。

  2. 对于程序集名称，为包提供唯一标识符。 如果你尝试发布名称已存在的包，则会看到一个错误。

    重要

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

  3. 选择“程序集信息，此时会显示一个对话框，可在其中输入清单中的其他属性（请参阅替换令牌）。 最常用的字段是“标题”、“描述”、“公司”、“版权所有”和“程序集版本”。 因为这些属性在发布后会随包出现在主机上（例如 nuget.org ），因此请确保对其进行完整描述。

    Screenshot showing the Assembly Information page in a .NET Framework project in Visual Studio.

  4. （可选）若要直接查看和编辑属性，请选择“项目>”“编辑项目文件”，在项目中打开 Properties/AssemblyInfo.cs 文件。

  5. 设置这些属性后，将“生成>”“配置管理器”中的“活动解决方案配置”设置为“发布”，然后重建项目以生成更新的 DLL。

生成初始清单

设置项目属性并创建 DLL 后，现在可以从项目生成初始 .nuspec 文件。 此步骤包括相关替换令牌，便于从项目文件中提取信息。

仅运行 nuget spec 一次即可生成初始清单。 如果更新包，可以更改项目中的值或直接编辑清单。

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

    命令提示符将在 AppLogger.csproj 文件所在的项目目录中打开。

  2. 运行以下命令：nuget spec AppLogger.csproj。

    NuGet 会创建匹配项目名称的清单，在此示例中为 AppLogger.nuspec。 它还会包括清单中的替换令牌。

  3. 在文本编辑器中打开 AppLogger.nuspec 可检查其内容，其内容将类似于以下代码：

    <?xml version="1.0"?>
<package >
  <metadata>
    <id>Package</id>
    <version>1.0.0</version>
    <authors>Your username</authors>
    <owners>Your username</owners>
    <license type="expression">MIT</license>
    <!-- <icon>icon.png</icon> -->
    <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Package description</description>
    <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
    <copyright>Copyright 2022</copyright>
    <tags>Tag1 Tag2</tags>
  </metadata>
</package>

编辑清单

  1. 继续操作之前，请编辑以下属性。 否则，如果尝试使用.nuspec 文件中的默认值创建 NuGet 包，则会发生错误。 有关这些属性的信息，请参阅可选元数据元素：

    • licenseUrl
    • projectUrl
    • releaseNotes
    • 标记

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

  3. 你也可以在此时向清单中添加任何其他元素，如 .nuspec 文件引用中所述。

  4. 在继续之前保存文件。

运行 pack 命令

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

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

  2. 运行以下命令：nuget pack。

    NuGet 以 identifier.version.nupkg 形式在当前文件夹中生成 .nupkg 文件。

发布包

创建 .nupkg 文件后，使用 NuGet CLI 和从 nuget.org 获取的 API 密钥将其发布到 nuget.org。对于 nuget.org，则必须使用 nuget.exe 4.1.0 或更高版本。

如果要在将包发布到公共库之前对其进行测试和验证，可以将它上传到测试环境，例如 int.nugettest.org 而不是 nuget.org。请注意，上传到 int.nugettest.org 的包可能无法保留。

注意

  • 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 密钥。

使用 NuGet CLI 进行发布

使用 NuGet CLI (nuget.exe) 是使用 .NET CLI 的替代方法：

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

  2. 运行以下命令。 将<包文件名>替换为包的文件名，并将 <API 密钥值>替换为 API 密钥。 包文件名是包 ID 和版本号与 .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。

发布错误

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

后续步骤

恭喜你使用 Visual Studio .NET Framework 创建了 NuGet 包。 进入下一篇文章，了解如何使用 NuGet CLI 创建 NuGet 包。

使用 NuGet CLI 创建包

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