How to Use the dotnet-maui Plugin for Environment Setup: Complete Developer Guide

The dotnet-maui plugin automates .NET MAUI environment validation and remediation through a task-driven "doctor" skill that detects your OS, verifies SDKs and workloads, installs missing dependencies, and confirms setup by building a test project.

The dotnet-maui plugin in the dotnet/skills repository eliminates manual configuration headaches by providing a self-contained validation system. This plugin orchestrates a ten-step workflow defined in plugins/dotnet-maui/skills/dotnet-maui-doctor/SKILL.md to ensure your development machine meets all platform-specific requirements. Whether you are targeting Android, iOS, macOS, or Windows, the dotnet-maui plugin dynamically discovers the latest official constraints directly from NuGet feeds, ensuring your environment always matches current standards.

Understanding the dotnet-maui-doctor Skill Architecture

The core functionality resides in the dotnet-maui-doctor skill, which implements a task-driven workflow that executes sequentially. Each task performs granular validation and triggers targeted remediation when discrepancies are detected.

Workflow Definition Source

The entire validation logic is documented in plugins/dotnet-maui/skills/dotnet-maui-doctor/SKILL.md, which maps out ten distinct tasks ranging from OS detection to final build verification. This architecture ensures idempotent operations—you can run the skill repeatedly, and it will only install missing components without affecting existing configurations.

Step-by-Step Environment Validation Process

The dotnet-maui plugin executes a comprehensive ten-step validation pipeline. Here is how each phase works according to the source code implementation.

Step 1: Host OS Detection

The skill executes platform-specific shell snippets to identify the operating system and architecture. On macOS, it runs sw_vers and uname -m; on Windows, it queries systeminfo; on Linux, it parses /etc/os-release. This detection determines which platform-specific reference files the plugin loads for subsequent validation steps.

Step 2: .NET SDK Verification

The skill executes dotnet --info and compares your installed SDK against the latest active release listed in the official releases-index.json. This dynamic comparison avoids hard-coded version checks and ensures you are always running a supported SDK.

Step 3: MAUI Workload Validation

The plugin consults a platform-specific workload matrix to verify required installations. The matrix specifies that Windows and macOS require the maui meta-workload, while Linux developers must use maui-android since the full maui workload is unavailable on that platform. This logic is defined in references/platform-requirements-linux.md.

Step 4: Dynamic Version Requirement Discovery

Instead of embedding version numbers, the skill pulls the WorkloadDependencies.json file directly from NuGet. This JSON contains the exact JDK version ranges, Android SDK packages, and Xcode version ranges required by the current MAUI release. This approach guarantees the plugin always enforces the latest official constraints without manual updates.

Step 5: Microsoft OpenJDK Verification

The skill confirms that java -version reports a Microsoft-supplied JDK. Critically, the implementation does not require JAVA_HOME to be set; MAUI auto-detects the JDK from known install locations. This behavior is documented in references/microsoft-openjdk.md.

Step 6: Android SDK Validation

Using the package list extracted from the workload manifest in Step 4, the skill invokes sdkmanager (or sdkmanager.bat on Windows) to install any missing Android SDK components. The specific packages validate against the exact versions required by your target MAUI release.

Step 7: Xcode Validation (macOS Only)

On macOS systems, the skill runs xcodebuild -version and validates the installed Xcode version against the range specified in the WorkloadDependencies.json discovered in Step 4.

Step 8: Windows SDK Validation (Windows Only)

The plugin confirms the Windows SDK presence, checking whether it is installed as part of the MAUI workload or through Visual Studio. This step ensures UWP and WinUI development capabilities are available.

Step 9: Centralized Remediation

All installation commands are centralized in references/installation-commands.md. The skill uses explicit --version flags for all dotnet workload install commands and deliberately never invokes workload update or workload repair. This precise approach prevents unintended side effects and ensures reproducible environments.

Step 10: Final Build Verification

After remediation, the skill creates a temporary MAUI project using dotnet new maui and attempts a full dotnet build. A successful build confirms the environment is ready for production development. This verification occurs in an isolated temporary directory that is cleaned up automatically.

