MSBuild 属性

项目
06/09/2015

属性是可用于配置生成的名称/值对。在将值传递给任务、计算条件，以及存储将在整个项目文件中引用的值时，可以使用属性。

在项目文件中定义和引用属性

属性的声明方式是：创建一个与属性同名的元素，将其指定为 PropertyGroup 元素的子元素。例如，下面的 XML 创建一个名为 BuildDir 的属性，其值为 Build。

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

在整个项目文件中，可以使用语法 $(PropertyName) 来引用属性。例如，可以使用 $(BuildDir) 引用上例中的属性。

通过重定义属性可以更改属性值。使用下面的 XML 可以为 BuildDir 属性指定新值：

<PropertyGroup>
    <BuildDir>Alternate</BuildDir>
</PropertyGroup>

属性按其在项目文件中出现的顺序进行计算。必须先将旧值赋给 BuildDir，然后才能声明其新值。

保留属性

MSBuild 保留了一些属性名称，用于存储有关项目文件和二进制 MSBuild 文件的信息。与任何其他属性一样，这些属性也通过 $ 表示法进行引用。例如，$(MSBuildProjectFile) 返回项目文件的完整文件名，包括文件扩展名。

有关更多信息，请参见如何：引用项目文件的名称或位置和MSBuild 保留属性和已知属性。

环境属性

可以像引用保留属性那样，在项目文件中引用环境变量。例如，若要在项目文件中使用 PATH 环境变量，请使用 $(Path)。如果项目中包含的某个属性定义与环境属性同名，则项目中的这个属性将重写环境变量的值。

每个 MSBuild 项目都有一个隔离环境块：它只能看到对自己块的读写。在项目文件被计算或生成之前，MSBuild 初始化属性集合时仅读取环境变量。在此之后，环境变量属性是静态的，也就是说，每个生成工具使用相同的名称和值启动。

从一个给定的工具中获取环境变量的当前值，使用属性函数 System.Environment.GetEnvironmentVariable。然而，首选方法是使用带有任务 EnvironmentVariables 参数的方法。此字符串数组中的环境属性集可以传递给指定的工具，而不影响系统环境变量。

提示

并非所有的环境变量被读入成为初始属性。任何不是有效的 MSBuild 属性名称的环境变量如“386”，将被忽略。

有关详细信息，请参阅如何：在生成中使用环境变量。

注册表属性

可以使用下面的语法读取系统注册表值，其中 Hive 为注册表配置单元（例如 HKEY_LOCAL_MACHINE），Key 为注册表项名称，SubKey 为子项名称，Value 为子项的值。

$(registry:Hive\MyKey\MySubKey@Value)

若要获取默认子项值，请省略 Value。

$(registry:Hive\MyKey\MySubKey)

此注册表值可以用于初始化生成属性。例如，若要创建表示 Visual Studio Web 浏览器主页的生成属性，请使用此代码：

<PropertyGroup>
  <VisualStudioWebBrowserHomePage>
    $(registry:HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\12.0\WebBrowser@HomePage)
  </VisualStudioWebBrowserHomePage>
<PropertyGroup>

全局属性

MSBuild 允许您在命令行中使用 /property（或 /p）开关设置属性。这些全局属性值会重写在项目文件中设置的属性值。这包括环境属性，但不包括保留属性，保留属性无法更改。

下面的示例将 Configuration 全局属性设置为 DEBUG。

msbuild.exe MyProj.proj /p:Configuration=DEBUG

还可以使用 MSBuild 任务的 Properties 特性，为多项目生成中的子项目设置或修改全局属性。有关详细信息，请参阅MSBuild 任务。

如果您使用 TreatAsLocalProperty 属性在项目标记中指定一个属性，则项目文件中设置的属性值不会被全局的属性值重写。有关更多信息，请参见Project 元素 (MSBuild)和如何：使用不同选项生成相同的源文件。

属性函数

在 .NET Framework 4 版中，可以使用属性函数来计算您的 MSBuild 脚本。可以在生成脚本中读取系统时间、比较字符串、匹配正则表达式及执行多种其他操作，而无需使用 MSBuild 任务。

可以使用字符串（实例）方法来操作任何属性值，还可以调用许多系统类的静态方法。例如，通过以下方式可以将生成属性设置为当天的日期。

<Today>$([System.DateTime]::Now.ToString("yyyy.MM.dd"))</Today>

有关更多信息以及属性函数的列表，请参见属性函数。

在执行过程中创建属性

如果属性位于 Target 元素之外，则在生成的计算阶段为其赋值。在随后的执行阶段中，可以如下创建或修改属性：

属性可以由任何任务发出。若要发出属性，Task 元素必须有具备 PropertyName 特性的 Output 子元素。
属性可以由 CreateProperty 任务发出。此用法已弃用。
从 .NET Framework 3.5 开始，Target 元素可以包含 PropertyGroup 元素，后者可以包含属性声明。

在属性中存储 XML

属性可以包含任意 XML，这有助于将值传递给任务，或是显示日志记录信息。下面的示例显示 ConfigTemplate 属性，该属性具有的值包含 XML 和其他属性引用。 MSBuild 使用属性引用的相应属性值来替换属性引用。属性的赋值按其出现顺序进行。因此，在此示例中应已定义 $(MySupportedVersion)、$(MyRequiredVersion) 和 $(MySafeMode)。

<PropertyGroup>
    <ConfigTemplate>
        <Configuration>
            <Startup>
                <SupportedRuntime
                    ImageVersion="$(MySupportedVersion)"
                    Version="$(MySupportedVersion)"/>
                <RequiredRuntime
                    ImageVersion="$(MyRequiredVersion)
                    Version="$(MyRequiredVersion)"
                    SafeMode="$(MySafeMode)"/>
            </Startup>
        </Configuration>
    </ConfigTemplate>
</PropertyGroup>

请参见