Azure DevOps の Microsoft-hosted agent で .NET SDK 8.0.300 を使うと、「MSBuild のバージョン不足」でビルドが失敗することがあります。原因はパイプラインが Visual Studio 2019 世代（MSBuild 16.x）を参照しているため。ホステッドエージェントを維持したまま、最新 SDK を使い続けるための切り分けと解決手順をまとめます。
起きている現象：.NET SDK 8.0.300 なのに MSBuild 16.11.2 で落ちる
Azure DevOps の Microsoft-hosted agents（Azure Pipelines のホステッドエージェント）でビルドすると、次のようなメッセージで突然失敗するケースがあります。
Error : Version 8.0.300 of the .NET SDK requires at least version 17.8.3 of MSBuild.
The current available version of MSBuild is 16.11.2.50704.
Change the .NET SDK specified in global.json to an older version ...ポイントは、プロジェクト側は .NET SDK 8.0.300 前提なのに、パイプライン側が古い MSBuild（16.11.x）を実行していることです。ローカル PC では通るのに Azure DevOps だけ落ちる場合、ほぼこのパターンです。
原因：Microsoft-hosted agent の「Visual Studio 世代」と「呼び出しているビルド手段」がズレている
.NET のビルドは一見シンプルですが、Azure DevOps のパイプラインでは次の 2 系統が混在しがちです。
- dotnet build / dotnet test：.NET SDK に同梱された MSBuild（MSBuild.dll）でビルドする
- msbuild.exe / VSBuild タスク：Visual Studio に同梱された MSBuild（msbuild.exe）でビルドする
このうち後者（Visual Studio 側の msbuild.exe）を呼ぶ構成のまま SDK だけを 8.0.300 に上げると、「SDK が要求する MSBuild の最低版」を満たせずに失敗します。これは .NET 8 の SDK から「動作保証する Visual Studio / MSBuild の最低版」が明確に引き上げられたためです。
| .NET SDK（例） | 最低限必要な Visual Studio / MSBuild | よくある症状 |
|---|---|---|
| 8.0.100 | 17.7 以上 | 古い VS / MSBuild だと net8.0 をターゲットした瞬間に失敗 |
| 8.0.200 / 8.0.300 | 17.8 以上（実運用では 17.8.3 以上を目安） | MSBuild 16.x（VS2019）ではロード自体が拒否される |
| 8.0.400 | 17.9 以上 | エージェント更新に追従できないと再発しやすい |
上の「最低版」は Microsoft の互換性ドキュメントに整理されています。とくに 8.0.300 は 17.8 系（VS2022 世代）以上が前提です。
なぜホステッドエージェントなのに MSBuild 16.11（VS2019 相当）が出てくるのか
Microsoft-hosted agent は「OS イメージ（例：windows-2019 / windows-2022 / windows-2025）」に、各種ツール（Visual Studio、.NET SDK など）がインストールされた VM を毎回払い出します。指定したイメージによって入っている Visual Studio 世代が異なるため、イメージが VS2019 世代だと MSBuild 16.x が既定になります。
| vmImage（例） | 入っている Visual Studio の世代 | MSBuild の世代 | 向いている用途 |
|---|---|---|---|
| windows-2019 | VS2019 世代 | MSBuild 16.x | レガシー向け（※廃止スケジュールあり） |
| windows-2022 | VS2022 世代 | MSBuild 17.x | .NET 8 以降や最新 SDK 前提のビルド |
| windows-2025 | （現状）VS2022 世代 | MSBuild 17.x | より新しい OS での互換性確認や今後の移行 |
windows-2019 は deprecation が進んでおり、スケジュール上は 2025 年 12 月 31 日にホステッドイメージとして削除されています。今から対策するなら、実質的に windows-2022 以上へ寄せるのが安全です。
最初にやるべき切り分け：どのタスクが「古い MSBuild」を呼んでいるか
同じパイプラインでも、タスクによって参照するビルドエンジンが変わります。対策の前に、ログへ「現状の実行環境」を出しておくと再発防止になります。
確認用の診断ステップ（そのまま貼れる）
Windows エージェントを前提に、PowerShell で次を出力します。
- pwsh: |
Write-Host "=== dotnet --info ==="
dotnet --info
Write-Host ""
Write-Host "=== where dotnet / msbuild ==="
where dotnet
where msbuild
Write-Host ""
Write-Host "=== msbuild -version (if exists) ==="
if (Get-Command msbuild -ErrorAction SilentlyContinue) { msbuild -version }
displayName: "Diagnostics: dotnet & MSBuild"dotnet --info の出力には MSBuild のバージョンも含まれます。ここが 16.x になっているなら、実行系が古い側に寄っています。
よく使われるタスクと参照先の違い
| タスク/コマンド | 主に使う MSBuild | この問題が起きやすい条件 | 推奨の考え方 |
|---|---|---|---|
| VSBuild@1（Visual Studio build） | Visual Studio の msbuild.exe | vsVersion が 16.0 / エージェントが VS2019 世代 | VS2022 世代に上げるか、vsVersion を 17.0 にする |
| MSBuild@1 | Visual Studio の msbuild.exe（または指定パス） | msbuildVersion が 16.0 などに固定 | MSBuild 17.x を明示する／dotnet build へ移行 |
| NuGetCommand@2（restore） | 内部で MSBuild を呼ぶケースがある | SDK-style プロジェクト評価で MSBuild が必要 | 可能なら dotnet restore に寄せる |
| DotNetCoreCLI@2（dotnet build/test/publish） | .NET SDK 同梱の MSBuild | 基本的に起きにくい | 新しめの .NET はこちらへ寄せると安定 |
注意：msbuildVersion を 17.0 にしても「見つからなければ 16.0 にフォールバック」する
MSBuild@1 タスクで msbuildVersion: "17.0" を指定しても、エージェント側に MSBuild 17 が入っていなければ、ログに 「17.0 が見つからないので 16.0 にフォールバックする」という警告が出て結局失敗します。つまり、タスク指定だけではなく、イメージ（Visual Studio 世代）を上げる必要があります。
結論：ホステッドエージェントを維持して最新 SDK を使うなら「windows-2022（VS2022 世代）」へ切り替える
今回の要件は「ホステッドエージェントは維持」「.NET SDK 8.0.300 を使い続けたい」です。結論としては、エージェントイメージを VS2022 世代（MSBuild 17 系）に切り替えるのが最短で確実です。
YAML の pool を windows-2022（または windows-latest）へ変更
まずはビルドジョブの pool を見直します。安定運用したい場合は windows-2022 を明示するのがおすすめです。windows-latest は将来指すイメージが変わる可能性があるため、再現性を重視するなら固定が安心です。
pool:
vmImage: "windows-2022"参考までに、Azure Pipelines では 2025 年 9 月 2 日以降、windows-latest が windows-2025 を指すように変更されています。こうした更新があるため、ツールチェーンを安定させたい場合は「明示したラベルに固定」が有効です。
Classic（GUI）パイプラインの場合
YAML ではなく Classic パイプライン（GUI）でも同じです。Agent job の「Agent Specification（または Hosted agent）」で windows-2022 を選びます。windows-2019 を選んでいる場合、.NET 8 の SDK を上げたタイミングでこの問題に直撃しやすくなります。
VSBuild タスク / msbuild.exe を使い続ける場合の具体策
ソリューションに .NET Framework プロジェクトやインストーラ、特殊なビルドが混ざっていると、どうしても VSBuild@1 や msbuild.exe が必要なことがあります。その場合は「イメージの世代」＋「タスクの Visual Studio 指定」を揃えるのがコツです。
VSBuild@1 で Visual Studio 2022 を明示する
VSBuild@1 のドキュメント上、Visual Studio のバージョンは 15.0 / 16.0 / 17.0 のように指定できます。VS2022 を使いたいなら 17.0 を指定し、前提として pool を windows-2022 にします。
- task: VSBuild@1
displayName: "Build (VS2022 / MSBuild 17)"
inputs:
solution: "**/*.sln"
vsVersion: "17.0"
msbuildArgs: "/restore"
platform: "Any CPU"
configuration: "Release"MSBuild@1 で「msbuild の場所」を固定する（必要なときだけ）
タスクのバージョン指定が効かない、あるいは複数の VS が入っていて意図しない方が選ばれる場合は、msbuild.exe のパスを明示するのが確実です。ただし Microsoft-hosted agent ではインストール状態が更新されるため、パス固定は最後の手段として扱うのが無難です。
- task: MSBuild@1
displayName: "Build (MSBuild path fixed)"
inputs:
solution: "**/*.sln"
msbuildLocationMethod: "location"
msbuildLocation: "C:\\Program Files\\Microsoft Visual Studio\\2022\\Enterprise\\MSBuild\\Current\\Bin\\MSBuild.exe"
msbuildArguments: "/restore"
platform: "Any CPU"
configuration: "Release"エディション（Enterprise / Professional など）でパスが変わることがあるため、固定するなら vswhere で検出して変数に入れる方法もあります。
vswhere で MSBuild の実体パスを検出する例
- pwsh: |
$vswhere = "${env:ProgramFiles(x86)}\\Microsoft Visual Studio\\Installer\\vswhere.exe"
$msbuild = & $vswhere -latest -requires Microsoft.Component.MSBuild -find MSBuild\\**\\Bin\\MSBuild.exe | Select-Object -First 1
Write-Host "MSBuildPath=$msbuild"
Write-Host "##vso[task.setvariable variable=MSBuildPath]$msbuild"
displayName: "Detect MSBuild by vswhere"
* task: MSBuild@1
displayName: "Build with detected MSBuild"
inputs:
solution: "**/*.sln"
msbuildLocationMethod: "location"
msbuildLocation: "$(MSBuildPath)"
msbuildArguments: "/restore"
platform: "Any CPU"
configuration: "Release"可能なら dotnet build に寄せる：SDK 同梱 MSBuild で「SDK とビルドエンジン」を一体化する
この手のトラブルは、突き詰めると「SDK は新しいのに msbuild.exe が古い」という二重管理で起きます。そこで、構成が許すなら DotNetCoreCLI@2（dotnet build）中心に寄せると安定します。
UseDotNet で 8.0.300 を明示してから dotnet build
Microsoft-hosted agent には複数の .NET SDK が入っていますが、プロジェクトが global.json で 8.0.300 を固定しているなら、パイプライン側でも同じバージョンを用意しておくと事故が減ります。
- task: UseDotNet@2
displayName: "Install .NET SDK 8.0.300"
inputs:
packageType: "sdk"
version: "8.0.300"
* task: DotNetCoreCLI@2
displayName: "dotnet restore"
inputs:
command: "restore"
projects: "**/*.sln"
* task: DotNetCoreCLI@2
displayName: "dotnet build"
inputs:
command: "build"
projects: "**/*.sln"
arguments: "-c Release --no-restore"
* task: DotNetCoreCLI@2
displayName: "dotnet test"
inputs:
command: "test"
projects: "**/*Tests/*.csproj"
arguments: "-c Release --no-build --logger trx"この構成なら、ビルドに使う MSBuild は基本的に .NET SDK 側に揃うため、VS の世代差で壊れにくくなります。
「dotnet build だけで済まない」ケースの現実解
逆に、次のような場合は VSBuild / msbuild.exe を残す必要があります。
- SSDT（SQL Database Project）など Visual Studio コンポーネント依存のプロジェクトがある
- 古い拡張やカスタムターゲットで devenv.com が必要
- ネイティブ（C++）や C++/CLI を含み、VS のツールセットに強く依存する
この場合でも「windows-2022（VS2022）に上げる」だけで解決することが多いです。もしツールが不足しているなら、Microsoft-hosted agent の「含まれるソフトウェア」一覧を確認し、必要なら self-hosted / Managed DevOps Pools へ検討を進めます。
補足ワークアラウンド：global.json で SDK を下げる前に知っておきたいこと
エラーには「global.json で古い SDK に落とせ」と出ます。確かに回避にはなりますが、運用上は次のデメリットがあります。
- 最新 SDK の修正（セキュリティ/不具合修正）を取り込めない
- ローカル環境と CI 環境の差分が増える（誰かの PC だけ通る等）
- 将来 .NET 8 の feature band を上げるたびに同じ問題が再発する
どうしても一時しのぎが必要なら、いつ戻すか（VS を上げる期限）を決めたうえで実施するのが現実的です。最低限、global.json を置くなら「意図」と「戻し条件」を README に残しておくと、数か月後の自分を助けます。
{
"sdk": {
"version": "8.0.204",
"rollForward": "latestPatch"
}
}rollForward を指定しておくと、同じ feature band（8.0.2xx）の範囲でセキュリティパッチを取り込みやすくなります。逆に「完全固定」が必要なら rollForward を省略し、UseDotNet でも同一バージョンを入れるようにします。
よくある落とし穴：対策したのにまだ落ちるときのチェックリスト
windows-2022 へ切り替えてもハマりやすい点をまとめます。
pool は変えたのに、タスクが VS2019 を探しに行く
- VSBuild@1 の
vsVersionが 16.0 固定になっていないか - MSBuild@1 の
msbuildVersionが 16.0 固定になっていないか - 古いテンプレートを流用して「msbuild.exe を直叩き」していないか
この 3 つは移行時に最も見落とされます。「どの exe を実行しているか」をログに残すだけで原因特定が早くなります。
NuGet restore が先に失敗している
SDK-style の csproj を評価するために、NuGet 側が MSBuild を必要とすることがあります。もし restore の段階で同種のエラーが出るなら、NuGetCommand@2 を dotnet restore に置き換えるだけで解決することがあります（ただし packages.config のプロジェクトがある場合は注意）。
windows-latest にしていたら、ある日ツールが更新されて挙動が変わった
Microsoft-hosted agent はメンテナンスとアップグレードが自動で、同じラベルでも中身が更新されます。再現性を重視するなら、vmImage を固定し、SDK は UseDotNet と global.json で揃えるのが安全です。
まとめ：MSBuild 16.x を捨てて VS2022 世代へ上げるのが最短ルート
.NET SDK 8.0.300 の導入で「MSBuild のバージョン不足」が出た場合、ほとんどは VS2019（MSBuild 16.x）を呼んでいることが原因です。ホステッドエージェントを維持して最新 SDK を使い続けたいなら、次の優先順で対応するとスムーズです。
- pool を windows-2022（または windows-2025 / windows-latest）へ切り替える
- VSBuild / MSBuild タスクを使うなら vsVersion: 17.0 を明示する
- 可能なら dotnet build 中心へ寄せ、SDK とビルドエンジンを一体化する
この順で整えると、.NET 8 の feature band を上げても「CI だけ落ちる」を最小化できます。
コメント