Nuspec 引用

.nuspec 文件是包含包元数据的 XML 清单。 此清单同时用于生成包以及为使用者提供信息。 清单始终包含在包中。

本主题内容：

• 常规形式和架构
• 替换令牌（用于 Visual Studio 项目时）
• 依赖项
• 显式程序集引用
• Framework 程序集引用
• 包括程序集文件
• 包括内容文件
• nuspec 示例文件

项目类型兼容性

• 将具有 nuget.exe pack 的 .nuspec 用于采用 packages.config 的非 SDK 式项目。

• 不需要使用 .nuspec 文件来为 SDK 式项目创建包（通常为使用 SDK 属性的 .NET Core 和 .NET Standard 项目）。 （请注意，创建包时会生成一个 .nuspec。）

  如果使用 dotnet.exe pack 或 msbuild pack target 来创建包，则建议改为在项目文件中包含通常位于 .nuspec 文件中的所有属性。 但是，可改为选择使用 .nuspec 文件从而借助 dotnet.exe 或 msbuild pack target 来打包。

• 对于从 packages.config 迁移到 PackageReference 的项目，创建包不需要使用 .nuspec 文件。 此时，应使用 msbuild -t:pack。

常规形式和架构

nuspec.xsd 架构文件可在 NuGet GitHub 存储库中找到。 请注意，此文件仅代表 .nuspec 文件的最新架构。 没有正式发布的版本存在，并且该文件的任何版本都与 NuGet 版本没有对应关系。

在此构架中，.nuspec 文件具有以下常规形式：

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Required elements-->
        <id></id>
        <version></version>
        <description></description>
        <authors></authors>

        <!-- Optional elements -->
        <!-- ... -->
    </metadata>
    <!-- Optional 'files' node -->
</package>

有关架构的清晰可视表示形式，请在 Visual Studio 中以“设计”模式打开架构文件，然后单击“XML 架构资源管理器”链接。 或者，将该文件作为代码打开，在编辑器中右键单击，然后选择“显示 XML 架构资源管理器”。 无论哪种方式，都会获得如下所示的视图（大多数部件都处于扩展状态）：

.nuspec 文件中的所有 XML 元素名称均区分大小写，如同常规 XML 一样。 例如，使用元数据元素 <description> 正确，但使用 <Description> 则不正确。 每个元素名称的正确大小写记录如下。

重要

虽然 .nuspec 文件中包含对于架构 (xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd") 引用，但 NuGet-Team 从未发布过可用于自动架构验证的架构文件。

所需的元数据元素

尽管以下元素是包的最低要求，但应该考虑添加可选元数据元素以改善开发人员对包的整体体验。

这些元素必须出现在 <metadata> 元素中。

id

不区分大小写的包标识符，在 nuget.org 或包驻留的任意库中必须是唯一的。 ID 不得包含空格或对 URL 无效的字符，通常遵循 .NET 命名空间规则。 有关指南，请参阅选择唯一的包标识符。

将包上传到 nuget.org 时，id 字段被限制为 128 个字符。

版本

遵循 major.minor.patch 模式的包版本。 版本号可能包括预发布后缀，如包版本控制中所述。

将包上传到 nuget.org 时，version 字段被限制为 64 个字符。

description

用于 UI 显示的包的说明。

将包上传到 nuget.org 时，description 字段被限制为 4,000 个字符。

作者

包作者的逗号分隔列表。 将包上传到 nuget.org 时，忽略来自 nuspec 的 authors 和 owners。若要在 nuget.org 上设置包所有权，请参阅在 nuget.org 上管理包所有者。

可选元数据元素

owners

重要

所有者已被弃用。 请改用作者。

包所有者的逗号分隔列表。 将包上传到 nuget.org 时，忽略来自 nuspec 的 owners。若要在 nuget.org 上设置包所有权，请参阅在 nuget.org 上管理包所有者。

projectUrl

包的主页 URL，通常显示在 UI 中以及 nuget.org 中。

将包上传到 nuget.org 时，projectUrl 字段被限制为 4,000 个字符。

licenseUrl

重要

licenseUrl 已被弃用。 请改用许可证。

包许可证的 URL，它通常显示在 nuget.org 等 UI 中。

将包上传到 nuget.org 时，licenseUrl 字段被限制为 4,000 个字符。

license

受到 NuGet 4.9.0 及更高版本的支持

包中许可证文件的 SPDX 许可证表达式或路径，它通常显示在 nuget.org 等 UI 中。如果要根据常用许可证（如 MIT 或 BSD-2-Clause）来对包进行许可，请使用关联的 SPDX 许可证标识符。 例如：

<license type="expression">MIT</license>

注意

NuGet.org 仅接受开放源代码计划或免费软件基金会批准的许可证表达式。

如果要根据多个常用许可证对包进行许可，则可使用 SPDX 表达式语法版本 2.0 来指定复合许可证。 例如：

<license type="expression">BSD-2-Clause OR MIT</license>

如果使用许可证表达式不支持的自定义许可证，则可使用许可证的文本来打包 .txt 或 .md 文件。 例如：

<package>
  <metadata>
    ...
    <license type="file">LICENSE.txt</license>
    ...
  </metadata>
  <files>
    ...
    <file src="licenses\LICENSE.txt" target="" />
    ...
  </files>
</package>

有关 MSBuild 等效项的信息，请参阅打包许可证表达式或许可证文件。

NuGet 的许可证表达式的准确语法如以下 ABNF 所述。

license-id            = <short form license identifier from https://spdx.org/spdx-specification-21-web-version#h.luq9dgcle9mo>

license-exception-id  = <short form license exception identifier from https://spdx.org/spdx-specification-21-web-version#h.ruv3yl8g6czd>

simple-expression = license-id / license-id”+”

compound-expression =  1*1(simple-expression /
                simple-expression "WITH" license-exception-id /
                compound-expression "AND" compound-expression /
                compound-expression "OR" compound-expression ) /                
                "(" compound-expression ")" )

