MSBuild 屬性

發行項
03/01/2013

屬性是成對的名稱-值組，可以用來設定組建 (Build)。屬性的用途包括將值傳遞給工作、評估條件，以及儲存整個專案檔中所要參考的值。

在專案檔中定義和參考屬性

宣告屬性的方式，是建立一個具有屬性名稱的項目，做為 PropertyGroup 項目的子項目。例如，下列 XML 會建立名為 BuildDir 並具有 Build 值的屬性。

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

在整個專案檔中，是使用語法 $(PropertyName) 參考屬性的。例如，上述範例的屬性是藉由使用 $(BuildDir) 參考的。

您可以藉由重新定義屬性來變更屬性值。使用這段 XML 即可以讓 BuildDir 屬性取得新值：

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

屬性的評估順序就是該屬性在專案檔中出現的順序。BuildDir 的新值必須在指派舊值之後宣告。

保留的屬性

MSBuild 保留一些屬性名稱來儲存專案檔和 MSBuild 二進位檔案的相關資訊。這些屬性就跟其他任何屬性一樣，都使用 $ 標記法來參考。例如，$(MSBuildProjectFile) 會傳回專案檔的完整檔名，包括副檔名。

如需詳細資訊，請參閱HOW TO：參考專案檔的名稱或位置與MSBuild 保留屬性。

環境屬性

在專案檔中參考環境變數的方式，就跟參考保留的屬性一樣。例如，若要在專案檔中使用 PATH 環境變數，請使用 $(Path)。如果專案含有與環境屬性同名的屬性定義，則專案的屬性會覆寫環境變數的值。

每個 MSBuild 專案具有隔離環境區塊:它只會看到給其區塊讀取和寫入。MSBuild 只讀取環境變數，當它初始化時，屬性集，在專案檔中評估或建置之前。在此之後，環境屬性是靜態的，也就是說，每個具有相同的名稱和值的產生的工具啟動。

若要取得環境變數的目前值從一個產生的工具的內部，請使用屬性函式 System.Environment.GetEnvironmentVariable。慣用的方法，不過，將使用工作參數 EnvironmentVariables。在這個字串陣列時設定的環境屬性可以傳遞至產生的工具，而不影響系統環境變數。

提示
並非所有的環境變數寫入成為初始屬性。名稱不是有效的 MSBuild 屬性名稱，例如「386 "的所有環境變數，則會忽略。

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

登錄屬性

您可以使用下列語法讀取系統登錄值，其中 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\11.0\WebBrowser@HomePage)
  </VisualStudioWebBrowserHomePage>
<PropertyGroup>

全域屬性

MSBuild 可以讓您藉由使用 /property (或 /p) 參數，在命令列設定屬性。這些全域屬性值會覆寫專案檔中設定的屬性值。這包括環境屬性，但不包括無法變更的保留屬性。

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

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

對於多專案建置中的子專案，也可以藉由使用 MSBuild 工作的 Properties 屬性 (Attribute) 設定或修改全域屬性 (Property)。如需詳細資訊，請參閱MSBuild 工作。

如果指定屬性使用 TreatAsLocalProperty 屬性在專案標記，該全域屬性值不會覆寫專案檔設定的屬性值。如需詳細資訊，請參閱Project 項目 (MSBuild)與HOW TO：使用不同選項來建置相同的原始程式檔。

屬性函式

在 Microsoft .NET Framework 4 中，您可以使用屬性函式評估您的 MSBuild 指令碼。不需要使用 MSBuild 工作，您就可以在建置指令碼內讀取系統時間、比較字串、比對規則運算式以及執行許多其他動作。

您可以使用字串 (執行個體) 方法操作任何屬性值，並呼叫許多系統類別的靜態方法。例如，您可以使用如下方式將建置屬性的日期設定為今天：

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

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

建立執行期間的屬性

置於 Target 項目外的屬性，是在組建的評估階段期間指派值的。在後續的執行階段期間，您可以下列方式建立或修改屬性：

屬性 (Property) 可以由任何工作發出。若要發出屬性 (Property)，Task 項目必須具有包含 PropertyName 屬性 (Attribute) 的子項目 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>

請參閱

共用方式為