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

> Learn to automate .NET MAUI environment setup with the dotnet-maui plugin. This guide details how the plugin validates SDKs, installs dependencies, and builds a test project for seamless development.

- Repository: [.NET Platform/skills](https://github.com/dotnet/skills)
- Tags: how-to-guide
- Published: 2026-07-06

---

**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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-maui/plugin.json)** – Declares the plugin metadata and available skills.
- **[`plugins/dotnet-maui/skills/dotnet-maui-doctor/SKILL.md`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-maui/skills/dotnet-maui-doctor/references/workload-dependencies-discovery.md)** – Documents how the skill queries NuGet for [`WorkloadDependencies.json`](https://github.com/dotnet/skills/blob/main/WorkloadDependencies.json).
- **[`plugins/dotnet-maui/skills/dotnet-maui-doctor/references/installation-commands.md`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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:

```bash

# Detect OS (macOS example)

sw_vers && uname -m

```

```powershell

# Detect OS (Windows PowerShell example)

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

```

```bash

# 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'

```

```bash

# 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>

```

```bash

# Validate Microsoft OpenJDK presence

java -version  # Output must contain "Microsoft"

```

```bash

# Install Android SDK components manually

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

```

```bash

# 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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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.