license-expression =  1*1(simple-expression / compound-expression / UNLICENSED)

iconUrl

重要

iconUrl 已被弃用。 请改用图标。

128x128 透明背景图像的 URL，它可用作 UI 显示中包的图标。 请确保此元素包含直接图像 URL，而不是包含图像的网页的 URL。 例如，若要使用 GitHub 中的图像，请使用如下所示的原始文件 URL：https://github.com/<username>/<repository>/raw/<branch>/<logo.png>。

将包上传到 nuget.org 时，iconUrl 字段被限制为 4,000 个字符。

图标

受到 NuGet 5.3.0 及更高版本的支持

它是包中图像文件的路径，且通常以包图标的形式显示在 nuget.org 一类的 UI 中。 图像文件大小被限制为 1 MB。 支持的文件格式为 JPEG 和 PNG。 建议使用分辨率为 128x128 的图像。

例如，使用 nuget.exe 创建包时，需将以下内容添加到 nuspec：

<package>
  <metadata>
    ...
    <icon>images\icon.png</icon>
    ...
  </metadata>
  <files>
    ...
    <file src="..\icon.png" target="images\" />
    ...
  </files>
</package>

包图标 nuspec 示例。

有关 MSBuild 等效项的信息，请查看打包图标图像文件。

提示

若要保持与尚不支持 icon 的客户端和源的向后兼容性，则请同时指定 icon 和 iconUrl。 Visual Studio 支持来自基于文件夹的源的包的对应 icon。

自述文件

受到 NuGet 5.10.0 预览版 2 和更高版本的支持

打包自述文件时，需使用 readme 元素来指定相对于包的根目录的包路径。 除此之外，还需确保此文件包含在包中。 支持的文件格式仅为 Markdown (.md)。

例如，要将自述文件与项目一起打包，则需将以下内容添加到 nuspec：

<package>
  <metadata>
    ...
    <readme>docs\readme.md</readme>
    ...
  </metadata>
  <files>
    ...
    <file src="..\readme.md" target="docs\" />
    ...
  </files>
</package>

有关 MSBuild 等效项的信息，请查看打包自述文件。

requireLicenseAcceptance

一个布尔值，用于指定客户端是否必须提示使用者接受包许可证后才可安装包。

developmentDependency

(2.8+) 一个布尔值，用于指定包是否被标记为仅开发依赖项，从而防止包作为依赖项包含到其他包中。 利用 PackageReference (NuGet 4.8+)，此标志还意味着将从编译中排除编译时资产。 请参阅针对 PackageReference 的 DevelopmentDependency 支持

summary

重要

summary 即将被弃用。 请改用 description。

