NuGetNuGet

NuGet 是 .NET 生态系统的包管理器,并且是开发人员用来发现并获取 .NET 开放源代码库的主要方法。NuGet is a package manager for the .NET ecosystem and is the primary way developers discover and acquire .NET open-source libraries. NuGet.org(由托管 NuGet 包的 Microsoft 提供的免费服务)是公共 NuGet 包的主要主机,但可以发布到自定义 NuGet 服务,如 MyGetAzure ArtifactsNuGet.org, a free service provided by Microsoft for hosting NuGet packages, is the primary host for public NuGet packages, but you can publish to custom NuGet services like MyGet and Azure Artifacts.

NuGetNuGet

创建 NuGet 包Create a NuGet package

NuGet 包 (*.nupkg) 是一个 zip 文件,其中包含 .NET 程序集和关联的元数据。A NuGet package (*.nupkg) is a zip file that contains .NET assemblies and associated metadata.

创建 NuGet 包有两种主要方式。There are two main ways to create a NuGet package. 较新的推荐方式是从 SDK 样式项目(其内容以 <Project Sdk="Microsoft.NET.Sdk"> 开头的项目文件)创建包。The newer and recommended way is to create a package from a SDK-style project (project file whose content starts with <Project Sdk="Microsoft.NET.Sdk">). 程序集和目标会自动添加到包,剩余元数据会添加到 MSBuild 文件,如包名称和版本号。Assemblies and targets are automatically added to the package and remaining metadata is added to the MSBuild file, like package name and version number. 使用 dotnet pack 命令编译会输出 *.nupkg 文件,而不是程序集。Compiling with the dotnet pack command outputs a *.nupkg file instead of assemblies.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <AssemblyName>Contoso.Api</AssemblyName>
    <PackageVersion>1.1.0</PackageVersion>
    <Authors>John Doe</Authors>
  </PropertyGroup>
</Project>

创建 NuGet 包的较旧方式是使用 *.nuspec 文件和 nuget.exe 命令行工具。The older way of creating a NuGet package is with a *.nuspec file and the nuget.exe command-line tool. nuspec 文件为你提供更好的控制,但必须仔细指定要包含在最终 NuGet 包中的程序集和目标。A nuspec file gives you great control but you must carefully specify what assemblies and targets to include in the final NuGet package. 很容易犯错或很容易忘记在发生更改时更新 nuspec。It's easy to make a mistake or for someone to forget to update the nuspec when making changes. nuspec 的优点是可以将其用于创建尚不支持 SDK 样式项目文件的框架的 NuGet 包。The advantage of a nuspec is you can use it create NuGet packages for frameworks that don't yet support an SDK-style project file.

✔️ 请考虑使用 SDK 样式项目文件创建 NuGet 包。✔️ CONSIDER using an SDK-style project file to create the NuGet package.

包依赖项Package dependencies

依赖项一文详细介绍了 NuGet 包依赖项。NuGet package dependencies are covered in detail in the Dependencies article.

重要的 NuGet 包元数据Important NuGet package metadata

NuGet 包支持多个元数据属性A NuGet package supports many metadata properties. 下表包含 NuGet.org 上的每个包应提供的核心元数据:The following table contains the core metadata that every package on NuGet.org should provide:

MSBuild 属性名称MSBuild Property name Nuspec 名称Nuspec name 描述Description
PackageId id 包标识符。The package identifier. 如果标识符的前缀满足条件,则可以保留该前缀。A prefix from the identifier can be reserved if it meets the criteria.
PackageVersion version NuGet 包版本。NuGet package version. 有关详细信息,请参阅 NuGet 包版本For more information, see NuGet package version.
Title title 明了易用的包标题。A human-friendly title of the package. 默认为 PackageIdIt defaults to the PackageId.
Description description UI 中显示的包的详细说明。A long description of the package displayed in UI.
Authors authors 包创建者的逗号分隔列表,与 nuget.org 上的配置文件名称一致。A comma-separated list of package authors, matching the profile names on nuget.org.
PackageTags tags 描述包的标记和关键字的空格分隔列表。A space-delimited list of tags and keywords that describe the package. 搜索包时使用标记。Tags are used when searching for packages.
PackageIcon icon 包中要用作包图标的图像的路径。A path to an image in the package to use as a package icon. 详细了解 icon 元数据Read more about icon metadata.
PackageProjectUrl projectUrl 项目主页或源存储库的 URL。A URL for the project homepage or source repository.
PackageLicenseExpression license 项目许可证的 SPDX 标识符The project license's SPDX identifier. 只有获得 OSI 和 FSF 批准的许可证才能使用标识符。Only OSI and FSF approved licenses can use an identifier. 其他许可证应使用 PackageLicenseFileOther licenses should use PackageLicenseFile. 详细了解 license 元数据Read more about license metadata.

重要

无许可证的项目默认为 exclusive copyright(独占版权所有),从而无法供其他人使用。A project without a license defaults to exclusive copyright, making it legally impossible for other people to use.

✔️ 请考虑选择带有满足 NuGet 前缀预留条件的前缀的 NuGet 包名称。✔️ CONSIDER choosing a NuGet package name with a prefix that meets NuGet's prefix reservation criteria.

✔️ 请使用指向包图标的 HTTPS href。✔️ DO use an HTTPS href to your package icon.

启用 HTTPS 运行并显示非 HTTPS 图像的 NuGet.org 等网站将创建混合内容警告。Sites like NuGet.org run with HTTPS enabled and displaying a non-HTTPS image will create a mixed content warning.

✔️ 请使用属于 64x64 并具有透明背景的包图标图像以获得最佳查看结果。✔️ DO use a package icon image that is 64x64 and has a transparent background for best viewing results.

