I spend a lot of time testing and debugging APIs, and so do my AI agents. Lately I notice that my agents lose time and tokens on it. They look for the right port, guess at endpoints, fight with a terminal, and try to get the database back into a known state. Every run starts with the same detective work.
So for this series of posts I picked one scenario and I’m sticking with it: the API-testing loop. The goal is to adapt Aspire so that I (and my agents) can debug and test easily and efficiently.
Note: this post is part of a series about the demos from my session “Bending Aspire to your will”.
The app is the aspire-shop sample: a frontend, a catalog service, a basket service, a catalog DB manager, PostgreSQL and Redis. The loop I run by hand looks like this:
- Get the OpenAPI spec
- Fire a test call at an endpoint
- Reset the state for a repeatable run
- Browse and try the API in one place
Out of the box, that means four tools and a handful of terminals. The goal is to do all of it from the Aspire graph.
We start with the first step. aspire run gives you a working dashboard with all resources, but the defaults stop quickly:
- I can’t tell my resources apart at a glance.
- The links in the summary are not the ones I want to click.
- To get the OpenAPI spec, I open a browser or a REST client, look up the port, and type the URL. Again.
Let’s try to fix this!
Icons and URLs: one line each
Both are just annotations on the resource. WithIconName takes any Fluent UI system icon name:
builder.AddProject<Projects.AspireShop_Frontend>("frontend")
.WithIconName("window")
.WithExternalHttpEndpoints()
.WithUrls(context =>
{
context.Urls.Clear();
context.Urls.Add(new() { Url = "/", DisplayText = "Online Store", Endpoint = context.GetEndpoint("https") });
context.Urls.Add(new() { Url = "/cart", DisplayText = "Shopping Basket", Endpoint = context.GetEndpoint("https") });
});
Instead of https://localhost:7123/, the dashboard now shows “Online Store” and “Shopping Basket”.
Remark: Urls.Clear() removes all URLs, including the ones Aspire adds by default. Everything you want to keep has to be added back.
The other resources get the same treatment with a one-liner: .WithIconName("database") on the catalog DB manager, "book" on the catalog service, "cart" on the basket service.
Export the OpenAPI spec as a command
Now the more interesting part. I download the OpenAPI document of the catalog service with curl all the time. So why not make that a button on the resource?
WithProcessCommand wraps a local executable as a dashboard command:
#pragma warning disable ASPIREPROCESSCOMMAND001
catalogService.WithProcessCommand(
commandName: "export-openapi",
displayName: "Export catalog OpenAPI",
processSpecFactory: context =>
{
var exportDirectory = Path.Combine(builder.AppHostDirectory, "artifacts", "openapi");
Directory.CreateDirectory(exportDirectory);
var timestamp = DateTimeOffset.UtcNow.ToString("yyyyMMdd-HHmmss-fffffff", CultureInfo.InvariantCulture);
var outputPath = Path.Combine(exportDirectory, $"catalog-openapi-{timestamp}.json");
context.Logger.LogInformation("Exporting catalog OpenAPI to {OutputPath}.", outputPath);
return new ProcessCommandSpec("curl")
{
Arguments =
[
"--fail",
"--silent",
"--show-error",
"--remove-on-error",
"--connect-timeout", "10",
"--max-time", "30",
"--output", outputPath,
"--write-out", "OpenAPI export destination: %{filename_effective}\nHTTP status: %{http_code}\n",
new Uri(new Uri(catalogEndpoint.Url), "/openapi/v1.json").AbsoluteUri,
],
};
},
commandOptions: new ProcessCommandOptions
{
IconName = "ArrowDownload",
IsHighlighted = true,
UpdateState = context => context.ResourceSnapshot.HealthStatus is HealthStatus.Healthy
? ResourceCommandState.Enabled
: ResourceCommandState.Disabled,
});
#pragma warning restore ASPIREPROCESSCOMMAND001
A few things worth pointing out:
- The process spec is a factory. The endpoint URL is resolved when you click the button, not when the AppHost builds the graph. At build time the port isn’t known yet.
IsHighlighted = trueputs the command directly on the resource row instead of in the overflow menu.UpdateStatedisables the button until the service is healthy, so you can’t export from a service that isn’t running.--failand--remove-on-errormake sure you never end up with a JSON file that is actually an HTTP error page.
Remark: WithProcessCommand is experimental, hence the ASPIREPROCESSCOMMAND001 pragma. The API can change or disappear. I tested this with Aspire 13.6.5 on .NET 10.
Click the button and a timestamped catalog-openapi-*.json appears in artifacts/openapi next to your AppHost. The output of curl shows up in the resource logs.
That’s it! A few lines in the AppHost, and a manual step I repeated every day is now one click.