用于 UI 显示的包的简要说明。 如果省略，则使用 description 的截断版本。

将包上传到 nuget.org 时，summary 字段被限制为 4,000 个字符。

releaseNotes

(1.5+) 此版本包中所作更改的说明，通常代替包说明用在 UI 中，如 Visual Studio 包管理器的“更新”选项卡。

将包上传到 nuget.org 时，releaseNotes 字段被限制为 35,000 个字符。

copyright

(1.5+) 包的版权详细信息。

将包上传到 nuget.org 时，copyright 字段被限制为 4,000 个字符。

language

包的区域设置 ID。 请参阅创建本地化包。

标记

以空格分隔的标记和关键字列表，描述包并通过搜索和筛选辅助包的可发现性。

将包上传到 nuget.org 时，tags 字段被限制为 4,000 个字符。

serviceable

(3.3+) 仅限内部使用。

repository

存储库元数据，它由四个可选属性组成：type、url（4.0 及以上版本）、branch 和 commit（4.6 及以上版本）。 通过这些属性，可将 .nupkg 映射到生成它的存储库，并有可能获取用于生成包的单个分支名称和/或提交 SHA-1 哈希等详情。 它应为可由版本控制软件直接调用的公开可用 URL。 它不应为 HTML 页面，因为这适用于计算机。 若要链接到项目页，请改用 projectUrl 字段。

例如：

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        ...
        <repository type="git" url="https://github.com/NuGet/NuGet.Client.git" branch="dev" commit="e1c65e4524cd70ee6e22abe33e6cb6ec73938cb3" />
        ...
    </metadata>
</package>

将包上传到 nuget.org 时，type 属性被限制为 100 个字符，而 url 属性则被限制为 4,000 个字符。

title

包的友好标题，它可在某些 UI 显示中使用。 （nuget.org 以及 Visual Studio 中的包管理器不会显示标题）

将包上传到 nuget.org 时，title 字段被限制为 256 个字符，但不会用于任何显示用途。

集合元素

packageTypes

(3.5+) 如果不是传统的依赖项包，则为指定包类型的包括零个或多个 <packageType> 元素的集合。 每个 packageType 都具有 name 和 version 特性。 请参阅设置包类型。

dependencies

零个或多个 <dependency> 元素的集合，用来指定包的依赖项。 每个 dependency 都具有 id、version、include (3.x+) 和 exclude (3.x+) 特性。 请参阅下面的依赖项。

frameworkAssemblies

(1.2+) 零个或多个 <frameworkAssembly> 元素的集合，用来标识此包要求的 .NET Framework 程序集引用，从而确保引用添加到使用该包的项目。 每个 frameworkAssembly 都具有 assemblyName 和 targetFramework 特性。 请参阅下面的指定 Framework 程序集引用 GAC。

引用

(1.5+) 零个或多个 <reference> 元素的集合，用来指定包的 lib 文件夹中添加为项目引用的程序集。 每个 reference 都具有 file 特性。 <references> 也可包含具有 targetFramework 属性的 <group> 元素，然后包含 <reference> 元素。 如果省略，则包含 lib 中的全部引用。 请参阅下面的指定显式程序集引用。

contentFiles

(3.3+) <files> 元素的集合，用来标识包含在使用项目中的内容文件。 这些文件用一组特性指定，用于描述如何在项目系统中使用这些文件。 请参阅下面的指定包含在包中的文件。

文件

<package> 节点可能包含作为 <metadata> 的同级的 <files> 节点以及 <metadata> 下的 <contentFiles> 子级，从而指定要包含在包中的程序集和内容文件。 有关详细信息，请参阅本主题后面的包含程序集文件和包含内容文件。

元数据属性

minClientVersion

指定可安装此包的最低 NuGet 客户端版本，并由 nuget.exe 和 Visual Studio 程序包管理器强制实施。 只要包依赖于特定 NuGet 客户端版本中添加的 .nuspec 文件的特定功能，就会使用此功能。 例如，使用 developmentDependency 特性的包应为 minClientVersion 指定“2.8”。 同样，使用 contentFiles 元素（请参阅下一部分）的包应将 minClientVersion 设置为“3.3”。 另请注意，早于 2.5 的 NuGet 客户端无法识别此标记，所以无论 minClientVersion 包含什么内容，它们始终拒绝安装该包。

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata minClientVersion="100.0.0.1">
        <id>dasdas</id>
        <version>2.0.0</version>
        <title />
        <authors>dsadas</authors>
        <owners />
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>My package description.</description>
    </metadata>
    <files>
        <file src="content\one.txt" target="content\one.txt" />
    </files>
