通过

常见的 MSBuild 项目项

在 MSBuild 中，项是对一个或多个字符串（如文件名）的命名引用。 项包含文件名、路径和版本号等元数据。 Visual Studio 中的所有项目类型都有多个共同项。 这些文件在文件 Microsoft.Build.CommonTypes.xsd 中定义。

本文列出了 MSBuild 本身中定义的所有常见项目项。 .NET SDK 提供的项和属性记录在 Microsoft.Net.Sdk 的 MSBuild 参考中。

Reference

表示项目中的 .NET 程序集（托管）引用。

项元数据名称 描述
HintPath 可选字符串。 程序集的相对路径或绝对路径。
名字 可选字符串。 程序集的显示名称，例如“System.Windows.Forms”。
FusionName 可选字符串。 指定项的简单或强融合名称。

当此属性存在时，它可能会节省时间，因为无需打开程序集文件即可获取融合名称。
SpecificVersion 可选的布尔值。 指定是否只应引用融合名称中的版本。
别名 可选字符串。 引用的任何别名。
私人 可选的布尔值。 指定是否应将引用复制到输出文件夹。 此属性与 Visual Studio IDE 中引用的 “复制本地 ”属性匹配。

注意

项目 Reference 类型还可用于引用本机 COM 对象的预生成包装程序集，例如，如果用于 tlbimp.exe 生成 PIA（主互作程序集）。 如果要使用已知输入自行预生成 COM 包装器程序集，而不是依赖 MSBuild 的算法在生成时生成 COM 包装器，这会在运行 MSBuild 的生成计算机上引入系统注册表状态的依赖项，这是一种适当的选择。

COMReference

表示项目中的 COM（非托管）组件引用。 ResolveComReference 任务使用此项，该任务生成包装程序集，或者（如果使用EmbedInteropTypes）在程序集中嵌入互作类型。 使用此类型的引用引入了对生成计算机上的系统注册表的依赖项，该注册表用于查找引用的 COM 对象。 当计算机上安装、更新或卸载产品时，注册表中的 COM 项目和 COM 条目可能会更改（或者在同一台计算机上运行同一生成时），即使生成逻辑未更改，也可能生成不同的包装程序集。

此项不适用于 non-.NET 项目。

项元数据名称 描述
名字 可选字符串。 组件的显示名称。
Guid 所需的字符串。 组件的 GUID，格式为 {12345678-1234-1234-1234-123456781234}。
VersionMajor 所需的字符串。 组件的版本号的主要部分。 例如，如果完整版本号为“5.46”，则为“5”。
VersionMinor 所需的字符串。 组件的版本号的次要部分。 例如，如果完整版本号为“5.46”，则为“46”。
EmbedInteropTypes 可选的布尔值。 如果为 true，请将此引用中的互操作类型直接嵌入到程序集中，而不是生成互操作 DLL。
Lcid 可选字符串。 组件的 LocaleID。
WrapperTool 可选字符串。 在组件上使用的包装器工具的名称。 值为：

1. 主要
2. tlbimp
3. primaryortlbimp
4. aximp
孤立 可选的布尔值。 指定组件是否为无注册组件。

COMFileReference

表示按文件路径引用的类型库列表，而不是使用系统注册表。 如果想要避免对生成计算机的注册表存在依赖关系，则此类引用可能是 COMReference 的一个很好的替代方法，因为运行生成的帐户没有提升的权限来编辑生成服务器上的注册表，或者不希望生成依赖于注册表的状态。 如果用于 COMFileReference 引用系统路径上的项目，则生成依赖于系统状态。 如果系统项目因系统状态发生更改而更改，例如安装、更新或卸载产品（或者在同一台计算机上运行同一生成），则包装器程序集可能会更改，即使生成逻辑尚未更改。 若要确保生成结果一致，可以将 COM 项目的已知副本缓存到你控制的某个位置（例如项目或解决方案文件夹下），并引用该副本而不是系统项目。

此项不适用于 non-.NET 项目。

项元数据名称 描述
EmbedInteropTypes 可选的布尔值。 如果为 true，请将此引用中的互操作类型直接嵌入到程序集中，而不是生成互操作 DLL。
WrapperTool 可选字符串。 在组件上使用的包装器工具的名称。 值为：

