MSBuild のバージョンを検索して使用する

2025-06-12

Visual Studio または MSBuild.exe内で実行されるアプリケーションからのプログラムビルドがビルドと一致するようにするには、特定のバージョンの Visual Studio でインストールされたのと同じバージョンの MSBuild アセンブリを読み込み、そのバージョンの Visual Studio 内で使用できるのと同じ SDK を使用することが必要になる場合があります。または、MSBuild、.NET、Visual Studio のさまざまなバージョンがインストールされているマシンで実行されるビルドアプリケーションを作成する場合は、一貫性のあるバージョンの MSBuild を検索して使用することもできます。 Microsoft.Build.Locator API により、このプロセスが効率化されます。

Microsoft.Build.Locator を使用する

Microsoft.Build.Locator パッケージは、クライアントマシン、仮想マシン、またはコンテナー内でアプリケーションが実行される状況 (Visual Studio がインストールされている環境、Visual Studio ビルドツールのみがインストールされている環境、またはビルドが dotnet build コマンドラインで要求された場合など) に関連します。いずれの場合も、アプリケーションで目的のバージョンの MSBuild を見つける必要があります。 MSBuild のそのバージョンは、Visual Studio、MSBuild.exe、または dotnet buildに一致するバージョン、またはアプリケーションが使用される可能性がある環境でのさまざまなマシン構成に関係なく、特定の一貫性のあるバージョンである可能性があります。

警告

Microsoft.Build.Locator パッケージには、.NET Framework および .NET Core 用のアセンブリが含まれています (.NET 5 以降にも適用できます)。 .NET Framework アプリケーションでは、.NET Framework バージョンの Microsoft.Build.Locator が使用され、.NET Core アプリケーションでは .NET Core バージョンが使用されます。ただし、.NET Core バージョンでは、.NET Core を使用してビルドされた MSBuild のインスタンスのみを検索できます。MSBuild は、Visual Studio のインストールや Visual Studio ビルドツールのインストールではなく、.NET SDK のインストールで dotnet.exe によって使用されます。 .NET Framework バージョンの Microsoft.Build.Locator では、.NET SDK のインストールではなく、Visual Studio のインストール、Visual Studio ビルドツールのインストールのみが表示されます。そのため、両方を対象とする 2 つの異なるターゲットフレームワーク構成でツールを構築することが必要になる場合があります。

アプリケーションで Microsoft.Build.Locator.dll を再配布する場合は、他の MSBuild アセンブリを配布する必要はありません。

ロケーター API を使用するには、プロジェクトにいくつかの変更が必要です。以下で説明します。プロジェクトの更新に必要な変更の例については、MSBuildLocator リポジトリのサンプルプロジェクトに対して行われたコミットのを参照してください。

MSBuild 参照の変更

MSBuild が中央の場所から読み込まれるようにするには、そのアセンブリをアプリケーションに配布しないでください。

中央の場所からの MSBuild の読み込みを回避するようにプロジェクトを変更するメカニズムは、MSBuild を参照する方法によって異なります。

NuGet パッケージを使用する (推奨)

これらの手順では、PackageReference スタイルの NuGet 参照を使用を前提としています。

NuGet パッケージから MSBuild アセンブリを参照するようにプロジェクトファイルを変更します。アセンブリがビルド時にのみ必要であり、出力ディレクトリにコピーしないことを NuGet に伝える ExcludeAssets=runtime を指定します。

MSBuild パッケージのメジャーバージョンとマイナーバージョンは、サポートする Visual Studio の最小バージョン以下である必要があります。たとえば、Visual Studio 2017 以降のバージョンをサポートする場合は、パッケージバージョン 15.1.548参照します。

たとえば、次の XML を使用できます。

<ItemGroup>
  <PackageReference Include="Microsoft.Build" Version="15.1.548" ExcludeAssets="runtime" />
  <PackageReference Include="Microsoft.Build.Utilities.Core" Version="15.1.548" ExcludeAssets="runtime" />