</package>

替换令牌

创建包时，nuget pack 命令使用来自项目文件的值或 pack 命令的 -properties 开关来替换 .nuspec 文件的 <metadata> 和 <files> 节点中用 $ 分隔的令牌。

在命令行中，可使用 nuget pack -properties <name>=<value>;<name>=<value> 指定令牌值。 例如，可使用 .nuspec 中的 $owners$ 和 $desc$ 令牌，并在封装时提供值，如下所示：

nuget pack MyProject.csproj -properties
    owners=janedoe,harikm,kimo,xiaop;desc="Awesome app logger utility"

如要使用项目中的值，请指定下表中描述的令牌（AssemblyInfo 指的是 Properties 中的文件，如 AssemblyInfo.cs 或 AssemblyInfo.vb）。

若要使用这些令牌，请通过项目文件而不仅仅是 .nuspec 来运行 nuget pack。 例如，使用以下命令时，.nuspec 文件中的 $id$ 和 $version$ 令牌会被替换为项目的 AssemblyName 和 AssemblyVersion 值：

nuget pack MyProject.csproj

通常情况下，如果已有项目，最初会使用自动包含一些标准令牌的 nuget spec MyProject.csproj 创建 .nuspec。 然而，如果项目缺少要求的 .nuspec 元素的值，那么 nuget pack 失败。 此外，如果更改项目值，请确定在创建包之前重新生成，可通过 pack 命令的 build 开关方便地完成此操作。

除 $configuration$ 外，项目中的值优先于在命令行上分配给相同令牌的任何值。

令牌	值来源	值
$id$	项目文件	项目文件中的 AssemblyName（标题）
$version$	AssemblyInfo	AssemblyInformationalVersion（如果存在），否则为 AssemblyVersion
$author$	AssemblyInfo	AssemblyCompany
$title$	AssemblyInfo	AssemblyTitle
$description$	AssemblyInfo	AssemblyDescription
$copyright$	AssemblyInfo	AssemblyCopyright
$configuration$	程序集 DLL	用于生成程序集的配置，默认为 Debug。 请注意，若要使用 Release 配置创建包，应始终在命令行上使用 -properties Configuration=Release。

包含程序集文件和内容文件时，令牌也可用于解析路径。 这些令牌与 MSBuild 属性具有相同的名称，因此可根据当前生成配置来选择要包含的文件。 例如，如果在 .nuspec 文件中使用以下令牌：

<files>
    <file src="bin\$configuration$\$id$.pdb" target="lib\net40" />
</files>

在 MSBuild 中生成具有 Release 配置且 AssemblyName 为 LoggingLibrary 的程序集，包中 .nuspec 文件中的结果行如下所示：

<files>
    <file src="bin\Release\LoggingLibrary.pdb" target="lib\net40" />
</files>

依赖项元素

<metadata> 中的 <dependencies> 元素包含任意数量的 <dependency> 元素，用来标识顶级包所依赖的其他包。 每个 <dependency> 的特性如下所示：

属性	说明
id	（必须）依赖项的包 ID，如“EntityFramework”和“NUnit”，同时也是 nuget.org 在包页面上显示的包名称。
version	（必需）可接受作为依赖项的版本范围。 有关准确语法，请参阅包版本控制。 不支持可变版本。
include	包括/排除标记的逗号分隔列表（见下文），指示要包含在最终包中的依赖项。 默认值为 all。
exclude	包括/排除标记的逗号分隔列表（见下文），指示要排除在最终包外的依赖项。 默认值为 build,analyzers（可被覆盖）。 但在最终包中也会隐式排除 content/ ContentFiles（无法被覆盖）。 用 exclude 指定的标记优先于用 include 指定的标记。 例如，include="runtime, compile" exclude="compile" 和 include="runtime" 相同。

将包上传到 nuget.org 时，每个依赖项的 id 属性被限制为 128 个字符，而 version 属性则被限制为 256 个字符。

包括/排除标记	受影响的目标文件夹
contentFiles	内容
运行库	运行时、资源和 FrameworkAssemblies
编译	lib
build	生成（MSBuild 属性和目标）
本机	本机
无	无文件夹
全部	全部文件夹

