MSBuild 保留属性和已知属性MSBuild reserved and well-known properties

MSBuild 提供了一组预定义的属性,这些属性存储项目文件和 MSBuild 二进制文件的相关信息。MSBuild provides a set of predefined properties that store information about the project file and the MSBuild binaries. 这些属性的计算方式与其他 MSBuild 属性相同。These properties are evaluated in the same manner as other MSBuild properties. 例如,要使用 MSBuildProjectFile 属性,应键入 $(MSBuildProjectFile)For example, to use the MSBuildProjectFile property, you type $(MSBuildProjectFile).

MSBuild 使用下表中的值预定义保留的属性和已知的属性。MSBuild uses the values in the following table to predefine reserved and well-known properties. 无法重写保留的属性,但可以使用名称相同的环境属性、全局属性或已在项目文件中声明的属性重写已知的属性。Reserved properties cannot be overridden, but well-known properties can be overridden by using identically named environment properties, global properties, or properties that are declared in the project file.

保留属性和已知属性Reserved and well-known properties

此部分中的表显示了 MSBuild 预定义属性。The table in this section shows the MSBuild predefined properties. 表中的示例列与以下示例项目文件相关(假定位于 C:\Source\Repos\ConsoleApp1\ConsoleApp1),并显示了这些属性在以下情况下的值:在项目文件中被访问时,以及在没有特殊命令行选项的情况下调用 MSBuild 时,同时安装了 Visual Studio 2019 版本 16.7 的预览内部版本。The example column in the table relates to the following example project file, assumed to be located at C:\Source\Repos\ConsoleApp1\ConsoleApp1, and shows the values of these properties have when accessed in the project file, when MSBuild is invoked with no special command-line options, with a preview build of Visual Studio 2019 version 16.7 installed.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>
</Project>
PropertyProperty 保留或已知Reserved or well-known 描述Description 示例Example
MSBuildBinPath 保留Reserved 当前正在使用的 MSBuild 二进制文件所在文件夹的绝对路径(例如,C:\Windows\Microsoft.Net\Framework\<versionNumber>)。The absolute path of the folder where the MSBuild binaries that are currently being used are located (for example, C:\Windows\Microsoft.Net\Framework\<versionNumber>). 如果必须引用 MSBuild 目录中的文件,此属性将非常有用。This property is useful if you have to refer to files in the MSBuild directory.

不要在此属性上添加最终反斜杠。Do not include the final backslash on this property.
C:\Program Files (x86)\Microsoft Visual Studio\2019\Preview\MSBuild\Current\Bin
MSBuildExtensionsPath 已知Well-known 在 .NET Framework 4 中引入:MSBuildExtensionsPathMSBuildExtensionsPath32 的默认值之间没有差异。Introduced in the .NET Framework 4: there is no difference between the default values of MSBuildExtensionsPath and MSBuildExtensionsPath32. 你可以设置环境变量 MSBUILDLEGACYEXTENSIONSPATH 为非 null 值,以启用早期版本中的 MSBuildExtensionsPath的默认值的行为。You can set the environment variable MSBUILDLEGACYEXTENSIONSPATH to a non-null value to enable the behavior of the default value of MSBuildExtensionsPath in earlier versions.

在 .NET Framework 3.5 和较早的版本中,根据当前进程的位数,MSBuildExtensionsPath 的默认值指向位于 \Program Files\ 或 \Program Files (x86) 文件夹下的 MSBuild 子文件夹路径 。In the .NET Framework 3.5 and earlier, the default value of MSBuildExtensionsPath points to the path of the MSBuild subfolder under the \Program Files\ or \Program Files (x86) folder, depending on the bitness of the current process. 例如,对于在 64 位计算机上的 32 位进程,此属性指向 \Program Files (x86) 文件夹。For example, for a 32-bit process on a 64-bit machine, this property points to the \Program Files (x86) folder. 对于在 64 位计算机上的 64 位进程,此属性指向 \Program Files 文件夹。For a 64-bit process on a 64-bit machine, this property points to the \Program Files folder.

