MSBuild 屬性

屬性是可用來設定組建的名稱/值組。屬性適用於將值傳遞至工作、評估條件，以及儲存將在專案檔中參考的值。

在項目檔中定義和參考屬性

屬性是透過在 PropertyGroup 元素中創建一個包含屬性名稱的子元素來宣告。例如，下列 XML 會建立名為 BuildDir 的屬性，其值為 Build。

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

有效的屬性名稱以大寫或小寫 ASCII 字母或底線（）_ 開頭;有效的後續字元包括英數字元（ASCII 字母或數字）、底線和連字號（-）。

在整個項目檔中，屬性會使用語法 $(<PropertyName>)來參考。例如，使用來參考 $(BuildDir)上一個範例中的屬性。

您可以重新定義屬性來變更屬性值。 BuildDir屬性可以使用這個 XML 來指定新的值：

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

屬性會依照專案檔中出現的順序進行評估。的新值必須在指派舊值 BuildDir 之後宣告。

保留的屬性

MSBuild 會保留一些屬性名稱，以儲存項目檔和 MSBuild 二進位檔的相關信息。這些屬性是使用 $ 表示法來參考，就像任何其他屬性一樣。例如，$（MSBuildProjectFile）會傳回項目檔的完整檔名，包括擴展名。

如需詳細資訊，請參閱如何：參考專案檔的名稱或位置，和 MSBuild 保留和已知屬性。

MSBuild 內部屬性

以底線（_）開頭的標準匯入檔案中定義的屬性是 MSBuild 的私人屬性，不應在使用者程式代碼中讀取、重設或覆寫。

環境屬性

您可以參考項目檔中的環境變數，就像參考保留屬性一樣。例如，若要在項目檔中使用 PATH 環境變數，請使用 $（Path）。如果專案包含與環境屬性同名的屬性定義，則專案中的屬性會覆寫環境變數的值。

每個 MSBuild 專案都有一個隔離的環境區塊：它只會看到讀取和寫入到它自己的區塊。 MSBuild 只會在初始化屬性集合時讀取環境變數，然後再評估或建置項目檔。之後，環境屬性是靜態的，也就是說，每個繁衍的工具都會以相同的名稱和值開頭。

若要從繁衍的工具內取得環境變數的目前值，請使用 Property 函式 System.Environment.GetEnvironmentVariable。不過，慣用的方法是使用工作參數 EnvironmentVariables。在此字串陣列中設定的環境屬性可以傳遞至繁衍的工具，而不會影響系統環境變數。

小提示

並非所有環境變數都會讀取為初始屬性。忽略名稱不是有效的 MSBuild 屬性名稱，例如「386」的任何環境變數。

如需詳細資訊，請參閱如何：在組建中使用環境變數。

登錄屬性

您可以使用下列語法來讀取系統登錄值，其中 Hive 是登錄區（例如 ，HKEY_LOCAL_MACHINE）， MyKey 是機碼名稱、 MySubKey 子機碼名稱，而 Value 是子機碼的值。

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

若要取得預設子機碼值，請省略 Value。

$(registry:Hive\MyKey\MySubKey)

這個登錄值可用來初始化組建屬性。例如，若要建立代表Visual Studio網頁瀏覽器首頁的組建屬性，請使用下列程式代碼：

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

警告

在 MSBuild 的 .NET SDK 版本中，dotnet build不支援登錄屬性。

在執行期間建立屬性

位於專案外部 Target 的屬性會在組建的評估階段指派值。在後續的執行階段中，可以建立或修改屬性，如下所示：

屬性可由任何工作發出。若要發出屬性，Task 元素必須有具有屬性的子 PropertyName 元素。
CreateProperty 工作可以發出屬性。此使用方式已被取代。
Target 元素可能包含 PropertyGroup 可能包含屬性宣告的專案。

全域屬性

MSBuild 可讓您使用 -property （或 -p）參數，在命令行上設定屬性。這些全域屬性值會覆寫項目檔中設定的屬性值。這包括環境屬性，但不包含無法變更的保留屬性。

下列範例會將全域 Configuration 屬性設定為 DEBUG。

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

