次の方法で共有

チュートリアル: MSBuild を使用する

  • [アーティクル]

MSBuild は、Microsoft および Visual Studio 用のビルド プラットフォームです。 このチュートリアルでは、MSBuild の構成要素について説明し、MSBuild プロジェクトの記述、操作、デバッグを行う方法について説明します。 以下について学習します。

  • プロジェクト ファイルの作成と操作。

  • ビルド プロパティを使用する方法。

  • ビルド項目の使用方法。

MSBuild は、Visual Studio または コマンド ウィンドウから実行できます。 このチュートリアルでは、Visual Studio を使用して MSBuild プロジェクト ファイルを作成します。 Visual Studio でプロジェクト ファイルを編集し、コマンド ウィンドウ を使用してプロジェクトをビルドし、結果を確認します。

MSBuild をインストールする

Visual Studio をお持ちの場合は、MSBuild が既にインストールされています。 Visual Studio 2019 以降では、Visual Studio インストール フォルダーの下にインストールされます。 Windows 10 での一般的な既定のインストールでは、MSBuild.exe は MSBuild\Current\Bin のインストール フォルダー下にあります。

インストーラーで、使用するワークロードの MSBuild ツールが選択されていることを確認し、[ インストール] を選択します。

MSBuild のインストール

Visual Studio を持たないシステムに MSBuild をインストールするには、Visual Studio 2019 のビルド ツールに移動するか、.NET SDKをインストールします。

Visual Studio をお持ちの場合は、MSBuild が既にインストールされています。 Visual Studio 2022 では、Visual Studio のインストール フォルダーの下にインストールされます。 Windows 10 での一般的な既定のインストールでは、MSBuild.exe は MSBuild\Current\Bin のインストール フォルダー下にあります。

Visual Studio インストーラーで、[個々のコンポーネント]に移動し、MSBuildのチェック ボックスを見つけます。 インストールする他のワークロードのいずれかを選択すると、自動的に選択されます。

Visual Studio を持たないシステムに MSBuild をインストールするには、ダウンロード ページの Build Tools for Visual Studio 2022に移動します。 MSBuild を取得するもう 1 つの方法は、.NET SDKをインストールすることです。

MSBuild プロジェクトを作成する

Visual Studio プロジェクト システムは MSBuild に基づいています。 Visual Studio を使用して新しいプロジェクト ファイルを簡単に作成できます。 このセクションでは、C# プロジェクト ファイルを作成します。 代わりに Visual Basic プロジェクト ファイルを作成することもできます。 このチュートリアルのコンテキストでは、2 つのプロジェクト ファイルの違いは軽微です。