例如，以下行指示 PackageA 版本 1.1.0 或更高版本，以及 PackageB 版本 1.x 的依赖项。

<dependencies>
    <dependency id="PackageA" version="1.1.0" />
    <dependency id="PackageB" version="[1,2)" />
</dependencies>

以下行指示相同包上的依赖项，但指定包括 PackageA 的 contentFiles 和 build 文件夹，以及除 PackageB 的 native 和 compile 文件夹以外的所有文件夹。

<dependencies>
    <dependency id="PackageA" version="1.1.0" include="contentFiles, build" />
    <dependency id="PackageB" version="[1,2)" exclude="native, compile" />
</dependencies>

重要

从使用 nuget spec 的项目创建 .nuspec 时，该项目中存在的依赖项不会自动包含在生成的 .nuspec 文件中。 此时，请改用 nuget pack myproject.csproj 并从生成的 .nupkg 文件获取 .nuspec 文件。 此 .nuspec 包含依赖项。

依赖项组

版本 2.0+

作为单个简单列表的替代方法，可使用 <dependencies> 中的 <group> 元素根据目标项目的框架配置文件指定依赖项。

每个组都有一个名为 targetFramework 的特性，并包含零个或多个 <dependency> 元素。 当目标框架与项目的框架配置文件兼容时，将会一起安装这些依赖项。

无 targetFramework 属性的 <group> 元素被用作依赖项的默认列表或回退列表。 有关确切的框架标识符，请参阅目标框架。

重要

组格式不能与简单列表混合使用。

注意

与在 dependency groups 文件夹中使用的 TFM 相比，lib/ref 文件夹中所用目标框架名字对象 (TFM) 的格式有所不同。 如果 dependencies group 中声明的目标框架以及 .nuspec 文件的 lib/ref 文件夹没有完全匹配项，pack 命令则会引发 NuGet 警告 NU5128。

以下示例显示了 <group> 元素的不同变体：

<dependencies>
    <group>
        <dependency id="RouteMagic" version="1.1.0" />
    </group>

    <group targetFramework=".NETFramework4.7.2">
        <dependency id="jQuery" version="1.6.2" />
        <dependency id="WebActivator" version="1.4.4" />
    </group>

    <group targetFramework="netcoreapp3.1">
    </group>
</dependencies>

显式程序集引用

<references> 元素由采用 packages.config 的项目使用，从而显式指定目标项目在使用包时应引用的程序集。 显式引用通常用于仅设计时程序集。 有关详细信息，请参阅有关选择项目引用的程序集的页面。

例如，以下 <references> 元素指示 NuGet 仅对 xunit.dll 和 xunit.extensions.dll 添加引用，即使包中还有其他程序集：

<references>
    <reference file="xunit.dll" />
    <reference file="xunit.extensions.dll" />
</references>

引用组

作为单个简单列表的替代方法，可使用 <references> 中的 <group> 元素根据目标项目的框架配置文件指定引用。

每个组都有一个名为 targetFramework 的特性，并包含零个或多个 <reference> 元素。 当目标框架与项目的框架配置文件兼容时，会将引用添加到项目中。

无 targetFramework 属性的 <group> 元素被用作引用的默认列表或回退列表。 有关确切的框架标识符，请参阅目标框架。

重要

组格式不能与简单列表混合使用。

以下示例显示了 <group> 元素的不同变体：

<references>
    <group>
        <reference file="a.dll" />
    </group>

    <group targetFramework="net45">
        <reference file="b45.dll" />
    </group>

    <group targetFramework="netcore45">
        <reference file="bcore45.dll" />
    </group>
</references>

Framework 程序集引用

Framework 程序集是 .NET Framework 的一部分，并已存在于任何给定计算机的全局程序集缓存 (GAC) 中。 通过在 <frameworkAssemblies> 元素中标识这些程序集，包可确保在项目尚未具有此类引用的情况下，将必需的引用添加到项目中。 当然，此类程序集不直接包含在包中。

<frameworkAssemblies> 元素包含零个或多个 <frameworkAssembly> 元素，这些元素指定以下特性：

属性	说明
assemblyName	（必需）完全限定程序集名称。
targetFramework	（可选）指定此引用适用的目标框架。 如果省略，则表示该引用适用于全部框架。 有关确切的框架标识符，请参阅目标框架。