不要在此属性上添加最终反斜杠。Do not include the final backslash on this property.

此位置用于存放自定义目标文件。This location is a useful place to put custom target files. 例如,目标文件可能安装在 \Program Files\MSBuild\MyFiles\Northwind.targets 中,然后使用此 XML 代码导入到项目文件中:For example, your target files could be installed at \Program Files\MSBuild\MyFiles\Northwind.targets and then imported in project files by using this XML code:

<Import Project="$(MSBuildExtensionsPath)\MyFiles\Northwind.targets"/>
C:\Program Files (x86)\Microsoft Visual Studio\2019\Preview\MSBuild
MSBuildExtensionsPath32 已知Well-known 位于 \Program Files 或 \Program Files (x86) 文件夹下的 MSBuild 子文件夹的路径。The path of the MSBuild subfolder under the \Program Files or \Program Files (x86) folder. 此路径始终指向 32 位计算机上的 32 位 \Program Files (x86) 文件夹和 64 位计算机上的 \Program Files 。The path always points to the 32-bit \Program Files (x86) folder on a 32-bit machine and \Program Files on a 64-bit machine.". 另请参见 MSBuildExtensionsPathMSBuildExtensionsPath64See also MSBuildExtensionsPath and MSBuildExtensionsPath64.

不要在此属性上添加最终反斜杠。Do not include the final backslash on this property.
C:\Program Files (x86)\Microsoft Visual Studio\2019\Preview\MSBuild
MSBuildExtensionsPath64 已知Well-known 位于 \Program Files 文件夹下的 MSBuild 子文件夹的路径。The path of the MSBuild subfolder under the \Program Files folder. 对于 64 位计算机,此路径始终指向 \Program Files 文件夹。For a 64-bit machine, this path always points to the \Program Files folder. 对于 32 位计算机,此路径为空。For a 32-bit machine, this path is blank. 另请参见 MSBuildExtensionsPathMSBuildExtensionsPath32See also MSBuildExtensionsPath and MSBuildExtensionsPath32.

不要在此属性上添加最终反斜杠。Do not include the final backslash on this property.
C:\Program Files\MSBuild
MSBuildInteractive 保留Reserved true,如果 MSBuild 以交互方式运行,则允许用户输入。true if MSBuild is running interactively, allowing user input. 此设置由 -interactive 命令行选项控制。This setting is controlled by the -interactive command-line option. false
MSBuildLastTaskResult 保留Reserved true,如果前一项任务完成没有出现任何错误(即使有警告);否则如果前一项任务出现错误,则为 falsetrue if the previous task completed without any errors (even if there were warnings), or false if the previous task had errors. 通常,当任务中出现错误时,错误会发生在项目的最后。Typically, when an error occurs in a task, the error is the last thing that happens in that project. 因此,此属性的值决不会是 false,但以下情况除外:Therefore, the value of this property is never false, except in these scenarios:

- Task 元素 (MSBuild)ContinueOnError 属性设置为 WarnAndContinue(或 true)或 ErrorAndContinue 时。- When the ContinueOnError attribute of the Task element (MSBuild) is set to WarnAndContinue (or true) or ErrorAndContinue.

- TargetOnError 元素 (MSBuild) 作为子元素时。- When the Target has an OnError element (MSBuild) as a child element.
true
MSBuildNodeCount 保留Reserved 生成过程中使用的并发进程的最大数目。The maximum number of concurrent processes that are used when building. 这是在命令行中为 -maxcpucount 指定的值。This is the value that you specified for -maxcpucount on the command line. 如果指定了 -maxcpucount 但没有指定值,MSBuildNodeCount 会指定计算机中的处理器数。If you specified -maxcpucount without specifying a value, then MSBuildNodeCount specifies the number of processors in the computer. 有关详细信息,请参阅命令行参考并行生成多个项目For more information, see Command-line reference and Build multiple projects in parallel. 11
MSBuildProgramFiles32 保留Reserved 32 位程序文件夹的位置;例如,C:\Program Files (x86)。The location of the 32-bit program folder; for example, C:\Program Files (x86).

