Add EmulatorRunner for emulator CLI operations

[rmarinho]

EmulatorRunner: High-level emulator lifecycle management

Adds EmulatorRunner — a managed wrapper over the Android SDK emulator CLI binary, following the same pattern as AdbRunner and AvdManagerRunner.

API Surface

Method	Description
LaunchEmulator(avdName, options?)	Fire-and-forget: starts an emulator process and returns the Process handle. Caller owns the process lifetime. Validates avdName is non-empty.
BootEmulatorAsync(avdName, adb, options?, token?)	Full lifecycle: checks if device is already online → checks if emulator process is running → launches emulator → polls adb devices until boot completes or timeout. Returns EmulatorBootResult with status and serial. Disposes Process handle on success (emulator keeps running).
ListAvdNamesAsync(token?)	Lists available AVD names via emulator -list-avds. Checks exit code for failures.

Key Design Decisions

• Naming: LaunchEmulator (fire-and-forget) vs BootEmulatorAsync (full lifecycle) — clear verb distinction matching the emulator domain
• Kept EmulatorRunner name (not AvdRunner) — follows convention of naming runners after their CLI binary (emulator → EmulatorRunner, adb → AdbRunner)
• Process handle management: LaunchEmulator returns Process (caller-owned); BootEmulatorAsync disposes handle on success (emulator keeps running as detached process), kills+disposes on failure/timeout
• Pipe draining: LaunchEmulator calls BeginOutputReadLine()/BeginErrorReadLine() after Start() to prevent OS pipe buffer deadlock
• TryKillProcess: Instance method, uses typed catch (Exception ex) with logger for diagnostics, uses Kill(entireProcessTree: true) on .NET 5+

AdbRunner Enhancements (in this PR)

• Added optional Action? logger parameter to constructor
• RunShellCommandAsync(serial, command, ct) — single-string shell command (⚠️ device shell interprets it — documented in XML doc)
• RunShellCommandAsync(serial, command, args, ct) — NEW: structured overload that passes args as separate tokens, bypassing device shell interpretation via exec(). Safer for dynamic input.
• GetShellPropertyAsync returns first non-empty line (for getprop queries)
• Shell methods log stderr via logger on non-zero exit codes
• Fixed RS0026/RS0027: only the most-params overload has optional CancellationToken
• AVD name detection fix: GetEmulatorAvdNameAsync now falls back to adb shell getprop ro.boot.qemu.avd_name when adb emu avd name returns empty (observed returning empty on some adb/emulator v36 combinations)

Models

• EmulatorBootOptions — configurable timeout (default 120s), poll interval (default 2s), cold boot, extra args (IEnumerable?)
• EmulatorBootResult — immutable record with init-only properties: Status (enum), Serial, Message. Statuses: Success, AlreadyRunning, Timeout, Error

Bug Fix: AVD Name Detection on Emulator v36+

The adb emu avd name console command can return empty output on some adb/emulator version combinations (observed with adb v36). This caused BootEmulatorAsync to never match the running emulator by AVD name, resulting in a perpetual polling loop and eventual timeout.

Root cause: GetEmulatorAvdNameAsync relied solely on adb -s <serial> emu avd name. On some adb/emulator version combinations this command silently returns empty output (exit code 0, no content). The exact cause is unclear but the getprop fallback provides reliable AVD name resolution regardless.

Fix: Added fallback to adb shell getprop ro.boot.qemu.avd_name, which reads the boot property set by the emulator kernel. This property is always available via the standard adb shell interface and does not depend on the emulator console protocol.

Verified: BootEmulatorAsync now completes in ~3s (was timing out at 120s) on emulator v36.4.9 with API 36 image.

Consumer PR

• dotnet/android #10949 — replaces BootAndroidEmulator MSBuild task (~454 lines) with a ~180-line wrapper delegating to EmulatorRunner.BootEmulatorAsync()

Tests (24 EmulatorRunner + 9 AdbRunner = 33 total)

EmulatorRunner (24):