您也可以使用 Properties MSBuild 工作的屬性，為多專案建置中的子項目設定或修改全域屬性。全域屬性也會轉送至子專案，除非 RemoveProperties 使用 MSBuild 工作的屬性來指定不轉送的屬性清單。如需詳細資訊，請參閱 MSBuild 工作。

本機屬性

本機屬性可以在專案中重設。全域屬性無法。使用選項從命令行 -p 設定本機屬性時，項目檔中的設定會優先於命令行。

您可以使用項目標記中的屬性來指定本機屬性 TreatAsLocalProperty 。

下列程式代碼指定兩個屬性是本機屬性：

<Project Sdk="Microsoft.Net.Sdk" TreatAsLocalProperty="Prop1;Prop2">

本機屬性不會轉送至多項目組建中的子專案。如果您在命令行 -p 上使用選項提供值，則子項目會獲得全域屬性值，而不是父專案中變更的本機值，但是子專案（或其任何匯入專案）也可以使用自己的 TreatAsLocalProperty來變更它。

具有本機屬性的範例

下列程式代碼範例示範的效果 TreatAsLocalProperty：

<!-- test1.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <PropertyGroup>
        <TreatedAsLocalProp>LocalOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <Target Name="Go">
        <MSBuild Projects="$(MSBuildThisFileDirectory)\test2.proj" Targets="Go2" Properties="Inner=true" />
    </Target>

    <Target Name="Go2" BeforeTargets="Go">
        <Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
    </Target>
</Project>

<!-- test2.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <Target Name="Go2">
        <Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
    </Target>
</Project>

假設您建置 test1.proj 命令行，並提供 TreatedAsLocalProperty 全域值 GlobalOverrideValue：

dotnet msbuild .\test1.proj -p:TreatedAsLocalProp=GlobalOverrideValue

輸出如下所示：

test1.proj(11,9): warning : TreatedAsLocalProp(test): LocalOverrideValue
test2.proj(3,9): warning : TreatedAsLocalProp(test2): GlobalOverrideValue

子專案會繼承全域值，但父專案會使用本機設定屬性。

本機屬性和匯入

在匯入的專案上使用屬性時 TreatAsLocalProperty ，當考慮屬性取得的值時，順序很重要。

下列程式代碼範例顯示對匯入項目的影響 TreatAsLocalProperty ：

<!-- importer.proj -->
<Project>
    <PropertyGroup>
        <TreatedAsLocalProp>FirstOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <Import Project="import.props" />

    <PropertyGroup>
        <TreatedAsLocalProp Condition=" '$(TrySecondOverride)' == 'true' ">SecondOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <Target Name="Go">
        <Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
    </Target>
</Project>

<!-- import.props -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <PropertyGroup>
        <TreatedAsLocalProp>ImportOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <!-- Here, TreatedAsLocalProp has the value "ImportOverrideValue"-->
</Project>

假設您建置 importer.proj 並設定的全域值 TreatedAsLocalProp ，如下所示：

dotnet msbuild .\importer.proj -p:TreatedAsLocalProp=GlobalOverrideValue

輸出如下：

importer.proj(9,9): warning : TreatedAsLocalProp(importer.proj): ImportOverrideValue

現在假設您將屬性 TrySecondOverride 建置為 true：

dotnet msbuild .\importer.proj -p:TreatedAsLocalProp=GlobalOverrideValue -p:TrySecondOverride=true

輸出如下：

importer.proj(13,9): warning : TreatedAsLocalProp(importer.proj): SecondOverrideValue

此範例顯示屬性會在使用屬性的匯入項目TreatAsLocalProperty視為本機屬性，而不只是在匯入的檔案內。屬性的值會受到全域覆寫值的影響，但只在使用匯入的專案TreatAsLocalProperty。

如需詳細資訊，請參閱 Project 元素（MSBuild）和如何：使用不同的選項建置相同的原始程序檔。

屬性函式

從 .NET Framework 第 4 版開始，您可以使用屬性函式來評估 MSBuild 腳本。您可以讀取系統時間、比較字串、比對正則表達式，以及在建置腳本中執行許多其他動作，而不使用 MSBuild 工作。

您可以使用字串（instance）方法來作任何屬性值，而且您可以呼叫許多系統類別的靜態方法。例如，您可以將組建屬性設定為今天的日期，如下所示。

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

如需詳細資訊和屬性函式的清單，請參閱屬性函式。

將 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>

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-12