Introduce CommandOptions & HttpCommandOptions

[DamianEdwards]

Description

React to feedback on API review: #7811 (comment)

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
• Does the change make any security assumptions or guarantees?
  • No
• Does the change require an update in our Aspire docs?
  • Yes
    • Is this introducing a breaking change?
      • Yes
        • [Breaking change]: WithCommand obsolete, call WithCommand overload that accepts CommandOptions instead docs-aspire#2888

[Copilot]

Pull Request Overview

This PR introduces a new configuration type, HttpCommandOptions, along with corresponding updates to the WithCommand and WithHttpCommand extension methods to consolidate various command settings into a single options object. Key changes include:

• Adding HttpCommandOptions inheriting from CommandOptions to encapsulate HTTP command configuration.
• Updating the WithCommand and WithHttpCommand overloads to accept a CommandOptions/HttpCommandOptions parameter in place of multiple individual parameters.
• Refactoring documentation and tests to reflect and validate the new API design.

Reviewed Changes

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

Show a summary per file

File	Description
src/Aspire.Hosting/ApplicationModel/HttpCommandOptions.cs	New HttpCommandOptions class introduced for HTTP command configuration.
src/Aspire.Hosting/ResourceBuilderExtensions.cs	Updated extension methods to leverage commandOptions and updated XML documentation.
src/Aspire.Hosting/ApplicationModel/CommandOptions.cs	New base CommandOptions class created and used across command APIs.
src/Aspire.Hosting/ApplicationModel/HttpCommandContext.cs	Updated XML doc comments to reference the new overloads.
tests/Aspire.Hosting.Tests/WithHttpCommandTests.cs	Modified tests to use the new overloads with commandOptions.
tests/Aspire.Hosting.Tests/Dashboard/DashboardServiceTests.cs	Updated tests to replace the obsolete overload with the new commandOptions parameter.

Comments suppressed due to low confidence (1)

src/Aspire.Hosting/ApplicationModel/HttpCommandOptions.cs:7

• The XML summary appears to have an extra '/>' at the end of the documentation comment. Please remove the extraneous characters to ensure proper XML formatting.

/// Optional configuration for resource HTTP commands added with <see cref="ResourceBuilderExtensions.WithHttpCommand{TResource}(IResourceBuilder{TResource}, string, string, string?, HttpCommandOptions?)"/>."/>

[mitchdenny]

commandOPtions.UpdateState ?? CommandOptions.Default.UpdateState ?

[DamianEdwards]

CommandOptions.Default.UpdateState is null by default so that it can be detected whether one was set or not.

[mitchdenny]

LGTM

[DamianEdwards]

@IEvangelist RE the pattern-matching suggestion, it can't be used with KnownResourceStates as pattern matching requires constant values when comparing to strings.

[IEvangelist]

@IEvangelist RE the pattern-matching suggestion, it can't be used with KnownResourceStates as pattern matching requires constant values when comparing to strings.

@DamianEdwards Ah, ok! I that these were an enum...that's the KnownResourceState type I was thinking, which caters nicely to the compile time const constraint on the pattern matching suggestion. I'm seeing that KnownResourceStates.* fields as static readonly instead of const, which would allow for pattern matching.