• Parse emulator -list-avds output (empty, single, multiple, blank lines, Windows newlines) — 4 tests
• Constructor validation (null/empty/whitespace tool path) — 3 tests
• LaunchEmulator argument validation (null, empty, whitespace AVD name) — 3 tests
• BootEmulatorAsync lifecycle: already online device, already running AVD, successful boot after polling, timeout, launch failure, cancellation token — 6 tests
• BootEmulatorAsync validation: invalid timeout, invalid poll interval, null AdbRunner, empty device name — 4 tests
• Ported from dotnet/android BootAndroidEmulatorTests: physical device passthrough, AdditionalArgs forwarding, ColdBoot flag, cancellation abort — 4 tests

AdbRunner (9):

• FirstNonEmptyLine parsing (null, empty, whitespace, single value, multiline, mixed) — 9 tests

Review Feedback Addressed

• ✅ LaunchEmulator validates avdName parameter (throws ArgumentException)
• ✅ LaunchEmulator drains stdout/stderr pipes via BeginOutputReadLine()/BeginErrorReadLine()
• ✅ RunShellCommandAsync returns full stdout (not just first line)
• ✅ Added structured RunShellCommandAsync overload (no shell interpretation)
• ✅ Added 12 new unit tests (LaunchEmulator validation + FirstNonEmptyLine parsing)
• ✅ Shell methods log stderr via logger on failure
• ✅ Removed TOCTOU HasExited guard from TryKillProcess
• ✅ Process handle disposed on successful boot (no handle leak)
• ✅ ListAvdNamesAsync checks exit code
• ✅ TryKillProcess uses typed catch (Exception ex) with logging
• ✅ RunShellCommandAsync XML doc warns about shell interpretation
• ✅ Fixed RS0026/RS0027 PublicAPI analyzer warnings
• ✅ EmulatorBootResult uses init-only properties (immutable record)
• ✅ Ported 6 additional tests from dotnet/android BootAndroidEmulatorTests
• ✅ Fixed AVD name detection for emulator v36+ (getprop fallback)

[Copilot]

Pull request overview

This PR adds a new EmulatorRunner to Xamarin.Android.Tools.AndroidSdk intended to wrap Android emulator CLI operations, alongside new shared infrastructure for running Android SDK command-line tools with environment setup and result modeling.

Changes:

• Added EmulatorRunner to start an AVD, stop an emulator, and list available AVD names.
• Added AndroidToolRunner utility to run SDK tools sync/async (with timeouts) and to start long-running background processes.
• Added AndroidEnvironmentHelper and ToolRunnerResult / ToolRunnerResult<T> to standardize tool environment and execution results.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 8 comments.

File	Description
src/Xamarin.Android.Tools.AndroidSdk/Runners/EmulatorRunner.cs	Introduces emulator wrapper methods (start/stop/list AVDs) built on the tool runner infrastructure.
src/Xamarin.Android.Tools.AndroidSdk/Runners/AndroidToolRunner.cs	Adds process execution helpers (sync/async + background) with timeout/output capture.
src/Xamarin.Android.Tools.AndroidSdk/Runners/AndroidEnvironmentHelper.cs	Adds env var setup and mapping helpers (ABI/API/tag display names).
src/Xamarin.Android.Tools.AndroidSdk/Models/ToolRunnerResult.cs	Adds a shared result model for tool execution.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jonathanpeppers]

I'd like to get the System.Diagnostics.Process code unified like mentioned here:

• Add base Android tool runner infrastructure #281 (comment)

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 4 comments.

[rmarinho]

Review feedback addressed — commit references

Feedback	Commit	Details
Port BootAndroidEmulator logic from dotnet/android	0088e39	BootAndWaitAsync with 3-phase boot, GetShellPropertyAsync, RunShellCommandAsync, 6 new tests

New files:

• Models/EmulatorBootResult.cs, Models/EmulatorBootOptions.cs
• Tests: 6 async boot scenarios ported from BootAndroidEmulatorTests.cs

Modified:

