MSBuild 工作

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

參數

下表描述 MSBuild 工作的參數。

參數	說明
BuildInParallel	選擇性 Boolean 參數。 如果 true，則 Projects 參數中指定的專案會盡可能平行建置。 預設值為 false。
Projects	必要 ITaskItem[] 參數。 指定要建置的項目檔。
Properties	選擇性 String 參數。 要套用為子專案之全域屬性的屬性名稱/值組分號分隔清單。 當您指定此參數時，其功能相當於當您使用 MSBuild.exe建置時，設定具有 -property 參數的屬性。 例如： Properties="Configuration=Debug;Optimize=$(Optimize)" 當您透過 Properties 參數將屬性傳遞至專案時，即使專案檔已載入，MSBuild 仍可能會建立專案的新實例。 MSBuild 會為指定的項目路徑和一組唯一的全域屬性建立單一項目實例。 例如，此行為可讓您建立多個 MSBuild 工作，以使用 Configuration=Release 呼叫 myproject.proj ，而且您會取得 myproject.proj 的單一實例（如果未在工作中指定唯一屬性）。 如果您指定 MSBuild 尚未看到的屬性，MSBuild 會建立專案的新實例，此實例可以與專案的其他實例平行建置。 例如，發行組態可以與偵錯組態同時建置。
RebaseOutputs	選擇性 Boolean 參數。 如果 true，則來自建置專案之目標輸出項目的相對路徑會將其路徑調整為相對於呼叫專案。 預設值為 false。
RemoveProperties	選擇性 String 參數。 指定要移除的一組全域屬性。
RunEachTargetSeparately	選擇性 Boolean 參數。 如果 true，MSBuild 工作會叫用清單中一次傳遞至 MSBuild 的每個目標，而不是同時。 將此參數設定為 true 保證即使先前叫用的目標失敗，仍會叫用後續目標。 否則，建置錯誤會停止叫用所有後續目標。 預設值為 false。
SkipNonexistentProjects	選擇性 Boolean 參數。 如果 true，則會略過磁碟上不存在的項目檔。 否則，這類專案會造成錯誤。 預設為 false。
SkipNonexistentTargets	選擇性 Boolean 參數。 如果 true，則會略過存在但不包含具名 Targets 的項目檔。 否則，這類專案會造成錯誤。 預設為 false。 MSBuild 15.5 中引進。
StopOnFirstFailure	選擇性 Boolean 參數。 如果 true，當其中一個項目無法建置時，就不會再建置任何專案。 目前不支援在平行建置時使用此選項（使用多個處理器）。
TargetAndPropertyListSeparators	選擇性 String[] 參數。 將目標和屬性的清單指定為 Project 專案元數據）。 在處理之前，分隔符是未逸出的。 例如，%3B （逸出的 ';'） 會被視為未逸出的 ';'。
TargetOutputs	選擇性 ITaskItem[] 唯讀輸出參數。 從所有項目檔傳回建置目標的輸出。 只會傳回所指定目標的輸出，而不會傳回那些目標相依的目標上可能存在的任何輸出。 TargetOutputs 參數也包含下列元資料： - MSBuildSourceProjectFile：MSBuild 項目檔，其中包含設定輸出的目標。 - MSBuildSourceTargetName：設定輸出的目標。 注意： 如果您想要個別識別每個專案檔或目標的輸出，請針對每個項目檔或目標個別執行 MSBuild 工作。 如果您只執行一次 MSBuild 工作來建置所有項目檔，則會將所有目標的輸出收集到一個陣列中。
Targets	選擇性 String 參數。 指定要在項目檔中建置的目標或目標。 使用分號分隔目標名稱清單。 如果在 MSBuild 工作中未指定任何目標，則會建置項目檔中指定的預設目標。 注意： 目標必須發生在所有項目檔中。 如果沒有，就會發生建置錯誤。
ToolsVersion	選擇性 String 參數。 指定要在建置傳遞至這項工作的專案時使用的 ToolsVersion。 可讓 MSBuild 工作建置以與專案中所指定版本不同的 .NET Framework 為目標的專案。 有效值為 2.0、3.0和 3.5。 預設值為 3.5。

備註

除了先前列出的參數之外，此工作也會從 TaskExtension 類別繼承參數，而該類別本身會繼承自 Task 類別。 如需這些其他參數及其描述的清單，請參閱 TaskExtension 基類。

不同於使用 Exec 工作 開始 MSBuild.exe，此工作會使用相同的 MSBuild 程式來建置子專案。 可以略過之已建置的目標清單會在父組建和子組建之間共用。 此工作也較快，因為不會建立新的 MSBuild 程式。

此工作不僅可以處理項目檔，也可以處理方案檔。 在 MSBuild 17.12 和更新版本中，會接受 .slnx 和 .sln 解決方案檔格式。

MSBuild 需要的任何設定，才能讓專案同時建置，即使設定涉及遠端基礎結構（例如埠、通訊協定、逾時、重試等等），都必須使用組態檔進行設定。 可能的話，組態項目應該能夠在 MSBuild 工作上指定為工作參數。

從 MSBuild 3.5 開始，方案項目現在會顯示其建置之所有子專案的 TargetOutputs。

將屬性傳遞至專案

在 MSBuild 3.5 之前的 MSBuild 版本中，將不同的屬性集傳遞至 MSBuild 專案中所列的不同專案是一項挑戰。 如果您使用 MSBuild 工作的 Properties 屬性，則除非您批處理 MSBuild 工作，並有條件地為專案清單中的每個專案提供不同的屬性，否則其設定會套用至所有正在建置的專案。

不過，MSBuild 3.5 提供兩個新的保留元數據專案 Properties 和 AdditionalProperties，可讓您彈性地針對使用 MSBuild 工作 建置的不同項目傳遞不同的屬性。

備註

這些新的元數據專案僅適用於在 MSBuild 工作的 Projects 屬性中傳遞的專案。

多處理器建置優點

當您在多處理器系統上平行建置專案時，會發生使用此新元數據的主要優點之一。 元數據可讓您將所有項目合併成單一 MSBuild 工作 呼叫，而不需要執行任何批處理或條件式 MSBuild 工作。 當您只呼叫單一 MSBuild 工作時，Projects 屬性中列出的所有項目都會以平行方式建置。 （不過，只有在 MSBuild 工作 BuildInParallel=true 屬性中。如需詳細資訊，請參閱 平行建置多個專案。

屬性元數據

指定時，Properties 元數據會覆寫工作的 Properties 參數，而 AdditionalProperties 元數據會附加至參數的定義。

常見的案例是，當您使用 MSBuild 工作建置多個方案檔時，只會使用不同的組建組態。 您可能想要使用偵錯組態建置解決方案 a1，並使用發行組態來建置解決方案 a2。 在 MSBuild 2.0 中，此項目檔看起來如下：

備註

在下列範例中，“...”表示其他方案檔。

a.proj

<Project xmlns="http://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="http://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="http://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 工作建置兩個方案檔，兩者都使用 Release 組態，但其中一個使用 x86 架構，另一個則使用 ia64 架構。 在 MSBuild 2.0 中，您必須建立多個 MSBuild 工作實例：一個是使用發行組態搭配 x86 架構來建置專案，另一個則使用發行組態搭配 ia64 架構。 您的項目檔看起來如下所示：

a.proj

<Project xmlns="http://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="http://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="http://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>

另請參閱

• 任務
• 任務參考