[docs] Document HTTP command timeout behavior

[aspire-repo-bot]

Documents changes from microsoft/aspire#18986

@JamesNK

Targeting release/13.5 based on the source PR milestone 13.5.

Why

PR #18986 removes the implicit 100-second HttpClient timeout for HTTP commands added with WithHttpCommand that do not specify HttpCommandOptions.HttpClientName. Previously, long-running HTTP commands (for example, database migrations) would fail once they exceeded the default HttpClient.Timeout. The existing http-commands.mdx page never documented timeout or cancellation behavior, so this is a documentation gap.

Changes

• Added a new HTTP command timeouts section to src/frontend/src/content/docs/fundamentals/http-commands.mdx explaining:
  • The default (unnamed) HttpClient now has Timeout.InfiniteTimeSpan, so the outgoing request can wait until a response or client-side cancellation.
  • Canceling from the dashboard cancels the client-side HTTP request, but does not guarantee that server-side work already started by the endpoint also stops.
  • How to opt into a finite timeout by configuring a named HttpClient via IHttpClientFactory and setting HttpCommandOptions.HttpClientName.
  • Included a C# code sample showing how to register a named client with a custom timeout.

Files modified

• src/frontend/src/content/docs/fundamentals/http-commands.mdx (updated, new section added)

No new pages were created; only the existing HTTP commands page was updated.

Generated by PR Documentation Check · auto · 39.7 AIC · ⌖ 5.53 AIC · ⊞ 19.6K · ◷

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1515. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.

[Copilot]

Pull request overview

This PR updates the existing HTTP commands documentation to describe the post-#18986 timeout behavior for WithHttpCommand, clarifying that HTTP commands no longer inherit the default 100-second HttpClient.Timeout unless a named client with a configured timeout is used.

Changes:

• Added a new HTTP command timeouts section describing the default infinite timeout for unnamed HTTP clients used by HTTP commands.
• Documented how to opt into a finite timeout via HttpCommandOptions.HttpClientName and a named HttpClient registered with IHttpClientFactory.
• Included a C# example showing named client registration with a custom timeout and wiring it into WithHttpCommand.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[David Pine (IEvangelist)]

Docs-accuracy review — PR #1515 “[docs] Document HTTP command timeouts”

Source of truth (Phase A): microsoft/aspire branch release/13.5 @ e076d8e427cb3afb528dbd605acd74c3aea69f94. The documented change corresponds to source PR microsoft/aspire#18986 (“Disable default timeout for HTTP commands”, commit 01646664f2), which is present on this branch.

Claims extracted: 7 verifiable + illustrative narrative. Verdicts: ✅ verified 7 · ◑ verified-with-nuance 0 · ❔ unverifiable 0 · ❌ contradicted 0.

Phase B (doc-tester, blind): Exercised 1 route — /fundamentals/http-commands/. Live page renders and the new HTTP command timeouts section slots logically between Considerations… and Add a custom HTTP command. Documented C# sample compile was attempted with the real Aspire 13.5 toolchain but could not run because the sandbox has no NuGet connectivity (staging darc feed + nuget.org both unreachable). Critical: 0 · Warnings: 0 (one environment-limited knowledge gap noted).

Verdict: COMMENT — every non-narrative claim verifies cleanly against release/13.5, and no doc defects were found; downgraded from approve only because Phase B could not complete the live compile/run of the sample in this offline environment.

---

Phase A — Claim verification

No contradicted or unverifiable claims, so there are no blocking inline comments. Full evidence below.

✅ All 7 claims verified (evidence)

#	Claim (normalized)	Verdict	Evidence in microsoft/aspire@release/13.5
C1	The unnamed (default) HttpClient used for an HTTP command has HttpClient.Timeout set to Timeout.InfiniteTimeSpan, so by default the request has no timeout.	✅ verified	src/Aspire.Hosting/ResourceBuilderExtensions.cs (WithHttpCommand callback): if (commandOptions.HttpClientName is null) { … httpClient.Timeout = Timeout.InfiniteTimeSpan; }. Also src/Aspire.Hosting/ApplicationModel/HttpCommandOptions.cs remarks: “When this property is null, the default HttpClient is used and its HttpClient.Timeout is set to Timeout.InfiniteTimeSpan.”
C2	Without this, long-running commands would fail at HttpClient’s default 100-second timeout.	✅ verified	Source comment in the same block (commit 01646664f2): “HTTP commands are user-cancelable and may legitimately run longer than HttpClient's 100-second default.” 100 s is the documented .NET HttpClient.Timeout default.
C3	HttpCommandOptions.HttpClientName (a string?) exists.	✅ verified	src/Aspire.Hosting/api/Aspire.Hosting.cs: public string? HttpClientName { get { … } set { } }; declared in HttpCommandOptions.cs.
C4	When HttpCommandOptions.HttpClientName is specified, the named HttpClient is used as configured, including its Timeout.	✅ verified	Callback resolves CreateClient(commandOptions.HttpClientName ?? Options.DefaultName) and only overrides the timeout when the name is null; XML doc: “Specify a named client to preserve its configured timeout.”
C5	builder.AddProject<…>("api").WithHttpCommand(path: …, displayName: …, commandOptions: new HttpCommandOptions { HttpClientName = … }) is a valid call.	✅ verified	api/Aspire.Hosting.cs overload: WithHttpCommand<TResource>(…, string path, string displayName, string? endpointName = null, string? commandName = null, HttpCommandOptions? commandOptions = null). With named args and no endpoint argument, this binds unambiguously (the sibling endpointSelector overload has a required parameter and is eliminated).
C6	HTTP commands are user-cancelable from the dashboard; the command stops when canceled.	✅ verified	Request is sent with the command’s token: httpClient.SendAsync(request, context.CancellationToken), with catch (OperationCanceledException) when (context.CancellationToken.IsCancellationRequested).
C7	A finite timeout is opted into via a named client configured with IHttpClientFactory (builder.Services.AddHttpClient("name", client => client.Timeout = …)).	✅ verified	Standard Microsoft.Extensions.Http API; referenced by the source XML docs (HttpClientFactoryServiceCollectionExtensions.AddHttpClient(IServiceCollection, string)) as the mechanism to configure “a specific handler, timeout, or other options.”