• Runners/EmulatorRunner.cs — BootAndWaitAsync, FindRunningAvdSerial, WaitForFullBootAsync
• Runners/AdbRunner.cs — GetShellPropertyAsync, RunShellCommandAsync (+ ListDevicesAsync made virtual for testability)

Draft dotnet/android consumer PR to follow.

[jonathanpeppers]

🤖 AI Review Summary

Found 7 issues: 1 correctness, 2 error handling, 1 API design, 1 code duplication, 1 code organization, 1 naming.

• Correctness: StartAvd redirects stdout/stderr but never drains the pipes — OS buffer fill will deadlock the emulator process (EmulatorRunner.cs:74)
• API design: AdditionalArgs is a single string — will be treated as one argument by ProcessUtils.ArgumentList, breaking multi-token args like -gpu swiftshader_indirect (EmulatorBootOptions.cs:14)
• Error handling: ListDevicesAsync ignores the exit code from ProcessUtils.StartProcess while sibling methods in AvdManagerRunner check it consistently (AdbRunner.cs:72)
• Code duplication: AvdManagerRunner.AvdManagerPath reimplements the cmdline-tools version scanning that ProcessUtils.FindCmdlineTool (added in this same PR) already provides (AvdManagerRunner.cs:33)
• Error handling: Bare catch { } swallows all exceptions without capturing them (AdbRunner.cs:107)

👍 Solid three-phase boot logic ported faithfully from dotnet/android. Good use of virtual on AdbRunner methods to enable clean test mocking. Thorough test coverage with 13+ unit tests covering parsing, edge cases, and the full boot flow. Nice extraction of AndroidEnvironmentHelper for shared env var setup.

---

This review was generated by the android-tools-reviewer skill based on review guidelines established by @jonathanpeppers.

[rmarinho]

@jonathanpeppers Here's the dotnet/android consumer PR you requested: dotnet/android#10948

It replaces the 454-line BootAndroidEmulator task with a ~180-line wrapper that delegates to EmulatorRunner.BootEmulatorAsync(). Same MSBuild interface, same error codes (XA0143/XA0145), but all the process management and polling logic is now in the shared library.

