feat: aspire exec 2 #10240

DeagleGross · 2025-07-03T09:03:22Z

Effectively is #10061 but with a couple of changes around DCP and usage.

Changes

does not change DcpExectutor now.
instead of starting as BackgroundService now ExecResourceManager subscribes to BeforeStartEvent and initializes the exec resource there. Whole resource manager pipeline is reused now.
changed ExecResourceManager to not generate its own DCP name for the ExecutableResource, but to wait until DCP starts the resource and fetch it.
now apphost is not launched via --operation exec, but it's an extension of run mode. Determines if it is exec or not based on --command flag existence.

This reverts commit f845f5b.

Copilot

Pull Request Overview

This PR integrates “exec” functionality into the existing run mode by introducing an ExecResourceManager that initializes via BeforeStartEvent, reuses the resource pipeline, and streams command logs over the backchannel. The CLI’s exec command is added (instead of a separate --operation exec), and both unit and E2E tests are updated to cover the new behavior.

Move exec initialization from a background service to event-driven in ExecResourceManager
Wire up exec logging through the backchannel (ExecAsync) and update DistributedApplicationBuilder
Add exec command to CLI, update interaction services, and expand test coverage

Reviewed Changes

Copilot reviewed 53 out of 54 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/Aspire.Hosting/Exec/ExecResourceManager.cs	New manager for exec resource initialization and log streaming
src/Aspire.Hosting/DistributedApplicationBuilder.cs	Configure exec options, subscribe to `BeforeStartEvent`
src/Aspire.Hosting/Exec/ExecOptions.cs	Define `ExecOptions` settings
src/Aspire.Hosting/Backchannel/AppHostRpcTarget.cs / BackchannelDataTypes.cs	Add `ExecAsync` and `CommandOutput` types
src/Aspire.Cli/Commands/ExecCommand.cs	Implement `exec` CLI command
src/Aspire.Cli/Interaction/IInteractionService.cs / ConsoleInteractionService.cs	Add `WriteConsoleLog` API and formatting
tests/Aspire.Cli.Tests/Commands/ExecCommandTests.cs / tests/Aspire.Cli.Tests/E2E/ExecTests.cs	Unit and E2E tests for exec scenarios

Files not reviewed (1)

src/Aspire.Cli/Resources/ExecCommandStrings.Designer.cs: Language not supported

Comments suppressed due to low confidence (2)

src/Aspire.Hosting/Exec/ExecResourceManager.cs:44

[nitpick] StreamExecResourceLogs contains complex logic for waiting, state transitions, and log streaming but lacks direct unit tests; adding targeted tests for resource initialization, waiting logic, and log output would improve confidence.

    public async IAsyncEnumerable<CommandOutput> StreamExecResourceLogs([EnumeratorCancellation] CancellationToken cancellationToken)

src/Aspire.Cli/Interaction/IInteractionService.cs:28

The new WriteConsoleLog method lacks an XML doc comment; consider adding a <summary> and parameter descriptions to align with existing interface documentation.

    void WriteConsoleLog(string message, int? lineNumber = null, string? type = null, bool isErrorMessage = false);

src/Aspire.Hosting/Exec/ExecResourceManager.cs

davidfowl · 2025-07-03T09:32:15Z

src/Aspire.Hosting/Exec/ExecResourceManager.cs

+        return targetExecResource switch
+        {
+            ProjectResource prj => BuildAgainstProjectResource(prj),
+            _ => throw new NotImplementedException(nameof(targetExecResource))


When this throws what is the experience? What crashes? How do you observe it?

refactored a bit - now any exception occured during CreateExecResource will be saved and then translated to the cli (user) in the same manner. Changed exception messages to be user-friendly and not having any implementation details.

davidfowl · 2025-07-03T09:32:57Z

src/Aspire.Hosting/Exec/ExecResourceManager.cs

+            annotation is EnvironmentAnnotation or EnvironmentCallbackAnnotation
+                       or ResourceRelationshipAnnotation or WaitAnnotation))


Why ResourceRelationshipAnnotation ?

it has the connection string expression; I am not sure if it is also located somewhere in the environment annotations

davidfowl · 2025-07-03T09:41:17Z

tests/Aspire.Cli.Tests/E2E/ExecTests.cs

+
+        var migrationName = "AddVersion";
+
+        var apiModelProjectDir = @$"{MSBuildUtils.GetRepoRoot()}\playground\DatabaseMigration\DatabaseMigration.ApiModel\DatabaseMigration.ApiModel.csproj";


This is going to fail on helix.

cc @joperezr @radical

this test is quarantined at a moment due to problems running it on the agent (there are a couple). I have an issue filed to take a look at this later.

