dotnet-maui-doctor

.NET MAUI Doctor

.NET MAUI の開発環境を検証し、修正します。すべてのバージョン要件は NuGet API から動的に取得します。バージョンをハードコードしないでください。

使用する場面

• 新しい .NET MAUI 開発環境をセットアップするとき
• SDK、ワークロード、JDK、Android コンポーネントの不足を示すビルドエラーが発生したとき
• 「Android SDK が見つかりません」、「Java のバージョン」、「Xcode が見つかりません」などのエラーが発生したとき
• SDK または OS の更新後に環境の状態を確認するとき

使用しない場面

• MAUI 以外の .NET プロジェクト（代わりに標準的な .NET SDK のトラブルシューティングを使用してください）
• Xamarin.Forms アプリ（ツールチェーンとワークロードの要件が異なります）
• 環境セットアップに関係のない実行時のアプリクラッシュ
• アプリストアへの公開や署名に関する問題
• IDE 固有の問題（Visual Studio または VS Code の構成）

重要：.NET バージョンの最新状況

学習データに含まれる .NET のバージョン情報は古くなっている可能性があります。.NET のメジャーリリースは毎年 11 月に公開されます。常に releases-index.json（タスク 2）を確認し、最新のサポート対象メジャーリリースを特定してください。学習データが現在のバージョンを反映していると決めつけないでください。たとえば、.NET 9.0 の情報を知っていても、リリースインデックスで .NET 10.0 がサポート対象と示されている場合は、.NET 10.0 を使用してください。

入力

• macOS、Windows、または Linux を実行している開発用マシン
• シェルアクセス（macOS/Linux では Bash、Windows では PowerShell）
• NuGet API のクエリと SDK のダウンロードに必要なインターネットアクセス
• SDK とワークロードのインストールに管理者または sudo のアクセスが必要な場合があります
• Bash の前提条件：curl、jq、unzip（macOS/Linux）
• PowerShell の前提条件：Invoke-RestMethod と System.IO.Compression（Windows に組み込み済み）

動作

• すべてのタスクを自律的に実行します
• 修正のたびに再検証します
• 完了するか、これ以上実行可能な対応がなくなるまで繰り返します
• プラットフォームの検出（タスク 1）後、一致するプラットフォーム固有のリファレンスのみを読み込みます

ワークフロー

タスク 1：環境を検出する

# macOS
sw_vers && uname -m

# Windows
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"

# Linux
cat /etc/os-release && uname -m

検出後、一致するプラットフォームのリファレンスを読み込みます。

• macOS：references/platform-requirements-macos.md、references/installation-commands-macos.md、references/troubleshooting-macos.md
• Windows：references/platform-requirements-windows.md、references/installation-commands-windows.md、references/troubleshooting-windows.md
• Linux：references/platform-requirements-linux.md

タスク 2：.NET SDK を確認する

dotnet --info

support-phase が "active" の場合の https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/releases-index.json にある latest-sdk と、インストール済みの SDK を比較します。

タスク 3：MAUI ワークロードを確認する

ワークロード	macOS	Windows	Linux
maui	必須	必須	❌ maui-android を使用
maui-android	エイリアス	エイリアス	必須
android	必須	必須	必須
ios	必須	任意	該当なし

タスク 4：NuGet から要件を特定する

完全な手順については、references/workload-dependencies-discovery.md を参照してください。

NuGet にクエリを実行してワークロードマニフェストを取得し、WorkloadDependencies.json を抽出して、以下を確認します。

• jdk.version の範囲と jdk.recommendedVersion
• androidsdk.packages、buildToolsVersion、apiLevel
• xcode.version の範囲

タスク 5：Java JDK を検証する

サポート対象は Microsoft OpenJDK のみです。 java -version の出力に「Microsoft」が含まれていることを確認します。検出パスについては、references/microsoft-openjdk.md を参照してください。

WorkloadDependencies.json で推奨される JDK バージョン（jdk.recommendedVersion）を使用し、それが jdk.version の範囲を満たしていることを確認してください。JDK バージョンをハードコードしないでください。

JAVA_HOME は不要です。 .NET MAUI ツールは、既知のパスにある Microsoft OpenJDK のインストールを自動検出します。JAVA_HOME の設定をユーザーに指示しないでください。不要であるうえ、Microsoft 製ではない JDK を指すリスクがあります。

JAVA_HOME の状態	問題なし？	対応
未設定	✅	対応不要 — 自動検出が機能します
Microsoft JDK に設定	✅	対応不要
Microsoft 製ではない JDK に設定	⚠️	異常として報告 — 解除するか、別のパスに変更するかはユーザーに判断してもらいます

タスク 6：Android SDK の検証

androidsdk.packages、buildToolsVersion、apiLevel（タスク 4）のパッケージを確認します。sdkmanager のコマンドについては、references/installation-commands.md を参照してください。

タスク 7：Xcode の検証（macOS のみ）

xcodebuild -version

