[msbuild/dotnet] Add support for listing the devices and simulators available to run on. #24279

rolfbjarne · 2025-11-18T11:13:08Z

This consists of two parts:

Add an MSBuild target that lists all the available devices (ComputeAvailableDevices), by returning them in a $(Devices) item group.
Add support for the $(Device) property to specify the device or simulator to use.

Regarding the device list, we'll filter the returned list by:

Platform (don't return an Apple TV simulator for an iOS app).
Minimum OS version (not return an iOS 18.0 device when the app's minimum OS version is 26.0).
Only devices that are actually available, as reported by devicectl or simctl.
Don't return an arm64 simulator on an x64 machine.
RuntimeIdentifier, if specified on the command-line.

References:

rolfbjarne · 2025-11-18T11:15:40Z

@jonathanpeppers I think the spec needs to be updated so that the correct RuntimeIdentifier is set, depending on what the user chose - maybe the returned item group with the devices can have a 'RuntimeIdentifier' metadata that, if specified, is set for the subsequent build/run operation?

Copilot

Pull Request Overview

This PR adds support for listing available devices and simulators for iOS and tvOS apps, enabling device selection via the dotnet run --device command. The implementation follows the .NET SDK's device selection specification for MAUI-style device management.

Key Changes:

New GetAvailableDevices MSBuild task that queries devicectl and simctl to retrieve available physical devices and simulators
New ComputeAvailableDevices target that can be invoked to list all compatible devices
Property rename from _DeviceName to Device for specifying target devices

Reviewed Changes

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

Show a summary per file

File	Description
tools/common/JsonExtensions.cs	New utility class with JSON parsing extension methods for processing devicectl/simctl output
tests/msbuild/Xamarin.MacDev.Tasks.Tests/TaskTests/GetAvailableDevicesTest.cs	Comprehensive test suite covering device filtering scenarios (platform, OS version, device family)
msbuild/Xamarin.MacDev.Tasks/Tasks/GetAvailableDevices.cs	Main task implementation that queries devices, applies filters, and returns available devices
msbuild/Xamarin.Shared/Xamarin.Shared.targets	Moved `_AppBundleManifestPath` property definition to allow access by GetAvailableDevices
msbuild/Xamarin.MacDev.Tasks/Xamarin.MacDev.Tasks.csproj	Added JsonExtensions.cs to the project
dotnet/targets/Xamarin.Shared.Sdk.targets	Added ComputeAvailableDevices target and Device property with backward compatibility for _DeviceName
tests/common/shared-dotnet.mk	Updated to use `Device` property instead of deprecated `_DeviceName`
docs/building-apps/build-targets.md	Documentation for the new ComputeAvailableDevices target
docs/building-apps/build-properties.md	Documentation for the new Device property

msbuild/Xamarin.MacDev.Tasks/Tasks/GetAvailableDevices.cs

docs/building-apps/build-targets.md

docs/building-apps/build-properties.md

Copilot · 2025-11-18T11:29:35Z

dotnet/targets/Xamarin.Shared.Sdk.targets

+
+	Target that queries available devices and simulators.
+	This target is called by 'dotnet run' to support device selection.
+	Returns @(Devices) items with metadata: ???????


The comment states "Returns @(Devices) items with metadata: ???????" which appears to be a placeholder that was not filled in. The metadata should be documented here (Description, Type, OSVersion, UDID) similar to what's in the build-targets.md documentation.

Suggested change

Returns @(Devices) items with metadata: ???????

Returns @(Devices) items with metadata: Description, Type, OSVersion, UDID

tools/common/JsonExtensions.cs

msbuild/Xamarin.MacDev.Tasks/Tasks/GetAvailableDevices.cs

jonathanpeppers · 2025-11-18T15:57:16Z

dotnet/targets/Xamarin.Shared.Sdk.targets

-		<DeviceName Condition="'$(DeviceName)' == ''">$(_DeviceName)</DeviceName>
+		<!-- Try to keep _DeviceName working for a while yet -->
+		<Device Condition="'$(Device)' == ''">$(_DeviceName)</Device>


Do you need to keep $(DeviceName) around, it's public? Maybe it's not really used/documented.

jonathanpeppers · 2025-11-18T15:57:49Z

dotnet/targets/Xamarin.Shared.Sdk.targets

+			Condition="'$(IsMacEnabled)' == 'true'"
+			SessionId="$(BuildSessionId)"


That is a question... Will this work on Windows? Ideally, it could, but that could be future PR.

…mulators available to run on. This consists of two parts: * Add an MSBuild target that lists all the available devices (`ComputeAvailableDevices`), by returning them in a `$(Devices)` item group. * Add support for the `$(Device)` property to specify the device or simulator to use. Regarding the device list, we'll filter the returned list by: * Platform (don't return an Apple TV simulator for an iOS app). * Minimum OS version (not return an iOS 18.0 device when the app's minimum OS version is 26.0). * Only devices that are actually available, as reported by `devicectl` or `simctl`. References: * dotnet/android#10576 * https://github.com/dotnet/sdk/blob/2b9fc02a265c735f2132e4e3626e94962e48bdf5/documentation/specs/dotnet-run-for-maui.md Fixes #23995.

Copilot

Pull request overview

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

Copilot · 2026-01-09T11:21:44Z

msbuild/Xamarin.MacDev.Tasks/Tasks/GetAvailableDevices.cs

+	[Output]
+	public ITaskItem [] DiscardedDevices { get; set; } = Array.Empty<ITaskItem> ();
+
+	[Output]


The RuntimeIdentifier property has the [Output] attribute but is being used as an input parameter. Output parameters should only be set by the task, not read as input. This property should not have the [Output] attribute if it's meant to be an input parameter for filtering devices.

Suggested change

[Output]

Copilot · 2026-01-09T11:21:44Z

msbuild/Xamarin.MacDev.Tasks/Tasks/GetAvailableDevices.cs

+					}
+				}
+
+				Version.TryParse (productVersion, out var minimumOSVersion);


