redth/maui.sherpa/maui-doctor

.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 -d /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