GitHub documentation updateで変わるAspire CLIのMSBuild Server設定｜影響範囲と確認手順

2026年5月21日に公開された公式リリース情報では、GitHub上の microsoft/aspire リポジトリにおいて、Aspire CLI が dotnet run / dotnet build 実行時に DOTNET_CLI_USE_MSBUILD_SERVER を強制設定する動作が削除されました。結論から言うと、Linux環境で .NET SDK 10.0.300 を使い、aspire run が AppHost ビルド時に System.TimeoutException で失敗していたチームは、Aspire CLIを修正済みバージョンへ更新し、CIや開発環境でMSBuild Server関連の環境変数を固定していないか確認すべきです。(GitHub)

今回の GitHub documentation update は、GitHubそのもののUIやGitHub Actionsの仕様変更ではありません。GitHub上で公開された Aspire CLI の修正PRとリリース情報を読み解き、管理者・開発者がどの環境を確認し、どの順番で更新・検証すべきかを整理します。

GitHub documentation updateの要点

今回の変更は、[release/13.3] Stop forcing MSBuild server for Aspire CLI builds というPRとして release/13.3 ブランチへ取り込まれたものです。PR #17314 は、mainブランチ向けのPR #17313を release/13.3 にバックポートした修正で、Aspire 13.3.5 のリリースノートにも同じ内容が反映されています。(GitHub)

項目	内容
対象	Aspire CLI の dotnet run / dotnet build 呼び出し
主な変更	DOTNET_CLI_USE_MSBUILD_SERVER をAspire CLI側で強制注入しない
影響が大きい環境	Linux + .NET SDK 10.0.300 + Aspire CLI 13.2/13.3系
発生していた問題	aspire run 実行時、AppHostビルドで named-pipe timeout が発生する可能性
管理者の優先対応	Aspire CLI更新、CIの環境変数確認、Linuxランナーでの再検証

重要なのは、MSBuild Server機能が削除されたわけではない点です。変更されたのは、Aspire CLIが子プロセスとして dotnet コマンドを呼び出す際に、MSBuild Serverを使うよう一律に押し付けていた挙動です。修正後は、.NET SDKや実行環境側の設定に従ってMSBuild Serverの利用が決まります。

何が変わったのか

変更前のAspire CLIでは、AppHostビルドや aspire run に伴う dotnet run / dotnet build 実行時に、DOTNET_CLI_USE_MSBUILD_SERVER がCLI側から設定されていました。PR #17314 では、この環境変数の注入処理が DotNetCliRunner から削除され、テストも「環境変数が注入されない」ことを確認する内容へ変更されています。(GitHub)

比較項目	変更前	変更後
dotnet build 実行時	Aspire CLIが DOTNET_CLI_USE_MSBUILD_SERVER を設定	Aspire CLIは設定せず、SDK側の判断に任せる
dotnet run 実行時	noBuild: false の場合に環境変数を注入	環境変数を注入しない
設定の主導権	Aspire CLI側	.NET SDK、システム環境変数、ユーザー設定側
期待される効果	反復ビルドの高速化を狙う	Linux + SDK 10.0.300 のタイムアウト回避を優先

この変更は、ビルド高速化の仕組みを否定するものではありません。MSBuild Serverは、ビルド時のコンテキストを長時間動作するプロセスにキャッシュし、繰り返しビルドで起動コストを下げるための機能です。Microsoft Learnでは、DOTNET_CLI_USE_MSBUILD_SERVER を true または 1 に設定すると有効化でき、0 または false で無効化できると説明されています。(Microsoft Learn)

つまり今回の修正は、「Aspire CLIが最適化設定を決め打ちする」のではなく、「実行中の.NET SDKが適切なMSBuild Server動作を選べるようにする」変更です。

なぜこの変更が必要だったのか

背景には、Linux環境で .NET SDK 10.0.300 を使った場合に、aspire run がAppHostビルド中に失敗する不具合があります。関連Issue #16849 では、Ubuntu 24.04.3 LTSに .NET SDK 10.0.300 と Aspire CLI 13.2を入れ、aspire run を実行すると System.TimeoutException: The operation has timed out が発生する手順が報告されています。さらに、SDK 10.0.300 + Aspire CLI 13.3でも再現し、直接 dotnet run や dotnet build を実行した場合は再現しないと記録されています。(GitHub)

ログ上は NamedPipeClientStream や Microsoft.Build.Experimental.MSBuildClient の呼び出しでタイムアウトしており、Aspire CLIがAppHostビルドを進められない状態になります。開発者から見ると、アプリ本体のコードを変更していないのに、SDK更新後に突然 aspire run だけが失敗するように見える点が厄介です。

このため、PR #17314 ではリスクを「Low」としつつ、変更範囲をCLIの dotnet run / dotnet build プロセス環境設定に限定しています。公式PRでは、.NET SDK 10.0.204では動作していたが、10.0.300とAspire CLI 13.2/13.3で回帰した問題として整理されています。(GitHub)

