dotnet-skills
Framework Cross-Platform UI v0.1.0

.NET MAUI Doctor

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.

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.

References

  • references/workload-dependencies-discovery.md — NuGet API discovery process
  • references/microsoft-openjdk.md — JDK detection paths, identification, JAVA_HOME
  • references/installation-commands.md — .NET workloads, Android SDK (sdkmanager)
  • references/troubleshooting.md — Common errors and solutions
  • references/platform-requirements-{platform}.md — Platform-specific requirements
  • references/installation-commands-{platform}.md — Platform-specific install commands
  • references/troubleshooting-{platform}.md — Platform-specific troubleshooting
  • .NET MAUI Installation
  • .NET SDK Downloads
  • Microsoft OpenJDK
  • Android SDK Command-Line Tools
  • Xcode Downloads

Related skills

.NET MAUI

Details →
Framework Cross-Platform UI

Build, review, or migrate .NET MAUI applications across Android, iOS, macOS, and Windows with correct cross-platform UI, platform integration, and native packaging assumptions.

Microsoft.Maui.*
dotnet skills install maui

.NET MAUI App Lifecycle

Details →
Framework Cross-Platform UI

.NET MAUI app lifecycle guidance — the four app states, cross-platform Window lifecycle events (Created, Activated, Deactivated, Stopped, Resumed, Destroying), platform-specific…

Microsoft.Maui.*
dotnet skills install maui-app-lifecycle

CollectionView — .NET MAUI

Details →
Framework Cross-Platform UI

Guidance for implementing CollectionView in .NET MAUI apps — data display, layouts (list & grid), selection, grouping, scrolling, empty views, templates, incremental loading…

Microsoft.Maui.*
dotnet skills install maui-collectionview