feat: aspire exec

[DeagleGross]

is the result of experiments #9842 and #9912

Description

This pull request introduces a new exec command to the Aspire CLI, allowing users to execute commands on a target resource through the app host. It also includes supporting changes to the backchannel, interaction services, and overall CLI infrastructure to enable this functionality.

Implementation

As discussed here feature is built fully on top of existing capabilities - aspire exec forces apphost on the startup to add a new ExecutableResource to the DCP resources, and then via streams the logs of the resource back to cli backchannel via ResourceLoggerService and manages the lifetime of the resource via ResourceNotificationService.

Moreover, new resource inherits Environment, ResourceRelationship and WaitFor annotations of the target resource in order to be launched exactly in the same configuration as the target resource.

There are 2 types of events I am waiting for from ResourceNotificationService:

1. when executable resource reaches KnownResourceStates.Running - i am changing the type of the log from "waiting" to "running". This is useful to have more interaction from the UI side and show that command is not yet being executed, but is waiting for other resources to start up (yellow text in the video)
2. when executable resource reaches KnownResourceStates.TerminalStates - we know there will be no logs coming, and we can complete the logger then. It will stop the async-foreach of watching the logs and cli will also understand that it can continue with the flow.

Extra configuration

1. Instead of specifying --resource one can write --start-resource forcing the target resource to start before the command execution.
2. --apphost-keepalive is a flag which will not force apphost shutdown from the cli, but simply exists the cli after command is executed.

Demo

Video shows execution of such aspire exec:

aspire exec --project .../TestingAppHost1.AppHost.csproj --resource mywebapp1 --add-postgres -- dotnet ef database update

WebApp does not have the connection string defined anywhere explicitly, it only has the DbContext registration like:

builder.Services.AddDbContextPool<MyAppDbContext>(options =>
{
    var connectionString = builder.Configuration.GetConnectionString("postgresDb");
    options.UseNpgsql(connectionString);
});

And AppHost only defines the pgSql resource and the webapp referencing and waiting for db:

if (args.Contains("--add-postgres"))
{
    pgsqlDb = builder
        .AddPostgres("postgres1", 6000, builder.AddParameter("pgsqluser"), builder.AddParameter("pgsqlpass", secret: true))
        .AddDatabase("postgresDb");
}

...

if (args.Contains("--add-postgres") && pgsqlDb is not null)
{
    webApp.WithReference(pgsqlDb).WaitFor(pgsqlDb);
}

That shows that connection string is coming from the apphost's runtime knowledge about how postgresDb resource is being built and launched.

aspire.exec.local.tool.migrations.add.mp4

aspire.exec.local.tool.database.update.mp4

Fixes #9859

[DeagleGross]

TODO:

• localize cli
• write tests to run different types of aspire execs and expect output logs

[joperezr]

NIT: Should this be apphost instead? I could see confusion for people thinking project means a project resource.

[DeagleGross]

It makes sense, but I am following the convention other commands have. For example RunCommand also refers to apphost path as --project, see

aspire/src/Aspire.Cli/Commands/RunCommand.cs

Line 81 in 3ec9e5a

var passedAppHostProjectFile = parseResult.GetValue<FileInfo?>("--project");

I think it will only bring confusion to users if in exec apphost flag would change from --project to --apphost.

[BrennanConroy]

Does this work? Should there be a test with an argument with a quoted string?

[DeagleGross]

added test with quoted string - it is running dotnet build "MyRandom.csproj" and it works! see Exec_EchoWithQuotedString_ShouldProduceLogs

[DeagleGross]

actually if you have other idea on how to parse / send the command to apphost - let me know. Aspire apphost does not have commandLineParser installed on its side, so it can only take the args passed from cli. I decided to pack the command in such a way, and I know it is not pretty, but it works at least.

[BrennanConroy]

This is a bit gnarly, looks like it was copied from other commands. Wonder if we can turn it into a helper method that handles all these different exception types.

[DeagleGross]

do you mind doing it in the follow-up PR? I can refactor all other commands as well

[BrennanConroy]

This seems like it should be an enum

[DeagleGross]

this is hard to achieve - apphost will have its own type of enum, and i have to somehow tell both cli and apphost to serialize/deserialize the enum in the same manner.

Nowdays apphost does not have the serialization context, and there is an effort to provide better experience, but not yet merged + requires serialization context for apphost:
#10058

lets do in the follow-up PR if possible.

[DeagleGross]

filed #10201