Add AdbRunner for adb CLI operations

[rmarinho]

Summary

Wraps adb CLI operations for device management. Addresses #279.

Parsing/formatting/merging logic ported from dotnet/android GetAvailableAndroidDevices MSBuild task, enabling code sharing via the external/xamarin-android-tools submodule. See draft PR: dotnet/android#10880

Public API

public class AdbRunner
{
    // Constructor — requires full path to adb executable
    public AdbRunner(string adbPath, IDictionary<string, string>? environmentVariables = null);

    // Instance methods (async, invoke adb process)
    public Task<IReadOnlyList<AdbDeviceInfo>> ListDevicesAsync(CancellationToken ct = default);
    public Task WaitForDeviceAsync(string? serial = null, TimeSpan? timeout = null, CancellationToken ct = default);
    public Task StopEmulatorAsync(string serial, CancellationToken ct = default);

    // Static helpers — public so dotnet/android can call without instantiating AdbRunner
    public static List<AdbDeviceInfo> ParseAdbDevicesOutput(IEnumerable<string> lines);
    public static AdbDeviceStatus MapAdbStateToStatus(string adbState);
    public static string BuildDeviceDescription(AdbDeviceInfo device, Action<TraceLevel, string>? logger = null);
    public static string FormatDisplayName(string avdName);
    public static List<AdbDeviceInfo> MergeDevicesAndEmulators(
        IReadOnlyList<AdbDeviceInfo> adbDevices,
        IReadOnlyList<string> availableEmulators,
        Action<TraceLevel, string>? logger = null);
}

Internal methods (not part of public API):

• GetEmulatorAvdNameAsync — queries AVD name via adb emu avd name with TCP console fallback
• ProcessUtils.ThrowIfFailed — shared exit code validation (string and StringWriter overloads)

Key Design Decisions

• Constructor takes string adbPath: Callers pass the resolved path; no lazy Func<> indirection. Optional environmentVariables dictionary for ANDROID_HOME/JAVA_HOME/PATH.
• Static parsing methods are public static so dotnet/android can call them without instantiating AdbRunner (e.g., GetAvailableAndroidDevices MSBuild task passes List<string> to ParseAdbDevicesOutput)
• IEnumerable<string> overload: dotnet/android passes List<string> directly from output lines
• Logger parameter: BuildDeviceDescription and MergeDevicesAndEmulators accept Action<TraceLevel, string>? — dotnet/android passes this.CreateTaskLogger() for MSBuild trace output
• Regex with explicit state list: Uses \s+ separator to match one or more whitespace characters (spaces or tabs). Matches explicit known states with IgnoreCase. Daemon startup lines (*) are pre-filtered.
• Exit code checking: ListDevicesAsync, WaitForDeviceAsync, and StopEmulatorAsync throw InvalidOperationException with stderr context on non-zero exit via ProcessUtils.ThrowIfFailed (internal)
• MapAdbStateToStatus as switch expression: Simple value mapping uses C# switch expression for conciseness
• Property patterns instead of null-forgiving: Uses is { Length: > 0 } patterns throughout for null checks on netstandard2.0 where string.IsNullOrEmpty() lacks [NotNullWhen(false)]
• FormatDisplayName: Lowercases before ToTitleCase to normalize mixed-case input (e.g., "PiXeL" → "Pixel")
• Environment variables via StartProcess: Runners pass env vars dictionary to ProcessUtils.StartProcess. AndroidEnvironmentHelper.GetEnvironmentVariables() builds the dict.

Tests

45 unit tests (AdbRunnerTests.cs):

• ParseAdbDevicesOutput: real-world data, empty output, single/multiple devices, mixed states, daemon messages, IP:port, Windows newlines, recovery/sideload, tab-separated output
• FormatDisplayName: underscores, title case, API capitalization, mixed case, special chars, empty
• MapAdbStateToStatus: all known states + unknown (recovery, sideload)
• MergeDevicesAndEmulators: no emulators, no running, mixed, case-insensitive dedup, sorting
• Constructor: valid path, null/empty throws
• WaitForDeviceAsync: timeout validation (negative, zero)

4 integration tests (RunnerIntegrationTests.cs):

• Run only when TF_BUILD=True or CI=true (case-insensitive truthy check), skipped locally
• Require pre-installed JDK (JAVA_HOME) and Android SDK (ANDROID_HOME) on CI agent
• Assert.Ignore when ANDROID_HOME missing (no bootstrap/network dependency)
• Cover: constructor, ListDevicesAsync, WaitForDeviceAsync timeout, tool discovery

Review Feedback Addressed

