この記事では、ビルドのカスタマイズ オプションの概要と、各アプローチを使用するタイミングに関するガイダンスを提供します。 オプションは、コマンド ライン引数からシステム全体のカスタマイズまで、複雑な順序で表示されます。
[前提条件]
- MSBuild プロジェクト ファイル構造に関する知識 (
.csproj、.vbprojなど) - MSBuild のプロパティとターゲットの基本的な理解
概要
標準のビルド プロセス (Microsoft.Common.props と Microsoft.Common.targets のインポート) を使用する MSBuild プロジェクトには、ビルド プロセスのカスタマイズに使用できる機能拡張フックがいくつかあります。
カスタマイズ可能なビルド操作の多くは、プロパティによって制御されます。 目的の効果を得るには、プロパティ値を設定する方法と場所を知っていることが重要です。 プロパティは、コマンド ライン (および応答ファイル)、 Directory.Build.props などの特殊なファイル、インポートされたファイル、またはプロジェクト ファイルで設定できます。 プロパティが使用、設定、または変更される場所と、インポートされたファイルの順序 (.NET SDK などの SDK からの暗黙的なインポートを含む) を把握することが重要です。
プロパティの一覧については、 MSBuild の共通プロパティを参照してください。
カスタマイズ オプションを調べる
次のカスタマイズ オプションは、複雑さと影響範囲を増やす順序で一覧表示されます。 この一覧の先頭から、目的に合った最も複雑なカスタマイズ オプションを使用することをお勧めします。
| カスタマイズ オプション | Description |
|---|---|
| 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ファイルで既定値を設定します。MSBuild がユーザーのプロジェクトを読み取るまでカスタマイズは行われないため、カスタマイズされた可能性があるプロパティの値を読み取って、
.propsファイルに依存プロパティを設定しないようにします。個々のプロジェクトからカスタマイズを選択するため、
.targetsファイルの依存プロパティを設定します。プロパティをオーバーライドする必要がある場合は、すべてのユーザー プロジェクトのカスタマイズを有効にした後、
.targetsファイルで行います。 派生プロパティを使用する場合は注意してください。派生プロパティもオーバーライドする必要があります。.propsファイルに項目を含める (プロパティに条件付け)。 すべてのプロパティはアイテムの前に考慮されるため、ユーザー プロジェクトのプロパティのカスタマイズが取得され、.propsファイルにアイテムをインポートすると、ユーザーのプロジェクトは、インポートによって取り込まれた項目をRemoveまたはUpdateできます。.targetsファイル内のターゲットを定義します。 ただし、.targetsファイルが SDK によってインポートされる場合は、ユーザーのプロジェクトに既定でオーバーライドする場所がないため、このシナリオではターゲットのオーバーライドがより困難になる点に注意してください。可能であれば、ターゲット内のプロパティを変更するよりも、評価時にプロパティをカスタマイズすることを優先します。 このガイドラインを使用すると、プロジェクトを読み込み、プロジェクトの実行内容を理解しやすくなります。