1. 主要
2. tlbimp
3. primaryortlbimp
4. aximp

NativeReference

表示本机清单文件或对此类文件的引用。

项元数据名称 描述
名字 所需的字符串。 清单文件的基名称。
HintPath 所需的字符串。 清单文件的相对路径。

ProjectReference

表示对另一个项目的引用。 ProjectReference 项由 目标转换为 ResolveProjectReferences 项，因此，如果转换过程未覆盖引用，则引用上的任何有效元数据可能在 ProjectReference有效。

项元数据名称 描述
名字 可选字符串。 引用的显示名称。
GlobalPropertiesToRemove 可选 string[]。 生成引用的项目时要删除的属性的名称，例如 RuntimeIdentifier;PackOnBuild。 默认值为空。
项目 可选字符串。 引用的 GUID，格式为 {12345678-1234-1234-1234-123456781234}。
OutputItemType 可选字符串。 要向中发出目标输出的项类型。 默认值为空。 如果引用元数据设置为“true”（默认值），则目标输出将成为编译器的引用。
ReferenceOutputAssembly 可选的布尔值。 如果设置为 false，则不包括引用项目的输出作为此项目的 引用 ，但仍确保另一个项目在此项目之前生成。 默认为 true。
私人 可选的布尔值。 指定是否应将引用复制到输出文件夹。 此属性与 Visual Studio IDE 中引用的 “复制本地 ”属性匹配。
SetConfiguration 可选字符串。 设置所引用项目的全局属性 Configuration，例如 Configuration=Release。
SetPlatform 可选字符串。 设置所引用项目的全局属性 Platform，例如 Platform=AnyCPU。
SetTargetFramework 可选字符串。 设置所引用项目的全局属性 TargetFramework，例如 TargetFramework=netstandard2.0。
SkipGetTargetFrameworkProperties 可选的布尔值。 如果 true，则生成引用的项目，而无需协商最兼容的 TargetFramework 值。 默认为 false。
目标 可选 string[]。 应生成的引用项目中的目标的分号分隔列表。 默认值为 $(ProjectReferenceBuildTargets)的值，默认值为空，指示默认目标。 在 Visual Studio 中生成（而不是 MSBuild.exe 或 dotnet build），指定这不会阻止 Visual Studio 生成引用项目的默认目标。

注意

.NET Framework 和 .NET Core（包括 .NET 5 及更高版本）之间的项目引用的工作方式存在差异。 在 .NET Framework 项目中，项目引用不可传递。 也就是说，如果 Project1 引用 Project2，而 Project2 引用 Project3，则不能从 Project1 针对 Project3 进行代码编码。 但是，在 .NET Core（包括 .NET 5 及更高版本中），项目引用 可传递。 可以在 Project1 中针对 Project3 编写代码。

编译

表示编译器的源文件。

项元数据名称 描述
DependentUpon 可选字符串。 指定此文件所依赖的文件以正确编译。
AutoGen 可选的布尔值。 指示文件是否由 Visual Studio 集成开发环境（IDE）为项目生成。
链接 可选字符串。 当文件在物理上位于项目文件的影响之外时要显示的表示法路径。
可见 可选的布尔值。 指示是否在 Visual Studio 的解决方案资源管理器 中显示文件。
CopyToOutputDirectory 可选字符串。 确定是否将文件复制到输出目录。 值为：

1. 从不
2. 始终
3. PreserveNewest
4. IfDifferent

EmbeddedResource

表示要嵌入到生成的程序集中的资源。