Potential null reference exception: Version.TryParse may leave minimumOSVersion as null if parsing fails, but it's used directly on line 271 without a null check. Consider using a default value like 'new Version (0, 0)' if parsing fails.

Suggested change

Version.TryParse (productVersion, out var minimumOSVersion);

var minimumOSVersion = new Version (0, 0);

Version.TryParse (productVersion, out minimumOSVersion);

Copilot · 2026-01-09T11:21:44Z

msbuild/Xamarin.MacDev.Tasks/Tasks/GetAvailableDevices.cs

+	System.Threading.Tasks.Task<IEnumerable<DeviceInfo>> RunSimCtlAsync ()
+	{
+		var doc = ExecuteCtlToJsonAsync ("simctl", "list", "--json").Result;


Using .Result on an async task in a non-async method can cause deadlocks. The RunSimCtlAsync method should be declared as async and use 'await' instead of '.Result'. The method signature on line 277 should be 'async System.Threading.Tasks.Task<IEnumerable> RunSimCtlAsync ()' and line 279 should use 'await ExecuteCtlToJsonAsync'.

Copilot · 2026-01-09T11:21:44Z

dotnet/targets/Microsoft.Sdk.Mobile.targets

+
+	Target that queries available devices and simulators.
+	This target is called by 'dotnet run' to support device selection.
+	Returns @(Devices) items with metadata: ???????


Incomplete documentation: The comment on line 150 says "Returns @(Devices) items with metadata: ???????" which indicates the metadata documentation is incomplete. The metadata fields should be documented here as they are in the build-targets.md file (Description, Type, OSVersion, UDID, RuntimeIdentifier).

Suggested change

Returns @(Devices) items with metadata: ???????

Returns @(Devices) items with metadata: Description, Type, OSVersion, UDID, RuntimeIdentifier

dotnet run will only use %(RuntimeIdentifier), but I put all kinds of other metadata that Android had mainly for debugging purposes.

vs-mobiletools-engineering-service2 · 2026-01-09T11:44:51Z

✅ [CI Build #6823a2b] Build passed (Build packages) ✅

Pipeline on Agent
Hash: 6823a2b4fe0d130da44a71cffeae9369512456c0 [PR build]

vs-mobiletools-engineering-service2 · 2026-01-09T11:46:24Z

✅ [PR Build #6823a2b] Build passed (Detect API changes) ✅

Pipeline on Agent
Hash: 6823a2b4fe0d130da44a71cffeae9369512456c0 [PR build]

vs-mobiletools-engineering-service2 · 2026-01-09T12:13:24Z

✅ API diff for current PR / commit

NET (empty diffs)

iOS: vsdrops gist ( No breaking changes )
tvOS: vsdrops gist ( No breaking changes )
MacCatalyst: vsdrops gist ( No breaking changes )
macOS: vsdrops gist ( No breaking changes )

✅ API diff vs stable

NET (empty diffs)

iOS: vsdrops gist ( No breaking changes )
tvOS: vsdrops gist ( No breaking changes )
MacCatalyst: vsdrops gist ( No breaking changes )
macOS: vsdrops gist ( No breaking changes )

ℹ️ Generator diff

Generator Diff: vsdrops (html) vsdrops (raw diff) gist (raw diff) - Please review changes)

Pipeline on Agent
Hash: 6823a2b4fe0d130da44a71cffeae9369512456c0 [PR build]

vs-mobiletools-engineering-service2 · 2026-01-09T12:19:11Z

✅ [CI Build #6823a2b] Build passed (Build macOS tests) ✅

Pipeline on Agent
Hash: 6823a2b4fe0d130da44a71cffeae9369512456c0 [PR build]

vs-mobiletools-engineering-service2 · 2026-01-09T12:28:40Z

💻 [CI Build #6823a2b] Tests on macOS X64 - Mac Sonoma (14) passed 💻

✅ All tests on macOS X64 - Mac Sonoma (14) passed.

Pipeline on Agent
Hash: 6823a2b4fe0d130da44a71cffeae9369512456c0 [PR build]

vs-mobiletools-engineering-service2 · 2026-01-09T12:33:11Z

💻 [CI Build #6823a2b] Tests on macOS arm64 - Mac Sequoia (15) passed 💻

✅ All tests on macOS arm64 - Mac Sequoia (15) passed.

Pipeline on Agent
Hash: 6823a2b4fe0d130da44a71cffeae9369512456c0 [PR build]

vs-mobiletools-engineering-service2 · 2026-01-09T13:13:56Z

❌ [CI Build #6823a2b] Tests on macOS arm64 - Mac Tahoe (26) failed ❌

Failed tests are:

monotouch-test

Pipeline on Agent
Hash: 6823a2b4fe0d130da44a71cffeae9369512456c0 [PR build]

vs-mobiletools-engineering-service2 · 2026-01-09T13:20:59Z

🔥 [CI Build #6823a2b] Test results 🔥

Test results

❌ Tests failed on VSTS: test results

0 tests crashed, 4 tests failed, 113 tests passed.

Failures

❌ linker tests

1 tests failed, 43 tests passed.

Failed tests

dont link/tvOS - simulator/Debug: Crashed

Html Report (VSDrops) Download

❌ monotouch tests (macOS)

1 tests failed, 8 tests passed.

Failed tests

monotouch-test/macOS/Debug: Failed (Test run failed.
Tests run: 3462 Passed: 3300 Inconclusive: 7 Failed: 1 Ignored: 161)

Html Report (VSDrops) Download

❌ msbuild tests

1 tests failed, 1 tests passed.

Failed tests

MSBuild tasks tests: Failed (Execution failed with exit code 1)
- Xamarin.MacDev.Tasks.GetAvailableDevicesTests.Ctl1: System.IndexOutOfRangeException : Index was outside the bounds of the array.Multiple failures or warnings in test:

Device...
* Xamarin.MacDev.Tasks.GetAvailableDevicesTests.Ctl1_AppleTV: System.IndexOutOfRangeException : Index was outside the bounds of the array.Multiple failures or warnings in test:
Device...
* Xamarin.MacDev.Tasks.GetAvailableDevicesTests.Ctl1_iPad: System.IndexOutOfRangeException : Index was outside the bounds of the array.Multiple failures or warnings in test:
Device...
* ... and 4 more

Html Report (VSDrops) Download

❌ xcframework tests

1 tests failed, 3 tests passed.

Failed tests

xcframework-test/tvOS - simulator/Debug: Crashed

Html Report (VSDrops) Download

Successes

✅ cecil: All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (iOS): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (MacCatalyst): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (macOS): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (Multiple platforms): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (tvOS): All 1 tests passed. Html Report (VSDrops) Download
✅ framework: All 2 tests passed. Html Report (VSDrops) Download
✅ fsharp: All 4 tests passed. Html Report (VSDrops) Download
✅ generator: All 5 tests passed. Html Report (VSDrops) Download
✅ interdependent-binding-projects: All 4 tests passed. Html Report (VSDrops) Download
✅ introspection: All 4 tests passed. Html Report (VSDrops) Download
✅ monotouch (iOS): All 9 tests passed. Html Report (VSDrops) Download
✅ monotouch (MacCatalyst): All 11 tests passed. Html Report (VSDrops) Download
✅ monotouch (tvOS): All 9 tests passed. Html Report (VSDrops) Download
✅ windows: All 3 tests passed. Html Report (VSDrops) Download
✅ xtro: All 1 tests passed. Html Report (VSDrops) Download

Pipeline on Agent
Hash: 6823a2b4fe0d130da44a71cffeae9369512456c0 [PR build]

jonathanpeppers

Overall looks good! There is a possible exception the JSON parsing can throw, but might not happen in real life.

jonathanpeppers · 2026-01-09T14:19:25Z

dotnet/targets/Microsoft.Sdk.Mobile.targets

+
+	Target that queries available devices and simulators.
+	This target is called by 'dotnet run' to support device selection.
+	Returns @(Devices) items with metadata: ???????


dotnet run will only use %(RuntimeIdentifier), but I put all kinds of other metadata that Android had mainly for debugging purposes.

jonathanpeppers · 2026-01-09T14:22:14Z

msbuild/Xamarin.MacDev.Tasks/Tasks/GetAvailableDevices.cs

+			await ExecuteAsync (Log, "xcrun", arguments, sdkDevPath: SdkDevPath, cancellationToken: cancellationTokenSource!.Token);
+			return File.ReadAllText (tmpfile);


If the file is long, you could avoid making a large string if JsonDocument opened a Stream instead.

Do you know how long the task takes? If it's fast, probably doesn't matter.

jonathanpeppers · 2026-01-09T14:26:28Z

tools/common/JsonExtensions.cs

+
+	public static string? GetStringProperty (this JsonElement? element, string propertyName)
+	{
+		return GetNullableProperty (element, propertyName)?.GetString ();


The only thing I've run into is if you got values like JsonValueKind.True, JsonValueKind.Number, JsonValueKind.Null, I think it will throw InvalidOperationException:

https://github.com/dotnet/runtime/blob/881c160a342b1f20946451e264eaad7a337659da/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonElement.cs#L369-L371

I had to do stuff like this in the past:

static string? GetJsonValueAsString (JsonElement element) => element.ValueKind switch { JsonValueKind.String => element.GetString (), JsonValueKind.True => "true", JsonValueKind.False => "false", JsonValueKind.Number or JsonValueKind.Object or JsonValueKind.Array => element.GetRawText (), _ => null, // Null or Undefined };

rolfbjarne requested a review from Copilot November 18, 2025 11:19

Copilot started reviewing on behalf of rolfbjarne November 18, 2025 11:19 View session

Copilot finished reviewing on behalf of rolfbjarne November 18, 2025 11:22

Copilot AI reviewed Nov 18, 2025

View reviewed changes

This comment has been minimized.

Sign in to view

jonathanpeppers reviewed Nov 18, 2025

View reviewed changes

This comment has been minimized.

Sign in to view

rolfbjarne force-pushed the dev/rolf/dotnet-run-device-selection branch from 700ce36 to 2ccb1f6 Compare January 8, 2026 14:59

This comment has been minimized.

Sign in to view

rolfbjarne force-pushed the dev/rolf/dotnet-run-device-selection branch from 2ccb1f6 to 6823a2b Compare January 9, 2026 11:11

rolfbjarne marked this pull request as ready for review January 9, 2026 11:11

rolfbjarne requested review from emaf and mauroa as code owners January 9, 2026 11:11

rolfbjarne requested a review from Copilot January 9, 2026 11:11

Copilot started reviewing on behalf of rolfbjarne January 9, 2026 11:12 View session

Copilot AI reviewed Jan 9, 2026

View reviewed changes

dalexsoto approved these changes Jan 9, 2026

View reviewed changes

jonathanpeppers approved these changes Jan 9, 2026

View reviewed changes

	Returns @(Devices) items with metadata: ???????
	Returns @(Devices) items with metadata: Description, Type, OSVersion, UDID

		Condition="'$(IsMacEnabled)' == 'true'"
		SessionId="$(BuildSessionId)"

	Version.TryParse (productVersion, out var minimumOSVersion);
	var minimumOSVersion = new Version (0, 0);
	Version.TryParse (productVersion, out minimumOSVersion);

		await ExecuteAsync (Log, "xcrun", arguments, sdkDevPath: SdkDevPath, cancellationToken: cancellationTokenSource!.Token);
		return File.ReadAllText (tmpfile);

[msbuild/dotnet] Add support for listing the devices and simulators available to run on. #24279

Are you sure you want to change the base?

[msbuild/dotnet] Add support for listing the devices and simulators available to run on. #24279

Uh oh!

Conversation

rolfbjarne commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rolfbjarne commented Nov 18, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes:

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

jonathanpeppers Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

jonathanpeppers Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

rolfbjarne commented Nov 18, 2025 •

edited

Loading