Skip to content

[dotnet-run] implement "device" selection logic #51914

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonathanpeppers merged 12 commits into from
Dec 4, 2025
Merged

[dotnet-run] implement "device" selection logic #51914

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
43482d4
[dotnet-run] implement "device" selection logic
jonathanpeppers Nov 24, 2025
f184fd0
Apply suggestions from code review
jonathanpeppers Nov 26, 2025
94ef0e9
Simplify tests for macOS arm64
jonathanpeppers Dec 1, 2025
17b0edc
Make "current" target framework the default
jonathanpeppers Dec 1, 2025
e154617
Store everything in a single `.binlog`
jonathanpeppers Dec 1, 2025
7264d8c
Update tests
jonathanpeppers Dec 1, 2025
de396aa
Fix "double-shutdown" of logger
jonathanpeppers Dec 1, 2025
821ca29
Remove `_disposed` flag, unnecessary
jonathanpeppers Dec 1, 2025
462c9ab
Merge branch 'main' into dev/peppers/dotnet-run-devices
jonathanpeppers Dec 2, 2025
cae5e26
Fix logger for file-based runs (.cs files)
jonathanpeppers Dec 2, 2025
5e6fbcd
Suggestions from code review
jonathanpeppers Dec 3, 2025
a26459e
Merge branch 'main' into dev/peppers/dotnet-run-devices
jonathanpeppers Dec 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 36 additions & 15 deletions documentation/specs/dotnet-run-for-maui.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,21 +56,24 @@ to make extensible for .NET MAUI (and future) scenarios.
```xml
<ItemGroup>
<!-- Android examples -->
<Devices Include="emulator-5554" Description="Pixel 7 - API 35" Type="Emulator" Status="Offline" />
<Devices Include="emulator-5555" Description="Pixel 7 - API 36" Type="Emulator" Status="Online" />
<Devices Include="0A041FDD400327" Description="Pixel 7 Pro" Type="Device" Status="Online" />
<Devices Include="emulator-5554" Description="Pixel 7 - API 35" Type="Emulator" Status="Offline" RuntimeIdentifier="android-x64" />
<Devices Include="emulator-5555" Description="Pixel 7 - API 36" Type="Emulator" Status="Online" RuntimeIdentifier="android-x64" />
<Devices Include="0A041FDD400327" Description="Pixel 7 Pro" Type="Device" Status="Online" RuntimeIdentifier="android-arm64" />
<!-- iOS examples -->
<Devices Include="94E71AE5-8040-4DB2-8A9C-6CD24EF4E7DE" Description="iPhone 11 - iOS 18.6" Type="Simulator" Status="Shutdown" />
<Devices Include="FBF5DCE8-EE2B-4215-8118-3A2190DE1AD7" Description="iPhone 14 - iOS 26.0" Type="Simulator" Status="Booted" />
<Devices Include="23261B78-1E31-469C-A46E-1776D386EFD8" Description="My iPhone 13" Type="Device" Status="Unavailable" />
<Devices Include="AF40CC64-2CDB-5F16-9651-86BCDF380881" Description="My iPhone 15" Type="Device" Status="Paired" />
<Devices Include="94E71AE5-8040-4DB2-8A9C-6CD24EF4E7DE" Description="iPhone 11 - iOS 18.6" Type="Simulator" Status="Shutdown" RuntimeIdentifier="iossimulator-arm64" />
<Devices Include="FBF5DCE8-EE2B-4215-8118-3A2190DE1AD7" Description="iPhone 14 - iOS 26.0" Type="Simulator" Status="Booted" RuntimeIdentifier="iossimulator-arm64" />
<Devices Include="23261B78-1E31-469C-A46E-1776D386EFD8" Description="My iPhone 13" Type="Device" Status="Unavailable" RuntimeIdentifier="ios-arm64" />
<Devices Include="AF40CC64-2CDB-5F16-9651-86BCDF380881" Description="My iPhone 15" Type="Device" Status="Paired" RuntimeIdentifier="ios-arm64" />
</ItemGroup>
```

_NOTE: each workload can decide which metadata values for `%(Type)`
and `%(Status)` are useful, filtering offline devices, etc. The output
above would be analogous to running `adb devices`, `xcrun simctl list
devices`, or `xcrun devicectl list devices`._
_NOTE: each workload can decide which metadata values for `%(Type)`,
`%(Status)`, and `%(RuntimeIdentifier)` are useful, filtering offline
devices, etc. The output above would be analogous to running `adb
devices`, `xcrun simctl list devices`, or `xcrun devicectl list
devices`. The `%(RuntimeIdentifier)` metadata is optional but
recommended, as it allows the build system to pass the appropriate RID
to subsequent build, deploy, and run steps._

* Continuing on...