Narrative (noted, non-blocking): examples such as “database migrations or other admin actions” are illustrative and match the source’s own framing (“admin actions”).

---

Phase B — Doc-tester results (blind, no source consulted)

Focus area: /fundamentals/http-commands/ → new “HTTP command timeouts” section (the only changed content).
Tester: doc-tester skill · Date: 2026-08-18

Summary

Category	Passed	Failed	Warnings
Content accuracy	1	0	0
Navigation / placement	1	0	0
Code examples (compile/run)	0	0	0¹

¹ Not executed — see knowledge gap below.

Passed checks

• Page renders and is healthy. /fundamentals/http-commands/ loads (HTTP 200); heading/TOC structure is intact (HTTP command APIs → Considerations when registering HTTP commands → Add a custom HTTP command → …).
• Section placement is coherent. The new ## HTTP command timeouts section is inserted between Considerations… and Add a custom HTTP command, which reads in a logical order for a user learning the feature.
• Blind read is clear and self-consistent. The section states the default (no timeout / Timeout.InfiniteTimeSpan), explains that commands remain cancelable from the dashboard, and shows the opt-in path (named HttpClient via IHttpClientFactory + HttpCommandOptions.HttpClientName) with a runnable-looking sample. Terminology (HttpClient, IHttpClientFactory, HttpCommandOptions) is consistent with the rest of the page.
• No new internal links introduced by the section, so no broken-link risk added.

Critical issues

None.

Warnings

None.

Knowledge gap / limitation

• Live compile/run of the C# sample could not be performed in this run. A starter AppHost was created with the Aspire 13.5.0 CLI and the documented sample was pasted verbatim (only substituting the generated project symbol for Projects.Api), but dotnet build/restore failed with NU1301 TLS-handshake errors to both the darc staging feed (pinned Aspire.AppHost.Sdk/13.5.0) and api.nuget.org. This is an environment/network limitation, not a documentation problem; the sample’s APIs are independently confirmed to exist in release/13.5 (Phase A, C3–C5, C7). One item therefore remains unobserved rather than verified: that builder.Services.AddHttpClient(...) resolves in an AppHost via implicit/global usings without an explicit using — this is consistent with the page’s other code samples (which also omit usings), so no change is recommended.

Recommendations

• No documentation changes required based on this review. If a future run has NuGet connectivity, re-run the sample end-to-end (build + trigger the command from the dashboard) to positively confirm the 30-second named-client timeout behavior and the infinite default.

[Adam Ratzman (adamint)]

One cancellation detail could be clearer.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/frontend/src/content/docs/fundamentals/http-commands.mdx:45

• The first paragraph in this new section is a bit hard to parse and is slightly ambiguous about when the infinite timeout applies. Consider rephrasing to explicitly tie the default behavior to when HttpCommandOptions.HttpClientName is not specified, and avoid the redundant “HttpClient … HttpClient.Timeout” wording.

HTTP commands are user-cancelable from the dashboard, so by default the request the command sends has no timeout: the unnamed `HttpClient` used to send the request has its `HttpClient.Timeout` set to `Timeout.InfiniteTimeSpan`. This allows long-running commands, such as ones that trigger database migrations or other admin actions, to run for as long as needed without failing due to `HttpClient`'s default 100-second timeout. Canceling the command from the dashboard cancels this client-side HTTP request through the command's cancellation token; it doesn't guarantee that server-side work already started, such as a migration, also stops.

src/frontend/src/content/docs/fundamentals/http-commands.mdx:43

• This page has a Japanese localized counterpart (src/frontend/src/content/docs/ja/fundamentals/http-commands.mdx) that currently doesn’t include the new “HTTP command timeouts” section. To avoid localized docs drifting out of sync, please update the JA page (or add a tracking issue if localization is handled separately).

## HTTP command timeouts

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.