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");