不要在此属性上添加最终反斜杠。Do not include the final backslash on this property.
C:\Program Files (x86)
MSBuildProjectDefaultTargets 保留Reserved DefaultTargets 元素的 Project 特性中指定的目标的完整列表。The complete list of targets that are specified in the DefaultTargets attribute of the Project element. 例如,下面的 Project 元素的 MSBuildDefaultTargets 属性值为 A;B;CFor example, the following Project element would have an MSBuildDefaultTargets property value of A;B;C:

<Project DefaultTargets="A;B;C" >
Build
MSBuildProjectDirectory 保留Reserved 项目文件所在目录的绝对路径,例如,C:\MyCompany\MyProduct。The absolute path of the directory where the project file is located, for example C:\MyCompany\MyProduct.

不要在此属性上添加最终反斜杠。Do not include the final backslash on this property.
C:\Source\Repos\ConsoleApp1\ConsoleApp1
MSBuildProjectDirectoryNoRoot 保留Reserved MSBuildProjectDirectory 属性的值,但不包括根驱动器。The value of the MSBuildProjectDirectory property, excluding the root drive.

不要在此属性上添加最终反斜杠。Do not include the final backslash on this property.
Source\Repos\ConsoleApp1\ConsoleApp1
MSBuildProjectExtension 保留Reserved 项目文件的文件扩展名(包括点号);例如,.proj。The file name extension of the project file, including the period; for example, .proj. .csproj
MSBuildProjectFile 保留Reserved 项目文件的完整文件名(包括文件扩展名);例如,MyApp.proj。The complete file name of the project file, including the file name extension; for example, MyApp.proj. ConsoleApp1.csproj
MSBuildProjectFullPath 保留Reserved 项目文件的绝对路径和完整文件名(包括文件扩展名);例如,C:\MyCompany\MyProduct\MyApp.proj。The absolute path and complete file name of the project file, including the file name extension; for example, C:\MyCompany\MyProduct\MyApp.proj. c:\Source\Repos\ConsoleApp1\ConsoleApp1\ConsoleApp1.csproj
MSBuildProjectName 保留Reserved 项目文件的文件名(不包括文件扩展名);例如,MyApp。The file name of the project file without the file name extension; for example, MyApp. ConsoleApp1
MSBuildRuntimeType 保留Reserved 当前正在执行的运行时类型。The type of the runtime that is currently executing. 在 MSBuild 15 中引入。Introduced in MSBuild 15. 可能未定义值(MSBuild 15 之前),Full 指示 MSBuild 在桌面 .NET Framework 上运行,Core 指示 MSBuild 在 .NET Core 上运行(例如在 dotnet build 中),Mono 指示 MSBuild 在 Mono 上运行。Value may be undefined (prior to MSBuild 15), Full indicating that MSBuild is running on the desktop .NET Framework, Core indicating that MSBuild is running on .NET Core (for example in dotnet build), or Mono indicating that MSBuild is running on Mono. Full
MSBuildStartupDirectory 保留Reserved 在其中调用 MSBuild 的文件夹的绝对路径。The absolute path of the folder where MSBuild is called. 使用此属性,无需在每个目录中都创建 <dirs>.proj 文件,就可以在项目树中的某个特定点下生成所有内容。By using this property, you can build everything below a specific point in a project tree without creating <dirs>.proj files in every directory. 而你只有一个项目,例如 c:\traversal.proj(如此处所示):Instead, you have just one project—for example, c:\traversal.proj, as shown here:

<Project ...> <ItemGroup> <ProjectFiles Include="$ (MSBuildStartupDirectory) **\*.csproj"/> </ItemGroup> <Target Name="build"> <MSBuild Projects="@(ProjectFiles)"/> </Target> </Project>

若要在该树中的任意一点生成,请键入:To build at any point in the tree, type:

msbuild c:\traversal.proj

