共用方式為

MSBuild 工作

更新：2007 年 11 月

從另一個 MSBuild 專案建置 MSBuild 專案。

參數

下表說明 MSBuild 工作的參數。

參數

描述

BuildInParallel

選擇性的 Boolean 參數。

如果為 true，Projects 參數中指定的專案會在可能的情況下同時建置。預設值為 true。

Projects

必要的 ITaskItem[] 參數。

指定要建置的專案檔。

Properties

選擇性 (Optional) String 參數。

以分號分隔的屬性名稱/值組清單，可當做全域屬性套用至子專案。當您指定這個參數時，其功能相當於使用 MSBuild.exe 建置時設定有 /property 參數的屬性。例如：

Properties="Configuration=Debug;Optimize=$(Optimize)"

當您透過 Properties 參數傳遞屬性給專案時，MSBuild 會建立專案的新執行個體，即使專案檔已經載入。建立了專案的新執行個體之後，MSBuild 會將它視為不同的專案，有不同的全域屬性，而且可以與專案的其他執行個體同時建置。例如，發行組態可以與偵錯組態同時建置。

ToolsVersion

選擇性的 String 參數。

可讓 MSBuild 工作建置專案時，將目標設為不同於專案所指定的 .NET Framework 版本。有效值為 2.0、3.0 和 3.5。預設值為 3.5。

RebaseOutputs

選擇性 Boolean 參數。

如果為 true，則建置專案中目標輸出項目的相對路徑，會將其路徑調整為相對於呼叫的專案。預設值為 false。

RunEachTargetSeparately

選擇性 Boolean 參數。

如果為 true，MSBuild 工作會一次叫用一個傳遞給 MSBuild 的清單中的每個目標，而不是同時叫用。將此參數設為 true 可保證即使先前叫用的目標失敗，仍會叫用後續的目標。否則，建置錯誤就會停止叫用所有後續目標。預設值為 false。

StopOnFirstFailure

選擇性 Boolean 參數。

如果為 true，會強制工作在任何專案無法運作之後，立即停止建置其餘的專案。

TargetOutputs

選擇性的 ITaskItem[] 唯讀輸出參數。

傳回來自所有專案檔之建置目標的輸出。只會傳回指定目標的輸出，而不是任何可能存在於這些目標所相依目標上的輸出。

TargetOutputs 參數也包含下列中繼資料 (Metadata)：

  • MSBuildProjectFile：MSBuild 專案檔，其中包含設定輸出的目標。

  • MSBuildTargetName：設定輸出的目標。

注意事項：

如果要分開識別每個專案檔或目標的輸出，請針對每個專案檔或目標個別執行 MSBuild 工作。如果只執行一次 MSBuild 工作來建置所有的專案檔，則所有目標的輸出都會收集到一個陣列中。

Targets

選擇性 String 參數。

指定要在專案檔中建置的一個或多個目標。使用分號來分隔目標名稱清單。如果沒有在 MSBuild 工作中指定目標，則會建置專案檔中所指定的預設目標。

注意事項：

目標必須存在於所有的專案檔中。如果沒有的話，就會發生建置錯誤。

備註

不同於使用 Exec 工作來啟動 MSBuild.exe，此工作使用相同的 MSBuild 處理序來建置子專案。在父建置和子建置之間，共用可以略過的已建置目標清單。由於沒有建立新的 MSBuild 處理序，此工作的速度也會更快。

此工作不僅能處理專案檔，也能處理方案檔。

MSBuild 可讓專案同時建置所需的任何組態 (即使組態牽涉到遠端基礎結構，例如通訊埠、通訊協定、逾時、重試次數等等)，都必須可以使用組態檔來設定。如果可能，組態項目應能夠指定為 MSBuild 工作上的工作參數。

從 MSBuild 3.5 開始，方案專案現在會將 TargetOutputs 從其建置的所有子專案提至最上層。

傳遞屬性至專案

在 MSBuild 3.5 先前的 MSBuild 版本中，將不同幾組屬性傳遞至 MSBuild 項目所列的專案並不容易。如果您使用 MSBuild 工作的 Properties 屬性 (Attribute)，其設定會套用到建置的所有專案，除非您批次處理 MSBuild 工作，並使用條件提供不同屬性 (Property) 給項目清單中的每個專案。

