MSBuild タスク

  • [アーティクル]

他の MSBuild プロジェクトから MSBuild プロジェクトをビルドします。

パラメーター

MSBuild タスクのパラメーターの説明を次の表に示します。

パラメーター

説明

BuildInParallel

省略可能な Boolean 型のパラメーターです。

true に設定すると、可能な場合、Projects パラメーターに指定されたプロジェクトが同時にビルドされます。 既定値は false です。

Projects

必須の ITaskItem[] 型のパラメーターです。

ビルドするプロジェクト ファイルを指定します。

Properties

省略可能な String 型のパラメーターです。

子プロジェクトにグローバル プロパティとして適用するプロパティ名と値のペアを、セミコロン (;) で区切って指定します。 このパラメーターを指定することは、MSBuild.exe でビルドするときに /property スイッチでプロパティを設定することと同じ意味になります。 次に例を示します。

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

Properties パラメーター経由でプロジェクトにプロパティを渡すと、プロジェクト ファイルが既に読み込まれている場合でも、MSBuild はプロジェクトの新しいインスタンスを作成します。 プロジェクトの新しいインスタンスが作成されると、MSBuild はそのインスタンスを、異なるグローバル プロパティを持ち、プロジェクトの他のインスタンスと同時にビルド可能な別のプロジェクトとして扱います。 たとえば、リリース構成をデバッグ構成と同時にビルドできます。

RebaseOutputs

省略可能な Boolean 型のパラメーターです。

true に設定すると、ビルドするプロジェクトからのターゲットの出力アイテムの相対パスは、呼び出し元プロジェクトからの相対パスに合わせられます。 既定値は false です。

RemoveProperties

省略可能な String 型のパラメーターです。

削除するグローバル プロパティのセットを指定します。

RunEachTargetSeparately

省略可能な Boolean 型のパラメーターです。

true に設定すると、MSBuild タスクでは、MSBuild に渡された一覧内のターゲットが (同時にではなく) 1 つずつ起動されます。 このパラメーターを true に設定すると、前に起動したターゲットが失敗しても、以降のターゲットは起動されることが保証されます。 それ以外の場合は、ビルド エラーが発生すると、以降のターゲットの起動は停止されます。 既定値は false です。

SkipNonexistentProjects

省略可能な Boolean 型のパラメーターです。

true の場合、ディスク上に存在しないプロジェクト ファイルはスキップされます。 それ以外の場合は、そのようなプロジェクトによりエラーが発生します。

StopOnFirstFailure

省略可能な Boolean 型のパラメーターです。

true の場合、プロジェクトの 1 つがビルドに失敗すると、それ以上のプロジェクトはビルドされません。 この機能は現在、平行ビルド (複数のプロセッサを使用) の際にはサポートされません。

TargetAndPropertyListSeparators

省略可能な String[] 型のパラメーターです。

