[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.

References:

…vailable 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.

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

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

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

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


According to the coding guidelines, output properties should be initialized with [] instead of Array.Empty<ITaskItem>(). Change to:

public ITaskItem [] DiscardedDevices { get; set; } = [];

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

docs/building-apps/build-targets.md

+Queries and returns a list of available iOS or tvOS devices and simulators that can be used with `dotnet run`.
+
+This target is called automatically by the .NET SDK's `dotnet run` command to
+support device selection via the `--device` option. It returns a `@(Devices)``


There's a double backtick after @(Devices). It should be @(Devices) with no trailing backticks.

Suggested change

support device selection via the `--device` option. It returns a `@(Devices)``

support device selection via the `--device` option. It returns a `@(Devices)`

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

docs/building-apps/build-targets.md

+
+- **Description**: The name of the device (e.g., "iPhone 16 - iOS 26.0" for simulators, "My iPhone 16" for physical devices)
+- **Type**: Either "Device" or "Simulator"
+- **OSVersion**: The OS version if the device


Grammar error: should be "The OS version of the device" instead of "The OS version if the device".

Suggested change

- **OSVersion**: The OS version if the device

- **OSVersion**: The OS version of the device

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

docs/building-apps/build-properties.md

+The value can be anything the command-line tools `simctl` or `devicectl`
+accept for the device name; this is typically either the UDID or the name of
+the device. For example, for the device `My iOS Device` with UDID `0000-aaaabbbb`, use
+either `-p:Device="My iOS Device"` or `-p:Device=0000-aaaabbbb`.


Inconsistent code formatting: The second command example should use backticks for consistency with the first example. Change -p:Device=0000-aaaabbbb to `-p:Device=0000-aaaabbbb`.

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

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

tools/common/JsonExtensions.cs

@@ -0,0 +1,107 @@
+using System.ComponentModel.DataAnnotations;


The using System.ComponentModel.DataAnnotations; directive appears to be unused. This namespace is typically used for validation attributes like [Required], but none of the methods in this file use these attributes.

Suggested change

using System.ComponentModel.DataAnnotations;

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

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

+using System.Net;
+


The using System.Net; directive appears to be unused in this file. Consider removing it to improve code clarity.

Suggested change

using System.Net;

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

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

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


According to the coding guidelines, output properties should be initialized with [] instead of Array.Empty<ITaskItem>(). Change to:

public ITaskItem [] Devices { get; set; } = [];

vs-mobiletools-engineering-service2 · 2025-11-18T11:47:33Z

✅ [CI Build #a396aa9] Build passed (Build packages) ✅

Pipeline on Agent
Hash: a396aa99e72f86f01eeb6f0133591320865e8dc4 [PR build]

vs-mobiletools-engineering-service2 · 2025-11-18T11:50:03Z

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

Pipeline on Agent
Hash: a396aa99e72f86f01eeb6f0133591320865e8dc4 [PR build]

vs-mobiletools-engineering-service2 · 2025-11-18T12:17:08Z

✅ 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: a396aa99e72f86f01eeb6f0133591320865e8dc4 [PR build]

vs-mobiletools-engineering-service2 · 2025-11-18T12:25:11Z

✅ [CI Build #a396aa9] Build passed (Build macOS tests) ✅

Pipeline on Agent
Hash: a396aa99e72f86f01eeb6f0133591320865e8dc4 [PR build]

vs-mobiletools-engineering-service2 · 2025-11-18T12:34:37Z

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

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

Pipeline on Agent
Hash: a396aa99e72f86f01eeb6f0133591320865e8dc4 [PR build]

vs-mobiletools-engineering-service2 · 2025-11-18T12:42:00Z

💻 [CI Build #a396aa9] Tests on macOS M1 - Mac Monterey (12) passed 💻

✅ All tests on macOS M1 - Mac Monterey (12) passed.

Pipeline on Agent
Hash: a396aa99e72f86f01eeb6f0133591320865e8dc4 [PR build]

vs-mobiletools-engineering-service2 · 2025-11-18T12:43:34Z

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

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

Pipeline on Agent
Hash: a396aa99e72f86f01eeb6f0133591320865e8dc4 [PR build]

vs-mobiletools-engineering-service2 · 2025-11-18T12:43:56Z

💻 [CI Build #a396aa9] Tests on macOS M1 - Mac Ventura (13) passed 💻

✅ All tests on macOS M1 - Mac Ventura (13) passed.

Pipeline on Agent
Hash: a396aa99e72f86f01eeb6f0133591320865e8dc4 [PR build]

vs-mobiletools-engineering-service2 · 2025-11-18T12:57:13Z

💻 [CI Build #a396aa9] Tests on macOS arm64 - Mac Tahoe (26) passed 💻

✅ All tests on macOS arm64 - Mac Tahoe (26) passed.

Pipeline on Agent
Hash: a396aa99e72f86f01eeb6f0133591320865e8dc4 [PR build]

vs-mobiletools-engineering-service2 · 2025-11-18T13:42:53Z

🚀 [CI Build #a396aa9] Test results 🚀

Test results

✅ All tests passed on VSTS: test results.

🎉 All 117 tests passed 🎉

Tests counts

✅ 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
✅ linker: All 44 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 (macOS): All 9 tests passed. Html Report (VSDrops) Download
✅ monotouch (tvOS): All 9 tests passed. Html Report (VSDrops) Download
✅ msbuild: All 2 tests passed. Html Report (VSDrops) Download
✅ windows: All 3 tests passed. Html Report (VSDrops) Download
✅ xcframework: All 4 tests passed. Html Report (VSDrops) Download
✅ xtro: All 1 tests passed. Html Report (VSDrops) Download

Pipeline on Agent
Hash: a396aa99e72f86f01eeb6f0133591320865e8dc4 [PR build]

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.

Auto-format source code

a396aa9

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

	support device selection via the `--device` option. It returns a `@(Devices)``
	support device selection via the `--device` option. It returns a `@(Devices)`

	- OSVersion: The OS version if the device
	- OSVersion: The OS version of the device

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

		@@ -0,0 +1,107 @@
		using System.ComponentModel.DataAnnotations;

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

[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

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!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

vs-mobiletools-engineering-service2 commented Nov 18, 2025

✅ [CI Build #a396aa9] Build passed (Build packages) ✅

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Nov 18, 2025

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

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Nov 18, 2025

✅ API diff for current PR / commit

✅ API diff vs stable

ℹ️ Generator diff

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Nov 18, 2025

✅ [CI Build #a396aa9] Build passed (Build macOS tests) ✅

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Nov 18, 2025

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

Uh oh!

vs-mobiletools-engineering-service2 commented Nov 18, 2025

💻 [CI Build #a396aa9] Tests on macOS M1 - Mac Monterey (12) passed 💻

Uh oh!

vs-mobiletools-engineering-service2 commented Nov 18, 2025

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

Uh oh!

vs-mobiletools-engineering-service2 commented Nov 18, 2025

💻 [CI Build #a396aa9] Tests on macOS M1 - Mac Ventura (13) passed 💻

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.

vs-mobiletools-engineering-service2 commented Nov 18, 2025

💻 [CI Build #a396aa9] Tests on macOS arm64 - Mac Tahoe (26) passed 💻

Uh oh!

vs-mobiletools-engineering-service2 commented Nov 18, 2025

🚀 [CI Build #a396aa9] Test results 🚀

Test results