The PR is in draft since it depends on this PR (#284) merging first — the submodule currently points to feature/emulator-runner.

[rmarinho]

Note: the consumer PR was recreated after a branch rename — the correct link is now dotnet/android#10949 (the previous #10948 was auto-closed).

[jonathanpeppers]

I tried it locally, but it errors:

Is anything different from the code <BootAndroidEmulator/> had before?

[rmarinho]

🔬 Definitive Proof: adb emu avd name Bug on Emulator v36+

Following up on the AVD name detection fix — I did thorough live testing on a properly running emulator (v36.4.9, API 36, arm64) to confirm the behavior.

Test Environment

• Emulator: v36.4.9.0 (build 14788078), AVD MAUI_Emulator_API_36
• ADB: v37.0.0-14910828
• macOS: Darwin 25.3.0 (arm64, Apple M3 Pro)
• Emulator fully booted: sys.boot_completed=1, adb devices shows device state

Results

Method	Result
adb -s emulator-5554 emu avd name	EMPTY (exit code 0, no output)
adb shell getprop ro.boot.qemu.avd_name	MAUI_Emulator_API_36 ✅
echo "avd name" | nc localhost 5554 (raw telnet)	MAUI_Emulator_API_36 ✅
Console port 5554	OPEN (nc -z succeeds)

Analysis

1. The console port IS accessible — raw telnet to 5554 returns the AVD name correctly
2. adb emu returns empty — adb uses a different protocol path than raw telnet, and something changed in emulator v36 that breaks it
3. The emulator warns: The emulator now requires a signed jwt token for gRPC access! — while gRPC (port 8554) differs from telnet console (port 5554), this may affect how adb authenticates to the console

Impact on dotnet/android

The original BootAndroidEmulator.GetRunningAvdName() on main uses the exact same command:

MonoAndroidHelper.RunProcess(adbPath, $"-s {serial} emu avd name", ...);

This means FindRunningEmulatorForAvd would fail to match the AVD → WaitForEmulatorOnline would poll indefinitely → timeout after 120s. This is exactly the bug @jonathanpeppers reported.

Fix Validation

Our getprop ro.boot.qemu.avd_name fallback in AdbRunner.GetEmulatorAvdNameAsync:

• Completes in 13ms (vs infinite timeout)
• BootEmulatorAsync end-to-end: 2.8 seconds (vs 120s timeout)
• All 259 existing tests pass

[rmarinho]

🔄 Correction: ADB v37 Regression (not emulator v36 issue)

After deeper investigation, the root cause is more specific:

The Real Issue: ADB v37.0.0 broke adb emu commands

Platform-tools 37.0.0 (ADB 37.0.0-14910828) returns empty output for ALL adb emu subcommands — not just avd name. This is a regression from ADB 36.x where these commands work fine.

I verified with a .NET test program using both MonoAndroidHelper.RunProcess-style (event-based) and ProcessUtils.StartProcess-style (stream-based) approaches — both get identical empty results. It's not a process execution issue.

Why dotnet/android CI works today

dotnet/android's Configuration.props pins XAPlatformToolsVersion to 36.0.0, so CI uses ADB 36.x where adb emu avd name works correctly. Users who manually upgrade to platform-tools 37 will hit this bug.

The getprop fallback is forward-compatible

The getprop ro.boot.qemu.avd_name fallback works regardless of ADB version, making EmulatorRunner robust against both the current ADB 37 regression and any future changes to the console protocol.

[rmarinho]

📋 Research: ADB v37.0.0 adb emu Regression — Evidence & References

Following up on the correction comment with formal evidence supporting the getprop fallback fix.

1. Platform-Tools 37.0.0 is a stable public release

• Google's official download servers host it:
  • https://dl.google.com/android/repository/platform-tools_r37.0.0-{win,linux,darwin}.zip
• GitHub Actions macOS 15 runner images ship with it (image version 20260303):
  • Android SDK Platform-Tools | 37.0.0 (source)
  • Same emulator version we tested: Android Emulator | 36.4.9
• Listed as "Latest Stable Release" in ADB-Explorer's version catalog
• Google's official release notes at developer.android.com haven't been updated past 36.0.2 yet — the version is released but undocumented

2. Known Google Bug: adb emu returns empty

• Google Issue Tracker #251776353: "adb avd id returns empty"
• Originally reported on Intel Macs (platform-tools 34.x), still open/unresolved
• Our testing confirms it now affects Apple Silicon (M3 Pro) with ADB 37.0.0
• ALL adb emu subcommands return empty (not just avd name/id) — the entire console-via-ADB pathway is broken
• Raw telnet to the console port (5554) works perfectly — proving the emulator console itself is fine

3. Why dotnet/android CI is not affected (yet)

• Configuration.props pins XAPlatformToolsVersion=36.0.0 → CI uses ADB 36.x where adb emu works
• Any CI/CD using macos-15 GitHub Actions runners WILL be affected — they already have pt 37.0.0
• Developers using Android Studio (which auto-updates SDK components) will also hit this

4. The getprop fallback is the correct fix

• getprop ro.boot.qemu.avd_name uses adb shell (standard ADB transport), not the emulator console protocol
• Works on all ADB versions (35.x, 36.x, 37.x) — we verified this
• Avoids the broken console-via-ADB pathway entirely
• Available since Android API 21+ (emulator sets ro.boot.qemu.avd_name at boot)
• Completes in ~13ms vs 120s timeout with broken adb emu

Summary

Evidence	Finding
Platform-tools 37.0.0	✅ Stable, public release on dl.google.com
GitHub Actions macOS 15	✅ Ships with pt 37.0.0 + emulator 36.4.9
Google Issue Tracker	✅ #251776353 — known open bug
dotnet/android CI	Uses pt 36.0.0 (pinned) — not yet affected
getprop fallback	Works on ALL ADB versions — forward-compatible fix

[jonathanpeppers]

The build failures is an issue rerunning -- attempt number need to be on artifacts (I'm fixing separately).

Merging shortly.