Key Implementation Files and References

The dotnet-maui plugin relies on several reference documents that define its behavior:

• plugins/dotnet-maui/plugin.json – Declares the plugin metadata and available skills.
• plugins/dotnet-maui/skills/dotnet-maui-doctor/SKILL.md – Contains the complete task-driven workflow specification (tasks 1-10).
• plugins/dotnet-maui/skills/dotnet-maui-doctor/references/workload-dependencies-discovery.md – Documents how the skill queries NuGet for WorkloadDependencies.json.
• plugins/dotnet-maui/skills/dotnet-maui-doctor/references/installation-commands.md – Central repository of all platform-specific installation commands.
• plugins/dotnet-maui/skills/dotnet-maui-doctor/references/platform-requirements-linux.md – Defines Linux-specific constraints, including the requirement to use maui-android instead of the full maui workload.
• plugins/dotnet-maui/skills/dotnet-maui-doctor/references/microsoft-openjdk.md – Specifies detection logic for the Microsoft OpenJDK distribution.

Manual Verification Commands

While the dotnet-maui plugin automates these checks, you can run these commands manually for debugging or learning purposes:

# Detect OS (macOS example)

sw_vers && uname -m

# Detect OS (Windows PowerShell example)

systeminfo | Select-String "OS Name","OS Version"

# Verify .NET SDK and compare against latest active release

dotnet --info
curl -s https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/releases-index.json |
  jq -r '.releases[] | select(.supportPhase=="active") | .latestSdk'

# Install correct MAUI workloads (Linux requires maui-android)

dotnet workload install maui-android --version <VERSION>

# Windows/macOS use the full meta-workload

dotnet workload install maui --version <VERSION>

# Validate Microsoft OpenJDK presence

java -version  # Output must contain "Microsoft"

# Install Android SDK components manually

sdkmanager "platforms;android-34" "build-tools;34.0.0" "platform-tools"

# Final verification build

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

Note: The skill automatically derives all <VERSION> parameters from the workload manifest, eliminating the need for hard-coded version strings.

Summary

• The dotnet-maui plugin provides an automated "doctor" skill that validates and repairs .NET MAUI development environments through a ten-step task-driven workflow defined in SKILL.md.
• The plugin operates cross-platform (macOS, Windows, Linux) and dynamically discovers version requirements from official NuGet feeds rather than using hard-coded values.
• Idempotent execution allows repeated runs without side effects—the skill only installs missing components and never modifies correctly configured elements.
• Key validation steps include OS detection, .NET SDK verification, workload matrix validation (with Linux requiring maui-android instead of maui), Microsoft OpenJDK detection, Android SDK management, and final build verification.
• All installation logic is centralized in references/installation-commands.md using explicit version flags to ensure reproducible environments.

Frequently Asked Questions

What platforms does the dotnet-maui plugin support?

The plugin supports macOS, Windows, and Linux. Each platform uses specific detection logic (sw_vers for macOS, systeminfo for Windows, /etc/os-release for Linux) and loads platform-specific requirement files to validate the correct workload configurations.

Do I need to set JAVA_HOME for the dotnet-maui plugin to work?

No. According to references/microsoft-openjdk.md, the skill deliberately does not require JAVA_HOME to be configured. MAUI automatically detects the Microsoft OpenJDK from known installation locations, simplifying the setup process for developers.

How does the plugin handle version updates?

The plugin pulls the latest WorkloadDependencies.json directly from NuGet during the Discover Requirements step. This file contains current JDK version ranges, Android SDK requirements, and Xcode version constraints. By querying this at runtime, the skill always validates against the latest official requirements without needing manual updates to the plugin itself.

Can I run the dotnet-maui-doctor skill multiple times safely?

Yes. The skill is designed to be idempotent. You can invoke it repeatedly, and it will only install missing components or repair misconfigurations. It will not reinstall existing workloads or modify correctly configured SDKs, making it safe to run as part of automated CI/CD pipelines or daily development workflows.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}