/dotnet-maui-doctor

name: dotnet-maui-doctor
description: >-
  Diagnoses and fixes .NET MAUI development environment issues. Validates .NET SDK,
  workloads, Java JDK, Android SDK, Xcode, and Windows SDK. All version requirements
  discovered dynamically from NuGet WorkloadDependencies.json — never hardcoded.
  Use when: setting up MAUI development, build errors mentioning SDK/workload/JDK/Android,
  "Android SDK not found", "Java version" errors, "Xcode not found", environment verification
  after updates, or any MAUI toolchain issues. Do not use for: non-MAUI .NET projects,
  Xamarin.Forms apps, runtime app crashes unrelated to environment setup, or app store
  publishing issues. Works on macOS, Windows, and Linux.
license: MIT

.NET MAUI Doctor

Validate and fix .NET MAUI development environments. All version requirements are discovered dynamically from NuGet APIs — never hardcode versions.

When to Use

• Setting up a new .NET MAUI development environment
• Build errors mentioning missing SDKs, workloads, JDK, or Android components
• Errors like "Android SDK not found", "Java version", or "Xcode not found"
• Verifying environment health after SDK or OS updates

When Not to Use

• Non-MAUI .NET projects (use standard .NET SDK troubleshooting instead)
• Xamarin.Forms apps (different toolchain and workload requirements)
• Runtime app crashes unrelated to environment setup
• App store publishing or signing issues
• IDE-specific issues (Visual Studio or VS Code configuration)

Important: .NET Version Currency

Your training data may be outdated regarding .NET versions. .NET ships new major releases annually (November). Always check the releases-index.json (Task 2) to discover the **latest active major release** — do not assume your training data reflects the current version. For example, if you know about .NET 9.0 but the releases index shows .NET 10.0 as active, use .NET 10.0.

Inputs

• A development machine running macOS, Windows, or Linux
• Shell access (Bash on macOS/Linux, PowerShell on Windows)
• Internet access for NuGet API queries and SDK downloads
• Admin/sudo access may be required for installing SDKs and workloads
• **Bash prerequisites**: `curl`, `jq`, and `unzip` (macOS/Linux)
• **PowerShell prerequisites**: `Invoke-RestMethod` and `System.IO.Compression` (built-in on Windows)

Behavior

• Run through ALL tasks autonomously
• Re-validate after each fix
• Iterate until complete or no further actions possible
• After detecting platform (Task 1), load only the matching platform-specific references

Workflow

Task 1: Detect Environment

# macOS
sw_vers && uname -m

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

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

After detection, load the matching platform references:

• **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`

Task 2: Check .NET SDK

dotnet --info

Compare installed vs `latest-sdk` from https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/releases-index.json where `support-phase` is `"active"`.

Task 3: Check MAUI Workloads

| Workload | macOS | Windows | Linux | |----------|-------|---------|-------| | `maui` | Required | Required | ❌ Use `maui-android` | | `maui-android` | Alias | Alias | Required | | `android` | Required | Required | Required | | `ios` | Required | Optional | N/A |

Task 4: Discover Requirements from NuGet

See `references/workload-dependencies-discovery.md` for complete process.

Query NuGet for workload manifest → extract `WorkloadDependencies.json` → get:

• `jdk.version` range and `jdk.recommendedVersion`
• `androidsdk.packages`, `buildToolsVersion`, `apiLevel`
• `xcode.version` range

Task 5: Validate Java JDK

**Only Microsoft OpenJDK supported.** Verify `java -version` output contains "Microsoft". See `references/microsoft-openjdk.md` for detection paths.

> Use the JDK version recommended by WorkloadDependencies.json (`jdk.recommendedVersion`), ensuring it satisfies the `jdk.version` range. Do not hardcode JDK versions.

**JAVA_HOME is NOT required.** .NET MAUI tools auto-detect Microsoft OpenJDK installations from known paths. Do not tell users to set JAVA_HOME — it is unnecessary and risks pointing to a non-Microsoft JDK.

| JAVA_HOME state | OK? | Action | |-----------------|-----|--------| | Not set | ✅ | None needed — auto-detection works | | Set to Microsoft JDK | ✅ | None needed | | Set to non-Microsoft JDK | ⚠️ | **Report as anomaly** — let user decide to unset or redirect |

Task 6: Validate Android SDK

Check packages from `androidsdk.packages`, `buildToolsVersion`, `apiLevel` (Task 4). See `references/installation-commands.md` for sdkmanager commands.

Task 7: Validate Xcode (macOS Only)

xcodebuild -version

Compare against `xcode.version` range from Task 4. See `references/installation-commands-macos.md`.

Task 8: Validate Windows SDK (Windows Only)

The Windows SDK is typically installed as part of the .NET MAUI workload or Visual Studio. See `references/installation-commands-windows.md`.

Task 9: Remediation

See `references/installation-commands.md` for all commands.

Key rules:

• **Workloads**: Always use `--version` flag. Never use `workload update` or `workload repair`.
• **JDK**: Only install Microsoft OpenJDK. Do not set JAVA_HOME (auto-detected).
• **Android SDK**: Use `sdkmanager` (from Android SDK command-line tools). On Windows use `sdkmanager.bat`.

Task 10: Re-validate

After each fix, re-run the relevant validation task. Iterate until all checks pass.

Validation

A successful run produces:

• .NET SDK installed and matches an active release
• All required workloads installe