ビルドのカスタマイズ

  • [アーティクル]

標準のビルド プロセス (Microsoft.Common.props と Microsoft.Common.targets のインポート) を使用する MSBuild プロジェクトには、ビルド プロセスのカスタマイズに使用できる拡張フックがいくつかあります。

カスタマイズ可能なビルド操作の多くは、プロパティによって制御されます。 必要な効果が得られるように、プロパティ値を設定する方法と場所を把握しておくことが重要です。 プロパティは、コマンド ライン (および応答ファイル)、Directory.Build.props などの特殊なファイル、インポートされたファイル、またはプロジェクト ファイルで設定できます。 プロパティを使用、設定、または変更する場所と、インポートされたファイル (.NET SDK などの SDK からの暗黙的なインポートを含む) の順序を把握しておくことが重要です。

プロパティの一覧については、MSBuild の共通プロパティに関する記事を参照してください。

カスタマイズ オプションを調べる

次のカスタマイズ オプションは、増す複雑性と影響の範囲の順に一覧表示されています。 この一覧の一番上から、目的に合った最も複雑度の低いカスタマイズ オプションを使用することをお勧めします。

カスタマイズ オプション 説明
MSBuild コマンド ラインに引数を追加する メイン プロジェクトのビルドと、依存するすべてのプロジェクトのビルドに影響するグローバル プロパティを設定します。
1 つのプロジェクトのビルドをカスタマイズする .props または .targets ファイルにプロパティを追加して、ビルド設定をカスタマイズします。
ビルド プロセスで生成されたファイルを処理する 生成されたファイルがビルド出力に正しく含まれていることを確認する方法。
1 つ以上のプロジェクトのビルドをカスタマイズする Directory.Build.props にプロパティを追加するか、Directory.Build.targets にプロパティとターゲットを追加して、フォルダーの下にあるすべてのプロジェクトのビルドをカスタマイズします。 この手法は、SDK によって設定または使用されるプロパティを設定したり、カスタマイズをスコープ設定してフォルダーまたはサブフォルダー内のすべてのプロジェクトに影響を与える場合に便利です。
ローカル ビルドをカスタマイズする 共有ソース ファイルに影響を与えることなく、ローカル コンピューター上のビルドに変更を加えます。
すべての .NET ビルドをカスタマイズする .NET ビルド用に、システム全体のスコープを使用してビルドをカスタマイズします。
C++ ビルドのカスタマイズ システム上の MSBuild のインストールによって管理されるプロジェクト、ソリューション、フォルダー、またはすべてのビルドを対象範囲とする C++ ビルドをカスタマイズします。

プロジェクトのコマンドライン MSBuild 呼び出しに引数を追加する

コマンド ラインではグローバル プロパティを設定することができます。 グローバル プロパティは、依存関係を含むすべてのプロジェクト ビルドに影響します。 プロジェクトをビルドすると、すべてのプロジェクト依存関係に対して可能なビルドが自動的にトリガーされることを思い出してください。 MSBuild の通常の動作は、古くなっているすべての依存プロジェクトをビルドすることです。 そのような依存プロジェクトのビルドは、元のプロジェクトと同じコマンド ラインのグローバル プロパティ設定を使って起動されます。

ソース ディレクトリの中またはその上にある Directory.Build.rsp ファイルがプロジェクトのコマンドライン ビルドに適用されます。 詳細については、「MSBuild 応答ファイル」を参照してください。

.props または .targets ファイルのどちらにプロパティを追加するかを選択する

MSBuild はインポートの順序に依存するので、最後のプロパティ (または、UsingTask またはターゲット) の定義が使われます。

明示的なインポートを使うときは、いつでも .props または .targets ファイルからインポートできます。 広く使われている規則を次に示します。

  • .props ファイルは、インポート順序の早い段階でインポートします。

  • .targets ファイルは、ビルド順序の後の方でインポートします。

この規則は、<Project Sdk="SdkName"> のインポートによって適用されます (つまり、Sdk.props はファイルのすべての内容の前で最初にインポートされ、Sdk.targets はファイルのすべての内容の後で最後にインポートされます)。

プロパティを格納する場所を決定するときは、次の一般的なガイドラインを使います。

  • 多くのプロパティについては、上書きされず、実行時にのみ読み取られるため、どこで定義してもかまいません。

  • 個々のプロジェクトでカスタマイズされる可能性がある動作については、 .props ファイルで既定値を設定します。

  • カスタマイズされている可能性のあるプロパティの値を読み取ることによって、.props ファイルで依存プロパティを設定しないでください。カスタマイズは、MSBuild でユーザーのプロジェクトが読み取られるまで行われません。

  • 依存プロパティは、.targets ファイルで設定してください。そうすれば、個々のプロジェクトからカスタマイズが取得されます。

  • プロパティをオーバーライドする必要がある場合は、ユーザー プロジェクトのすべてのカスタマイズが有効になる機会を持った後の、 .targets ファイルの中で行います。 派生プロパティを使うときは注意してください。派生プロパティのオーバーライドも必要な場合があります。

  • .props ファイルで項目をインクルードします (プロパティの条件に応じて)。 すべての項目の前ですべてのプロパティが考慮されるので、ユーザー プロジェクトのプロパティのカスタマイズが取得され、.props ファイルに項目をインポートしたことにより、ユーザーのプロジェクトでインポートによって取り込まれた項目を Remove または Update する機会があります。

  • ターゲットは .targets ファイル内で定義します。 ただし、 .targets ファイルが SDK によってインポートされる場合は、ユーザーのプロジェクトによって既定でターゲットをオーバーライドする場所がないため、ターゲットのオーバーライドが難しくなることに注意してください。

  • 可能であれば、ターゲット内のプロパティを変更するより、評価時にプロパティをカスタマイズするようにします。 このガイドラインに従うと、プロジェクトを読み込むこと、および何が行われているか理解することが、容易になります。

関連するコンテンツ