MSBuild 條件

發行項
12/21/2023

MSBuild 支援一組特定的條件，可在允許屬性的位置 Condition 套用;請參閱支援的元素。下表說明這些條件。

條件	描述
'`stringA`' == '`stringB`'	如果 `stringA` 等於 `stringB`，即會評估為 `true`。例如： `Condition="'$(Configuration)'=='DEBUG'"` 簡單英數位元字串或布爾值不需要單引號。不過，需要使用單引號括住空白值。此檢查不區分大小寫。
`'stringA' != 'stringB'`	如果 `stringA` 不等於，則`true`評估為 `stringB`。例如： `Condition="'$(Configuration)'!='DEBUG'"` 簡單英數位元字串或布爾值不需要單引號。不過，需要使用單引號括住空白值。此檢查不區分大小寫。
<、、><=、>=	評估運算元的數值。如果關聯式評估為 true，即會傳回 `true`。運算元必須評估為十進位或十六進位數字或四部分虛線版本。十六進位數字必須以開頭 `0x`。注意︰在 XML 中，必須逸出字元 `<` 和 `>`。符號 `<` 是以 `<` 表示。符號 `>` 是以 `>` 表示。
Exists('`stringA`')	如果有名稱為 `stringA` 的檔案或資料夾存在，即會評估為 `true`。例如： `Condition="!Exists('$(Folder)')"` 簡單英數位元字串或布爾值不需要單引號。不過，需要使用單引號括住空白值。此條件不會展開通配符，例如 `*`。
HasTrailingSlash ('`stringA`')	如果指定的字串包含尾端反斜線 (\) 或正斜線 (/) 字元，則會評估為 `true`。例如： `Condition="!HasTrailingSlash('$(OutputPath)')"` 簡單英數位元字串或布爾值不需要單引號。不過，需要使用單引號括住空白值。
!	如果運算元評估為 `false`，即會評估為 `true`。
`And`	如果這兩個運算元都評估為 `true`，即會評估為 `true`。
`Or`	如果至少有一個運算元評估為 `true`，即會評估為 `true`。
()	如果內部包含的運算式評估為 `true`，即會評估為 `true` 的群組機制。
`$if$ ( %expression% ), $else$, $endif$`	檢查指定的 `%expression%` 是否符合所傳遞自訂範本參數的字串值。如果 $if$ 條件評估為 `true`，即會執行它的陳述式，否則會檢查 $else$ 條件。如果 $else$ 條件為`true`，即會執行它的陳述式，否則 $endif$ 條件會結束運算式評估。如需使用方式的範例，請參閱 Visual Studio project/item template parameter logic (Visual Studio 專案/項目範本參數邏輯)。

運算子 And 的優先順序高於 Or，但為了清楚起見，建議您在使用多個布林運算子，使用括弧讓評估順序變得明確。如果沒有，MSBuild 會提供警告 MSB4130。

您可以在條件中使用字串方法，如下列範例所示，其中 TrimEnd() 函式用來僅比較字串的相關部分，以區分.NET Framework 與 .NET Core 目標 Framework。

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

    <PropertyGroup>
        <TargetFrameworks>net45;net48;netstandard2.1;netcoreapp2.1;netcoreapp3.1</TargetFrameworks>
    </PropertyGroup>

    <PropertyGroup Condition="'$(TargetFramework.TrimEnd(`0123456789`))' == 'net'">
        <!-- Properties for .NET Framework -->
    </PropertyGroup>

</Project>

在 MSBuild 專案檔中，沒有真正的布林類型。布林值資料會以可能空白或設定為任何值的屬性來表示。因此，'$(Prop)' == 'true' 表示「如果 Prop 為 true」，但 '$(Prop)' != 'false' 表示「如果 Prop 為 true 或取消設定或設定為其他項目」。

布林邏輯只會在條件的內容中進行評估，因此，屬性設定 (例如 <Prop2>'$(Prop1)' == 'true'</Prop>) 會以字串表示 (在變數展開之後)，而不會評估為布林值。

MSBuild 會實作一些特殊的處理規則，讓您更輕鬆地處理用作布林值的字串屬性。接受布林常值，讓 Condition="true" 與 Condition="false" 如預期般運作。 MSBuild 也包含特殊規則，支援布林否定運算子。因此，如果 $(Prop) 為 'true'， !$(Prop) 則會展開至 !true ，且此值會與相等 false，如您所預期。

比較版本

關係運算子 <、>、<= 和 >= 支援依 System.Version 剖析的版本，因此您可以將具有四個數值部分的版本相互比較。例如， '1.2.3.4' < '1.10.0.0' 是 true。

警告

當一或兩個版本未指定所有四個部分時，System.Version 比較可能會產生令人驚訝的結果。例如，1.1 版比 1.1.0 版還舊。

MSBuild 會提供要比較版本的屬性函式，這些版本具有與語意版本設定 (semver) 相容的不同規則集。

條件中的展開

根據專案檔中的位置，您可以針對屬性 ($)、項目清單 (@) 和項目中繼資料 (%) 使用展開。。展開取決於 MSBuild 處理專案檔的方式。

屬性

包含運算式的條件，例如 $(SomeProperty) 會進行評估並轉換成屬性值。如果條件在目標之外，則會在評估專案檔期間評估運算式。屬性的值取決於展開所有匯入項目之後專案檔中的位置。如果條件在目標中，則會在目標執行時評估該條件，而且值會受到建置執行期間發生的任何變更所影響。

在展開的項目檔中未定義的屬性，其中條件表達式會評估為空字串，而不會發生任何診斷錯誤或警告。

項目清單

包含 @-expression (例如 @(SomeItems)) 的條件會在最上層和目標中的項目群組中展開。

項目可以依賴任何屬性，也可以依賴已定義在序列中的項目。

原因是 MSBuild 會分數個階段處理專案檔。項目評估階段會在初始屬性評估和匯入展開階段之後發生。因此，在開始定義項目之後評估的任何條件中，都允許 @-expression。也就是說，在項目、項目群組和目標中。

中繼資料

包含元中繼資料運算式 (例如 %(ItemMetadata)) 的條件會在與項目清單相同的內容中展開，也就是在最上層和目標的項目群組中。不過，展開可在項目群組中具有不同的行為，取決於項目群組在目標外還是目標內。此外，在各種形式的的中繼資料運算式 (%(ItemName.MetadataName)、%(JustTheMetadataName) 和 @(ItemName->'%(MetadataName)'))，僅允許項目轉換 (最後一個) 在目標外。目標中的 %-expression 值會在執行階段進行評估，並取決於目標執行期間的任何狀態變更。目標的執行以及其內所含任何 %-expression 的值也相依於目標的批次處理，而且也可以觸發批次處理；請參閱 MSBuild 批次處理。

支援的元素

下列元素支援 Condition 屬性：

Import
ImportGroup
項目
ItemDefinitionGroup
ItemGroup
ItemMetadata
OnError
輸出
屬性
PropertyGroup
目標
Task
UsingTask
時機