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

docs/building-apps/build-properties.md

@@ -344,6 +344,20 @@ Only applicable to macOS and Mac Catalyst projects.
 
 See [BuildIpa](#buildipa) for iOS and tvOS projects.
 
+## Device
+
+Specifies which mobile device or emulator to target when using `dotnet run
+--device <Device>` or MSBuild targets that interact with devices (such as
+`Run`, `Install`, or `Uninstall`).
+
+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`.
+
+For more information about device selection, see the
+[.NET SDK device selection specification](https://github.com/dotnet/sdk/blob/2b9fc02a265c735f2132e4e3626e94962e48bdf5/documentation/specs/dotnet-run-for-maui.md).
+
 ## DeviceSpecificBuild
 
 If the build should be specific to the selected device.

docs/building-apps/build-targets.md

@@ -16,11 +16,38 @@ Builds the source code within a project and all dependencies.
 
 Removes all files generated by the build process.
 
+## ComputeAvailableDevices
+
+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)`
+item group where each device has the following metadata:
+
+- **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 of the device
+- **UDID**: The UDID of the device
+
+For example, to list all available devices:
+
+```shell
+$ dotnet build -t:ComputeAvailableDevices
+```
+
+This target is part of the [.NET SDK device selection specification](https://github.com/dotnet/sdk/blob/2b9fc02a265c735f2132e4e3626e94962e48bdf5/documentation/specs/dotnet-run-for-maui.md) and enables commands like:
+
+```shell
+$ dotnet run --device UDID
+```
+
+Added in .NET 11.
+
 ## Run
 
 Builds the source code within a project and all dependencies, and then deploys and runs it
-on a default simulator/device. A specific deployment target can be set by using the `$(_DeviceName)` property. 
+on a default simulator/device. A specific deployment target can be set by using the `$(Device)` property. 
 
 ```dotnetcli
-dotnet build -t:Run project.csproj -p:_DeviceName=$(MY_DEVICE_UDID)
+dotnet build -t:Run project.csproj -p:Device=$(MY_DEVICE_UDID)
 ```

dotnet/targets/Xamarin.Shared.Sdk.targets

@@ -2407,7 +2407,8 @@
 		<RelativeMlaunchPath Condition="'$(RelativeMlaunchPath)' == ''">$(XamarinRelativeSdkRootDirectory)tools\bin\mlaunch</RelativeMlaunchPath>
 		<_RelativeMlaunchPath Condition="'$(_RelativeMlaunchPath)' == ''">$(RelativeMlaunchPath)</_RelativeMlaunchPath>
 
-		<DeviceName Condition="'$(DeviceName)' == ''">$(_DeviceName)</DeviceName>
+		<!-- Try to keep _DeviceName working for a while yet -->
+		<Device Condition="'$(Device)' == ''">$(_DeviceName)</Device>
 	</PropertyGroup>
 
 	<Target
@@ -2445,7 +2446,7 @@
 		<GetMlaunchArguments
 			SessionId="$(BuildSessionId)"
 			AppManifestPath="$(_AppBundleManifestPath)"
-			DeviceName="$(DeviceName)"
+			DeviceName="$(Device)"
 			InstallApp="$(_AppBundlePath)"
 			MlaunchPath="$(MlaunchPath)"
 			SdkDevPath="$(_SdkDevPath)"
@@ -2558,6 +2559,33 @@
 		</PropertyGroup>
 	</Target>
 
+	<!--
+	***********************************************************************************************
+	ComputeAvailableDevices
+
+	Target that queries available devices and simulators.
+	This target is called by 'dotnet run' to support device selection.
+	Returns @(Devices) items with metadata: ???????
+
+	See: https://github.com/dotnet/sdk/blob/2b9fc02a265c735f2132e4e3626e94962e48bdf5/documentation/specs/dotnet-run-for-maui.md
+	***********************************************************************************************
+	-->
+	<Target Name="ComputeAvailableDevices"
+		DependsOnTargets="_DetectSdkLocations;_GenerateBundleName;"
+		Returns="@(Devices)">
+		<GetAvailableDevices
+			Condition="'$(IsMacEnabled)' == 'true'"
+			SessionId="$(BuildSessionId)"
+			AppBundleManifestPath="$(_AppBundleManifestPath)"
+			RuntimeIdentifier="$(RuntimeIdentifier)"
+			SdkDevPath="$(_SdkDevPath)"
+			TargetFrameworkMoniker="$(_ComputedTargetFrameworkMoniker)"
+		>
+			<Output TaskParameter="Devices" ItemName="Devices" />
+			<Output TaskParameter="DiscardedDevices" ItemName="DiscardedDevices" />
+		</GetAvailableDevices>
+	</Target>
+
 	<!--
 		Add a 'global using nfloat = System.Runtime.InteropServices.NFloat' to ease migration from Xamarin.
 		We're not using a the Usings item group, because this code shows a warning in .NET 7: