Custom Resource Commands - Dynamic Command-Line Arguments

[BaconSoap]

Goal: add a custom resource command that conditionally sets a command-line argument before running the resource/executable.

this --migrate flag is set for a single run by the command

Using EF migrations in an Aspire world require some workarounds vs command-line tooling, with the most appealing & currently documented being a custom command-line app, managed via the dashboard.

With the new custom resource commands I wanted to add a single MyProject.Tools executable, with different in-UI commands for applying migrations, run certain seeding, etc. This was easy to achieve using a "set flag + run app" pair with a global bool:

from memory

var shouldMigrate = false;
builder.AddProject<Projects.MyProject_Cli>("my-project-tools")
  .WithArgs(c => {
    if (shouldMigrate) {
      c.Args.Add("--migrate");
    }
  })
  .WithCommand("migrate-db", "Migrate DB", context => {
    shouldMigrate = true;
    return CommandResults.Success();
  });

but not very pleasant - requires multiple interactions and it's not clear what the current state is. By #6015 , there's not a built-in way that's exposed to end users.

The built-in commands (see here - very helpful for reference!) use ApplicationOrchestrator, which is internal - but with a simple signature, easy to get via reflection 😎.

---

Warning

This uses reflection and isn't very hardened - just sharing my workaround to what I suspect is a growing need + some thoughts on improvements.

Here's a gist that uses reflection to add a proxy class over ApplicationOrchestrator, with the .Start() method implemented (since that's all I needed). There are definitely better ways to do this, but with the baseline being "reflection of library's internal methods" I didn't put in too much effort. It's likely not very safe for long-running operations, and would need effort to prevent running multiple conflicting commands.

To use:

1. copy the extension method + proxy class into your solution
2. in your apphost's builder, call builder.Services.AddApplicationOrchestratorProxy()
3. in the apphost builder's scope, create a variable to hold the flag state (in my case a boolean, likely an enum once I add more flags)
4. Configure the resource for the new custom command - see this example
   1. Call .WithArgs(c => /** conditionally call c.Args.Add() based on the flag or other logic **/)
   2. Call .WithCommand() to configure your custom command. This should set the global flag, resolve the proxy, start the app, and unset the flag when done.
   3. Optional: call .WithExplicitStart() to prevent the app from running by default, if you want to require an explicit action
   4. Optional: configure the command with an icon from the catalog.
   5. Optional: set isHighlighted, which moves the icon from the submenu to an (icon-only) option in the main bar - makes it one-click but requires a bit of duplication if you also want it in the list of text items.

If successful, a new option will appear in your resource's section in the Aspire dashboard - both the main table, and in places like the log details toolbar. If configured as a highlighted option, it will be an icon next to the start/stop/logs icons.

---

Aspire team: in general, but especially with the EF migrations story strongly encouraging the "separate executable" scenarios, I feel it'd be helpful to have an official way to do one of:

1. temporarily update annotations for a specific start of a resource (*understanding this may break the abstraction model and be a bad idea)
2. manage resource lifecycle within a command via its context object
3. (or) expose an injectable, minimal orchestrator proxy to use the global state approach

A combo of 1 + 2 or 3 would solve this story in a fairly flexible way, without being overly tied to a specific resource type or encouraging loose global state. 2 or 3 alone would also work well but (unless I'm missing something) wouldn't feel as clean/safe for this use case.

I also played around with the app instead being a minimal server + HTTP commands, but didn't want to leave that running...

Please let me know if I missed an easier/safer option! And thanks for the tooling & platform, every update is easing modern dev pains.

[davidfowl]

cc @DamianEdwards

[rob-king-volpara]

This would also be handy for running end-to-end tests from the Aspire dashboard where we could have custom commands that trigger different test filters.

[davidfowl]

What’s the scenario for running tests from the dashboard?

[rob-king-volpara]

As part of a shift-left apporach, we have a bunch of Playwright automation tests that we want to run against the application during development. We don't always want to run all tests so we use filters on the command-line to cherry-pick the tests we want to run.

builder.AddProject<Tests_SmokeTest>("tests-smoke")
    .WithExplicitStart()
    .WithArgs("--filter", "App_Home_LoadsSuccessfully");

The dev can manually fire the tests off, but there isn't a way to specify the args at runtime. I would ideally like to add custom commands for each set of args so they appear on the dropdown.

Maybe we could pre-define sets of args and then we choose a set when the project starts (perhaps limited only to projects with WithExplicitStart())?

builder.AddProject<Tests_SmokeTest>("tests-smoke")
    .WithExplicitStart()
    .WithArgsSet("SmallTest", "--filter", "App_Home_LoadsSuccessfully")
    .WithArgsSet("BiggerTest", "--filter", "SomeBroaderTestClass")
    .WithArgsSet("WholeShebang", "--filter", "SomeOtherFilter");

[vandenbergjp]

I also think this would be very useful. I have a couple of scenarios that I'm thinking of.

I have a console application to run database migrations. I would like to start the app with different configurations. For example:

• migrate up
• migrate down
• migrate to versions 'x'

I have a console application to seed the database. I would like to start the app to seed with different options, like small, medium or large dataset.

Also, for running different test sets as @rob-king-volpara mentioned could be useful.

My current solution is to add the same project ((WithExplicitStart)) multiple times with different values for environment variables to the builder. It would be very nice if it was possible to add it only once but start it manually with different environment variables.

I tried to do this with Commands, but could not figure out how to change the environment variables and launch the app.

[BaconSoap]

The new Interaction Service looks to solve this (and then some) neatly - thanks! Will be giving it a go when I upgrade.

[vandenbergjp]

The interaction service looks really nice. I think I can use it to ask for information I need for running the resource. The piece I am missing is: how can i start an Aspire resource from a command using this information? So, for example, how can I ask: 'How many customers do you want to create?' and then start a resource (console app project that has a reference to the database and can seed data) and pass in the number of customers to create (e.g. as an environment variable).

I read that in 9.4 there is a new ResourceCommandService that you can use to execute command. Maybe I'm looking for something similar to start/execute the resource I created the command on (and pass in some additional environment variables).

[davidfowl]

I made an example here using 9.4:

https://github.com/davidfowl/AspireDynamicCommand