Consider clearer naming for HttpCommandOptions.GetCommandResult alongside PrepareRequest
- 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
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