Feedback	Commit	Details
Constructor: require string adbPath	25e7711	Replace Func<> with string adbPath, remove lazy resolution
Port device listing from dotnet/android	2dac552, 93aca4b, b9be955	ParseAdbDevicesOutput, BuildDeviceDescription, FormatDisplayName, MergeDevicesAndEmulators
Exit code check, internal visibility	a42544f	ProcessUtils.ThrowIfFailed, visibility adjustments
Fix regex: explicit states + tab support	eb63cb5	\s+ separator, explicit state list, IgnoreCase
Fix nullable reference type warnings	e689e82	For dotnet/android WarningsAsErrors=Nullable compatibility
Optional logger callback	b9be955	Action<TraceLevel, string>? on BuildDeviceDescription + MergeDevicesAndEmulators
IEnumerable<string> parse overload	93aca4b	dotnet/android passes List<string> directly
Log exception in bare catch	f68600d	GetEmulatorAvdNameAsync logs via Trace.WriteLine
Emulator console fallback for AVD name	90ef8b5	TCP console query when adb emu avd name fails
ThrowIfFailed StringWriter overload	b4d9a5f	Delegates to string version; single IEnumerable<string> parse method
Replace null-forgiving ! with patterns	850cb39	is { Length: > 0 } patterns; MapAdbStateToStatus → switch expression
Remove section separator comments	da3000c	Removed // ── Section ── region-style comments
Tighten RequireCi() truthy check	da3000c	string.Equals("true", OrdinalIgnoreCase) instead of presence check
Remove bootstrap fallback in tests	da3000c	Assert.Ignore when ANDROID_HOME missing — no network-dependent SDK download
Fix regex comment accuracy	da3000c	Comment matches \s+ behavior (1+ whitespace)
Apply review suggestions (pattern matching, comment)	72291e2	is { Length: > 0 } in ProcessUtils, improved netstandard2.0 comment

Co-authored-by: Copilot [email protected]

[jonathanpeppers]

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

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

[rmarinho]

Implemented your suggested approach:

• Ported the device listing logic from dotnet/android's GetAvailableAndroidDevices MSBuild task into AdbRunner in feature/adb-runner branch
• AdbDeviceInfo now has all the same fields: Serial, Description, Type (enum), Status (enum), AvdName, Model, Product, Device, TransportId
• Ported ParseAdbDevicesOutput (same regex pattern), BuildDeviceDescription (same priority order), FormatDisplayName (title case + API capitalization), MapAdbStateToStatus, and MergeDevicesAndEmulators (dedup + sorting)
• Added GetEmulatorAvdNameAsync (async version of GetEmulatorAvdName)
• 33 unit tests ported from the dotnet/android test cases (parsing, display name formatting, status mapping, merging/dedup, path discovery)

Next steps per your plan:

1. ✅ feature/adb-runner has the ported logic (pushed)
2. ⬜ Open a draft PR in dotnet/android that updates the submodule + rewrites GetAvailableAndroidDevices.cs to consume the new shared API
3. ⬜ Review/merge android-tools first, then dotnet/android

[rmarinho]

The dotnet/android side is now ready as a draft PR: dotnet/android#10880

It delegates GetAvailableAndroidDevices parsing/formatting/merging to the shared AdbRunner methods from this PR, removing ~200 lines of duplicated code. All 33 existing tests are preserved and updated to use AdbRunner/AdbDeviceInfo directly (no more reflection).

Workflow:

1. Merge this PR first
2. Update the dotnet/android submodule pointer from feature/adb-runner to main
3. Take Use shared AdbRunner from android-tools for device listing android#10880 out of draft and merge

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

---

You can also share your feedback on Copilot code review. Take the survey.

[jonathanpeppers]

🤖 AI Review Summary

Found 3 issues: 2 API design, 1 documentation accuracy.

• API design: ParseAdbDevicesOutput and MergeDevicesAndEmulators return List<T> instead of IReadOnlyList<T> (AdbRunner.cs:142,264)
• Documentation: GetEmulatorAvdNameAsync doc comment mentions TCP console fallback that isn't implemented (AdbRunner.cs:74)

👍 Positives:

• Excellent OperationCanceledException handling — caught and rethrown before the general catch (Exception) in GetEmulatorAvdNameAsync, and the when clause in WaitForDeviceAsync correctly distinguishes timeout from caller cancellation.
• Consistent exit code checking via ProcessUtils.ThrowIfFailed across all three async methods.
• All process creation goes through ProcessUtils.CreateProcessStartInfo with separate argument strings — no string interpolation into commands.
• Clean one-type-per-file organization with file-scoped namespaces.
• Property patterns (is { Length: > 0 }) used throughout instead of null-forgiving !.
• CancellationToken properly propagated to every downstream async call.
• Solid test coverage (45 unit + 4 integration) with real-world adb output data.

---

Review generated by android-tools-reviewer from review guidelines by @jonathanpeppers.

[jonathanpeppers]

I tested the changes upstream in dotnet/android. I had this setup an emulator running + device attached:

> adb devices
List of devices attached
0A041FDD400327  device
emulator-5554   device

> emulator -list-avds
Pixel_9_Pro_XL
pixel_7_-_api_29
pixel_7_-_api_36

> adb -s emulator-5554 emu avd name
Pixel_9_Pro_XL
OK

Selection looks OK (donut is alias for dotnet-local.cmd):

> donut run -bl
Restore complete (0.5s)

Build succeeded in 0.5s
    info NETSDK1057: You are using a preview version of .NET. See: https://aka.ms/dotnet-support-policy

Build succeeded in 0.4s
Select a device to run on:

  0A041FDD400327 - Pixel 5
> emulator-5554 - Pixel 9 Pro Xl
  pixel_7_-_api_29 - Pixel 7 - API 29 (Not Running)
  pixel_7_-_api_36 - Pixel 7 - API 36 (Not Running)

Type to search

I was able to deploy to emulator and device.