不要在此属性上添加最终反斜杠。Do not include the final backslash on this property.
c:\Source\Repos\ConsoleApp1
MSBuildThisFile 保留Reserved MSBuildThisFileFullPath 的文件名和文件扩展名部分。The file name and file extension portion of MSBuildThisFileFullPath. ConsoleApp1.csproj
MSBuildThisFileDirectory 保留Reserved MSBuildThisFileFullPath 的目录部分。The directory portion of MSBuildThisFileFullPath.

将最终反斜杠包括在路径中。Include the final backslash in the path.
c:\Source\Repos\ConsoleApp1\ConsoleApp1\
MSBuildThisFileDirectoryNoRoot 保留Reserved MSBuildThisFileFullPath 的目录部分不包括根驱动器。The directory portion of MSBuildThisFileFullPath, excluding the root drive.

将最终反斜杠包括在路径中。Include the final backslash in the path.
Source\Repos\ConsoleApp1\ConsoleApp1\
MSBuildThisFileExtension 保留Reserved MSBuildThisFileFullPath的文件扩展名部分。The file name extension portion of MSBuildThisFileFullPath. .csproj
MSBuildThisFileFullPath 保留Reserved 项目或包含正在运行目标的目标文件的绝对路径。The absolute path of the project or targets file that contains the target that is running.

提示:你可指定在相对于目标文件而不是相对于原始项目文件的目标文件中的相对路径。Tip: You can specify a relative path in a targets file that's relative to the targets file and not relative to the original project file.
c:\Source\Repos\ConsoleApp1\ConsoleApp1\ConsoleApp1.csproj
MSBuildThisFileName 保留Reserved MSBuildThisFileFullPath 的文件名部分,不包含文件扩展名。The file name portion of MSBuildThisFileFullPath, without the file name extension. ConsoleApp1
MSBuildToolsPath 保留Reserved MSBuildToolsVersion 的值相关联的 MSBuild 版本的安装路径。The installation path of the MSBuild version that's associated with the value of MSBuildToolsVersion.

不要将最终的反斜杠包含在路径中。Do not include the final backslash in the path.

不能重写此属性。This property cannot be overridden.
C:\Program Files (x86)\Microsoft Visual Studio\2019\Preview\MSBuild\Current\Bin
MSBuildToolsVersion 保留Reserved 用于生成项目的 MSBuild 工具集版本。The version of the MSBuild Toolset that is used to build the project.

注意:包含用于生成应用程序的任务、目标和工具的 MSBuild 工具集。Note: An MSBuild Toolset consists of tasks, targets, and tools that are used to build an application. 工具包括编译器,例如 csc.exe 和 vbc.exe 。The tools include compilers such as csc.exe and vbc.exe. 有关详细信息,请参阅工具集 (ToolsVersion)标准和自定义工具集配置For more information, see Toolset (ToolsVersion), and Standard and custom Toolset configurations.
Current
MSBuildVersion 保留Reserved 用于生成项目的 MSBuild 版本。The version of MSBuild used to build the project.

此属性不能重写,否则将返回 MSB4004 - The 'MSBuildVersion' property is reserved, and can not be modified. 错误消息。This property can't be overridden, otherwise the error message MSB4004 - The 'MSBuildVersion' property is reserved, and can not be modified. is returned.
16.7.016.7.0

与 MSBuild 元素冲突的名称Names that conflict with MSBuild elements

除上述名称外,对应于 MSBuild 语言元素的名称也不能用于用户定义的属性、项或项元数据:In addition to the above, names corresponding to MSBuild language elements cannot be used for user-defined properties, items, or item metadata:

  • VisualStudioProjectVisualStudioProject
  • TargetTarget
  • PropertyGroupPropertyGroup
  • OutputOutput
  • ItemGroupItemGroup
  • UsingTaskUsingTask
  • ProjectExtensionsProjectExtensions
  • OnErrorOnError
  • ImportGroupImportGroup
  • ChooseChoose
  • WhenWhen
  • OtherwiseOtherwise

请参阅See also