✔️ 请考虑设置源链接以将源代码管理元数据添加到程序集和 NuGet 包中。✔️ CONSIDER setting up Source Link to add source control metadata to your assemblies and NuGet package.

源链接会自动将 RepositoryUrlRepositoryType 元数据添加到 NuGet 包中。Source Link automatically adds RepositoryUrl and RepositoryType metadata to the NuGet package. 源链接还会添加用于构建包的确切源代码的相关信息。Source Link also adds information about the exact source code the package was built from. 例如,从 Git 存储库创建的包将添加提交哈希作为元数据。For example, a package created from a Git repository will have the commit hash added as metadata.

预发行包Pre-release packages

具有版本后缀的 NuGet 包被视为预发行版NuGet packages with a version suffix are considered pre-release. 默认情况下,NuGet 包管理器 UI 显示稳定版本,除非用户选择预发行包,使预发行包适用于受限的用户测试。By default, the NuGet Package Manager UI shows stable releases unless a user opts-in to pre-release packages, making pre-release packages ideal for limited user testing.

<PackageVersion>1.0.1-beta1</PackageVersion>

备注

稳定版包不能依赖于预发行包。A stable package cannot depend on a pre-release package. 必须创建自己的预发行包或依赖于较旧的稳定版本。You must either make your own package pre-release or depend on an older stable version.

NuGet 预发布版本包依赖项NuGet pre-release package dependency

✔️ 请在测试、预览或试用预发行包后进行发布。✔️ DO publish a pre-release package when testing, previewing, or experimenting.

✔️ 请在稳定版包就绪后进行发布,以便其他稳定版包可以引用它。✔️ DO publish a stable package when its ready so other stable packages can reference it.

符号包Symbol packages

符号文件 (*.pdb) 由 .NET 编译器与程序集一起生成。Symbol files (*.pdb) are produced by the .NET compiler alongside assemblies. 符号文件将执行位置映射到原始源代码,以便可以逐行执行源代码(因为它使用调试程序运行)。Symbol files map execution locations to the original source code so you can step through source code as it is running using a debugger. NuGet 支持生成单独的符号包 (*.snupkg)(包含符号文件)以及主包(包含 .NET 程序集)。NuGet supports generating a separate symbol package (*.snupkg) containing symbol files alongside the main package containing .NET assemblies. 符号包的理念是它们托管在符号服务器上并仅由 Visual Studio 等工具按需下载。The idea of symbol packages is they're hosted on a symbol server and are only downloaded by a tool like Visual Studio on demand.

NuGet.org 托管了自己的符号服务器存储库NuGet.org hosts its own symbols server repository. 开发人员可以通过向其在 Visual Studio 中的符号源添加 https://symbols.nuget.org/download/symbols,来使用发布到 NuGet.org 符号服务器的符号。Developers can use the symbols published to the NuGet.org symbol server by adding https://symbols.nuget.org/download/symbols to their symbol sources in Visual Studio.

重要

NuGet.org 符号服务器仅支持由 SDK 样式项目创建的新的可移植符号文件 (*.pdb)。The NuGet.org symbol server only supports the new portable symbol files (*.pdb) created by SDK-style projects.

若要在调试 .NET 库时使用 NuGet.org 符号服务器,开发人员必须安装有 Visual Studio 2017 版本 15.9 或更高版本。To use the NuGet.org symbol server when debugging a .NET library, developers must have Visual Studio 2017 version 15.9 or later.

创建符号包的另一种方法是在主 NuGet 包中嵌入符号文件。An alternative to creating a symbol package is embedding symbol files in the main NuGet package. 主 NuGet 包将变大,但嵌入的符号文件意味着开发人员不需要配置 NuGet.org 符号服务器。The main NuGet package will be larger, but the embedded symbol files means developers don't need to configure the NuGet.org symbol server. 如果使用 SDK 样式项目生成 NuGet 包,则可以通过设置 AllowedOutputExtensionsInPackageBuildOutputFolder 属性来嵌入符号文件:If you're building your NuGet package using an SDK-style project, then you can embed symbol files by setting the AllowedOutputExtensionsInPackageBuildOutputFolder property:

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
    <!-- Include symbol files (*.pdb) in the built .nupkg -->
    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
  </PropertyGroup>
</Project>

嵌入式符号文件的缺点是,对于使用 SDK 样式项目编译的 .NET 库,它们会将包的大小增加约 30%。The downside of embedding symbol files is that they increase the package size by about 30% for .NET libraries compiled using SDK-style projects. 如果要考虑包大小,应改成在符号包中发布符号。If package size is a concern, you should publish symbols in a symbol package instead.

✔️ 请考虑将符号作为符号包 (*.snupkg) 发布到 NuGet.org✔️ CONSIDER publishing symbols as a symbol package (*.snupkg) to NuGet.org

符号包 (*.snupkg) 为开发人员提供了良好的按需调试体验,而不会使主程序包大小膨胀,也不会影响那些不打算调试 NuGet 包的用户的还原性能。Symbol packages (*.snupkg) provide developers a good on-demand debugging experience without bloating the main package size and impacting restore performance for those who don't intend to debug the NuGet package.

需要注意的是,用户可能需要在其 IDE 中查找和配置 NuGet 符号服务器(作为一次性设置)来获取符号文件。The caveat is that users may need to find and configure the NuGet symbol server in their IDE (as a one-time setup) to get symbol files. Visual Studio 2019 版本 16.1 将 NuGet.org 的符号服务器添加到了默认符号服务器列表中。Visual Studio 2019 version 16.1 added NuGet.org's symbol server to the list of default symbol servers.