タスク 4 の xcode.version の範囲と照合します。references/installation-commands-macos.md を参照してください。

タスク 8：Windows SDK の検証（Windows のみ）

Windows SDK は通常、.NET MAUI ワークロードまたは Visual Studio の一部としてインストールされます。references/installation-commands-windows.md を参照してください。

タスク 9：修復

すべてのコマンドについては、references/installation-commands.md を参照してください。

重要なルール：

• ワークロード：常に --version フラグを使用してください。workload update や workload repair は使用しないでください。
• JDK：Microsoft OpenJDK のみをインストールしてください。JAVA_HOME は設定しないでください（自動検出されます）。
• Android SDK：Android SDK コマンドラインツールに含まれる sdkmanager を使用してください。Windows では sdkmanager.bat を使用してください。

タスク 10：再検証

各修正の後、該当する検証タスクを再実行してください。すべてのチェックに合格するまで繰り返します。

検証

実行が正常に完了すると、次の状態になります：

• .NET SDK がインストールされ、サポート対象のリリースに一致している
• 必要なすべてのワークロードが、一貫したバージョンでインストールされている
• Microsoft OpenJDK が検出されている（java -version に「Microsoft」が含まれている）
• 必要なすべての Android SDK パッケージがインストールされている（WorkloadDependencies.json に基づく）
• Xcode のバージョンがサポート対象の範囲内である（macOS のみ）
• Windows SDK が検出されている（Windows のみ）

ビルド検証（推奨）

すべてのチェックに合格した後、テストプロジェクトを作成してビルドし、環境が実際に動作することを確認します：

TEMP_DIR=$(mktemp -d)
dotnet new maui -o "$TEMP_DIR/MauiTest"
dotnet build "$TEMP_DIR/MauiTest"
rm -rf "$TEMP_DIR"

Windows では、一時ディレクトリに $env:TEMP または New-TemporaryFile を使用してください。

ビルドが成功すれば、環境は検証済みです。失敗した場合は、エラー出力を使って残りの問題を診断してください。

実行検証（任意 — 先にユーザーに確認）

ビルドが成功した後、エンドツーエンドで検証するために、対象プラットフォームでアプリを起動するかどうかユーザーに確認してください：

# Replace net10.0 with the current major .NET version
dotnet build -t:Run -f net10.0-android
dotnet build -t:Run -f net10.0-ios        # macOS only
dotnet build -t:Run -f net10.0-maccatalyst # macOS only
dotnet build -t:Run -f net10.0-windows    # Windows only

ユーザーのプラットフォームと目的に関連するターゲットフレームワークのみを実行してください。この手順ではエミュレーター／シミュレーター／デバイスにデプロイするため、続行する前にユーザーに確認してください。

よくある落とし穴

• maui と maui-android ワークロードの違い：Linux では maui メタワークロードを利用できません。代わりに maui-android を使用してください。macOS／Windows では、maui によりすべてのプラットフォームワークロードがインストールされます。
• workload update／workload repair：これらのコマンドは使用しないでください。バージョンの一貫性を確保するため、ワークロードは必ず明示的な --version フラグを付けてインストールしてください。
• Microsoft 以外の JDK：サポートされているのは Microsoft OpenJDK のみです。ほかのディストリビューション（Oracle、Adoptium、Azul）は、バージョンが正しくてもビルドの失敗を引き起こします。
• 不要な JAVA_HOME：JAVA_HOME は設定しないでください。MAUI は既知のインストールパスから JDK を自動検出します。JAVA_HOME が Microsoft 以外の JDK（例：Temurin）を指している場合は、異常として報告してください。自動検出より優先され、失敗の原因になる可能性があります。JAVA_HOME を解除するかどうかはユーザーに判断してもらってください。
• バージョンのハードコード：SDK、ワークロード、依存関係のバージョンをハードコードしないでください。常に NuGet API から動的に確認してください（タスク 4 を参照）。
• Windows での Android SDK sdkmanager：Windows では sdkmanager ではなく sdkmanager.bat を使用してください。
• 古い学習データ：LLM の学習データには、古い .NET バージョンが含まれている場合があります。常に releases-index.json を確認して、現在サポートされているリリースを特定してください。

参考資料

• references/workload-dependencies-discovery.md — NuGet API の検出プロセス
• references/microsoft-openjdk.md — JDK の検出パス、識別、JAVA_HOME
• references/installation-commands.md — .NET ワークロード、Android SDK（sdkmanager）
• references/troubleshooting.md — よくあるエラーと解決策
• references/platform-requirements-{platform}.md — プラットフォーム固有の要件
• references/installation-commands-{platform}.md — プラットフォーム固有のインストールコマンド
• references/troubleshooting-{platform}.md — プラットフォーム固有のトラブルシューティング

公式ドキュメント：

• .NET MAUI のインストール
• .NET SDK のダウンロード
• Microsoft OpenJDK
• Android SDK コマンドラインツール
• Xcode のダウンロード