Project 項目メタデータとしてターゲットおよびプロパティのリストを指定します。 区切り記号は、処理の前にエスケープ解除されます。 たとえば.. %3B (エスケープする; " ) は "エスケープすると同じように扱われます; "。

TargetOutputs

省略可能な ITaskItem[] 型の読み取り専用出力パラメーターです。

すべてのプロジェクト ファイルからビルドされたターゲットの出力を返します。 指定したターゲットの出力だけが戻ります。指定したターゲットが依存するターゲットが存在しても、それらのターゲットの出力は戻りません。

TargetOutputs パラメーターには、次のメタデータも含まれます。

  • MSBuildSourceProjectFile: 出力を設定するターゲットを含む MSBuild プロジェクト ファイルです。

  • MSBuildSourceTargetName: 出力を設定するターゲットです。

注意

各プロジェクト ファイルまたはターゲットの出力を分けるには、プロジェクト ファイルまたはターゲットごとに MSBuild タスクを実行します。MSBuild タスクを 1 度だけ実行してすべてのプロジェクト ファイルをビルドすると、すべてのターゲットが 1 つの配列に格納されます。

Targets

省略可能な String 型のパラメーターです。

ターゲットや、プロジェクト ファイルでビルドするターゲットを指定します。 ターゲット名の一覧を区切るには、セミコロン (;) を使用します。 MSBuild タスクにターゲットを指定しない場合は、プロジェクト ファイルで指定されている既定のターゲットがビルドされます。

注意

ターゲットは、すべてのプロジェクト ファイルに必要です。ターゲットが存在しない場合は、ビルド エラーが発生します。

ToolsVersion

省略可能な String 型のパラメーターです。

このタスクに渡されたプロジェクトのビルド時に使用する ToolsVersion を指定します。

プロジェクトで指定されたものとは異なる、.NET Framework の別のバージョンを対象とするプロジェクトをビルドする MSBuild タスクを有効にします。 有効な値は 2.0、3.0、および 3.5 です。 既定値は 3.5 です。

UnloadProjectsOnCompletion

省略可能な Boolean 型のパラメーターです。

true の場合、操作が完了したらプロジェクトはアンロードされます。

UseResultsCache

省略可能な Boolean 型のパラメーターです。

true の場合、キャッシュされた結果が返されます (ある場合)。 MSBuild タスクが実行された場合、その結果は、ビルドされた項目のリストとしてスコープ ((ProjectFileName, GlobalProperties)[TargetNames])

にキャッシュされます。

解説

上記のパラメーター以外に、このタスクは TaskExtension クラスからパラメーターを継承します。このクラス自体は、Task クラスから継承されます。 これらの追加のパラメーターの一覧とその説明については、「TaskExtension 基本クラス」を参照してください。

Exec タスクを使用して MSBuild.exe を起動する場合と異なり、このタスクでは、同じ MSBuild プロセスで子プロジェクトがビルドされます。 ビルド済みであるためスキップできるターゲットの一覧は、親プロジェクトのビルドと子プロジェクトのビルドの両方で共有されます。 また、新しい MSBuild プロセスが作成されないため、このタスクは高速です。

このタスクでは、プロジェクト ファイルだけでなく、ソリューション ファイルも処理できます。

プロジェクトを同時にビルドすることを有効にするために MSBuild によって求められる構成は、構成に (ポート、プロトコル、タイムアウト、再試行などの) リモート インフラストラクチャが関連する場合でも、構成ファイルを使用して構成可能にする必要があります。 可能であれば、構成項目を MSBuild タスクのタスク パラメーターとして指定できるようにします。

MSBuild 3.5 以降、ソリューション プロジェクトは、ビルドするすべてのサブプロジェクトから TargetOutputs を出力するようになりました。

プロジェクトへのプロパティの引き渡し

MSBuild 3.5 以前のバージョンの MSBuild では、MSBuild 項目に一覧が表示されている別のプロジェクトに対してプロパティの別のセットを渡すことは困難でした。 MSBuild タスクの Properties 属性を使用すると、MSBuild タスクをバッチ処理し、項目リスト内の各プロジェクトに対して別のプロパティを条件に応じて用意する場合を除き、その設定はビルド対象のすべてのプロジェクトに適用されました。

しかし、MSBuild 3.5 には、新しい予約済みのメタデータ項目が 2 つあります (Properties および AdditionalProperties)。これらのメタデータ項目は、MSBuild タスクを使用してビルドされる別プロジェクトに異なるプロパティを渡すための柔軟な方法を提供します。

注意

これらのメタデータ項目は、MSBuild タスクの Projects 属性に渡される項目に対してのみ適用可能です。

マルチプロセッサ上でのビルドの利点

この新しいメタデータを使用する最大の利点の 1 つは、マルチプロセッサ上でプロジェクトを同時にビルドする場合に見られます。 メタデータを使用することで、すべてのプロジェクトを単一の MSBuild タスク呼び出しに統合することができます。バッチ処理や条件付き MSBuild タスクを実行する必要はありません。 単一の MSBuild タスクだけを呼び出すと、Projects 属性に指定されているすべてのプロジェクトが同時にビルドされます (ただし、BuildInParallel=true 属性が MSBuild タスクに指定されている場合に限定されます)。詳細については、「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 タスクを使用して 2 つのソリューション ファイルをビルドするシナリオを考えます。いずれのソリューション ファイルでもリリース構成を使用しますが、一方は 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 タスク リファレンス