Back to Details

dotnet-maui-doctor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

.NET MAUI Doctor

.NET MAUI Doctor

Validate and fix .NET MAUI development environments. All version requirements are discovered dynamically from NuGet APIs — never hardcode versions.
验证并修复.NET MAUI开发环境。所有版本要求均通过NuGet API动态获取——绝不硬编码版本号。

When to Use

适用场景

  • Setting up a new .NET MAUI development environment
  • Build errors mentioning missing SDKs, workloads, JDK, or Android components
  • Errors like "Android SDK not found", "Java version", or "Xcode not found"
  • Verifying environment health after SDK or OS updates
  • 搭建新的.NET MAUI开发环境
  • 出现提及缺失SDK、工作负载、JDK或Android组件的构建错误
  • 出现"Android SDK未找到"、"Java版本"或"Xcode未找到"等错误
  • SDK或系统更新后验证环境健康状态

When Not to Use

不适用场景

  • Non-MAUI .NET projects (use standard .NET SDK troubleshooting instead)
  • Xamarin.Forms apps (different toolchain and workload requirements)
  • Runtime app crashes unrelated to environment setup
  • App store publishing or signing issues
  • IDE-specific issues (Visual Studio or VS Code configuration)
  • 非MAUI的.NET项目（请使用标准.NET SDK故障排查方法）
  • Xamarin.Forms应用（工具链和工作负载要求不同）
  • 与环境设置无关的运行时应用崩溃
  • 应用商店发布或签名问题
  • IDE特定问题（Visual Studio或VS Code配置问题）

Important: .NET Version Currency

重要提示：.NET版本时效性

Your training data may be outdated regarding .NET versions. .NET ships new major releases annually (November). Always check the releases-index.json (Task 2) to discover the latest active major release — do not assume your training data reflects the current version. For example, if you know about .NET 9.0 but the releases index shows .NET 10.0 as active, use .NET 10.0.
你的训练数据可能关于.NET版本的内容已过时。.NET每年11月发布新的主版本。请始终查看releases-index.json（任务2）以了解最新的活跃主版本——不要假设训练数据反映当前版本。例如，如果你知道.NET 9.0，但版本索引显示.NET 10.0为活跃版本，请使用.NET 10.0。

Inputs

输入要求

  • A development machine running macOS, Windows, or Linux
  • Shell access (Bash on macOS/Linux, PowerShell on Windows)
  • Internet access for NuGet API queries and SDK downloads
  • Admin/sudo access may be required for installing SDKs and workloads
  • Bash prerequisites: 
    curl
    , 
    jq
    , and 
    unzip
    (macOS/Linux)
  • PowerShell prerequisites: 
    Invoke-RestMethod
    and 
    System.IO.Compression
    (built-in on Windows)
  • 运行macOS、Windows或Linux的开发机器
  • Shell访问权限（macOS/Linux使用Bash，Windows使用PowerShell）
  • 可访问互联网，用于NuGet API查询和SDK下载
  • 安装SDK和工作负载可能需要管理员/ sudo权限
  • Bash前置依赖：
    curl
    、
    jq
    和
    unzip
    （macOS/Linux）
  • PowerShell前置依赖：
    Invoke-RestMethod
    和
    System.IO.Compression
    （Windows系统内置）

Behavior

行为规则

  • Run through ALL tasks autonomously
  • Re-validate after each fix
  • Iterate until complete or no further actions possible
  • After detecting platform (Task 1), load only the matching platform-specific references
  • 自动执行所有任务
  • 每次修复后重新验证
  • 循环执行，直到完成或无法进行进一步操作
  • 检测平台（任务1）后，仅加载匹配的平台特定参考文档

Workflow

工作流程

Task 1: Detect Environment

任务1：检测环境

bash
undefined
bash
undefined

macOS

macOS

sw_vers && uname -m
sw_vers && uname -m

Windows

Windows

systeminfo | findstr /B /C:"OS Name" /C:"OS Version"
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"