影響を受ける可能性が高い環境

すべてのGitHub利用者や、すべての.NET開発者が対応する必要はありません。優先して確認すべきなのは、Aspire CLIを使ってAppHostを起動・ビルドしている環境です。

環境	影響度	確認すべきこと
Linux上で aspire run を使っている	高	.NET SDK 10.0.300とAspire CLIの組み合わせを確認
GitHub ActionsやセルフホストランナーでAspireを実行している	高	ランナーのOS、SDK、Aspire CLI、環境変数を確認
WindowsまたはmacOS中心のローカル開発	中	同様のエラーが出ていなければ緊急度は低いが、CLI更新は検討
dotnet build のみでAspire CLIを使っていない	低	今回の修正による直接影響は小さい
DOTNET_CLI_USE_MSBUILD_SERVER=true をCIで明示設定している	中〜高	修正後も環境変数が残ると同じ系統の問題が続く可能性

特に注意したいのは、「PRを取り込んだからMSBuild Serverが必ず無効になる」と誤解することです。今回の修正は、Aspire CLIが強制設定しなくなるだけです。CI、Dockerfile、devcontainer、シェルプロファイル、GitHub Actionsの環境変数で DOTNET_CLI_USE_MSBUILD_SERVER=true を指定している場合、その設定は引き続き.NET SDKに渡ります。

管理者・開発者がまず確認すべき設定

最初に、問題が発生している環境で次の3点を確認します。

aspire --version
dotnet --info
printenv DOTNET_CLI_USE_MSBUILD_SERVER

PowerShell環境では、次のように確認できます。

aspire --version
dotnet --info
Get-ChildItem Env:DOTNET_CLI_USE_MSBUILD_SERVER

aspire --version で古い13.2系または13.3系を使っている場合、今回の修正を含むバージョンへ更新することが第一候補です。Aspire 13.3.5のリリースノートでは、Linux + .NET SDK 10.0.300でのAspire CLI named-pipe timeoutが修正対象として明記され、PR #17313およびバックポートPR #17314が関連付けられています。(GitHub)

次に、リポジトリ内で環境変数が固定されていないか確認します。

grep -R "DOTNET_CLI_USE_MSBUILD_SERVER" .github/ .devcontainer/ Dockerfile* docker-compose*.yml eng/ build/ 2>/dev/null

PowerShellの場合は、リポジトリルートで次のように検索できます。

Get-ChildItem -Recurse -File |
  Select-String "DOTNET_CLI_USE_MSBUILD_SERVER"

見つかった場合は、なぜその設定を入れたのかを確認してください。過去にビルド高速化目的で true を固定していたなら、今回のAspire CLI修正後もLinux CIで同種の問題を誘発する可能性があります。逆に、一時回避として false や 0 を設定している場合は、修正済みCLIへ更新したあとに不要にならないか検証します。

Aspire CLIを更新する手順

Aspire公式の13.3アップグレード案内では、CLIの更新に次のコマンドが示されています。(Aspire)

aspire update --self

プロジェクト側のAspireパッケージも更新する場合は、リポジトリルートで次のコマンドを実行します。

aspire update

ただし、今回のnamed-pipe timeout対策として最優先なのは、Aspire CLI本体の修正を取り込むことです。プロジェクトパッケージの更新は、13.3系への移行や他の修正も含めて検証するタイミングで実施します。

更新後は、既存のビルドサーバープロセスやキャッシュの影響を切り分けるため、必要に応じて次のコマンドも実行します。MSBuild Serverの停止には dotnet build-server shutdown を使えるとMicrosoft Learnに記載されています。(Microsoft Learn)

dotnet build-server shutdown
aspire run

CIでは、ローカルだけでなくランナー側のバージョンも必ず確認してください。開発者PCでは修正済みでも、GitHub Actionsのセルフホストランナー、Dockerイメージ、devcontainer、ビルドキャッシュに古いAspire CLIが残っていると、同じ障害が再発します。

GitHub ActionsやCIでの確認ポイント

GitHub ActionsなどのCIでAspireを使っている場合は、ワークフローに一時的な診断ステップを追加すると切り分けが速くなります。

- name: Check Aspire and .NET versions
  run: |
    aspire --version
    dotnet --info
    printenv DOTNET_CLI_USE_MSBUILD_SERVER || true

確認すべきポイントは、単に「ビルドが通るか」ではありません。次の観点で見ると、原因を見落としにくくなります。

確認項目	見落としやすい理由	対応
ランナーOS	ローカルがWindows、CIがLinuxだと再現差が出る	Linuxジョブで aspire run を実行して確認
.NET SDKバージョン	SDK更新で突然再現することがある	dotnet --info をログに残す
Aspire CLIの入手方法	インストールスクリプト、dotnet tool、キャッシュで差が出る	ジョブ内で明示的に更新またはバージョン表示
環境変数	Organization VariablesやDockerfileで固定されることがある	DOTNET_CLI_USE_MSBUILD_SERVER の設定元を調査
直接 dotnet build だけの検証	今回のIssueでは直接実行では再現しないと報告されている	aspire run でも検証する

