microsoft / microsoft/aspire

Consider clearer naming for HttpCommandOptions.GetCommandResult alongside PrepareRequest

Open
#20,114 0 comments 0 reactions 0 assignees View on GitHub
needs-area-label
Dominant language
C#
Stars
6.3k
Forks
991
Avg merge
2d 15h
Merged PRs (30d)
196

Description

### Is there an existing issue for this?

- [ ] I have searched the existing issues

### Is your feature request related to a problem? Please describe the problem.

`HttpCommandOptions` exposes two callbacks for the HTTP command lifecycle: `PrepareRequest` and `GetCommandResult`. The names do not read as a natural pair. `PrepareRequest` clearly describes work supplied by the caller, while `GetCommandResult` sounds more like a getter to invoke than a callback that processes the HTTP response and determines the command outcome.

This is particularly noticeable in commands that build a JSON request from invocation arguments and then transform the response into a Markdown summary for the dashboard. The options-based structure is useful, but the response callback's name makes the API harder to discover and explain.

### Describe the solution you'd like

Consider clearer response-callback naming, such as **`PrepareRequest` / `ProcessResponse`**, while preserving compatibility for existing users. This is a design proposal, not a request for an unconditional breaking rename.

Illustrative proposed usage:

```csharp
commandOptions: new HttpCommandOptions
{
Method = HttpMethod.Post,
PrepareRequest = PrepareSquaresImport,
ProcessResponse = CreateImportSummary
}
```

The response handler would keep the existing semantics: receive the HTTP response context and return an `ExecuteCommandResult`, including success/failure, message, and optional text/JSON/Markdown result data.

Please evaluate:

- Whether `ProcessResponse` or another name more clearly communicates the existing callback's role.
- A compatibility-preserving rename/migration strategy or alias, including whether the additional API surface is worth the improvement.
- If an alias is introduced, explicitly define behavior when both names are configured; avoid silently ignoring one handler.
- Consistent naming for future polyglot exports and related documentation/examples.

An alternative considered was moving the response handler into a direct `WithHttpCommand` overload parameter to mirror `WithCommand`. That reads well for response-only commands, but becomes asymmetric when `PrepareRequest` remains nested in options. Keeping both lifecycle callbacks together seems more consistent.

Named handlers already improve readability with the current API (`PrepareRequest = PrepareSquaresImport`, `GetCommandResult = CreateImportSummary`), but do not address the discoverability/naming concern itself.

### Additional context

Related but separate: #20113 tracks exposing the missing response callback to TypeScript and other polyglot AppHosts. This issue concerns API naming and ergonomics, not that capability gap.

The existing callback is defined in `src/Aspire.Hosting/ApplicationModel/HttpCommandOptions.cs`. Any change should preserve current behavior, including the callback taking precedence over `ResultMode` and being invoked for both successful and unsuccessful HTTP responses.

Contributor guide

Open the contributing guide

Research direction

Start by reading src/Aspire.Hosting/ApplicationModel/HttpCommandOptions.cs and trace the existing GetCommandResult behavior, including its precedence over ResultMode and handling of successful and unsuccessful responses. A complete outcome would choose a response-callback name, define compatibility and dual-configuration behavior, and decide whether the added API surface and related documentation are worthwhile.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
api, developer-experience
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.