Conversation
|
@copilot why can t you review these files? |
- Add MauiDevice JSON schema with all fields (platforms[], idiom, runtime_identifiers, etc.) - Add SdkPackage JSON schema with is_installed flag - Update sdk list command: --available and --all flags (replaces list-available) - Update avd commands: stop, delete; --package optional with auto-detection - Update bootstrap: --packages flag for comma-separated package list - Add progress reporting documentation with JSON format - Add shell quoting implementation notes for semicolon handling - Update jdk commands: check, list (consistent naming) - Bump version to 2.7-draft
## Summary Syncs the DevTools spec with the current CLI implementation on `maui-client-tool` branch. ### What changed **New commands documented:** - `apple xcode list` — List installed Xcode versions with version, build number, selected status - `apple xcode select <path>` — Switch active Xcode installation - `android sdk accept-licenses` — Accept SDK licenses - `android avd stop/delete` — Stop and delete AVDs - `android bootstrap/jdk` commands in capabilities model **Schema updates:** - `MauiDevice`: Added `type`, `state`, `details` fields - `MauiDevice`: Documented Android-specific field semantics (identifier = AVD name for emulators, version = API level, version_name = OS version without prefix, platform_architecture = raw ABI) - New `XcodeInstallation` schema (path, developer_dir, version, build, is_selected) **Spec corrections to match implementation:** - `doctor --platform` → `doctor --category` (matching actual CLI flag) - Simulator boot/shutdown/delete use positional `<udid>` not `--udid` option - Global options: marked `--non-interactive`, `--correlation-id`, `--offline` as vNext (not yet implemented) - FR-X13/X14: Updated from vague 'handle multiple Xcode versions' to specific `xcode list`/`xcode select` commands (P0) **MVP tracking:** - Added status column to MVP table showing which features are implemented - Moved `deploy`, `config`, `diagnostic-bundle`, `telemetry` to vNext (not yet implemented) Version bumped to 2.8-draft.
| │ └── logs # Stream logs from device (unified across platforms) | ||
| │ ├── --device <id> # Device identifier (required) | ||
| │ ├── --filter <expr> # Filter expression (platform-specific) | ||
| │ ├── --maui-only # Filter to MAUI-related logs only | ||
| │ └── --since <time> # Show logs since timestamp |
There was a problem hiding this comment.
dotnet run shows live logs now, I would drop this for now.
There was a problem hiding this comment.
what if i want logs without using dotnet run, like the app is installed and i have the simulator running, and i want to just the device logs to look what happens when i open my app or other app.
There was a problem hiding this comment.
right now, VS and VSCOde have this feature of getting device logs, we want to combine this.
Is there other way to get the logs using the android workload without dotnet run? is there a target for that ?
There was a problem hiding this comment.
I think there are two different things:
- Get the output (stdout/stderr) from the app. This is what
dotnet runshows. - Get the device log (on iOS this is stdout/stderr/NSLog from any app). This is what the IDE shows, and IMHO this is also valuable, so I'd keep it.
| │ │ ├── --platform # Filter by platform | ||
| │ │ └── --json # Output as JSON | ||
| │ ├── screenshot # Capture screenshot | ||
| │ │ ├── --device <id> # Target device |
There was a problem hiding this comment.
One note on what I imagined for this:
- Some amount of code is shared with dotnet/sdk -- the target framework and device selection, which uses in-memory MSBuild APIs
- If you have a
.csprojin the current directory, it calls the same workflow asdotnet runfor selecting a framework and device.
It would be cool to mention this in here, if you left --device blank, as the default behavior.
There was a problem hiding this comment.
can this be shared on android-tools ?
There was a problem hiding this comment.
Do you mean shared with dotnet/sdk? That is where the code is today.
I don't think they'll want the dotnet/sdk to start using dotnet/android-tools.
Per PR #33865 feedback: - Rename 'android bootstrap' to 'android install' throughout spec - Remove deploy command (covered by 'dotnet run'/'dotnet build -t:Install') - Remove config command (not needed for MVP) - Remove diagnostic-bundle section (deferred to vNext) - Remove telemetry section (deferred to vNext) - Rename §9 from 'Telemetry & Diagnostics' to 'Diagnostics' - Remove APK install and logcat from command tree (covered by 'dotnet run') - Clean up vNext list
Per PR #33865 feedback: - Rename 'android bootstrap' to 'android install' throughout spec - Remove deploy command (covered by 'dotnet run'/'dotnet build -t:Install') - Remove config command (not needed for MVP) - Remove diagnostic-bundle section (deferred to vNext) - Remove telemetry section (deferred to vNext) - Rename §9 from 'Telemetry & Diagnostics' to 'Diagnostics' - Remove APK install and logcat from command tree (covered by 'dotnet run') - Clean up vNext list
Per PR #33865 feedback from @jonathanpeppers: - Rename 'android bootstrap' to 'android install' (analogous to 'dotnet workload install') - Remove 'deploy' command (covered by 'dotnet run' and 'dotnet build -t:Install') - Update all user-facing strings, method names, and tests
…; doctor --platform; emulator stop by name
| | `maui apple xcode select` | — | ✓ | Yes (sudo) | `environment.modify` | | ||
| | `maui apple xcode accept-licenses` | — | ✓ | Yes (sudo) | `environment.modify` | | ||
|
|
||
| *OS Elevation required for: installing Android SDK/JDK to system locations (e.g., `Program Files`), installing Xcode runtimes, switching Xcode, accepting Xcode licenses |
There was a problem hiding this comment.
The table shows "Sometimes*" for OS Elevation on several install operations, with a footnote explaining it's required when installing to system locations. However, the footnote doesn't mention that on macOS, installing to user home directories (the default paths shown in the table at lines 252-256) does NOT require elevation. The current wording "installing Android SDK/JDK to system locations" could be misinterpreted. Consider clarifying the footnote to explicitly state: "Required only when installing to system-protected paths (e.g., Program Files on Windows, /opt on macOS). Default user-home installations do not require elevation."
| *OS Elevation required for: installing Android SDK/JDK to system locations (e.g., `Program Files`), installing Xcode runtimes, switching Xcode, accepting Xcode licenses | |
| *OS Elevation required only when installing to system-protected paths (e.g., `Program Files` on Windows, `/opt` on macOS) or performing privileged Apple operations (installing Xcode runtimes, switching Xcode, accepting Xcode licenses). Default user-home installations of the Android SDK/JDK do not require elevation. |
| **"Ask Copilot for Help" Flow**: | ||
|
|
||
| 1. User clicks button or types `/maui-help` in Copilot Chat | ||
| 2. Extension sends diagnostic context to Copilot | ||
| 3. Copilot receives structured data + conversation prompt: | ||
|
|
||
| ``` | ||
| The MAUI Dev Tools detected an issue it couldn't fix automatically. | ||
|
|
||
| **Issue**: Android SDK installation failed (E4001 - Connection reset) | ||
| **Environment**: macOS 15.0, corporate network with proxy | ||
| **Attempted**: 3 download retries, cache clear | ||
|
|
||
| The diagnostic bundle is attached. Please help the user resolve this issue. | ||
| Common causes for this error include proxy configuration, firewall rules, | ||
| or SSL inspection. Ask clarifying questions if needed. | ||
| ``` | ||
|
|
||
| 4. Copilot engages in conversational troubleshooting | ||
| 5. Copilot can suggest manual steps or request tool actions with user approval | ||
|
|
There was a problem hiding this comment.
The "Ask Copilot for Help" flow shows a diagnostic context being sent to Copilot with the issue details, but there's no corresponding security or privacy consideration mentioned. The main spec document has section 5.5 on Privacy (NFR-PR1, NFR-PR2, NFR-PR3) requiring PII redaction and file path sanitization. This IDE integration flow should reference those requirements or explicitly state that diagnostic context sent to Copilot must follow the redaction rules defined in the main spec section 5.5 and 9.1.
| - Integrates with Visual Studio's environment detection UI | ||
| - Surfaces issues in Error List window | ||
| - Provides menu items in Tools > MAUI submenu | ||
| - Can consume the Android/iOS provider packages directly (as a library) or invoke the `maui` CLI -- either way, the business logic is shared. This avoids duplicating environment detection and fix logic between VS and the CLI. |
There was a problem hiding this comment.
The Visual Studio Extension section states that it "Can consume the Android/iOS provider packages directly (as a library) or invoke the maui CLI". However, this dual-mode approach isn't reflected in the main spec's architecture section 6.2 or the Platform Providers description at line 616. If the providers are designed to be consumable as libraries (not just CLI wrappers), this should be documented in the main spec architecture section, including any API surface area, versioning strategy, and compatibility guarantees for library consumers.
| - Can consume the Android/iOS provider packages directly (as a library) or invoke the `maui` CLI -- either way, the business logic is shared. This avoids duplicating environment detection and fix logic between VS and the CLI. | |
| - Invokes the `maui` CLI for environment detection and fixes; the CLI, in turn, uses the shared Android/iOS platform provider packages defined in the main MAUI Dev Tools specification. This ensures Visual Studio and the CLI share the same environment detection and fix logic without duplication. |
|
|
||
| | Capability | Source in `android-platform-support` | Benefit | | ||
| |-----------|--------------------------------------|---------| | ||
| | **JDK installation** | `JavaDependencyInstaller` | IDEs, build tasks, and DevTools can auto-install missing JDKs instead of just reporting errors. | | ||
| | **SDK bootstrap & management** | `AndroidSDKInstaller` | Shared API for downloading command-line tools and managing SDK packages — used by DevTools CLI, IDE extensions, and CI. | | ||
| | **License acceptance** | `AndroidLicensesStorage` | Unattended CI scenarios across all .NET Android tooling. | | ||
|
|
There was a problem hiding this comment.
The PR description references issues #273, #271, and #272 in the context of contributing to dotnet/android-tools. However, the mentioned issues in the PR metadata are actually unrelated old MAUI repository issues about web support, README formatting, and screenshots. The PR description table shows these as android-tools issue numbers but they don't match. Consider verifying these issue numbers and updating the table to link to the correct dotnet/android-tools issues, or removing the issue references if those issues haven't been created yet.
| # With specific packages (comma-separated) | ||
| maui android install --packages "platform-tools,build-tools;35.0.0,platforms;android-35" |
There was a problem hiding this comment.
The example shows --packages flag but inconsistently describes the package parameter. Line 276 shows the flag with comma-separated packages in quotes, but this conflicts with the command description at line 943 which shows --packages <list> as a single argument. The shell quoting section (lines 423-430) emphasizes avoiding shell interpretation, but this example requires shell interpretation of the comma separator. Consider clarifying whether packages should be space-separated (passed as multiple arguments) or comma-separated (single argument requiring parsing).
| # With specific packages (comma-separated) | |
| maui android install --packages "platform-tools,build-tools;35.0.0,platforms;android-35" | |
| # With specific packages (space-separated list) | |
| maui android install --packages platform-tools "build-tools;35.0.0" "platforms;android-35" |
| #### Error Code Registry (Partial) | ||
|
|
||
| | Code | Category | Message | Remediation Type | | ||
| |------|----------|---------|------------------| | ||
| | `E1001` | tool | Internal error | terminal | | ||
| | `E2001` | platform | SDK licenses not accepted | auto_fixable | | ||
| | `E2002` | platform | sdkmanager not found | auto_fixable (install) | | ||
| | `E2003` | platform | xcrun failed | user_action | | ||
| | `E2004` | platform | Emulator acceleration unavailable | user_action | | ||
| | `E3001` | user | Xcode not installed | user_action | | ||
| | `E3002` | user | Developer Mode not enabled | user_action | | ||
| | `E3003` | user | Insufficient disk space | user_action | | ||
| | `E3004` | user | Network unavailable | user_action | | ||
|
|
There was a problem hiding this comment.
The error category definition includes 'unknown' with prefix E0xxx, but the Error Code Registry table only shows E0000. Consider adding at least one or two more example codes in the E0xxx range to illustrate different types of unknown errors (e.g., E0001 for truncated output, E0002 for unrecognized error patterns) to help implementers understand the category better.
| - When calling `avdmanager` or `sdkmanager`, arguments with semicolons **SHOULD** be passed directly to the child process as an argument list (not via a shell) so that semicolons are not interpreted as command separators. | ||
| - If shell invocation is unavoidable, quoting **MUST** be documented per shell: | ||
| - POSIX shells (`bash`, `zsh`): `--package 'system-images;android-35;google_apis;arm64-v8a'` | ||
| - Windows `cmd.exe`: `--package "system-images;android-35;google_apis;arm64-v8a"` | ||
| - PowerShell: `--package 'system-images;android-35;google_apis;arm64-v8a'` | ||
| - Correct quoting prevents shell interpretation of semicolons as command separators. |
There was a problem hiding this comment.
The shell quoting section states that package identifiers "SHOULD" be passed directly as an argument list to avoid shell interpretation. However, this conflicts with the design principle of using native tools. When calling avdmanager or sdkmanager, these are typically shell scripts (.bat on Windows, shell scripts on Unix), not native executables, which means shell invocation may be unavoidable. Consider strengthening this to "MUST pass as argument list when using ProcessStartInfo" and providing specific guidance for cases where shell invocation is truly unavoidable.
| - When calling `avdmanager` or `sdkmanager`, arguments with semicolons **SHOULD** be passed directly to the child process as an argument list (not via a shell) so that semicolons are not interpreted as command separators. | |
| - If shell invocation is unavoidable, quoting **MUST** be documented per shell: | |
| - POSIX shells (`bash`, `zsh`): `--package 'system-images;android-35;google_apis;arm64-v8a'` | |
| - Windows `cmd.exe`: `--package "system-images;android-35;google_apis;arm64-v8a"` | |
| - PowerShell: `--package 'system-images;android-35;google_apis;arm64-v8a'` | |
| - Correct quoting prevents shell interpretation of semicolons as command separators. | |
| - When calling `avdmanager` or `sdkmanager` via `ProcessStartInfo` (or an equivalent API), arguments with semicolons **MUST** be passed directly to the child process as an argument list (not via an intermediate shell) so that semicolons are not interpreted as command separators. | |
| - If shell invocation is truly unavoidable (for example, due to platform behavior when invoking `.bat` or shell wrapper scripts where a shell cannot be bypassed), quoting **MUST** be documented per shell: | |
| - POSIX shells (`bash`, `zsh`): `--package 'system-images;android-35;google_apis;arm64-v8a'` | |
| - Windows `cmd.exe`: `--package "system-images;android-35;google_apis;arm64-v8a"` | |
| - PowerShell: `--package 'system-images;android-35;google_apis;arm64-v8a'` | |
| - Correct quoting prevents shell interpretation of semicolons as command separators in those unavoidable shell cases. |
| | `doctor --fix` | ✓ | ✓ | Sometimes* | `environment.modify` | | ||
| | `maui device list` | ✓ | ✓ | No | None | | ||
| | `maui device screenshot` | ✓ | ✓ | No | `device.capture` | | ||
| | `maui device logs` | ✓ | ✓ | No | `device.logs` | |
There was a problem hiding this comment.
The Capabilities Model table shows that maui device logs requires the device.logs AI Agent Permission with "Prompt" as default. However, the command hierarchy at line 934 and the functional requirement FR-A10 at line 156 don't mention any security sensitivity for log streaming. Device logs can contain sensitive user data, PII, and security tokens, so this permission gate is appropriate. Consider adding a note in the Functional Requirements section (FR-A10 or FR-X10) that log streaming requires user consent when invoked by AI agents due to potential sensitive data exposure.
| │ ├── stop # Stop emulator | ||
| │ │ └── <name> # Emulator name |
There was a problem hiding this comment.
The command description shows <name> as a positional argument, but the table at line 1114 and the command hierarchy at line 972 show it should be an emulator name. However, the error at line 971 says "Stop emulator" with <name> which is inconsistent with how physical devices are stopped (they use device serials). The doc should clarify whether this stops by emulator name (AVD name) or by adb serial when the emulator is running.
| │ ├── stop # Stop emulator | |
| │ │ └── <name> # Emulator name | |
| │ ├── stop # Stop emulator by name (AVD) | |
| │ │ └── --name # Emulator name (AVD) |
| | `version` | string? | API level for Android (e.g., `"35"`), OS version for iOS (e.g., `"18.5"`) | | ||
| | `version_name` | string? | OS version number without platform prefix (e.g., `"15.0"` not `"Android 15.0"`) | |
There was a problem hiding this comment.
The MauiDevice schema field version_name is described as "OS version number without platform prefix (e.g., '15.0' not 'Android 15.0')", but the example at line 1144 shows "version_name": "18.5" for iOS which matches version at line 1143. This suggests version_name might be redundant. The Android-specific semantics table at lines 1186-1192 clarifies that version_name comes from ro.build.version.release, but for iOS the distinction between version and version_name is unclear. Consider clarifying the purpose of both fields or merging them if they're always identical for iOS.
| | `version` | string? | API level for Android (e.g., `"35"`), OS version for iOS (e.g., `"18.5"`) | | |
| | `version_name` | string? | OS version number without platform prefix (e.g., `"15.0"` not `"Android 15.0"`) | | |
| | `version` | string? | API level for Android (e.g., `"35"`), OS version for iOS/macOS (e.g., `"18.5"`) | | |
| | `version_name` | string? | Human-readable OS version string. On Android this is `ro.build.version.release` (e.g., `"15.0"`) and may differ from `version` (API level); on iOS/macOS it currently matches `version`. | |
Adds a focused command reference for the maui CLI covering Android, Apple/iOS commands, and --version. References PR #33865 for the full specification (architecture, error contracts, IDE integration, schemas). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…CLI) Adopts the same interactivity pattern as dotnet/sdk: --interactive defaults to true for terminals, false when CI env vars are detected (TF_BUILD, GITHUB_ACTIONS, CI, etc.) or Console.IsOutputRedirected. References dotnet/sdk CommonOptions.CreateInteractiveOption implementation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Aligns platform filter values with .NET MAUI TFMs across doctor, device list, and all --platform references. Adds platform values reference table with host availability. Removes 'dotnet' and 'apple' as platform values in favor of the TFM-aligned names. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Xcode can't be installed programmatically; 'install' was misleading - 'apple check' verifies Xcode, runtimes, and environment status - Singular 'accept-license' matches xcodebuild -license accept - Android SDK keeps plural 'accept-licenses' (multiple SDK licenses) - Updated command tree, usage examples, command table, permissions Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- apple install: optionally accepts Xcode license and installs runtimes - apple check: read-only environment status (no modifications) - Could prompt user to install Xcode in the future - Singular accept-license for Apple (matches xcodebuild -license accept) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Extends docs/design/cli.md with environment setup commands for Android (SDK/JDK/emulator) and Apple (Xcode/simulator/runtime), global options (--json, --interactive, --dry-run), platform filter values, and implementation references to dotnet/android-tools. Full specification: PR #33865 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Extends docs/design/cli.md with environment setup commands for Android (SDK/JDK/emulator) and Apple (Xcode/simulator/runtime), global options (--json, --interactive, --dry-run), platform filter values, and implementation references to dotnet/android-tools. Full specification: PR #33865 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Extends docs/design/cli.md with environment setup commands for Android (SDK/JDK/emulator) and Apple (Xcode/simulator/runtime), global options (--json, --interactive, --dry-run), platform filter values, and implementation references to dotnet/android-tools. Full specification: PR #33865 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Extends docs/design/cli.md with environment setup commands for Android (SDK/JDK/emulator) and Apple (Xcode/simulator/runtime), global options (--json, --interactive, --dry-run), platform filter values, and implementation references to dotnet/android-tools. Full specification: PR #33865 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Extends docs/design/cli.md with environment setup commands for Android (SDK/JDK/emulator) and Apple (Xcode/simulator/runtime), global options (--json, --interactive, --dry-run), platform filter values, and implementation references to dotnet/android-tools. Full specification: PR #33865 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Extends docs/design/cli.md with environment setup commands for Android (SDK/JDK/emulator) and Apple (Xcode/simulator/runtime), global options (--json, --interactive, --dry-run), platform filter values, and implementation references to dotnet/android-tools. Full specification: PR #33865 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Extends docs/design/cli.md with environment setup commands for Android (SDK/JDK/emulator) and Apple (Xcode/simulator/runtime), global options (--json, --interactive, --dry-run), platform filter values, and implementation references to dotnet/android-tools. Full specification: PR #33865 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Extends docs/design/cli.md with environment setup commands for Android (SDK/JDK/emulator) and Apple (Xcode/simulator/runtime), global options (--json, --interactive, --dry-run), platform filter values, and implementation references to dotnet/android-tools. Full specification: PR #33865 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
> [!NOTE] > Are you waiting for the changes in this PR to be merged? > It would be very helpful if you could [test the resulting artifacts](https://github.com/dotnet/maui/wiki/Testing-PR-Builds) from this PR and let us know in a comment if this change resolves your issue. Thank you! ## Summary Adds a concise command reference for the `maui` CLI — focused on **Android**, **Apple/iOS**, and `--version`. This is a quick-review companion to the full specification in [PR #33865](#33865). ### What this covers - `maui --version` - All `maui android` subcommands (install, jdk, sdk, emulator) - All `maui apple` subcommands (install, check, xcode, simulator, runtime) - Global options (`--json`, `--verbose`, `--interactive`, `--dry-run`) ### Key design points - **Delegate to native toolchains** — wraps `sdkmanager`, `adb`, `xcrun simctl`, etc. - **Reuse shared libraries** — leverages [`dotnet/android-tools`](https://github.com/dotnet/android-tools) for SDK/JDK discovery and installation - **Machine-first output** — every command supports `--json` - **Interactive detection** — follows `dotnet` CLI pattern (auto-detects CI via env vars, checks `Console.IsOutputRedirected`) ### What this intentionally omits - Device listing (covered by `dotnet run --list-devices`) - Install path defaults (handled by `dotnet/android-tools`) - Windows commands (see full spec) - Architecture, error contracts, JSON schemas, IDE integration, elevation model All omitted details are in the [full specification (PR #33865)](#33865). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Move device list, screenshot, logs to vNext - Update IDE integration: VS consumes android-tools NuGet directly - Remove runtime list --available (can't enumerate downloadable runtimes) - Replace maui doctor --json IDE reference with specific check commands Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 33865Or
iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 33865" |
> [!NOTE] > Are you waiting for the changes in this PR to be merged? > It would be very helpful if you could [test the resulting artifacts](https://github.com/dotnet/maui/wiki/Testing-PR-Builds) from this PR and let us know in a comment if this change resolves your issue. Thank you! ## Summary Adds a concise command reference for the `maui` CLI — focused on **Android**, **Apple/iOS**, and `--version`. This is a quick-review companion to the full specification in [PR #33865](#33865). ### What this covers - `maui --version` - All `maui android` subcommands (install, jdk, sdk, emulator) - All `maui apple` subcommands (install, check, xcode, simulator, runtime) - Global options (`--json`, `--verbose`, `--interactive`, `--dry-run`) ### Key design points - **Delegate to native toolchains** — wraps `sdkmanager`, `adb`, `xcrun simctl`, etc. - **Reuse shared libraries** — leverages [`dotnet/android-tools`](https://github.com/dotnet/android-tools) for SDK/JDK discovery and installation - **Machine-first output** — every command supports `--json` - **Interactive detection** — follows `dotnet` CLI pattern (auto-detects CI via env vars, checks `Console.IsOutputRedirected`) ### What this intentionally omits - Device listing (covered by `dotnet run --list-devices`) - Install path defaults (handled by `dotnet/android-tools`) - Windows commands (see full spec) - Architecture, error contracts, JSON schemas, IDE integration, elevation model All omitted details are in the [full specification (PR #33865)](#33865). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
New reference article for the maui CLI tool introduced in .NET 11: - maui doctor: environment health checks and auto-fix - maui android install: JDK, SDK, and emulator setup - maui apple install: Xcode, licenses, and iOS runtime management - Structured --json output for CI/CD and AI agent integration Upstream: dotnet/maui#34217, spec PR dotnet/maui#33865 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Per PR #33865 feedback from @jonathanpeppers: - Rename 'android bootstrap' to 'android install' (analogous to 'dotnet workload install') - Remove 'deploy' command (covered by 'dotnet run' and 'dotnet build -t:Install') - Update all user-facing strings, method names, and tests
|
|
Per PR #33865 feedback from @jonathanpeppers: - Rename 'android bootstrap' to 'android install' (analogous to 'dotnet workload install') - Remove 'deploy' command (covered by 'dotnet run' and 'dotnet build -t:Install') - Update all user-facing strings, method names, and tests
<!-- Please let the below note in for people that find this PR --> > [!NOTE] > Are you waiting for the changes in this PR to be merged? > It would be very helpful if you could [test the resulting artifacts](https://github.com/dotnet/maui/wiki/Testing-PR-Builds) from this PR and let us know in a comment if this change resolves your issue. Thank you! ## Summary Adds the `maui device list` command specification to the existing CLI design document (`docs/design/cli.md`). This command provides unified, cross-platform device enumeration without requiring a project context. See [PR #33865](#33865) for the full DevTools spec. ## What is added ### Command: `maui device list [--platform <p>] [--json]` Lists connected devices, running emulators, and available simulators across all platforms in a single call. ### Two approaches analysis The spec analyzes two discovery approaches and recommends the project-free one: | | MSBuild (`dotnet run --list-devices`) | Native CLI (`maui device list`) | |---|---|---| | Project required | Yes | **No** | | Cross-platform | One TFM at a time | All platforms at once | | Speed | Slower (MSBuild eval) | Fast (<2s) | | ID compatibility | Source of truth | Same native IDs | ### Scenarios requiring project-free discovery 1. AI agent bootstrapping (no `.csproj` yet) 2. IDE startup (device picker before project loads) 3. Environment validation ("can I see my phone?") 4. CI pipeline setup (check emulator before build) 5. Multi-project solutions (unified view) 6. Cross-platform overview (all devices at once) ### Recommended approach `maui device list` uses direct native tool invocation (`adb devices`, `simctl list`, `devicectl list`). Device IDs are compatible with `dotnet run --device`, making them complementary: ``` maui device list → "What devices exist on this machine?" dotnet run --list-devices → "What devices can run this project?" ``` ### Other changes - Added references to `ComputeAvailableDevices` MSBuild targets in [dotnet/android](https://github.com/dotnet/android) and [dotnet/macios](https://github.com/dotnet/macios) - Updated AI agent workflow example to include device discovery step - Fixed AppleDev.Tools reference (xcdevice → devicectl) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Note
Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!
MAUI Dev Tools Client -- Product Specification
This PR adds the product specification for
maui-- a unified CLI tool for environment setup, device management, and AI agent integration across all MAUI platforms.Problem
Setting up a MAUI development environment is one of the biggest friction points:
sdkmanager,avdmanager,xcrun simctl,xcode-select) with different UX patternsSolution:
mauiCLIA new CLI tool that provides environment health checks, automated fixes, and device management -- designed for three consumers in priority order: AI Agents > CI/CD > Humans.
Design Principles
sdkmanager,xcrun simctl, etc. No custom download/install logicdotnet/android-toolsfor SDK/JDK discovery. Moves proven code fromandroid-platform-support(internal) to the publicandroid-toolspackage.--jsonwith stable schema;--dry-run,--cifor automationCommand Surface
Cross-Platform
maui doctormaui doctor --fixmaui doctor --platform <p>maui device listmaui device list --platform <p>maui device screenshot --device <id>maui device logs --device <id>maui --versionAndroid
maui android installmaui android install --accept-licensesmaui android install --packages <list>maui android jdk checkmaui android jdk installmaui android jdk listmaui android sdk listmaui android sdk list --availablemaui android sdk install <packages>maui android sdk accept-licensesmaui android sdk uninstall <package>maui android emulator listmaui android emulator create <name>maui android emulator start <name>maui android emulator stop <name>maui android emulator delete <name>Apple (macOS only)
maui apple installmaui apple install --accept-licensesmaui apple install --runtime <version>maui apple simulator listmaui apple simulator create <name> <type> <runtime>maui apple simulator start <id>maui apple simulator stop <id>maui apple simulator delete <id>maui apple runtime checkmaui apple runtime listmaui apple runtime list --availablemaui apple runtime list --allmaui apple runtime install <version>maui apple xcode checkmaui apple xcode listmaui apple xcode select <path>maui apple xcode accept-licensesWindows (Windows only)
maui windows sdk listmaui windows developer-mode statusmaui windows developer-mode enableGlobal Options
All commands support:
--json,--verbose,--ci,--dry-runKey Features
maui android install --accept-licensesinstalls JDK 17, Android SDK, and recommended packagesmaui apple install --accept-licenses --runtime 18.5verifies Xcode, accepts license, installs runtimeGoals
Shared Libraries & Code Reuse
DevTools reuses existing Android tooling rather than building from scratch:
Xamarin.Android.Tools.AndroidSdkdotnet/android-tools(public NuGet)Contributing to
dotnet/android-toolsAs part of this work, we are moving proven implementations from
android-platform-support(internal) into the publicdotnet/android-toolspackage. This benefits both themauiCLI and the broader .NET Android toolchain -- any tool or IDE that referencesXamarin.Android.Tools.AndroidSdkgets these capabilities for free.sdkmanagerfor package operationsNo hardcoded download URLs -- all SDK/JDK URLs and SHA-1 checksums come from the Xamarin Android Manifest Feed and Google's repository. Every download is checksum-verified before installation.
Spec Documents
maui-devtools-spec.mdmaui-devtools-ide-integration.mdMVP Status
Most P0 features are implemented. VS Code extension integration is in progress. See Section 10 of the main spec for the full MVP vs vNext breakdown.