以下示例显示了对全部目标框架的 System.Net 的引用，以及对仅用于 .NET Framework 4.0 的 System.ServiceModel 的引用：

<frameworkAssemblies>
    <frameworkAssembly assemblyName="System.Net"  />

    <frameworkAssembly assemblyName="System.ServiceModel" targetFramework="net40" />
</frameworkAssemblies>

包含程序集文件

如果遵循创建包中介绍的约定，则不必在 .nuspec 文件中显式指定文件列表。 nuget pack 命令自动选取所需的文件。

重要

当包安装到项目中时，NuGet 自动将程序集引用添加到包的 DLL，不包括命名为 .resources.dll 的内容，因为它们被假定为本地化的附属程序集。 为此，请避免对包含基本包代码的文件使用 .resources.dll。

若要绕过此自动行为，并显式控制包中包含的文件，请将 <files> 元素作为 <package> 的子元素（和 <metadata> 的同级元素），并使用单独的 <file> 元素标识每个文件。 例如：

<files>
    <file src="bin\Debug\*.dll" target="lib" />
    <file src="bin\Debug\*.pdb" target="lib" />
    <file src="tools\**\*.*" exclude="**\*.log" />
</files>

在 NuGet 2.x 及更早版本中，如果项目使用 packages.config，在安装包时，<files> 元素也用于包含不可变的内容文件。 通过 NuGet 3.3+ 和项目 PackageReference，将改为使用 <contentFiles> 元素。 有关详细信息，请参阅下面的包含内容文件。

文件元素属性

每个 <file> 元素指定以下特性：

属性	说明
src	文件或要包含的文件位置，受 exclude 特性指定排除规则约束。 路径是相对于 .nuspec 文件的路径，除非指定了绝对路径。 允许使用通配符 *，双通配符 ** 意味着递归文件夹搜索。
目标	放置源文件的包中文件夹的相对路径，必须以 lib、content、build 或 tools 开头。 请参阅从基于约定的工作目录创建 .nuspec。
exclude	要从 src 位置排除的文件或文件模式的分号分隔列表。 允许使用通配符 *，双通配符 ** 意味着递归文件夹搜索。

示例

单个程序集

Source file:
    library.dll

.nuspec entry:
    <file src="library.dll" target="lib" />

Packaged result:
    lib\library.dll

特定于目标框架的单个程序集

Source file:
    library.dll

.nuspec entry:
    <file src="assemblies\net40\library.dll" target="lib\net40" />

Packaged result:
    lib\net40\library.dll

使用通配符的 DLL 集

Source files:
    bin\release\libraryA.dll
    bin\release\libraryB.dll

.nuspec entry:
    <file src="bin\release\*.dll" target="lib" />

Packaged result:
    lib\libraryA.dll
    lib\libraryB.dll

适用于不同框架的 DLL

Source files:
    lib\net40\library.dll
    lib\net20\library.dll

.nuspec entry (using ** recursive search):
    <file src="lib\**" target="lib" />

Packaged result:
    lib\net40\library.dll
    lib\net20\library.dll

排除文件

Source files:
    \tools\fileA.bak
    \tools\fileB.bak
    \tools\fileA.log
    \tools\build\fileB.log

.nuspec entries:
    <file src="tools\*.*" target="tools" exclude="tools\*.bak" />
    <file src="tools\**\*.*" target="tools" exclude="**\*.log" />

Package result:
    (no files)

包含内容文件

内容文件是包需要包含在项目中的不可变文件。 不可变文件指的是使用项目不会修改的文件。 内容文件示例包括：

• 作为资源嵌入的图像
• 已编译的源文件
• 需要包含在项目的生成输出中的脚本
• 需要包含在项目中，但不需要进行任何项目特定的更改的包的配置文件

内容文件使用 <files> 元素包含在包中，并在 target 属性中指定 content 文件夹。 但是，使用 PackageReference（而不是使用 <contentFiles> 元素）将包安装到项目中时，将忽略这些文件。

为了最大限度地兼容使用项目，一个包最好在两个元素中指定内容文件。

对内容文件使用文件元素

对于内容文件，只需使用与程序集文件相同的格式，但应在 target 属性中将 content 指定为基本文件夹，如以下示例所示。

基本内容文件

Source files:
    css\mobile\style1.css
    css\mobile\style2.css