src/Aspire.Hosting/Exec/ExecResourceManager.cs

mitchdenny · 2025-07-03T10:39:16Z

src/Aspire.Cli/Commands/ExecCommand.cs

+        var resourceOption = new Option<string>("--resource", "-r");
+        resourceOption.Description = ExecCommandStrings.TargetResourceArgumentDescription;
+        Options.Add(resourceOption);
+
+        var startResourceOption = new Option<string>("--start-resource", "-s");
+        startResourceOption.Description = ExecCommandStrings.StartTargetResourceArgumentDescription;
+        Options.Add(startResourceOption);


@DeagleGross this feedback shouldn't block the PR merging, just more wanted to trigger a conversation with @DamianEdwards about these switches.

I was wondering whether this should be --wait-for instead of --start-resource. I think this probably aligns better with how this executable resource might look if it was defined in the apphost itself.

Seems to me that waiting for the target resource would be an additional and dependent option to starting the target resource? i.e. they're not the same thing, I may or may not want to start the target resource. Perhaps this should instead be something like --resource-action with choices of none, start, wait-for, etc.? We would likely have to debate the default as the "optimum" default is likely very scenario driven, e.g. EF migration creation vs. container exec, etc. Maybe the default could be different depending on the kind of resource specified by --resource? Some things to consider.

davidfowl · 2025-07-03T15:40:19Z

src/Aspire.Hosting/Exec/ExecResourceManager.cs

+        _ = Task.Run(async () =>
+        {
+            await _resourceNotificationService.WaitForResourceAsync(execResource!.Name, targetStates: KnownResourceStates.TerminalStates, cancellationToken).ConfigureAwait(false);
+
+            // hack: https://github.com/dotnet/aspire/issues/10245
+            // workarounds the race-condition between streaming all logs from the resource, and resource completion
+            await Task.Delay(1000, CancellationToken.None).ConfigureAwait(false);
+
+            _resourceLoggerService.Complete(dcpExecResourceName); // complete stops the `WatchAsync` async-foreach below
+        }, cancellationToken);


@karolz-ms do you have any recommendations here?

@DeagleGross you shouldn't be completing the log stream. The system should do that when the execution ends.

unfortunately, that does not work as we would expect. DCP does not close the WatchAsync on its own once the resource completes. We need to complete it somehow today, otherwise cli interaction with just hang here.

I have filed a separate issue to work on this; for now we would have a Task.Delay as a workaround, and we will update it once we have a solution (either new API or different DCP behavior or whatever)

I had a conversation with @DeagleGross about this, and I think it is fine to take this implementation as is is for now, but we should use the issue that Dmitry has opened to dig in and understand why WatchAsync does not complete for resources that reach the final state (which is the case here) because I think it should, and I explained why in the related issue.

src/Aspire.Hosting/Exec/ExecOptions.cs

mitchdenny · 2025-07-04T04:36:25Z

src/Aspire.Hosting.Testing/DistributedApplicationTestingBuilder.cs

