MSBuild 屬性MSBuild properties

屬性是名稱/值組,可以用來設定組建。Properties are name-value pairs that can be used to configure builds. 屬性可用於將值傳遞給工作、評估條件,以及儲存將在整個專案檔中參考的值。Properties are useful for passing values to tasks, evaluating conditions, and storing values that will be referenced throughout the project file.

定義和參考專案檔中的屬性Define and reference properties in a project file

宣告屬性的方式是建立具有屬性名稱的項目,做為 PropertyGroup 項目的子項目。Properties are declared by creating an element that has the name of the property as a child of a PropertyGroup element. 例如,下列 XML 會建立名為 BuildDir 並具有 Build 值的屬性。For example, the following XML creates a property named BuildDir that has a value of Build.

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

在整個專案檔中,可使用語法 $(<PropertyName>) 來參考屬性。Throughout the project file, properties are referenced by using the syntax $(<PropertyName>). 例如,使用 $(BuildDir) 來參考上述範例中的屬性。For example, the property in the previous example is referenced by using $(BuildDir).

您可以藉由重新定義屬性來變更屬性值。Property values can be changed by redefining the property. 您可以使用下列 XML,為 BuildDir 屬性指定新值:The BuildDir property can be given a new value by using this XML:

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

屬性會以其在專案檔中出現的順序來評估。Properties are evaluated in the order in which they appear in the project file. 在指派舊值之後,必須宣告 BuildDir 的新值。The new value for BuildDir must be declared after the old value is assigned.

保留的屬性Reserved properties

MSBuild 保留一些屬性名稱來儲存專案檔和 MSBuild 二進位檔案的相關資訊。MSBuild reserves some property names to store information about the project file and the MSBuild binaries. 這些屬性是使用 $ 標記法來參考,如同任何其他屬性。These properties are referenced by using the $ notation, just like any other property. 例如,$(MSBuildProjectFile) 會傳回專案檔的完整檔名,包括副檔名。For example, $(MSBuildProjectFile) returns the complete file name of the project file, including the file name extension.

如需詳細資訊,請參閱如何:參考專案檔的名稱或位置MSBuild 保留和已知的屬性For more information, see How to: Reference the name or location of the project file and MSBuild reserved and well-known properties.

環境屬性Environment properties

就像參考保留的屬性,您可以參考專案檔中的環境變數。You can reference environment variables in project files just as you reference reserved properties. 例如,若要在專案檔中使用 PATH 環境變數,請使用 $(Path)。For example, to use the PATH environment variable in your project file, use $(Path). 如果專案包含與環境屬性相同名稱的專案定義,則專案中的屬性會覆寫環境變數的值。If the project contains a property definition that has the same name as an environment property, the property in the project overrides the value of the environment variable.

每個 MSBuild 專案都有獨立的環境區塊:只會看見本身區塊中讀取和寫入的內容。Each MSBuild project has an isolated environment block: it only sees reads and writes to its own block. 在評估或建立專案檔案之前,MSBuild 只會在初始化屬性集合時讀取環境變數。MSBuild only reads environment variables when it initializes the property collection, before the project file is evaluated or built. 在此之後,環境屬性會是靜態的,也就是說,每個繁衍的工具一開始都會採用相同的名稱和值。After that, environment properties are static, that is, each spawned tool starts with the same names and values.

若要從衍生的工具內取得環境變數的目前值,請使用屬性函式 System.Environment.GetEnvironmentVariable。To get the current value of environment variables from within a spawned tool, use the Property functions System.Environment.GetEnvironmentVariable. 然而,一般慣用的方法是使用工作參數 EnvironmentVariablesThe preferred method, however, is to use the task parameter EnvironmentVariables. 這個字串陣列中設定的環境屬性可以傳遞至繁衍的工具,而不會影響系統環境變數。Environment properties set in this string array can be passed to the spawned tool without affecting the system environment variables.

Tip

並非所有環境變數都會在讀取後變成初始屬性。Not all environment variables are read in to become initial properties. 會忽略任何未採用有效 MSBuild 屬性名稱 (例如 "386") 的環境變數。Any environment variable whose name is not a valid MSBuild property name, such as "386", is ignored.

如需詳細資訊,請參閱如何:在組建中使用環境變數For more information, see How to: Use environment variables in a build.

登錄屬性Registry properties

您可以使用下列語法來讀取系統登錄值,其中 Hive 是登錄區 (例如 HKEY_LOCAL_MACHINE)、MyKey 是機碼名稱、MySubKey 是子機碼名稱,而 Value 是子機碼的值。You can read system registry values by using the following syntax, where Hive is the registry hive (for example, HKEY_LOCAL_MACHINE), MyKey is the key name, MySubKey is the subkey name, and Value is the value of the subkey.

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