不過，MSBuild 3.5 現在提供兩個新的保留中繼資料項目：Properties 和 AdditionalProperties，可讓您以彈性方式傳遞不同屬性給使用 MSBuild 工作建置的不同專案。

注意事項：

這兩個新的中繼資料項目只適用於傳遞到 MSBuild 工作的 Projects 屬性的項目。

多處理器建置的好處

當您在多處理器系統上同時建置專案時，就能感受到使用此新中繼資料的主要好處之一。此中繼資料可讓您將所有專案合併到單一 MSBuild 工作呼叫，而無須執行任何批次或條件式 MSBuild 工作。而且只要呼叫單一 MSBuild 工作，Projects 屬性中所列的全部專案將會同時建置(不過，前提是 BuildInParallel=true 屬性存在於 MSBuild 工作)。如需詳細資訊，請參閱使用多處理器進行建置。

Properties 中繼資料

當您使用 MSBuild 工作建置多個方案檔時，可能常會碰到想要使用不同組建組態的情況。您可能想要使用偵錯組態建置方案 a1，使用發行組態建置方案 a2。在 MSBuild 2.0 中，這個專案檔看起來可能如下：

注意事項：

在下列範例中，"…" 代表更多的方案檔。

a.proj

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="Build">
        <MSBuild Projects="a1.sln…" Properties="Configuration=Debug"/>
        <MSBuild Projects="a2.sln" Properties="Configuration=Release"/>
    </Target>
</Project>

不過，藉由使用 Properties 中繼資料，您可以簡化這個範例，只使用單一 MSBuild 工作，如下所示：

a.proj

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln…">
            <Properties>Configuration=Debug</Properties>
        </ProjectToBuild>
        <ProjectToBuild Include="a2.sln">
            <Properties>Configuration=Release</Properties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)"/>
    </Target>
</Project>

-或-

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln…"/>
        <ProjectToBuild Include="a2.sln">
            <Properties>Configuration=Release</Properties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)" 
          Properties="Configuration=Debug"/>
    </Target>
</Project>

AdditionalProperties 中繼資料

假設有下列情況：您使用 MSBuild 工作建置兩個方案檔，兩者都使用發行組態，但其中一個使用 x86 架構，另一個使用 ia64 架構。在 MSBuild 2.0 中，您會需要建立 MSBuild 工作的多個執行個體：其中一個使用具有 x86 架構的發行組態建置，另一個使用具有 ia64 架構的發行組態建置。這個專案檔看起來可能如下：

a.proj

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="Build">
        <MSBuild Projects="a1.sln…" Properties="Configuration=Release; 
          Architecture=x86"/>
        <MSBuild Projects="a2.sln" Properties="Configuration=Release; 
          Architecture=ia64"/>
    </Target>
</Project>

藉由使用 AdditionalProperties 中繼資料，您可以簡化這個範例，只使用單一 MSBuild 工作，如下所示：

a.proj

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln…">
            <AdditionalProperties>Architecture=x86
              </AdditionalProperties>
        </ProjectToBuild>
        <ProjectToBuild Include="a2.sln">
            <AdditionalProperties>Architecture=ia64
              </AdditionalProperties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)" 
          Properties="Configuration=Release"/>
    </Target>
</Project>

範例

下列範例使用 MSBuild 工作來建置 ProjectReferences 項目集合所指定的專案。結果目標輸出會儲存在 AssembliesBuiltByChildProjects 項目集合中。

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">

    <ItemGroup>
        <ProjectReferences Include="*.*proj" />
    </ItemGroup>

    <Target Name="BuildOtherProjects">
        <MSBuild
            Projects="@(ProjectReferences)"
            Targets="Build">
            <Output
                TaskParameter="TargetOutputs"
                ItemName="AssembliesBuiltByChildProjects" />
        </MSBuild>
    </Target>

</Project>

請參閱

概念

MSBuild 工作

其他資源

MSBuild 工作參考

  • Last updated on