+    /// <returns>
+    /// A new instance of <see cref="IDistributedApplicationTestingBuilder"/>.
+    /// </returns>
+    public static IDistributedApplicationTestingBuilder Create(


What is the purpose of the changes in Aspire.Hosting.Testing?

I am trying to setup tests against existing apphost (in my case playground/DatabaseMigrations). I need to lookup an assembly like that: typeof(DatabaseMigration_AppHost).Assembly. I have hid it under internal + exposed to Aspire.Cli.Tests via InternalsVisibleTo.

About the approach: my approach with using an existing apphost with some dependency of resources setup gives a great debugging experience and a way to fully test running AppHost + Dcp + even streaming the logs via AppHostRpcTarget. Tests code represent cli in this case, and apphost is, well, apphost.

I would really love to keep such an approach - it allowed me to iterate quickly and basically checks that functionality works as intended e2e, and if you insist on it - I can move usage to other test apphost (for example TestingAppHost1), but I dont see many problems targeting playground.

This is the thing I'm now most concerned about with this PR. We've learned from experience that these kinds of tests tend to be less reliable and tend to get disabled and quarantined pretty quickly reducing test coverage.

As a team we need to come up with a better way to do end to end testing for the CLI which isn't quite so flaky.

mitchdenny · 2025-07-04T04:52:25Z

tests/Aspire.Cli.Tests/E2E/ExecTests.cs

+    private async Task<DistributedApplication> BuildAppAsync(string[] args, Action<DistributedApplicationOptions, HostApplicationBuilderSettings>? configureBuilder = null)
+    {
+        configureBuilder ??= (appOptions, _) => { };
+        var builder = DistributedApplicationTestingBuilder.Create(args, configureBuilder, typeof(DatabaseMigration_AppHost).Assembly)


I think for the test cases here I would like to avoid taking a project reference dependency on the database migration project. This might also alleviate the need to make public API changes to the DistributedApplicationTestingBuilder. Instead I think a more efficient approach (and a approach that helps better isolate issues) is to build an apphost in the test case itself then instansiate a backchannel to the apphost inside the testcase itself.

Instead I think a more efficient approach (and a approach that helps better isolate issues) is to build an apphost in the test case itself then instansiate a backchannel to the apphost inside the testcase itself.

Sorry, did not catch this idea. I answered about the approach taken here: #10240 (comment)

mitchdenny

Functionality wise this is working for me now (even for really short running commands). I think that we still have some more work to do though. Here are my high level notes:

Lets see if we can avoid making any public API changes to the DistributedTestApplicationBuilder (it seems like we've done this just to validate the scenario with the migration projects, my suggestion is do a smaller more focused set of tests, ones that focus on testing the apphost side,and ones that focus on testing the CLI side - mocking out the other side each time).
I think we need to get rid of the light background on the text we are rendering to the screen. Just don't set the background color and let the terminal use what it has. In that case rendering yellow for the pre-text might not be great.
exit codes. I think we should consider returning the exit code from the executable resource when it runs. At the moment regardless of whether the command succeeds or fails we get exit code 0 which isn't great for scripting. This means we might need to add an exit code to the command output which is nullable, but on the last command output we send back populate the value with the exit code and return that from the CLI side.

DeagleGross · 2025-07-04T09:48:01Z

Thanks for feedback Mitch!
I got rid of background in console; avoided public changes in Aspire.Hosting.Testing (though probably not in the way you expected); and I've added a check of exit code in the end of running ExecResourceManager:

        int? exitCode;
        if (_resourceNotificationService.TryGetCurrentState(dcpExecResourceName, out var resourceEvent) && (exitCode = resourceEvent?.Snapshot?.ExitCode) is not null)
        {
            yield return new CommandOutput
            {
                Text = "Aspire exec exit code: " + exitCode.Value,
                IsErrorMessage = false,
                Type = "exitCode"
            };
        }

This allows to have such experience showing the exit code in the end of command execution. I made it show with yet another color to have a visual difference between messages:

tests/TestingAppHost1/TestingAppHost1.AppHost/appsettings.Development.json

tests/Shared/DistributedApplicationTestingBuilderExtensions.cs

tests/Aspire.Cli.Tests/TestServices/TestConsoleInteractionService.cs

mitchdenny · 2025-07-04T11:51:57Z

Thanks for feedback Mitch! I got rid of background in console; avoided public changes in Aspire.Hosting.Testing (though probably not in the way you expected);

I think we really want to have the exit code be returned from the CLI process. I expect that people will want to script aspire exec and they'll need to use the exit codes to determine success/failure of the executable resources. Returning the exit code as text forces them to have to do something like grep the text output to extract the text output.

Why not just add a nullable field to the CommandOutput type that you set at the end of an execution cycle? Alternatively add another API call to the contract that allows you to explicitly query the exit code for the resource (although I figured that might be more involved).

mitchdenny

Lets ship it. Keep a close eye on the helix tests, we may need to quarantine and take a different approach if these tests fail.

DeagleGross added 4 commits July 3, 2025 07:39

Reapply "feat: aspire exec (#10061)" (#10227)

9e633a1

This reverts commit f845f5b.

via eventing

1a02fed

refactor to run

47750e9

drop dcp executor changes

4668013

Copilot AI review requested due to automatic review settings July 3, 2025 09:03

DeagleGross requested review from ReubenBond, eerhardt and radical as code owners July 3, 2025 09:03

DeagleGross requested a review from mitchdenny July 3, 2025 09:03

DeagleGross self-assigned this Jul 3, 2025

github-actions bot added the area-cli label Jul 3, 2025

Copilot AI reviewed Jul 3, 2025

View reviewed changes

src/Aspire.Hosting/Exec/ExecResourceManager.cs Outdated Show resolved Hide resolved

src/Aspire.Hosting/Exec/ExecResourceManager.cs Outdated Show resolved Hide resolved

DeagleGross added 3 commits July 3, 2025 11:06

dont duplicate type

99b9633

merge main

d3619f5

remove unused

51f850a

davidfowl reviewed Jul 3, 2025

View reviewed changes

src/Aspire.Hosting/Exec/ExecResourceManager.cs Show resolved Hide resolved

davidfowl reviewed Jul 3, 2025

View reviewed changes

src/Aspire.Hosting/Exec/ExecResourceManager.cs Outdated Show resolved Hide resolved

davidfowl reviewed Jul 3, 2025

View reviewed changes

src/Aspire.Hosting/Exec/ExecResourceManager.cs Outdated Show resolved Hide resolved

davidfowl reviewed Jul 3, 2025

View reviewed changes

remove IResourceSupportsExec

5208b9b

davidfowl reviewed Jul 3, 2025

View reviewed changes

src/Aspire.Hosting/Exec/ExecResourceManager.cs Outdated Show resolved Hide resolved

davidfowl reviewed Jul 3, 2025

View reviewed changes

src/Aspire.Hosting/Exec/ExecResourceManager.cs Outdated Show resolved Hide resolved

davidfowl reviewed Jul 3, 2025

View reviewed changes

src/Aspire.Hosting/Exec/ExecResourceManager.cs Outdated Show resolved Hide resolved

davidfowl reviewed Jul 3, 2025

View reviewed changes

src/Aspire.Hosting/Exec/ExecResourceManager.cs Outdated Show resolved Hide resolved

DeagleGross added 2 commits July 3, 2025 12:03

use extension to resolve DCP name

ace9dfc

simplify name of dynamic resource

6c702bf

mitchdenny reviewed Jul 3, 2025

View reviewed changes

address PR comments

11eb853

davidfowl reviewed Jul 3, 2025

View reviewed changes

mitchdenny reviewed Jul 4, 2025

View reviewed changes

src/Aspire.Hosting/Exec/ExecOptions.cs Outdated Show resolved Hide resolved

mitchdenny reviewed Jul 4, 2025

View reviewed changes

DeagleGross added 3 commits July 4, 2025 09:48

Merge branch 'main' into dmkorolev/aspire-exec-2

ff83c84

dont set background

8d35d43

hide distributedapplicationtestingBuider under internal

af633e2

add exit code message

90f4a1a

mitchdenny reviewed Jul 4, 2025

View reviewed changes

tests/TestingAppHost1/TestingAppHost1.AppHost/appsettings.Development.json Outdated Show resolved Hide resolved

mitchdenny reviewed Jul 4, 2025

View reviewed changes

tests/Shared/DistributedApplicationTestingBuilderExtensions.cs Outdated Show resolved Hide resolved

rollback to main state

ef2388b

mitchdenny reviewed Jul 4, 2025

View reviewed changes

tests/Aspire.Cli.Tests/TestServices/TestConsoleInteractionService.cs Outdated Show resolved Hide resolved

DeagleGross added 2 commits July 4, 2025 13:32

remove test setup

2ea44c6

add a callback

a0e70d6

DeagleGross added 3 commits July 4, 2025 14:12

supply exit code from exec resource

20049d7

test exit code and dont display apphost logs

898a799

build apphost

592b308

mitchdenny approved these changes Jul 4, 2025

View reviewed changes

DeagleGross enabled auto-merge (squash) July 4, 2025 12:58

DeagleGross merged commit 7f4cdf7 into main Jul 4, 2025
252 checks passed

DeagleGross deleted the dmkorolev/aspire-exec-2 branch July 4, 2025 13:09

This was referenced Jul 4, 2025

feat: run apphost in tool mode #9912

Closed

[WIP] feat: aspire exec command support #9842

Closed

chore: aspire exec report error when executable failed to start #10277

Merged

[New article]: Aspire Exec dotnet/docs-aspire#4026

Closed

lvde0 mentioned this pull request Jul 16, 2025

Microsoft.Extensions.ApiDescription.Server: Aspire Exec support dotnet/aspnetcore#62750

Open

1 task

github-actions bot locked and limited conversation to collaborators Aug 6, 2025

		annotation is EnvironmentAnnotation or EnvironmentCallbackAnnotation
		or ResourceRelationshipAnnotation or WaitAnnotation))


		var migrationName = "AddVersion";

		var apiModelProjectDir = @$"{MSBuildUtils.GetRepoRoot()}\playground\DatabaseMigration\DatabaseMigration.ApiModel\DatabaseMigration.ApiModel.csproj";

feat: aspire exec 2 #10240

feat: aspire exec 2 #10240

Uh oh!

Conversation

DeagleGross commented Jul 3, 2025

Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mitchdenny left a comment • edited by DeagleGross Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DeagleGross commented Jul 4, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mitchdenny commented Jul 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mitchdenny left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

mitchdenny left a comment •

edited by DeagleGross

Loading

mitchdenny commented Jul 4, 2025 •

edited

Loading