Linux

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`
cat /etc/os-release && uname -m

检测完成后，加载匹配的平台参考文档：
- **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

任务2：检查.NET SDK

bash
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"
.
bash
dotnet --info
将已安装版本与https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/releases-index.json中`support-phase`为`"active"`的`latest-sdk`版本进行对比。

Task 3: Check MAUI Workloads

任务3：检查MAUI工作负载

WorkloadmacOSWindowsLinux
maui
RequiredRequired❌ Use 
maui-android
maui-android
AliasAliasRequired
android
RequiredRequiredRequired
ios
RequiredOptionalN/A
工作负载macOSWindowsLinux
maui
必填必填❌ 请使用
maui-android
maui-android
别名别名必填
android
必填必填必填
ios
必填可选不适用

Task 4: Discover Requirements from NuGet

任务4：从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
完整流程请查看
references/workload-dependencies-discovery.md
。
查询NuGet获取工作负载清单 → 提取
WorkloadDependencies.json
→ 获取以下信息：
  • jdk.version
    范围和
    jdk.recommendedVersion
  • androidsdk.packages
    、
    buildToolsVersion
    、
    apiLevel
  • xcode.version
    范围

Task 5: Validate Java JDK

任务5：验证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 stateOK?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
仅支持Microsoft OpenJDK。验证
java -version
输出中包含"Microsoft"。检测路径请查看
references/microsoft-openjdk.md
。
请使用WorkloadDependencies.json推荐的JDK版本（
jdk.recommendedVersion
），确保其满足
jdk.version
范围要求。请勿硬编码JDK版本。
无需设置JAVA_HOME。.NET MAUI工具会从已知路径自动检测Microsoft OpenJDK安装。请勿告知用户设置JAVA_HOME——这毫无必要，还可能指向非Microsoft JDK。
JAVA_HOME状态是否正常？操作
未设置✅无需操作——自动检测生效
已设置为Microsoft JDK✅无需操作
已设置为非Microsoft JDK⚠️报告异常——由用户决定是否取消设置或重定向

Task 6: Validate Android SDK

任务6：验证Android SDK

Check packages from 
androidsdk.packages
, 
buildToolsVersion
, 
apiLevel
(Task 4). See 
references/installation-commands.md
for sdkmanager commands.
根据任务4获取的
androidsdk.packages
、
buildToolsVersion
、
apiLevel
检查对应包。安装命令请查看
references/installation-commands.md
中的sdkmanager命令。

Task 7: Validate Xcode (macOS Only)

任务7：验证Xcode（仅macOS）

bash
xcodebuild -version
Compare against 
xcode.version
range from Task 4. See 
references/installation-commands-macos.md
.
bash
xcodebuild -version
与任务4获取的
xcode.version
范围进行对比。安装命令请查看
references/installation-commands-macos.md
。

Task 8: Validate Windows SDK (Windows Only)

任务8：验证Windows SDK（仅Windows）

The Windows SDK is typically installed as part of the .NET MAUI workload or Visual Studio. See 
references/installation-commands-windows.md
.
Windows SDK通常随.NET MAUI工作负载或Visual Studio一同安装。安装命令请查看
references/installation-commands-windows.md
。

Task 9: Remediation

任务9：修复操作

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
    .
所有命令请查看
references/installation-commands.md
。
核心规则：
  • 工作负载：始终使用
    --version
    参数。绝不要使用
    workload update
    或
    workload repair
    命令。
  • JDK：仅安装Microsoft OpenJDK。无需设置JAVA_HOME（自动检测）。
  • Android SDK：使用
    sdkmanager
    （来自Android SDK命令行工具）。Windows系统请使用
    sdkmanager.bat
    。

Task 10: Re-validate

任务10：重新验证

After each fix, re-run the relevant validation task. Iterate until all checks pass.
每次修复后，重新运行对应的验证任务。循环执行直到所有检查通过。

Validation

验证标准

A successful run produces:
  • .NET SDK installed and matches an active release
  • All required workloads installed with consistent versions
  • Microsoft OpenJDK detected (
    java -version
    contains "Microsoft")
  • All required Android SDK packages installed (per WorkloadDependencies.json)
  • Xcode version in supported range (macOS only)
  • Windows SDK detected (Windows only)
运行成功的标志：
  • .NET SDK已安装且匹配活跃版本
  • 所有必填工作负载已安装且版本一致
  • 检测到Microsoft OpenJDK（
    java -version
    输出包含"Microsoft"）
  • 所有必填Android SDK包已安装（符合WorkloadDependencies.json要求）
  • Xcode版本在支持范围内（仅macOS）
  • 检测到Windows SDK（仅Windows）

Build Verification (Recommended)

构建验证（推荐）

After all checks pass, create and build a test project to confirm the environment actually works:
bash
TEMP_DIR=$(mktemp -d)
dotnet new maui -o "$TEMP_DIR/MauiTest"
dotnet build "$TEMP_DIR/MauiTest"
rm -rf "$TEMP_DIR"
On Windows, use 
$env:TEMP
or 
New-TemporaryFile
for the temp directory.
If the build succeeds, the environment is verified. If it fails, use the error output to diagnose remaining issues.
所有检查通过后，创建并构建测试项目以确认环境可正常工作：
bash
TEMP_DIR=$(mktemp -d)
dotnet new maui -o "$TEMP_DIR/MauiTest"
dotnet build "$TEMP_DIR/MauiTest"
rm -rf "$TEMP_DIR"
Windows系统请使用
$env:TEMP
或
New-TemporaryFile
创建临时目录。
如果构建成功，则环境验证通过。如果失败，请使用错误输出诊断剩余问题。

Run Verification (Optional — Ask User First)

运行验证（可选——需先询问用户）

After a successful build, ask the user if they want to launch the app on a target platform to verify end-to-end:
bash
undefined
构建成功后，询问用户是否要在目标平台启动应用以验证端到端流程：
bash
undefined

Replace net10.0 with the current major .NET version

将net10.0替换为当前的.NET主版本

dotnet build -t:Run -f net10.0-android dotnet build -t:Run -f net10.0-ios # macOS only dotnet build -t:Run -f net10.0-maccatalyst # macOS only dotnet build -t:Run -f net10.0-windows # Windows only

Only run the target frameworks relevant to the user's platform and intent. This step deploys to an emulator/simulator/device, so confirm with the user before proceeding.
dotnet build -t:Run -f net10.0-android dotnet build -t:Run -f net10.0-ios # 仅macOS dotnet build -t:Run -f net10.0-maccatalyst # 仅macOS dotnet build -t:Run -f net10.0-windows # 仅Windows

仅运行与用户平台和需求相关的目标框架。此步骤会将应用部署到模拟器/仿真器/设备，因此请先征得用户同意再执行。

Common Pitfalls

常见误区

  • maui
    vs 
    maui-android
    workload    : On Linux, the 
    maui
    meta-workload is not available — use 
    maui-android
    instead. On macOS/Windows, 
    maui
    installs all platform workloads.
  • workload update
    / 
    workload repair
    : Never use these commands. Always install workloads with an explicit 
    --version
    flag to ensure version consistency.
  • Non-Microsoft JDK: Only Microsoft OpenJDK is supported. Other distributions (Oracle, Adoptium, Azul) will cause build failures even if the version is correct.
  • Unnecessary JAVA_HOME: Do not set JAVA_HOME. MAUI auto-detects JDK from known install paths. If JAVA_HOME is set to a non-Microsoft JDK (e.g., Temurin), report this as an anomaly — it may override auto-detection and cause failures. Let the user decide whether to unset it.
  • Hardcoded versions: Never hardcode SDK, workload, or dependency versions. Always discover them dynamically from the NuGet APIs (see Task 4).
  • Android SDK 
    sdkmanager
    on Windows    : Use 
    sdkmanager.bat
    , not 
    sdkmanager
    , on Windows.
  • Stale training data: LLM training data may reference outdated .NET versions. Always check the releases-index.json to discover the current active release.
  • maui
    与
    maui-android
    工作负载    ：Linux系统不提供
    maui
    元工作负载——请使用
    maui-android
    。macOS/Windows系统中，
    maui
    会安装所有平台工作负载。
  • workload update
    / 
    workload repair
    ：绝不要使用这些命令。始终使用显式
    --version
    参数安装工作负载，以确保版本一致性。
  • 非Microsoft JDK：仅支持Microsoft OpenJDK。其他发行版（Oracle、Adoptium、Azul）即使版本正确也会导致构建失败。
  • 不必要的JAVA_HOME：请勿设置JAVA_HOME。MAUI会从已知安装路径自动检测JDK。如果JAVA_HOME指向非Microsoft JDK（如Temurin），请将其报告为异常——这可能覆盖自动检测并导致失败。由用户决定是否取消设置。
  • 硬编码版本：绝不要硬编码SDK、工作负载或依赖版本。始终通过NuGet API动态获取（见任务4）。
  • Windows系统的Android SDK 
    sdkmanager
    ：Windows系统请使用
    sdkmanager.bat
    ，而非
    sdkmanager
    。
  • 过时的训练数据：大语言模型的训练数据可能引用过时的.NET版本。请始终查看releases-index.json以获取当前的活跃版本。

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
Official docs:
  • references/workload-dependencies-discovery.md
    — NuGet API获取流程
  • references/microsoft-openjdk.md
    — JDK检测路径、识别方法、JAVA_HOME相关说明
  • references/installation-commands.md
    — .NET工作负载、Android SDK（sdkmanager）安装命令
  • references/troubleshooting.md
    — 常见错误及解决方案
  • references/platform-requirements-{platform}.md
    — 平台特定要求
  • references/installation-commands-{platform}.md
    — 平台特定安装命令
  • references/troubleshooting-{platform}.md
    — 平台特定故障排查
官方文档：