.nuspec entry:
    <file src="css\mobile\*.css" target="content\css\mobile" />

Packaged result:
    content\css\mobile\style1.css
    content\css\mobile\style2.css

具有目录结构的内容文件

Source files:
    css\mobile\style.css
    css\mobile\wp7\style.css
    css\browser\style.css

.nuspec entry:
    <file src="css\**\*.css" target="content\css" />

Packaged result:
    content\css\mobile\style.css
    content\css\mobile\wp7\style.css
    content\css\browser\style.css

特定于目标框架的内容文件

Source file:
    css\cool\style.css

.nuspec entry
    <file src="css\cool\style.css" target="Content" />

Packaged result:
    content\style.css

复制到名称中带点的文件夹的内容文件

在此情况下，NuGet 发现 target 中的扩展名与 src 中的扩展名不匹配，因此将 target 中名称的该部分作为文件夹：

Source file:
    images\picture.png

.nuspec entry:
    <file src="images\picture.png" target="Content\images\package.icons" />

Packaged result:
    content\images\package.icons\picture.png

不具有扩展名的内容文件

若要包含不具有扩展名的文件，请使用 * 或 ** 通配符：

Source file:
    flags\installed

.nuspec entry:
    <file src="flags\**" target="flags" />

Packaged result:
    flags\installed

具有深层路径和深层目标的内容文件

在此情况下，由于源文件和目标文件的扩展名匹配，NuGet 假定目标是文件名而不是文件夹：

Source file:
    css\cool\style.css

.nuspec entry:
    <file src="css\cool\style.css" target="Content\css\cool" />
    or:
    <file src="css\cool\style.css" target="Content\css\cool\style.css" />

Packaged result:
    content\css\cool\style.css

重命名包中的内容文件

Source file:
    ie\css\style.css

.nuspec entry:
    <file src="ie\css\style.css" target="Content\css\ie.css" />

Packaged result:
    content\css\ie.css

排除文件

Source file:
    docs\*.txt (multiple files)

.nuspec entry:
    <file src="docs\*.txt" target="content\docs" exclude="docs\admin.txt" />
    or
    <file src="*.txt" target="content\docs" exclude="admin.txt;log.txt" />

Packaged result:
    All .txt files from docs except admin.txt (first example)
    All .txt files from docs except admin.txt and log.txt (second example)

对内容文件使用 contentFiles 元素

NuGet 4.0+ 与 PackageReference

默认情况下，包将内容放置在 contentFiles 文件夹中（见下文），nuget pack 使用默认特性将全部文件包含在该文件夹中。 在此情况下，根本没有必要在 .nuspec 中包含 contentFiles 节点。

若要控制包含哪些文件，<contentFiles> 元素指定是 <files> 元素的集合，可标识包含的确切文件。

这些文件用一组特性指定，用于描述如何在项目系统中使用这些文件：

属性	说明
包括	（必需）文件或要包含的文件位置，受 exclude 特性指定的排除规则约束。 此路径为相对于 contentFiles 文件夹的路径，除非指定了绝对路径。 允许使用通配符 *，双通配符 ** 意味着递归文件夹搜索。
exclude	要从 src 位置排除的文件或文件模式的分号分隔列表。 允许使用通配符 *，双通配符 ** 意味着递归文件夹搜索。
buildAction	生成操作，它可用于分配到 MSBuild 的内容项（如 Content、None、Embedded Resource、Compile）。默认值为 Compile。
copyToOutput	一个布尔值，用于指示是否将内容项复制到生成（或发布）输出文件夹。 默认值为 false。
flatten	一个布尔值，用于指示是将内容项复制到生成输出中的单个文件夹 (true)，还是保留包中的文件夹结构 (false)。 此标志仅在 copyToOutput 标志设置为 true 时才有效。 默认值为 false。

安装包时，NuGet 从上到下应用 <contentFiles> 的子元素。 如果多个条目与相同的文件匹配，那么应用全部条目。 如果相同特性发生冲突，则最上面的条目将替代靠下的条目。

包文件夹结构

包项目应使用以下模式构建内容结构：

/contentFiles/{codeLanguage}/{TxM}/{any?}

• codeLanguages 可以是 cs、vb、fs、any 或给定 $(ProjectLanguage) 的小写等效形式
• TxM 是 NuGet 支持的任何合法目标框架名字对象（请参阅目标框架）。
• 任何文件夹结构都可以附加到此语法的末尾。

