.NET MAUI CLI（maui 命令）设计指南：统一 Android/iOS 环境配置、设备发现与应用检查

.NET MAUI CLImaui 命令设计指南统一 Android/iOS 环境配置、设备发现与应用检查【免费下载链接】maui.NET MAUI is the .NET Multi-platform App UI, a framework for building native device applications spanning mobile, tablet, and desktop.项目地址: https://gitcode.com/GitHub_Trending/ma/mauimaui是 .NET MAUI 仓库设计文档docs/design/cli.md所规划的官方命令行工具目标是为跨 Android、iOS、macOS、Windows、Mac Catalyst 的 MAUI 开发提供统一的设备管理与环境配置接口。本文以其设计文档为主体结合仓库 CI 流水线中的实际使用方式eng/pipelines/common/provision.yml完整介绍安装调用、全部子命令、设备发现策略、IDE 集成架构与未来规划让读者既能直接上手使用也能理解其底层设计取舍。背景与动机为什么要为 MAUI 单独做一个 CLI.NET MAUI 横跨多个平台而各平台的原生工具链各自为政。文档以截图为例指出平台差异之痛在 iOS 上截屏需要xcrun simctl io booted screenshot在 Android 上则需要adb exec-out screencap。日志访问、可视树检查、设备管理同样存在各自的平台专属实现。这种碎片化对两类用户尤其不友好人类开发者需要在记忆多套平台命令之间来回切换AI Agent源于仓库作者此前用 WPF 进行的 vibe coding 实验vibe-wpf实验证明只要给 AI Agent 合适的工具它就能高效开发应用而 MAUI 跨平台命令的碎片化恰恰是 Agent 自动化开发的最大障碍。mauiCLI 的定位就是用一个统一的接口覆盖这些平台专属操作同时保持与现有dotnet工作流dotnet run、dotnet watch的兼容。设计原则文档为 CLI 确立了五条设计原则委托给原生工具链——maui自身不重新实现底层能力而是封装sdkmanager、adb、xcrun simctl等现成工具复用共享库——Android 侧复用dotnet/android-toolsXamarin.Android.Tools.AndroidSdk做 SDK/JDK 发现并把 JDK 安装、SDK 引导、许可接受等新能力回馈给该库机器优先输出——每个命令都支持--json结构化输出无状态——每个命令读状态、执行、退出不维护会话补充dotnet run——沿用dotnet run对 .NET MAUI 定义的设备标识符与框架选项二者互补而非竞争。五大目标环境设置用单一工具管理 Android SDK/JDK、Xcode 运行时、模拟器与仿真器截图捕获让 AI Agent 能对运行中的 .NET MAUI 应用截图用于验证视觉变更日志访问统一访问各平台设备日志logcat、Console 等可视树检查让 Agent 能检查运行时可视树的结构与属性.NET MAUI 可视树开发者体验无缝融入现有dotnetCLI 工作流与dotnet run、dotnet watch等协同。安装与调用方式CLI 支持三种调用形态# 1. 直接调用安装后 maui screenshot -o screenshot.png # 2. 通过 .NET CLI dotnet maui screenshot -o screenshot.png # 3. 内联安装并调用无需预先安装 dotnet tool exec -y Microsoft.Maui.Cli screenshot -o screenshot.png安装方式则分全局与本地两种# 作为全局工具 dotnet tool install --global Microsoft.Maui.Cli # 作为本地工具推荐用于项目 dotnet tool install Microsoft.Maui.Cli # 还原本地工具 dotnet tool restore工具安装后以maui命令出现在 PATH 上本文档中所有命令均使用maui形式。关于自动安装的规划.NET workload 规范中的tools-packs特性支持从 workload 自动安装工具但该特性目前尚未实现。一旦可用Microsoft.Maui.Cli有望在mauiworkload 安装时自动装上省去手动安装步骤在那之前dotnet tool install仍是标准途径。全局选项所有命令都支持以下全局选项标志说明--json结构化 JSON 输出--verbose详细日志--interactive控制交互提示默认终端中为trueCI 环境或输出被重定向时为false--dry-run预演动作不真正执行--platform p按平台过滤android、ios、maccatalyst、windows交互检测机制与dotnetCLI 保持一致自动识别 CI 环境变量TF_BUILD、GITHUB_ACTIONS、CI等并检测Console.IsOutputRedirected据此决定是否弹出交互提示。这意味着在 CI 中不加参数也能安全地非交互执行。环境设置命令Android命令说明maui android install安装 JDK SDK 推荐包maui android install --accept-licenses非交互安装maui android install --packages list安装指定包maui android jdk check检查 JDK 状态maui android jdk install安装 OpenJDK 21maui android jdk list列出已安装的 JDKmaui android sdk list列出已安装的包maui android sdk list --available显示可安装的包maui android sdk install packages安装指定包maui android sdk accept-licenses接受所有许可maui android sdk uninstall package卸载指定包maui android emulator list列出仿真器maui android emulator create name创建仿真器自动探测系统镜像maui android emulator start name启动仿真器maui android emulator stop name停止仿真器maui android emulator delete name删除仿真器安装路径与默认值由dotnet/android-tools处理。Apple仅 macOS命令说明maui apple install [--accept-license] [--runtime version]可选接受 Xcode 许可并安装模拟器运行时未来可能提示用户安装 Xcodemaui apple check检查 Xcode、运行时与环境状态maui apple xcode check检查 Xcode 安装与许可maui apple xcode list列出 Xcode 安装maui apple xcode select path切换当前 Xcodemaui apple xcode accept-license接受 Xcode 许可maui apple simulator list列出模拟器maui apple simulator create name type runtime创建模拟器maui apple simulator start id启动模拟器maui apple simulator stop id停止模拟器maui apple simulator delete id删除模拟器maui apple runtime check检查运行时状态maui apple runtime list列出已安装的运行时maui apple runtime list --all列出所有运行时已安装 可下载maui apple runtime install version安装 iOS 运行时许可标志命名差异Android 用accept-licenses复数因为sdkmanager要求接受多个 SDK 组件的许可Apple 用accept-license单数因为xcodebuild -license accept接受的是统一的 Xcode 许可协议。底层实现参考Android 侧委托给dotnet/android-toolsXamarin.Android.Tools.AndroidSdk功能实现SDK 发现、引导与许可接受SdkManagerJDK 发现与安装JdkInstallerADB 设备管理AdbRunnerAVD / 仿真器管理AvdManagerRunner、EmulatorRunnerApple 侧直接封装原生工具链功能原生工具模拟器管理xcrun simctllist、create、boot、shutdown、delete运行时管理xcrun simctl runtimelist、addXcode 管理xcode-select、xcodebuild -license设备检测xcrun devicectl list devices真机、xcrun simctl list模拟器Apple 操作通过 AppleDev.Tools 封装simctl与devicectl。退出码约定所有命令使用统一的退出码代码含义0成功1一般错误2环境/配置错误3权限被拒绝需要提权4网络错误下载失败5资源未找到仓库中的实际落地CI 已经用起来了这份设计并非纸上谈兵——.NET MAUI 仓库自己的 CI 流水线已经实际使用了mauiCLI。在 eng/pipelines/common/provision.yml 中环境准备阶段通过dotnet build -t:ProvisionJdk ...、-t:ProvisionAndroidSdkCommonPackages ...等 MSBuild target 调用 CLI 安装 JDK 与 SDK任务显示名直接标注为 (maui cli)随后用dotnet maui android sdk check --ci --json做非交互检查并解析其 JSON 输出读取status字段判断 SDK 是否可用读取details.path得到首选 SDK 路径进而设置ANDROID_SDK_ROOT与ANDROID_HOME两个环境变量。这恰好印证了设计文档的两点--json机器优先输出真的被 CI 消费--ci之类隐式关闭交互的标志让流水线可以安全地非交互执行。同时说明 Android 侧还存在文档命令表之外的maui android sdk check检查命令返回含status、details.path的 JSON 结构。设备发现maui device listmaui device list用一条命令列出所有平台的已连接设备、运行中的仿真器和可用模拟器maui device list [--platform p] [--json]选项--platform PLATFORM按平台过滤android、ios、maccatalyst省略则列出所有平台--json结构化 JSON 输出供机器消费。人类可读输出ID Description Type Platform Status emulator-5554 Pixel 7 - API 35 Emulator android Online 0A041FDD400327 Pixel 7 Pro Device android Online 94E71AE5-8040-4DB2-8A9C-6CD24EF4E7DE iPhone 16 - iOS 26.0 Simulator ios Shutdown FBF5DCE8-EE2B-4215-8118-3A2190DE1AD7 iPhone 14 - iOS 26.0 Simulator ios Booted AF40CC64-2CDB-5F16-9651-86BCDF380881 My iPhone 15 Device ios PairedJSON 输出--json{ devices: [ { id: emulator-5554, description: Pixel 7 - API 35, type: Emulator, platform: android, status: Online }, { id: FBF5DCE8-EE2B-4215-8118-3A2190DE1AD7, description: iPhone 14 - iOS 26.0, type: Simulator, platform: ios, status: Booted } ] }关键兼容性设计输出中的id字段与dotnet run --device id接受的标识符完全一致因此maui device list的结果可以直接管道给运行命令使用。设备枚举的两种途径途径 A通过dotnet run --list-devices基于项目.NET SDK≥ .NET 11提供dotnet run --list-devices它会调用各平台 workload 定义的ComputeAvailableDevicesMSBuild targetAndroid调用adb devices返回序列号、描述、类型Device/Emulator、状态、型号Apple调用simctl list与devicectl list返回 UDID、描述、类型Device/Simulator、OS 版本、RuntimeIdentifier。该途径必须存在项目文件——MSBuild 需要评估.csproj才能定位正确的 workload targets同时它是按框架工作的先选一个目标框架再获取该平台下的设备。途径 B直接调用原生工具无需项目mauiCLI 直接调用adb devices、xcrun simctl list devices、xcrun devicectl list devices不评估任何 MSBuild 项目一次调用即可拿到统一、跨平台的设备列表。对比维度途径 AMSBuild途径 B原生 CLI需要项目是——需要.csproj否跨平台每次调用一个平台按 TFM一次调用覆盖所有平台元数据丰富RuntimeIdentifier、workload 专属字段标准id、description、type、status速度较慢MSBuild 评估 restore快2s直接进程调用ID 兼容性dotnet run --device的权威来源相同的原生 ID——兼容需要 workload是必须安装平台 workload否只需原生工具adb、simctl可扩展性workload 自动添加新设备类型每平台需单独添加支持没有项目时的真实场景以下工作流在项目创建前或项目上下文之外就需要设备枚举AI Agent 引导——Agent 启动 vibe coding 会话时要在脚手架项目之前先发现可用目标此时还没有.csproj无法调用dotnet run --list-devicesIDE 启动——VS Code 打开的工作区尚未加载 MAUI 项目扩展需要填充设备选择器向用户展示可用设备无项目查询是唯一选择环境验证——开发者在任意目录运行maui device list回答能不能看到我的手机这是诊断步骤而非构建步骤CI 流水线设置——CI 脚本在调用dotnet run之前检查预期仿真器/模拟器是否在运行检查不应依赖具体项目文件多项目解决方案——解决方案同时含 Android 与 iOS 项目开发者想要一个统一的设备列表而不是逐项目跑--list-devices跨平台总览——dotnet run --list-devices一次只显示一个 TFM 的设备而同时切 Android/iOS 的开发者想一眼看全。推荐方案maui device list以途径 B直接调用原生工具为主实现理由随处可用——不需要项目、workload targets也没有 MSBuild 评估开销设备标识符与ComputeAvailableDevices产出的原生 ID 相同与dotnet run --device完全兼容mauiCLI 本来就要为其他命令环境设置、仿真器管理封装这些原生工具设备列表是自然延伸。而当项目可用且需要框架级设备过滤时dotnet run --list-devices仍是正确工具——它提供更丰富的元数据RuntimeIdentifier且受益于 workload 专属逻辑。两者互补maui device list → 这台机器上存在哪些设备 dotnet run --list-devices → 哪些设备能运行这个项目各平台枚举实现平台原生工具枚举内容Androidadb devices -l真机与运行中的仿真器iOS模拟器xcrun simctl list devices --json所有模拟器已启动 已关机iOS真机xcrun devicectl list devices已连接的真机Mac Catalyst宿主机器Mac 本身应用检查命令规划中应用检查命令计划在后续版本发布首个版本聚焦环境设置与设备管理。设备选择选项应用检查命令将沿用dotnet run对 .NET MAUI 约定的设备选择与框架选项-f|--framework FRAMEWORK Target framework (e.g., net10.0-android, net10.0-ios) -d|--device DEVICE_ID Target device identifier (from --list-devices) --list-devices List available devices/emulators/simulators -p|--project PATH Path to the .NET MAUI project (default: current directory) -h|--help Show help information --version Show version information交互提示行为未指定-f|--framework时若存在项目文件且含多个目标框架CLI 提示选择一个若无项目文件CLI 从已知 .NET MAUI 目标框架中提示如net10.0-android、net10.0-ios、net10.0-maccatalyst、net10.0-windows。已选框架但未指定-d|--device时CLI 提示从该平台可用的设备/仿真器/模拟器中选择设备列表来自与dotnet run相同的ComputeAvailableDevicesMSBuild target。注意-d|--device使用的设备标识符与dotnet run --list-devices返回的一致。screenshot命令捕获正在运行的 .NET MAUI 应用的截图。用法maui screenshot [options]选项-o|--output PATH输出文件路径默认screenshot_{timestamp}.png-w|--wait SECONDS捕获前等待秒数默认0。平台实现首个版本覆盖 Android 与 iOS/Mac CatalystWindows 与 macOS 支持按规划随后跟进。Android使用adb exec-out screencap -piOS/Mac Catalyst模拟器用xcrun simctl io booted screenshot file真机捕获走 Xcode 工具链未来Windows规划用 Windows 屏幕捕获 API 捕获活动应用窗口或全屏macOS规划用 macOS 屏幕捕获 API 或命令行工具捕获活动应用窗口或全屏。未来命令清单maui screenshot—— 捕获运行中应用的截图maui logs—— 流式输出设备日志maui tree—— 检查可视树。与dotnet run和dotnet watch的集成CLI 被设计为与现有 .NET 工作流无缝协同常规工作流示例# 终端 1带热重载运行应用 dotnet watch run # 终端 2检查应用 maui screenshot --output iteration1.png maui logs --follow --filter MyApp # 未来 maui tree --json # 未来AI Agent 工作流# 0. 发现可用设备无需项目 maui device list --json # 1. 修改代码 # ... agent modifies MainPage.xaml ... # 2. 等待热重载完成 sleep 2 # 3. 捕获截图 maui screenshot -o current.png # 4. 分析可视树未来 maui tree --json # 5. 检查日志错误未来 maui logs --level error # 6. Agent 分析输出并决定下一步这个闭环——改代码 → 热重载 → 截图 → 分析可视树 → 查日志——正是为 AI Agent 的感知-行动循环设计的也是vibe coding在 MAUI 上得以成立的基础设施。平台专属考量Android设备检测adb devices截图adb exec-out screencap -p或 UI Automator日志带包过滤的adb logcat。iOS / Mac Catalyst设备检测xcrun simctl list devices模拟器、xcrun devicectl list devices真机——经 AppleDev.Tools 封装截图xcrun simctl io booted screenshot file模拟器iOS 真机未来日志xcrun simctl spawn booted log stream或 Console.app模拟器、mlaunch --logdev真机。安全与隐私CLI 仅面向开发与调试场景设计上有三重约束仅调试构建功能应在Release构建中通过 trimmer 特性标志或#if DEBUG条件禁用复用现有基础设施优先复用调试器、Hot Reload 等既有传输机制不创建新的通信通道不暴露给生产环境除使用操作系统标准能力如截图、日志外CLI 不应能作用于生产应用。IDE 集成mauiCLI 及其底层库被设计为 IDE 扩展的共享后端消除各工具间重复的环境检测与设置逻辑。架构┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ VS Code ext │ │ Visual Studio │ │ AI Agent │ │ (vscode-maui) │ │ extension │ │ (Copilot, etc.) │ └────────┬─────────┘ └────────┬──────────┘ └────────┬─────────┘ │ │ │ spawns CLI references NuGet spawns CLI │ library directly │ │ │ │ ▼ ▼ ▼ ┌──────────────┐ ┌────────────────────┐ ┌──────────────┐ │ maui CLI │ │ android-tools │ │ maui CLI │ │ (process) │ │ (in-process) │ │ (--json) │ └──────┬───────┘ └────────┬───────────┘ └──────┬───────┘ │ │ │ └─────────┬───────────┴───────────────────────┘ │ spawns native tools ┌───────────┼───────────┐ ▼ ▼ ▼ ┌───────────┐ ┌──────────┐ ┌──────────┐ │ adb │ │ xcrun │ │ Windows │ │ sdkmanager│ │ simctl │ │ SDK │ └───────────┘ └──────────┘ └──────────┘集成模式消费方集成方式理由Visual Studio扩展直接引用android-toolsNuGet 包进程内.NET 扩展——无序列化开销直接 API 访问VS Codevscode-maui派生mauiCLI 进程解析--jsonstdoutTypeScript 扩展——CLI 是自然的进程边界AI Agent / CI以--json调用mauiCLI基于进程、语言无关终端人类直接调用mauiCLI默认人类可读输出需要时用--jsonVisual Studio 直接消费dotnet/android-tools中的Xamarin.Android.Tools.AndroidSdkNuGet 包——与 CLI 内部用的是同一个库既避免了进程开销又给 VS 扩展完整的 API 访问权非 .NET 消费方VS Code、AI Agent、CI则以 CLI 为规范接口。IDE 如何使用工作流CLI 命令IDE 行为工作区打开maui apple check --json、maui android jdk check --json在状态栏 / 问题面板显示环境状态环境修复maui android install --json显示进度条流式处理type: progress消息设备选择器maui device list --json填充设备下拉框 / 选择 UI仿真器启动maui android emulator start name --json显示通知完成后更新设备列表收益行为一致——VS、VS Code、CLI 通过共享库使用同一套检测与设置逻辑单一维护点——android-tools的缺陷修复自动传播到所有消费方AI 就绪——Agent 消费与 VS Code 相同的--json输出集成灵活——.NET 消费方进程内集成其余走 CLI。当前状态集成状态VS Code 扩展vscode-maui✅ 进行中Visual Studio 扩展规划中vNextGitHub Copilot / AI Agent✅ 通过--json输出支持未来目标MCP Server 的取舍CLI 设计过程中曾考虑提供 MCPModel Context Protocol服务器但最终结论是先做 CLI。AI Agent 可以通过copilot-instructions.md中的示例直接使用 CLI 命令无需自定义 MCP 服务器。若 CLI 完成后确实证明 MCP 服务器有价值届时再以薄封装形式把 CLI 操作暴露为 MCP 协议——Visual Studio 与 VS Code 扩展都提供分发 MCP 服务器的选项大概率会通过 .NET MAUI 工具链实现。更多子命令环境设置命令Android SDK/JDK、Xcode、仿真器、模拟器灵感来自既有社区项目.NET MAUI Check / Doctor 类工具如dotnet-maui-check、maui-cliAndroid SDK 管理工具如AndroidSdk.Tools。规划中的命令maui logs查看控制台输出、maui tree显示可视树、maui screenshot捕获截图。决策环境设置与设备列表先发布应用检查命令在后续版本跟进。总结mauiCLI 的设计体现了清晰的取舍委托原生工具链保证能力与生态兼容--json机器优先输出让 AI Agent 与 CI 成为一等公民复用共享库让 Visual Studio、VS Code 与 CLI 保持行为一致且单一维护。它不以替代dotnet run为目标而是补齐后者在无项目场景下的设备发现与运行中应用的检查能力。对本文档与设计细节感兴趣的读者可进一步阅读仓库中的 docs/design/cli.md 原文并在 eng/pipelines/common/provision.yml 中看到它在真实 CI 流水线中的落地用法。【免费下载链接】maui.NET MAUI is the .NET Multi-platform App UI, a framework for building native device applications spanning mobile, tablet, and desktop.项目地址: https://gitcode.com/GitHub_Trending/ma/maui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考