若要取得預設的子機碼值,請省略 ValueTo get the default subkey value, omit the Value.

$(registry:Hive\MyKey\MySubKey)

此登錄值可用來初始化建置屬性​​。This registry value can be used to initialize a build property. 例如,若要建立一個建置屬性​​來代表 Visual Studio Web 瀏覽器首頁,請使用下列程式碼:For example, to create a build property that represents the Visual Studio web browser home page, use this code:

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

全域屬性Global properties

MSBuild 可讓您使用 -property (或 -p) 參數,在命令列上設定屬性。MSBuild lets you set properties on the command line by using the -property (or -p) switch. 這些全域屬性值會覆寫專案檔中所設定的屬性值。These global property values override property values that are set in the project file. 這包括環境屬性,但不包含保留的屬性,您無法變更後者。This includes environment properties, but does not include reserved properties, which cannot be changed.

下列範例會將全域 Configuration 屬性設定為 DEBUGThe following example sets the global Configuration property to DEBUG.

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

您也可以使用 MSBuild 工作的 Properties 屬性,針對多專案組建中的子專案設定或修改全域屬性。Global properties can also be set or modified for child projects in a multi-project build by using the Properties attribute of the MSBuild task. 除非使用 MSBuild 工作的 RemoveProperties 屬性指定不轉送屬性清單,否則全域屬性也會轉送至子專案。Global properties are also forwarded to child projects unless the RemoveProperties attribute of the MSBuild task is used to specify the list of properties not to forward. 如需詳細資訊,請參閱 MSBuild 工作For more information, see MSBuild task.

如果您使用專案標記中的 TreatAsLocalProperty 屬性 (Attribute) 指定屬性 (Property),該全域屬性 (Property) 值就不會覆寫專案檔中設定的屬性 (Property) 值。If you specify a property by using the TreatAsLocalProperty attribute in a project tag, that global property value doesn't override the property value that's set in the project file. 如需詳細資訊,請參閱專案項目 (MSBuild)如何:使用不同選項來建置相同的來源檔案For more information, see Project element (MSBuild) and How to: Build the same source files with different options.

屬性函式Property functions

從 .NET Framework 4 版開始,您可以使用屬性函式評估您的 MSBuild 指令碼。Starting in .NET Framework version 4, you can use property functions to evaluate your MSBuild scripts. 您可以讀取系統時間、比較字串、比對規則運算式,以及執行組建指令碼中的其他動作,而不需使用 MSBuild 工作。You can read the system time, compare strings, match regular expressions, and perform many other actions within your build script without using MSBuild tasks.

您可以使用字串 (執行個體) 方法來操作任何屬性值,而且可以呼叫許多系統類別的靜態方法。You can use string (instance) methods to operate on any property value, and you can call the static methods of many system classes. 例如,您可以將建置屬性設為今天的日期,如下所示。For example, you can set a build property to today's date as follows.

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

如需詳細資訊及屬性函式清單,請參閱屬性函式For more information, and a list of property functions, see Property functions.

在執行期間建立屬性Create properties during execution

位於 Target 項目以外的屬性值是在組建的評估階段所指派。Properties positioned outside Target elements are assigned values during the evaluation phase of a build. 在後續的執行階段,可以使用下列方式來建立或修改屬性:During the subsequent execution phase, properties can be created or modified as follows:

  • 任何工作均可發出屬性。A property can be emitted by any task. 若要發出屬性,Task 項目必須含有具 PropertyName 屬性的子系 Output 項目。To emit a property, the Task element must have a child Output element that has a PropertyName attribute.

  • 透過 CreateProperty 工作來發出屬性。A property can be emitted by the CreateProperty task. 這種使用方式已過時。This usage is deprecated.

  • 從 .NET Framework 3.5 開始,Target 項目可能會包含 PropertyGroup 項目,其中可能包含屬性宣告。Starting in the .NET Framework 3.5, Target elements may contain PropertyGroup elements that may contain property declarations.

將 XML 儲存於屬性中Store XML in properties

屬性可以包含任意的 XML,其有助於將值傳遞給工作,或是顯示記錄資訊。Properties can contain arbitrary XML, which can help in passing values to tasks or displaying logging information. 下列範例示範 ConfigTemplate 屬性,其值會包含 XML 和其他屬性參考。The following example shows the ConfigTemplate property, which has a value that contains XML and other property references. MSBuildMSBuild 會藉由使用其各自的屬性值來取代屬性參考。replaces the property references by using their respective property values. 屬性值是以其出現的順序來指派。Property values are assigned in the order in which they appear. 因此,在此範例中,應該已經定義 $(MySupportedVersion)$(MyRequiredVersion)$(MySafeMode)Therefore, in this example, $(MySupportedVersion), $(MyRequiredVersion), and $(MySafeMode) should have already been defined.

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

另請參閱See also