项元数据名称 描述
文化 可选字符串。 指定资源文件的区域性。 如果指定，生成过程不会根据文件扩展名自动推断区域性（这依赖于托管生成的计算机上的 .NET/OS 可用的区域性）。 强烈建议设置 Culture={culture identifier} 或 WithCulture=false 元数据。
WithCulture 可选布尔值。 指定文件是非区域性的，应跳过 AssignCulture 任务进行区域性检测。 强烈建议设置 Culture={culture identifier} 或 WithCulture=false 元数据。
DependentUpon 可选字符串。 指定此文件依赖的文件进行正确编译
发电机 可选字符串。 在此项上运行的任何文件生成器的名称。
LastGenOutput 可选字符串。 由此项目上运行的任何文件生成器创建的文件的名称。
CustomToolNamespace 可选字符串。 在此项上运行的任何文件生成器都应创建代码的命名空间。
链接 可选字符串。 如果文件在物理上位于项目的影响之外，将显示表示法路径。
可见 可选的布尔值。 指示是否在 Visual Studio 的解决方案资源管理器 中显示文件。
CopyToOutputDirectory 可选字符串。 确定是否将文件复制到输出目录。 值为：

1. 从不
2. 始终
3. PreserveNewest
4. IfDifferent
LogicalName 所需的字符串。 嵌入资源的逻辑名称。

内容

表示未编译到项目中但可以嵌入或与其一起发布的文件。

项元数据名称 描述
DependentUpon 可选字符串。 指定此文件所依赖的文件以正确编译。
发电机 可选字符串。 在此项上运行的任何文件生成器的名称。
LastGenOutput 可选字符串。 由此项目上运行的任何文件生成器创建的文件的名称。
CustomToolNamespace 可选字符串。 在此项上运行的任何文件生成器都应创建代码的命名空间。
链接 可选字符串。 如果文件在物理上位于项目的影响之外，则显示表示法路径。
PublishState 所需的字符串。 内容的发布状态，任一：

-违约
-包括
-排除
- DataFile
-先决条件
IsAssembly 可选的布尔值。 指定文件是否为程序集。
可见 可选的布尔值。 指示是否在 Visual Studio 的解决方案资源管理器 中显示文件。
CopyToOutputDirectory 可选字符串。 确定是否将文件复制到输出目录。 值为：

1. 从不
2. 始终
3. PreserveNewest
4. IfDifferent
目标路径 可选字符串。 项的输出路径（相对于配置和/或特定于平台的输出目录），包括文件名。 这遵循 Link 元数据（如果提供）。 如果未提供 TargetPath，则会在生成过程中计算它。 请参阅 AssignTargetPath。

没有

表示在生成过程中不应具有任何角色的文件。

项元数据名称 描述
DependentUpon 可选字符串。 指定此文件所依赖的文件以正确编译。
发电机 可选字符串。 在此项上运行的任何文件生成器的名称。
LastGenOutput 可选字符串。 由此项目上运行的任何文件生成器创建的文件的名称。
CustomToolNamespace 可选字符串。 在此项上运行的任何文件生成器都应创建代码的命名空间。
链接 可选字符串。 如果文件在物理上位于项目的影响之外，则显示表示法路径。
可见 可选的布尔值。 指示是否在 Visual Studio 的解决方案资源管理器 中显示文件。
CopyToOutputDirectory 可选字符串。 确定是否将文件复制到输出目录。 值为：

1. 从不
2. 始终
3. PreserveNewest
4. IfDifferent

AssemblyMetadata

表示要作为 [AssemblyMetadata(key, value)]生成的程序集属性。

项元数据名称 描述
包括 成为 AssemblyMetadataAttribute 属性构造函数中的第一个参数（键）。
价值 所需的字符串。 成为 AssemblyMetadataAttribute 属性构造函数中的第二个参数（值）。

注意

此项适用于使用 SDK for .NET 5（和 .NET Core）及更高版本的项目。

InternalsVisibleTo

指定要作为 [InternalsVisibleTo(..)] 程序集属性发出的程序集。

项元数据名称 描述
包括 程序集名称。
钥匙 可选字符串。 程序集的公钥。

注意

此项适用于使用 SDK for .NET 5（和 .NET Core）及更高版本的项目。

BaseApplicationManifest

表示生成的基本应用程序清单，并包含 ClickOnce 部署安全信息。

CodeAnalysisImport

表示要导入的 FxCop 项目。

进口

表示 Visual Basic 编译器应导入其命名空间的程序集。

文件夹

此元素仅由 Visual Studio 用作空文件夹的占位符。 填充文件夹后，该文件夹将被另一个元素替换。

另请参阅