通过

使用 MSBuild 创建 NuGet 包

从代码创建 NuGet 包时，可将该功能打包到可以与其他任意数量的开发人员共享和使用的组件中。 本文介绍如何使用 MSBuild 创建包。 MSBuild 预安装了包含 NuGet 的每个 Visual Studio 工作负载。 此外，还可以通过 dotnet CLI 和 dotnet msbuild 使用 MSBuild。

对于使用 SDK 样式格式的 .NET Core 和 .NET Standard 项目，NuGet 直接使用项目文件中的信息来创建包。 对于使用 <PackageReference>的非 SDK 样式项目，NuGet 还使用项目文件创建包。

默认情况下，SDK 样式项目具有可用的包功能。 对于非 SDK 样式的 PackageReference 项目，从 Visual Studio 2026 开始，它默认也可用。 在早期版本的 Visual Studio 中，需要将 NuGet.Build.Tasks.Pack 包添加到项目依赖项，建议在升级到 Visual Studio 2026 时删除此包引用。 有关 MSBuild 包目标的详细信息，请参阅 NuGet 包并还原为 MSBuild 目标。

对于 SDK 样式的项目， msbuild -t:pack 在功能上等效于 dotnet pack.

重要

本主题适用于 SDK 样式 项目（通常是 .NET Core 和 .NET Standard 项目），以及使用 PackageReference 的非 SDK 样式项目。

设置属性

创建包需要以下属性。

  • PackageId，包标识符，该标识符在承载包的库中必须是唯一的。 如果未指定，默认值为 AssemblyName。
  • Version，一个特定版本号，格式为 Major.Minor.Patch[-Suffix] ，其中 -Suffix 标识 预发行版本。 如果未指定，则默认值为 1.0.0。
  • 程序包标题，因为它应出现在主机上（如 nuget.org）
  • Authors、作者和所有者信息。 如果未指定，默认值为 AssemblyName。
  • Company，您的公司名称。 如果未指定，默认值为 AssemblyName。

此外，如果要打包使用 PackageReference 的非 SDK 样式项目，则需要满足以下条件：

  • PackageOutputPath，调用包时生成的包的输出文件夹。

在 Visual Studio 中，可以在项目属性中设置这些值（右键单击解决方案资源管理器中的项目，选择 “属性”，然后选择“ 包 ”选项卡）。 还可以直接在项目文件中设置这些属性（.csproj）。

<PropertyGroup>
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>your_name</Authors>
  <Company>your_company</Company>
</PropertyGroup>

重要

为包提供在 nuget.org 或任何正在使用的包源中唯一的标识符。

以下示例显示了包含这些属性的简单完整项目文件。

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>ClassLibDotNetStandard</PackageId>
    <Version>1.0.0</Version>
    <Authors>your_name</Authors>
    <Company>your_company</Company>
  </PropertyGroup>
</Project>

还可以设置可选属性，如 TitlePackageDescriptionPackageTagsMSBuild 包目标、控制依赖项资产和 NuGet 元数据属性中所述。

注释

对于为公共使用的包，请特别注意 PackageTags 属性，因为标记可帮助其他人找到包并了解它的作用。

有关声明依赖项和指定版本号的详细信息，请参阅项目文件和包版本控制中的包引用。 还可以使用 <IncludeAssets> 和 <ExcludeAssets> 属性直接从包中的依赖项中显示资产。 有关详细信息，请参阅 控制依赖项资产。

添加可选说明字段

包的可选说明显示在包 nuget.org 页的 自述 文件选项卡上。 说明从项目文件中的 或 .nuspec 文件中的 提取。

以下示例展示了 .csproj 文件中 .NET 包的 Description。

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageId>Azure.Storage.Blobs</PackageId>
    <Version>12.4.0</Version>
    <PackageTags>Microsoft Azure Storage Blobs;Microsoft;Azure;Blobs;Blob;Storage;StorageScalable</PackageTags>
    <Description>
      This client library enables working with the Microsoft Azure Storage Blob service for storing binary and text data.
      For this release see notes - https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md and https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/CHANGELOG.md
      in addition to the breaking changes https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/BreakingChanges.txt
      Microsoft Azure Storage quickstarts and tutorials - https://free.blessedness.top/azure/storage/
      Microsoft Azure Storage REST API Reference - https://free.blessedness.top/rest/api/storageservices/
      REST API Reference for Blob Service - https://free.blessedness.top/rest/api/storageservices/blob-service-rest-api
    </Description>
  </PropertyGroup>
</Project>

选择唯一的包标识符并设置版本号

包标识符和版本号唯一标识包中包含的确切代码。