とくにセルフホストランナーでは、過去に手動インストールしたCLIやグローバル環境変数が残りやすいです。障害がCIだけで再現する場合は、ランナーを再作成する前に、インストール済みツールと環境変数の棚卸しを行ってください。

13.2系から移行する場合の注意点

Issue #16849では、Aspire CLI 13.2と13.3の両方で再現する旨が報告されています。したがって、13.2系を使い続けているチームも「13.3の問題だから関係ない」と判断しない方が安全です。(GitHub)

一方で、13.2から13.3へ移行する場合は、今回の修正以外の変更も同時に入ります。Aspire 13.3の公式案内では、--log-level から --pipeline-log-level への名称変更、dashboard MCP serverの削除、Azure NetworkやAKS関連APIの変更など、複数のbreaking changesが案内されています。(Aspire)

移行時は、次の順序で進めると安全です。

手順	作業	判断基準
1	現在のCLI、SDK、OSを記録	障害再現条件と照合する
2	ステージングまたは検証用ブランチでCLI更新	いきなり本番CIへ反映しない
3	DOTNET_CLI_USE_MSBUILD_SERVER の固定設定を確認	true 固定が残っていれば削除または再評価
4	aspire run でAppHostビルドを確認	dotnet build だけで済ませない
5	13.3のbreaking changesを確認	CI引数やAppHostコードの変更漏れを防ぐ
6	GitHub Actionsやセルフホストランナーへ展開	キャッシュや古いツールを削除する

13.3系へ移行済みのチームは、13.3.5のパッチ更新として扱いやすい一方、13.2系から上げるチームは「不具合修正」と「マイナー移行」を分けて検証するのが現実的です。

一時回避策を使う場合の考え方

すぐにCLI更新できない環境では、DOTNET_CLI_USE_MSBUILD_SERVER を 0 または false に設定してMSBuild Serverを無効化する方法を検証する価値があります。Microsoft Learnでも、MSBuild Serverを無効にする手段として同環境変数の 0 / false 指定や、dotnet build-server shutdown が説明されています。(Microsoft Learn)

Linuxシェルでは、次のように一時的に実行できます。

export DOTNET_CLI_USE_MSBUILD_SERVER=false
dotnet build-server shutdown
aspire run

ただし、これは恒久対応ではありません。今回の公式修正は、Aspire CLIが環境変数を強制注入しないようにすることです。根本的には、修正済みAspire CLIへ更新し、そのうえでMSBuild Serverを有効にするかどうかをチームのビルド方針として決めるべきです。

失敗しやすいポイント

今回の変更では、次のような誤解が起きやすいです。

誤解	実際の注意点
GitHub自体の障害や仕様変更だと思う	GitHub上のAspireリポジトリで公開されたCLI修正であり、GitHubプラットフォームの変更ではない
dotnet build が通るので問題ないと判断する	報告Issueでは、直接 dotnet build / dotnet run では再現せず、aspire run で再現するとされている
CLI更新だけでCIも直ると思う	CIのDockerイメージ、セルフホストランナー、ツールキャッシュに古いCLIが残ることがある
修正後はMSBuild Serverが常に無効になると思う	Aspire CLIが強制しないだけで、環境変数やSDK側の挙動は残る
13.3.5への更新を単なる小規模パッチと見なす	13.2から移行する場合は、13.3全体のbreaking changesも確認が必要

特に重要なのは、DOTNET_CLI_USE_MSBUILD_SERVER=true をCI全体の標準設定として入れているケースです。今回の修正後も、その設定が残っていればSDKは環境変数を見ます。パフォーマンス改善のために入れた設定が、特定SDK・OSの組み合わせで安定性を下げることがあるため、設定の目的と現在の必要性を見直してください。

今回の変更をどう評価すべきか

今回のGitHub documentation updateは、派手な新機能ではありません。しかし、Linux CIや開発コンテナでAspireを使うチームにとっては、開発ループを止める可能性がある重要な修正です。

MSBuild Serverは反復ビルドの高速化に役立つ機能ですが、CLIが一律に有効化するより、SDKと実行環境に判断を委ねた方が安全な場面があります。今回の修正は、そのバランスを取り直したものと見ると分かりやすいです。

管理者や開発者が次に取るべき行動は明確です。まず、Linux環境やGitHub Actionsで aspire run を使っているリポジトリを洗い出してください。次に、Aspire CLIと.NET SDKのバージョン、DOTNET_CLI_USE_MSBUILD_SERVER の設定有無を確認します。該当する場合は、修正済みのAspire CLIへ更新し、aspire run でAppHostビルドが通ることをCI上でも検証してください。