Expand All @@ -81,24 +84,28 @@ devices`, or `xcrun devicectl list devices`._
`--device` switch. Listing the options returned by the
`ComputeAvailableDevices` MSBuild target.

* `build`: unchanged, but is passed `-p:Device`.
* `build`: unchanged, but is passed `-p:Device` and optionally `-p:RuntimeIdentifier`
if the selected device provided a `%(RuntimeIdentifier)` metadata value.

* `deploy`

* If a `DeployToDevice` MSBuild target is available, provided by the
iOS or Android workload, etc.

* Call the MSBuild target, passing in the identifier for the selected
`-p:Device` global MSBuild property.
`-p:Device` global MSBuild property, and optionally `-p:RuntimeIdentifier`
if the selected device provided a `%(RuntimeIdentifier)` metadata value.

* This step needs to run, even with `--no-build`, as you may have
selected a different device.

* `ComputeRunArguments`: unchanged, but is passed `-p:Device`.
* `ComputeRunArguments`: unchanged, but is passed `-p:Device` and optionally
`-p:RuntimeIdentifier` if the selected device provided a `%(RuntimeIdentifier)`
metadata value.

* `run`: unchanged. `ComputeRunArguments` should have set a valid
`$(RunCommand)` and `$(RunArguments)` using the value supplied by
`-p:Device`.
`-p:Device` and optionally `-p:RuntimeIdentifier`.

## New `dotnet run` Command-line Switches

Expand Down Expand Up @@ -139,6 +146,20 @@ A new `--device` switch will:
* The iOS and Android workloads will know how to interpret `$(Device)`
to select an appropriate device, emulator, or simulator.

## Binary Logs for Device Selection

When using `-bl` with `dotnet run`, all MSBuild operations are logged to a single
binlog file: device selection, build, deploy, and run argument computation.

File naming for `dotnet run` binlogs:

* `-bl:filename.binlog` creates `filename-dotnet-run.binlog`
* `-bl` creates `msbuild-dotnet-run.binlog`

Note: The build step may also create `msbuild.binlog` separately. Use
`--no-build` with `-bl` to only capture run-specific MSBuild
operations.

## What about Launch Profiles?

The iOS and Android workloads ignore all
Expand Down
1 change: 1 addition & 0 deletions src/Cli/Microsoft.DotNet.Cli.Utils/Constants.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ public static class Constants
// MSBuild targets
public const string Build = nameof(Build);
public const string ComputeRunArguments = nameof(ComputeRunArguments);
public const string ComputeAvailableDevices = nameof(ComputeAvailableDevices);
public const string CoreCompile = nameof(CoreCompile);

// MSBuild item metadata
Expand Down
24 changes: 24 additions & 0 deletions src/Cli/dotnet/Commands/CliCommandStrings.resx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1786,6 +1786,30 @@ Your project targets multiple frameworks. Specify which framework to run using '
<data name="RunRuntimeOptionDescription" xml:space="preserve">
<value>The target runtime to run for.</value>
</data>
<data name="CommandOptionDeviceDescription" xml:space="preserve">
<value>The device identifier to use for running the application.</value>
</data>
<data name="CommandOptionDeviceHelpName" xml:space="preserve">
<value>DEVICE</value>
</data>
<data name="CommandOptionListDevicesDescription" xml:space="preserve">
<value>List available devices for running the application.</value>
</data>
<data name="RunCommandAvailableDevices" xml:space="preserve">
<value>Available devices:</value>
</data>
<data name="RunCommandNoDevicesAvailable" xml:space="preserve">
<value>No devices are available for this project.</value>
</data>
<data name="RunCommandSelectDevicePrompt" xml:space="preserve">
<value>Select a device to run on:</value>
</data>
<data name="RunCommandMoreDevicesText" xml:space="preserve">
<value>Move up and down to reveal more devices</value>
</data>
<data name="RunCommandExceptionUnableToRunSpecifyDevice" xml:space="preserve">
<value>Unable to run this project because multiple devices are available. Please specify which device to use by passing the {0} argument with one of the following values:</value>
</data>
<data name="RuntimeConfigDefinition" xml:space="preserve">
<value>Path to &lt;application&gt;.runtimeconfig.json file.</value>
</data>
Expand Down
4 changes: 3 additions & 1 deletion src/Cli/dotnet/Commands/Run/Api/RunApiCommand.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,8 @@ public override RunApiOutput Execute()
launchProfile: null,
noLaunchProfile: false,
noLaunchProfileArguments: false,
device: null,
listDevices: false,
noRestore: false,
noCache: false,
interactive: false,
Expand All @@ -112,7 +114,7 @@ public override RunApiOutput Execute()
msbuildRestoreProperties: ReadOnlyDictionary<string, string>.Empty);

runCommand.TryGetLaunchProfileSettingsIfNeeded(out var launchSettings);
var targetCommand = (Utils.Command)runCommand.GetTargetCommand(buildCommand.CreateProjectInstance, cachedRunProperties: null);
var targetCommand = (Utils.Command)runCommand.GetTargetCommand(buildCommand.CreateProjectInstance, cachedRunProperties: null, logger: null);
runCommand.ApplyLaunchSettingsProfileToCommand(targetCommand, launchSettings);

return new RunApiOutput.RunCommand
Expand Down
Loading