.NET MAUI Doctor

Validate and fix .NET MAUI development environments.

Key Principle

All version requirements discovered dynamically from NuGet APIs. Never hardcode versions. See references/workload-dependencies-discovery.md.

Behavior

• •Run through ALL tasks autonomously
• •Re-validate after each fix
• •Iterate until complete or no further actions possible

Platform Support

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

Task 2: Check .NET SDK

dotnet --info
curl -s "https://raw.githubusercontent.com/dotnet/core/refs/heads/main/release-notes/releases-index.json"

Compare installed vs latest-sdk where support-phase is "active".

Task 3: Check MAUI Workloads

Linux: Use maui-android NOT maui (meta-workload includes iOS deps).

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. See references/microsoft-openjdk.md for paths and detection.

Verify java -version output contains "Microsoft".

⚠️ TEMPORARY WORKAROUND: The jdk.recommendedVersion from WorkloadDependencies.json currently returns 17, but recommend JDK 21 instead. This will be fixed in a future Android workload update. Rule: If WorkloadDependencies suggests ≤21, recommend 21. If it suggests >21, use that value.

Task 6: Validate Android SDK

Check packages from androidsdk.packages, buildToolsVersion, apiLevel (Task 4).

See references/installation-commands.md for detection commands.

Task 7: Validate Xcode (macOS Only)

xcodebuild -version

Compare against xcode.version range from Task 4.

Task 8: Validate Windows SDK (Windows Only)

Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\Windows Kits\Installed Roots"

Quick Diagnosis (Before Reinstalling)

⏱️ 2-minute check that can save hours. Many "missing tool" errors are actually path/environment issues.

Diagnostic Steps:

1. •Is it actually missing? Check with direct path: ls /Applications/Xcode.app, ls /Library/Java/JavaVirtualMachines/
2. •Is it a shell issue? Open NEW terminal and retry
3. •Is it an env var issue? Check echo $ANDROID_HOME, echo $JAVA_HOME - often these don't need to be set

Only reinstall if the tool is genuinely missing from disk.

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.
• •Android SDK: Use android sdk install (if tool available) or sdkmanager.

Task 10: Re-validate

After each fix, re-run validation. Iterate until all pass.

Optional Tools (Third-Party)

Highly recommended to simplify and make validation and remediation more reliable / consistent.

Ask before installing: "This is a third-party tool (not Microsoft). Install it?"

Important Notes

• •Linux workloads: Use maui-android + android (NOT maui)
• •JDK: Only Microsoft OpenJDK. Look for "Microsoft" in java -version.
• •JDK Version: ⚠️ Recommend JDK 21 (not 17) until WorkloadDependencies.json is updated.
• •JAVA_HOME: Not required. Only problematic if set to non-Microsoft JDK.

Context-Specific Guidance

CI/CD Pipelines

For automated builds (Azure DevOps, GitHub Actions, etc.):

• •Pin versions: Always use dotnet workload install --version X.Y.Z for reproducibility
• •Use --skip-manifest-update: Prevents drift between pipeline runs
• •Cache aggressively: NuGet packages, workloads, Android SDK (~90% hit rate saves 5-10 min)
• •Accept licenses non-interactively: echo y | sdkmanager --licenses
• •Avoid: dotnet workload update, dotnet workload repair (non-reproducible)

Expected build times:

Linux (Android-Only)

• •Workloads: Use maui-android + android (NOT maui)
• •KVM acceleration: Critical for emulator performance
  bash

  sudo apt install qemu-kvm && sudo usermod -aG kvm $USER
  # Log out/in for group change
  kvm-ok  # Should say "can be used"
  

• •Disk space: Expect ~8-10GB for SDK + emulator images
• •Streamline .csproj: Remove unused TFMs
  xml

  <TargetFrameworks>net9.0-android</TargetFrameworks>
  

Productivity Tips

Shell aliases (~/.bashrc or ~/.zshrc):

alias maui-build='dotnet build -f net9.0-android'
alias maui-run='dotnet build -f net9.0-android -t:Run'

macOS parallel setup: Start iOS simulator download in Xcode while continuing with SDK/workload installation.

References

• •references/workload-dependencies-discovery.md - NuGet API discovery process
• •references/microsoft-openjdk.md - JDK paths, detection, installation
• •references/installation-commands.md - All validation and install commands
• •references/platform-requirements.md - Platform-specific details
• •references/troubleshooting.md - Common issues and solutions