</ItemGroup>

拡張機能アセンブリを使用する

NuGet パッケージを使用できない場合は、Visual Studio で配布されている MSBuild アセンブリを参照できます。 MSBuild を直接参照する場合は、Copy Local を Falseに設定して、出力ディレクトリにコピーされていないことを確認します。プロジェクトファイルでは、この設定は次のコードのようになります。

    <Reference Include="Microsoft.Build, Version=15.1.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL">
      <Private>False</Private>
    </Reference>

手記

15 より前のバージョンの MSBuild から更新する場合、MSBuild では特定のアセンブリ (Microsoft.Build アセンブリ) のバインドリダイレクトが必要ですが、Microsoft.Build.Locator パッケージを参照する場合は、アプリケーションで必要なバインドリダイレクトがバージョン 15.1.0.0 に自動的に使用されるようにします。このバージョンへのバインドリダイレクトでは、MSBuild 15.x、16.x、および 17.x がサポートされます。

出力がクリーンであることを確認する

プロジェクトをビルドし、出力ディレクトリを調べて、次の手順で追加した Microsoft.Build.Locator.dll以外の Microsoft.Build.*.dll アセンブリが含まれていないことを確認します。

Microsoft.Build.Locator のパッケージ参照を追加する

Microsoft.Build.Locatorの NuGet パッケージ参照を追加します。

    <PackageReference Include="Microsoft.Build.Locator">
      <Version>1.1.2</Version>
    </PackageReference>

Microsoft.Build.Locator パッケージの ExcludeAssets=runtime を指定しないでください。

MSBuild を呼び出す前にインスタンスを登録する

一般的に使用するビルドアプリケーションを作成する場合、アプリケーションを実行しているコンピューターにインストールされている Visual Studio、.NET、MSBuild のバージョンがわからない場合があります。 MSBuildLocator の目的は、多様なインストール環境のマシンで使用する MSBuild の適切なインストールを見つけることです。 MSBuildLocator を使用すると、使用する MSBuild を決定するロジックを指定できますが、アプリケーションの開発者は、必要な MSBuild のバージョンを決定するか、受け入れられるか、またはユーザーがバージョンを指定する方法を提供し、その選択を MSBuildLocator API への適切な呼び出しに変換するロジックを含める必要があります。

Locator API への呼び出しを追加する最も簡単な方法は、アプリケーションのスタートアップコードで MSBuildLocator.RegisterInstance への呼び出しを追加することです。 1 つの例として、次に示すように最新バージョンを選択しますが、アプリケーションに独自の要件がある場合があります。

MSBuildLocator を呼び出すメソッド内の (Microsoft.Build 名前空間から) MSBuild 型を参照することはできません。たとえば、次のようなコードを使用することはできません。

void ThisWillFail()
{
    // Register the most recent version of MSBuild
    RegisterInstance(MSBuildLocator.QueryVisualStudioInstances().OrderByDescending(
       instance => instance.Version).First());
    Project p = new Project(SomePath); // Could be any MSBuild type
    // Code that uses the MSBuild type
}

代わりに、次のようなコードを記述します。

void MethodThatDoesNotDirectlyCallMSBuild()
{
    var instance = ... // select which of the installed instances to use
    
    // Register a specific instance of MSBuild
    MSBuildLocator.RegisterInstance(instance);
    MethodThatCallsMSBuild();
}

void MethodThatCallsMSBuild()
{
    Project p = new Project(SomePath);
    // Code that uses the MSBuild type
}

MSBuild インスタンスを指定するには、必要なカスタムロジックを使用して、MSBuildLocator.RegisterInstance に渡す MSBuildLocator.QueryVisualStudioInstances の結果を選択できます。

MSBuild API リファレンスを参照して、MSBuild API について説明します。

次の方法で共有