プロジェクト ファイルを作成するには

  1. Visual Studio を開き、プロジェクトを作成します。

    検索ボックスに「winforms」と入力し、[新しい Windows フォーム アプリの作成 (.NET Framework)を選択します。 表示されたダイアログボックスで、を選び、を作成します。

    「プロジェクト名 ボックス」に「BuildApp」と入力します。 ソリューションの 場所 を入力します (例: D:\)。

  2. [OK] または [作成] をクリックしてプロジェクト ファイルを作成します。

プロジェクト ファイルを調べる

前のセクションでは、Visual Studio を使用して C# プロジェクト ファイルを作成しました。 プロジェクト ファイルは、BuildApp という名前のプロジェクト ノードによって ソリューション エクスプローラーで表されます。 Visual Studio コード エディターを使用して、プロジェクト ファイルを調べることができます。

プロジェクト ファイルを調べるには、次の手順に従います:

  1. ソリューション エクスプローラー で、BuildApp のプロジェクト ノードクリックします。

  2. プロパティ ブラウザーで、[プロジェクト ファイル] プロパティが BuildApp.csproj になっていることを確認します。 すべてのプロジェクト ファイルには、proj サフィックスが付いています。 Visual Basic プロジェクトを作成した場合、プロジェクト ファイル名は BuildApp.vbproj になります。

  3. プロジェクト ノードをもう一度右クリックし、[BuildApp.csproj 編集] をクリックします。

    プロジェクト ファイルがコード エディターに表示されます。

手記

C++ などの一部のプロジェクトの種類では、プロジェクト ファイルを開いて編集する前に、プロジェクトをアンロードする (プロジェクト ファイルを右クリックして [プロジェクトのアンロード] を選択する) 必要があります。

ターゲットとタスク

プロジェクト ファイルは、プロジェクト のルート ノードXML 形式のファイルです。

ほとんどの .NET プロジェクトには、Sdk 属性があります。 これらのプロジェクトは、SDK スタイルのプロジェクトと呼ばれます。 SDK を参照すると、MSBuild は、その SDK のビルド インフラストラクチャを提供する一連のファイルをインポートすることを意味します。 どの SDK も参照していない場合でも、MSBuild を使用できますが、SDK 固有のすべてのプロパティとターゲットが自動的に使用できるわけではありません。

<Project Sdk="Microsoft.NET.Sdk">

特別な目的のために、.NET SDK には多くのバリエーションがあります。これらは、.NET Project SDKで説明されています。

アプリケーションのビルド作業は、ターゲット とタスク 要素 使用して行われます。

  • タスクは、最小の作業単位、つまりビルドの "atom" です。 タスクは独立した実行可能コンポーネントであり、入力と出力を持つことができます。 現在、プロジェクト ファイルで参照または定義されているタスクはありません。 次のセクションでは、プロジェクト ファイルにタスクを追加します。 詳細については、「タスクの」を参照してください。

  • ターゲットは、タスクの名前付きシーケンスです。 タスクの名前付きシーケンスである可能性がありますが、重要なことに、ビルドまたは実行する内容を表すので、目標指向の方法で定義する必要があります。 詳細については、「ターゲット」を参照してください。

既定のターゲットはプロジェクト ファイルで定義されていません。 代わりに、インポートされたプロジェクトで指定されます。 Import 要素は、インポートされたプロジェクトを指定します。 たとえば、C# プロジェクトでは、既定のターゲットは Microsoft.CSharp.targets ファイルからインポートされます。

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

インポートされたファイルは、参照されている場所を問わず、プロジェクト ファイルに効果的に挿入されます。

SDK スタイルのプロジェクトでは、SDK 属性によってこのファイルが暗黙的にインポートされるため、このインポート要素は表示されません。

MSBuild はビルドのターゲットを追跡し、各ターゲットが一度だけビルドされることを保証します。

ターゲットとタスクを追加する

プロジェクト ファイルにターゲットを追加します。 メッセージを出力するタスクをターゲットに追加します。

ターゲットとタスク を追加するには

  1. Import ステートメントまたは開始 Project 要素の直後に、これらの行をプロジェクト ファイルに追加します。

    <Target Name="HelloWorld">
</Target>

    このコードにより、HelloWorld という名前のターゲットが作成されます。 プロジェクト ファイルの編集中に IntelliSense がサポートされていることに注意してください。

  2. HelloWorld ターゲットに行を追加して、結果のセクションを次のようにします。

    <Target Name="HelloWorld">
  <Message Text="Hello"></Message>
  <Message Text="World"></Message>
</Target>

  3. プロジェクト ファイルを保存します。

Message タスクは、MSBuild に付属する多くのタスクの 1 つです。 使用可能なタスクと使用状況の情報の完全な一覧については、「タスク リファレンス」を参照してください。

Message タスクは、Text 属性の文字列値を入力として受け取り、出力デバイスに表示します (または、該当する場合は 1 つ以上のログに書き込みます)。 HelloWorld ターゲットは、メッセージ タスクを 2 回実行します。最初に "Hello" を表示し、次に "World" を表示します。

ターゲットをビルドする

Visual Studio からこのプロジェクトをビルドしようとすると、定義したターゲットはビルドされません。 これは、Visual Studio が既定のターゲットを選択するためです。これは、インポートされた .targets ファイル内のターゲットのままです。

Visual Studio の 開発者コマンド プロンプト から MSBuild を実行して、前に定義した HelloWorld ターゲットをビルドします。 -target または -t コマンド ライン スイッチを使用して、ターゲットを選択します。

手記

以降のセクションでは、開発者コマンド プロンプト を コマンド ウィンドウ と見なします。

ターゲットをビルドするには:

  1. コマンド ウィンドウを開きます。

    タスク バーの検索ボックスに、ツールの名前 (dev や developer command promptなど) の入力を開始します。 検索パターンに一致するインストール済みアプリの一覧が表示されます。

    手動で見つける必要がある場合、ファイルは {Visual Studio インストール フォルダー}\Common7\Tools フォルダーに LaunchDevCmd.bat されます。

  2. コマンド ウィンドウから、プロジェクト ファイルを含むフォルダーに移動します。この場合は、D:\BuildApp\BuildApp します。

  3. コマンド スイッチ -t:HelloWorldを使用して msbuild を実行します。 このコマンドは、HelloWorld ターゲットを選択してビルドします。

    msbuild buildapp.csproj -t:HelloWorld

  4. コマンド ウィンドウで出力を確認します。 "Hello" と "World" の 2 行が表示されます。

    Hello
World

手記

代わりに The target "HelloWorld" does not exist in the project 表示される場合は、コード エディターでプロジェクト ファイルを保存するのを忘れた可能性があります。 ファイルを保存して、やり直してください。

コード エディターとコマンド ウィンドウを交互に使用することで、プロジェクト ファイルを変更し、結果をすばやく確認できます。

ビルドのプロパティ

ビルド プロパティは、ビルドをガイドする名前と値のペアです。 プロジェクト ファイルの先頭にいくつかのビルド プロパティが既に定義されています。

<PropertyGroup>
...
  <ProductVersion>10.0.11107</ProductVersion>
  <SchemaVersion>2.0</SchemaVersion>
  <ProjectGuid>{30E3C9D5-FD86-4691-A331-80EA5BA7E571}</ProjectGuid>
  <OutputType>WinExe</OutputType>
...
</PropertyGroup>

すべてのプロパティは、PropertyGroup 要素の子要素です。 プロパティの名前は子要素の名前で、プロパティの値は子要素のテキスト要素です。 例えば

<TargetFrameworkVersion>net8.0</TargetFrameworkVersion>

TargetFrameworkVersionという名前のプロパティを定義し、文字列値 "net8.0" を指定します。

ビルド プロパティはいつでも再定義できます。 もし

<TargetFrameworkVersion>net6.0</TargetFrameworkVersion>

プロジェクトファイルで後から表示されるか、またはプロジェクトファイルに後からインポートされたファイルに表示されると、TargetFrameworkVersionは新しい値「net6.0」を取ります。

プロパティの値を調べる

プロパティの値を取得するには、次の構文を使用します。ここで、PropertyName はプロパティの名前です。

$(PropertyName)

この構文を使用して、プロジェクト ファイル内のプロパティの一部を調べます。

プロパティの値を調べるには

  1. コード エディターから、HelloWorld ターゲットを次のコードに置き換えます。

    <Target Name="HelloWorld">
  <Message Text="Configuration is $(Configuration)" />
  <Message Text="MSBuildToolsPath is $(MSBuildToolsPath)" />
</Target>

  2. プロジェクト ファイルを保存します。

  3. コマンド ウィンドウから、次の行を入力して実行します。

    msbuild buildapp.csproj -t:HelloWorld

  4. 出力を確認します。 次の 2 行が表示されます (出力が異なる場合があります)。

    Configuration is Debug
MSBuildToolsPath is C:\Program Files\Microsoft Visual Studio\2022\MSBuild\Current\Bin\amd64

    Configuration is Debug
MSBuildToolsPath is C:\Program Files (x86)\Microsoft Visual Studio\2019\MSBuild\16.0\Bin

条件付きプロパティ

Configuration などの多くのプロパティは条件付きで定義されます。つまり、Condition 属性がプロパティ要素に表示されます。 条件プロパティは、条件が "true" と評価された場合にのみ定義または再定義されます。未定義のプロパティには、空の文字列の既定値が指定されます。 例えば

<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>

これは、"Configuration プロパティがまだ定義されていない場合は、それを定義して値を 'Debug' に設定する" という意味になります。

ほぼすべての MSBuild 要素に Condition 属性を指定できます。 Condition 属性の使用の詳細については、「条件の」を参照してください。

予約済みプロパティ

MSBuild は、プロジェクト ファイルと MSBuild バイナリに関する情報を格納するために、いくつかのプロパティ名を予約します。 MSBuildToolsPath は予約済みプロパティの例です。 予約済みプロパティは、他のプロパティと同様に $ 表記で参照されます。 詳しくは、「方法: プロジェクト ファイルの名前または場所を参照する」と「MSBuild の予約済みおよび既知のプロパティ」をご覧ください。

環境変数

プロジェクト ファイル内の環境変数は、ビルド プロパティと同じ方法で参照できます。 たとえば、プロジェクト ファイルで PATH 環境変数を使用するには、$(Pathを使用します。 プロジェクトに環境変数と同じ名前のプロパティ定義が含まれている場合、プロジェクト内のプロパティは環境変数の値をオーバーライドします。 詳細については、「方法: ビルドで環境変数を使用する」を参照してください。

コマンド ラインからプロパティを設定する

プロパティは、コマンドラインスイッチ -property または -p を使用して定義できます。 コマンド ラインから受け取ったプロパティ値は、プロジェクト ファイルと環境変数で設定されたプロパティ値をオーバーライドします。

コマンド ラインからプロパティ値を設定するには:

  1. コマンド ウィンドウから、次の行を入力して実行します。

    msbuild buildapp.csproj -t:HelloWorld -p:Configuration=Release

  2. 出力を確認します。 次の行が表示されます。

    Configuration is Release.

MSBuild は Configuration プロパティを作成し、値 "Release" を指定します。

特殊文字

MSBuild プロジェクト ファイルでは、特定の文字が特別な意味を持ちます。 これらの文字の例には、セミコロン (;) とアスタリスク (*) があります。 これらの特殊文字をプロジェクト ファイル内のリテラルとして使用するには、構文 %<xx>を使用して指定する必要があります。ここで、<xx> は文字の ASCII 16 進数の値を表します。

メッセージ タスクを変更して、特殊文字を含む Configuration プロパティの値を表示し、読みやすくします。

メッセージ タスクで特殊文字を使用するには:

  1. コード エディターから、両方のメッセージ タスクを次の行に置き換えます。

    <Message Text="%24(Configuration) is %22$(Configuration)%22" />

  2. プロジェクト ファイルを保存します。

  3. コマンド ウィンドウから、次の行を入力して実行します。

    msbuild buildapp.csproj -t:HelloWorld

  4. 出力を確認します。 次の行が表示されます。

    $(Configuration) is "Debug"

詳細については、MSBuild の特殊文字 を参照してください。

ビルドの項目

項目は情報の一部であり、通常はファイル名であり、ビルド システムへの入力として使用されます。 たとえば、ソース ファイルを表す項目のコレクションを Compile という名前のタスクに渡して、アセンブリにコンパイルできます。

すべての項目は ItemGroup 要素の子要素です。 項目名は子要素の名前で、項目の値は子要素の Include 属性の値です。 同じ名前の項目の値は、その名前の項目の種類に収集されます。 例えば

<ItemGroup>
    <Compile Include="Program.cs" />
    <Compile Include="Properties\AssemblyInfo.cs" />
</ItemGroup>

は、2 つの項目を含む項目グループを定義します。 項目の種類 Compile には、Program.cs と Properties\AssemblyInfo.csの 2 つの値があります。

次のコードでは、セミコロンで区切られた 1 つの Include 属性で両方のファイルを宣言することで、同じ項目の種類を作成します。

<ItemGroup>
    <Compile Include="Program.cs;Properties\AssemblyInfo.cs" />
</ItemGroup>

詳細については、「項目」を参照してください。

手記

ファイル パスは、プロジェクト ファイルがインポートされたプロジェクト ファイルである場合でも、MSBuild プロジェクト ファイルを含むフォルダーに対する相対パスです。 Import および UsingTask 要素を使用する場合など、これにはいくつかの例外があります。

項目の種類の値を調べる

項目の種類の値を取得するには、次の構文を使用します。ここで、ItemType は項目の種類の名前です。

@(ItemType)

この構文を使用して、プロジェクト ファイル内の Compile 項目の種類を調べます。

項目の種類の値を調べるには:

  1. コード エディターから、HelloWorld ターゲット タスクを次のコードに置き換えます。

    <Target Name="HelloWorld">
  <Message Text="Compile item type contains @(Compile)" />
</Target>

  2. プロジェクト ファイルを保存します。

  3. コマンド ウィンドウから、次の行を入力して実行します。

    msbuild buildapp.csproj -t:HelloWorld

  4. 出力を確認します。 この長い行が表示されます。

    Compile item type contains Form1.cs;Form1.Designer.cs;Program.cs;Properties\AssemblyInfo.cs;Properties\Resources.Designer.cs;Properties\Settings.Designer.cs

項目の種類の値は、既定ではセミコロンで区切られます。

項目の種類の区切り記号を変更するには、次の構文を使用します。ItemType は項目の種類で、Separator は 1 つ以上の区切り文字の文字列です。

@(ItemType, Separator)

Message タスクを、キャリッジリターンとラインフィード (%0A%0D) を使用してコンパイル項目を 1 行に 1 つずつ表示するように変更します。

項目の種類の値を行ごとに 1 つ表示するには

  1. コード エディターで、メッセージ タスクを次の行に置き換えます。

    <Message Text="Compile item type contains @(Compile, '%0A%0D')" />

  2. プロジェクト ファイルを保存します。

  3. コマンド ウィンドウから、次の行を入力して実行します。

    msbuild buildapp.csproj -t:HelloWorld

  4. 出力を確認します。 次の行が表示されます。

    Compile item type contains Form1.cs
Form1.Designer.cs
Program.cs
Properties\AssemblyInfo.cs
Properties\Resources.Designer.cs
Properties\Settings.Designer.cs

Include、Exclude、ワイルドカード

ワイルドカード "*"、"**"、および "?" を Include 属性と共に使用して、項目の種類に項目を追加できます。 例えば

<Photos Include="images\*.jpeg" />

フォルダー内の イメージ ファイル拡張子 .jpeg を持つすべてのファイルをフォトアイテムの種類に追加します。

<Photos Include="images\**\*.jpeg" />

は、イメージ フォルダー内のファイル拡張子 .jpeg を持つすべてのファイルと、そのすべてのサブフォルダーをフォトアイテムの種類に追加します。 その他の例については、「方法:をビルドするファイルを選択する」を参照してください。

項目が宣言されると、項目の種類に追加されます。 例えば

<Photos Include="images\*.jpeg" />
<Photos Include="images\*.gif" />

この例では Photos という名前の項目の種類が作成され、これには image フォルダーにあるファイルのうちファイル拡張子が .jpeg または .gif であるものすべてが含まれます。 これらの行は、次の行と同じです。

<Photos Include="images\*.jpeg;images\*.gif" />

Exclude 属性を持つ項目の種類から項目を除外できます。 例えば

<Compile Include="*.cs" Exclude="*Designer*">

この例では、ファイル拡張子が .cs であるすべてのファイルが Compile という項目の種類に追加されますが、ファイルの名前に文字列 Designer が含まれているものは除外されます。 その他の例については、「方法: ビルドからファイルを除外する」を参照してください。

Exclude 属性は、両方を含む item 要素の Include 属性によって追加された項目にのみ影響します。 例えば

<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">

は、前の item 要素に追加されたファイル Form1.csを除外しません。

アイテムを含めたり、除外したりするには

  1. コード エディターで、メッセージ タスクを次の行に置き換えます。

    <Message Text="XFiles item type contains @(XFiles)" />

  2. Import 要素の直後に、次の項目グループを追加します。

    <ItemGroup>
   <XFiles Include="*.cs;properties/*.resx" Exclude="*Designer*" />
</ItemGroup>

  3. プロジェクト ファイルを保存します。

  4. コマンド ウィンドウから、次の行を入力して実行します。

    msbuild buildapp.csproj -t:HelloWorld

  5. 出力を確認します。 次の行が表示されます。

    XFiles item type contains Form1.cs;Program.cs;Properties/Resources.resx

項目のメタデータ

項目には、Include および Exclude 属性から収集された情報に加えてメタデータを含めることができます。 項目の値だけでなく項目に関する詳細情報を必要とするタスクでは、このメタデータを使用できます。

項目メタデータは、メタデータの名前を持つ要素を項目の子要素として作成することによって、プロジェクト ファイルで宣言されます。 項目には、0 個以上のメタデータ値を含めることができます。 たとえば、次の CSFile 項目には、値が "Fr" の Culture メタデータがあります。

<ItemGroup>
    <CSFile Include="main.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

項目の種類のメタデータ値を取得するには、次の構文を使用します。ここで、ItemType は項目の種類の名前、MetaDataName はメタデータの名前です。

%(ItemType.MetaDataName)

項目のメタデータを調べるには:

  1. コード エディターで、メッセージ タスクを次の行に置き換えます。

    <Message Text="Compile.DependentUpon: %(Compile.DependentUpon)" />

  2. プロジェクト ファイルを保存します。

  3. コマンド ウィンドウから、次の行を入力して実行します。

    msbuild buildapp.csproj -t:HelloWorld

  4. 出力を確認します。 次の行が表示されます。

    Compile.DependentUpon:
Compile.DependentUpon: Form1.cs
Compile.DependentUpon: Resources.resx
Compile.DependentUpon: Settings.settings

"Compile.DependentUpon" という語句が複数回表示されていることに注目してください。 ターゲット内でこの構文でメタデータを使用すると、"バッチ処理" が発生します。バッチ処理とは、ターゲット内のタスクが一意のメタデータ値ごとに 1 回実行されることを意味します。 バッチ処理は、一般的な "foreach ループ" プログラミングコンストラクトに相当する MSBuild スクリプトです。 詳細については、「バッチ処理 を参照してください。

既知のメタデータ

項目が項目リストに追加されるたびに、その項目には既知のメタデータが割り当てられます。 たとえば、%(Filename) は項目のファイル名を返します。 既知のメタデータの完全な一覧については、「既知の項目メタデータ を参照してください。

既知のメタデータを調べるには:

  1. コード エディターで、メッセージ タスクを次の行に置き換えます。

    <Message Text="Compile Filename: %(Compile.Filename)" />

  2. プロジェクト ファイルを保存します。

  3. コマンド ウィンドウから、次の行を入力して実行します。

    msbuild buildapp.csproj -t:HelloWorld

  4. 出力を確認します。 次の行が表示されます。

    Compile Filename: Form1
Compile Filename: Form1.Designer
Compile Filename: Program
Compile Filename: AssemblyInfo
Compile Filename: Resources.Designer
Compile Filename: Settings.Designer

前の 2 つの例を比較すると、Compile 項目の種類のすべての項目に DependentUpon メタデータがあるわけではありませんが、すべての項目に既知のファイル名メタデータがあることがわかります。

メタデータ変換

項目リストは、新しい項目リストに変換できます。 項目リストを変換するには、次の構文を使用します。ここで、<ItemType> は項目の種類の名前、<MetadataName> はメタデータの名前です。

@(ItemType -> '%(MetadataName)')

たとえば、ソース ファイルの項目リストは、@(SourceFiles -> '%(Filename).obj')などの式を使用して、オブジェクト ファイルのコレクションに変換できます。 詳細については、変換に関する記事を参照してください。

メタデータを使用して項目を変換するには:

  1. コード エディターで、メッセージ タスクを次の行に置き換えます。

    <Message Text="Backup files: @(Compile->'%(filename).bak')" />

  2. プロジェクト ファイルを保存します。

  3. コマンド ウィンドウから、次の行を入力して実行します。

    msbuild buildapp.csproj -t:HelloWorld

  4. 出力を確認します。 次の行が表示されます。

    Backup files: Form1.bak;Form1.Designer.bak;Program.bak;AssemblyInfo.bak;Resources.Designer.bak;Settings.Designer.bak

この構文で表されるメタデータはバッチ処理を引き起こさないことに注意してください。

次の手順

簡単なプロジェクト ファイルを一度に 1 ステップずつ作成する方法については、Windows 最初から MSBuild プロジェクト ファイルを作成試してください。

主に .NET SDK を使用している場合は、「.NET SDK プロジェクトの MSBuild リファレンス に関するページを参照してください。

関連コンテンツ