例如：

Language- and framework-agnostic:
    /contentFiles/any/any/config.xml

net45 content for all languages
    /contentFiles/any/net45/config.xml

C#-specific content for net45 and up
    /contentFiles/cs/net45/sample.cs

空文件夹可以使用 _._ 来选择不提供特定语言和 TxM 组合的内容，例如：

/contentFiles/vb/any/code.vb
/contentFiles/cs/any/_._

contentFiles 部分示例

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        ...
        <contentFiles>
            <!-- Embed image resources -->
            <files include="any/any/images/dnf.png" buildAction="EmbeddedResource" />
            <files include="any/any/images/ui.png" buildAction="EmbeddedResource" />

            <!-- Embed all image resources under contentFiles/cs/ -->
            <files include="cs/**/*.png" buildAction="EmbeddedResource" />

            <!-- Copy config.xml to the root of the output folder -->
            <files include="cs/uap/config/config.xml" buildAction="None" copyToOutput="true" flatten="true" />

            <!-- Copy run.cmd to the output folder and keep the directory structure -->
            <files include="cs/commands/run.cmd" buildAction="None" copyToOutput="true" flatten="false" />

            <!-- Include everything in the scripts folder except exe files -->
            <files include="cs/net45/scripts/*" exclude="**/*.exe"  buildAction="None" copyToOutput="true" />
        </contentFiles>
        </metadata>
</package>

框架引用组

仅限采用 PackageReference 的版本 5.1 及以上版本

框架引用是一个表示共享框架（如 WPF 或 Windows 表单）的 .NET Core 概念。 通过指定共享框架，包可确保其所有框架依赖项均包含在引用项目中。

每个 <group> 元素均需一个 targetFramework 属性和零个或多个 <frameworkReference> 元素。

以下示例演示了为 .NET Core WPF 项目生成的 nuspec。 请注意，不建议手动创作包含框架引用的 nuspec。 请考虑改用 targets pack，以便从项目自动推断它们。

<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
  <metadata>
    <dependencies>
      <group targetFramework=".NETCoreApp3.1" />
    </dependencies>
    <frameworkReferences>
      <group targetFramework=".NETCoreApp3.1">
        <frameworkReference name="Microsoft.WindowsDesktop.App.WPF" />
      </group>
    </frameworkReferences>
  </metadata>
</package>

nuspec 示例文件

未指定依赖项或文件的简单 .nuspec

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.2.3</version>
        <authors>Kim Abercrombie, Franck Halmaert</authors>
        <description>Sample exists only to show a sample .nuspec file.</description>
        <language>en-US</language>
        <projectUrl>http://xunit.codeplex.com/</projectUrl>
        <license type="expression">MIT</license>
    </metadata>
</package>

具有依赖项的 .nuspec

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.0.0</version>
        <authors>Microsoft</authors>
        <dependencies>
            <dependency id="another-package" version="3.0.0" />
            <dependency id="yet-another-package" version="1.0.0" />
        </dependencies>
    </metadata>
</package>

具有文件的 .nuspec

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>routedebugger</id>
        <version>1.0.0</version>
        <authors>Jay Hamlin</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>Route Debugger is a little utility I wrote...</description>
    </metadata>
    <files>
        <file src="bin\Debug\*.dll" target="lib" />
    </files>
</package>

具有 Framework 程序集的 .nuspec

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>PackageWithGacReferences</id>
        <version>1.0</version>
        <authors>Author here</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>
            A package that has framework assemblyReferences depending
            on the target framework.
        </description>
        <frameworkAssemblies>
            <frameworkAssembly assemblyName="System.Web" targetFramework="net40" />
            <frameworkAssembly assemblyName="System.Net" targetFramework="net40-client, net40" />
            <frameworkAssembly assemblyName="Microsoft.Devices.Sensors" targetFramework="sl4-wp" />
            <frameworkAssembly assemblyName="System.Json" targetFramework="sl3" />
        </frameworkAssemblies>
    </metadata>
</package>

在此示例中，为特定的项目目标安装了以下内容：

• .NET4 ->System.Web、System.Net
• .NET4 客户端配置文件 ->System.Net
• Silverlight 3 ->System.Json
• WindowsPhone ->Microsoft.Devices.Sensors