按照以下最佳做法创建包标识符：

  • 该标识符必须在 nuget.org 和承载包的所有其他位置 唯一。 为了避免冲突，良好的模式是使用公司名称作为标识符的第一部分。

  • 使用点符号表示法，遵循 .NET 命名空间式命名约定。 例如，使用 Contoso.Utility.UsefulStuff 而不是 Contoso-Utility-UsefulStuff 或 Contoso_Utility_UsefulStuff。 如果将包标识符与代码使用的命名空间匹配，这对使用者也很有帮助。

  • 如果生成示例 代码 包，演示如何使用另一个包，请追加 .Sample 到标识符，如中所示 Contoso.Utility.UsefulStuff.Sample。

    示例包依赖于原始包。 创建示例包时，请添加值为 contentFiles 的 <IncludeAssets> 。 在 内容 文件夹中，排列名为 \Samples\<identifier> 的文件夹中的示例代码，例如 \Samples\Contoso.Utility.UsefulStuff.Sample。

遵循以下最佳做法设置包版本：

  • 通常，将包版本设置为 与项目或程序集版本匹配，尽管这并非严格要求。 将包限制为单个程序集时，匹配版本非常简单。 NuGet 本身在解析依赖项时处理包版本，而不是程序集版本。

  • 如果使用非标准版本方案，请务必考虑 NuGet 版本控制规则 ，如 包版本控制中所述。 NuGet 主要符合 语义版本控制 2.0.0。

注释

有关依赖项解析的详细信息，请参阅 带 PackageReference 的依赖项解析。 有关可能有助于了解版本控制的信息，请参阅以下系列博客文章：

为打包配置项目

SDK 样式项目不需要任何其他配置。

非 SDK 样式项目至少需要安装一个包（通过 PackageReference，而不是 packages.config），或者项目显式需要指示 NuGet 通过 RestoreProjectStyle 属性将项目视为 PackageReference 项目。

Visual Studio 2022 及更早版本没有内置包，因此还需要安装 NuGet.Build.Tasks.Pack 包。 升级到 Visual Studio 2026 或更高版本时，建议卸载包，以便受益于新功能和 bug 修复。

  1. 编辑项目文件。

    如果要显式指示 NuGet 将项目视为 PackageReference（项目未安装任何包），请查找或添加 <PropertyGroup> 不包含任何 Condition 语句的项，并添加：

    <PropertyGroup>
  <!-- other properties -->
  <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
  <!-- more properties are allowed -->
</PropertyGroup>

    如果使用 Visual Studio 2022 或更早版本，请在元素后面 <PropertyGroup> 添加以下内容：

    <ItemGroup>
  <!-- ... -->
  <PackageReference Include="NuGet.Build.Tasks.Pack" Version="6.14.0" PrivateAssets="all" />
  <!-- ... -->
</ItemGroup>

    注释

    请考虑使用此包的最新版本。

  2. 打开开发人员命令提示符（在 搜索 框中，键入 开发人员命令提示符）。

    通常想要从 “开始” 菜单启动 Visual Studio 的开发人员命令提示符，因为它将配置 MSBuild 所需的所有路径。

  3. 切换到包含项目文件的文件夹，然后键入以下命令以还原 NuGet.Build.Tasks.Pack 包。

    # Uses the project file in the current folder by default
msbuild -t:restore

    确保 MSBuild 输出指示生成已成功完成。

运行 msbuild -t：pack 命令

若要从项目生成 NuGet 包（ .nupkg 文件），请运行 msbuild -t:pack 该命令，该命令也会自动生成项目：

在 Visual Studio 的开发人员命令提示符中，键入以下命令：

# Uses the project file in the current folder by default
msbuild -t:pack

输出显示 .nupkg 文件的路径。

Microsoft (R) Build Engine version 16.1.76+g14b0a930a7 for .NET Framework
Copyright (C) Microsoft Corporation. All rights reserved.

Build started 8/5/2019 3:09:15 PM.
Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" on node 1 (pack target(s)).
GenerateTargetFrameworkMonikerAttribute:
Skipping target "GenerateTargetFrameworkMonikerAttribute" because all output files are up-to-date with respect to the input files.
CoreCompile:
  ...
CopyFilesToOutputDirectory:
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.dll" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll".
  ClassLib_DotNetStandard -> C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb".
GenerateNuspec:
  Successfully created package 'C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\AppLogger.1.0.0.nupkg'.
Done Building Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" (pack target(s)).

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:01.21

构建时自动生成软件包

若要在生成或还原项目时自动运行 msbuild -t:pack ，请将以下行添加到项目文件中 <PropertyGroup>：

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

msbuild -t:pack在解决方案上运行时，这会打包可打包的解决方案中的所有项目（<IsPackable>属性设置为 true）。

注释

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

测试包安装

在发布包之前，通常需要测试将包安装到项目中的过程。 测试确保必要的文件最终都正确地放置在项目中。

可以使用常规 包安装步骤在 Visual Studio 或命令行中手动测试安装。

重要

包是不可变的。 如果你解决了问题，并更改了包内容并重新打包，当你重新测试时，你仍将使用包的旧版本，直到清除你的全局包文件夹。 在测试未在每个构建上使用唯一预发行标识的包时，这尤其相关。

后续步骤

创建包（即 .nupkg 文件）后，即可将其发布到所选库，如 发布包中所述。

你可能还希望扩展包的功能，或者支持其他方案，如以下主题中所述：

最后，需要注意其他包类型：