Generate back-compat overload when a service method gains a new optional non-body parameter

[Copilot]

Adding an optional parameter to a service method is non-breaking in TypeSpec but breaks generated C# clients (callers binding to the old method signature fail to resolve). The generator now mirrors the Service-Driven Evolution guidance and emits a hidden overload matching the previous contract's signature.

Changes

• ClientProvider.BuildMethodsForBackCompatibility — after parameter reordering, scans LastContractView.Methods for previous signatures whose parameters are a same-order subset of a current method, where every extra current parameter is optional and non-body. Emits a hidden [EditorBrowsable(Never)] ScmMethodProvider overload (same ScmMethodKind as the current method) that delegates to the current method via the This.Invoke(string methodName, IReadOnlyList<ValueExpression> arguments) snippet, passing default for each new parameter. Async overloads delegate without await so the back-compat method itself remains non-async. The reordering and new-optional-parameter passes are factored into private helpers (ProcessBackCompatForParameterReordering and ProcessBackCompatForNewOptionalParameters) which share a single currentMethodSignatures dictionary and mutate the same materializedMethods list. The new-optional-parameter pass skips ScmMethodProviders with Kind == CreateRequest and only generates overloads for matched candidates whose Kind is Convenience or Protocol, inheriting that Kind/ServiceMethod from the current method. The candidate match collapses the ScmMethodProvider / Convenience|Protocol filter into the candidates loop's pattern match, and currentMethodSignatures.TryAdd is reused both for dedup and to make new overloads visible to subsequent iterations (no auxiliary lists or sets).
• Body parameters are intentionally excluded per the linked guidance, since adding a body parameter typically reflects a schema change handled elsewhere.
• BackCompatibilityChangeCategory.SvcMethodNewOptionalParameterOverloadAdded — new category surfaced in the emitter end-of-run summary.
• Tests — BackCompatibility_NewOptionalNonBodyParameterAdded, BackCompatibility_MultipleNewOptionalNonBodyParametersAdded, BackCompatibility_NewOptionalNonBodyParameterAddedWithModelBody (covers an InputModelType request body), BackCompatibility_NewOptionalNonBodyParameterAddedWithPathAndHeaderParameters (covers a method whose previous contract mixes a path parameter with a required query and a required header), BackCompatibility_NewOptionalBodyParameterDoesNotAddBackCompatOverload, BackCompatibility_NewRequiredParameterDoesNotAddBackCompatOverload. All six tests run TypeProviderWriter.Write() on the affected client wrapped in a FilteredMethodsTypeProvider so the expected .cs fixtures under TestData/ClientProviderTests/ only contain the affected operation's protocol + convenience + back-compat methods.
• Docs — new "Client Methods" section in backward-compatibility.md showing the full generated client (current sync/async then back-compat sync/async) with one-sentence per-overload comments, the optional default shown as default, the async modifier on the current async method, and the back-compat delegating call using named arguments. Includes a note verifying Azure SDK parameter ordering and a note explaining why the async back-compat overload returns the Task directly without await.

Example

Previous contract:

public virtual ClientResult GetData(int p1, BinaryContent body, RequestOptions options = null);
public virtual Task<ClientResult> GetDataAsync(int p1, BinaryContent body, RequestOptions options = null);

Current TypeSpec adds an optional @query p2?: boolean. Generated client:

// Current sync method generated from the updated TypeSpec.
public virtual ClientResult GetData(int p1, BinaryContent body, bool? p2 = default, RequestOptions options = null) { /* ... */ }

// Current async method generated from the updated TypeSpec.
public virtual async Task<ClientResult> GetDataAsync(int p1, BinaryContent body, bool? p2 = default, RequestOptions options = null) { /* ... */ }

// Back-compat sync overload matching the previous contract's signature.
[EditorBrowsable(EditorBrowsableState.Never)]
public virtual ClientResult GetData(int p1, BinaryContent body, RequestOptions options)
    => this.GetData(p1: p1, body: body, p2: default, options: options);

// Back-compat async overload matching the previous contract's signature.
[EditorBrowsable(EditorBrowsableState.Never)]
public virtual Task<ClientResult> GetDataAsync(int p1, BinaryContent body, RequestOptions options)
    => this.GetDataAsync(p1: p1, body: body, p2: default, options: options);

Defaults are stripped from the back-compat signature to avoid ambiguous call sites with the current method.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/http-client-csharp@10532

commit: 1ca179b

[jorgerangel-msft]

@copilot we need to also add unit tests that exercise the scenario where there is a model body type in operation.

[Copilot]

@copilot we need to also add unit tests that exercise the scenario where there is a model body type in operation.

Added BackCompatibility_NewOptionalNonBodyParameterAddedWithModelBody in 502a6dd which uses an InputModelType body parameter and asserts the full generated client (including the back-compat overloads taking SampleModel body) via Helpers.GetExpectedFromFile.

[jorgerangel-msft]

@copilot lets also add at least 1 test where we utilize path params mixed with query and header

[Copilot]

@copilot lets also add at least 1 test where we utilize path params mixed with query and header

Added BackCompatibility_NewOptionalNonBodyParameterAddedWithPathAndHeaderParameters in a1b4f97. The previous contract has GetData(string itemId, int filter, string region, CancellationToken) (path + query + header), and the current TypeSpec adds an optional sort query — the test asserts the back-compat overloads with all three legacy parameter kinds are emitted.