Generate back-compat overload when a service method gains a new optional non-body parameter by Copilot · Pull Request #10532 · microsoft/typespec

Copilot · 2026-04-28T21:01:49Z

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, passing default for each new parameter. Async overloads delegate without await so the back-compat method itself remains non-async.
Body parameters are intentionally excluded per the linked guidance, since adding a body parameter typically reflects a schema change handled elsewhere.
BackCompatibilityChangeCategory.MethodNewOptionalParameterOverloadAdded — new category surfaced in the emitter end-of-run summary.
Tests — BackCompatibility_NewOptionalNonBodyParameterAdded, BackCompatibility_MultipleNewOptionalNonBodyParametersAdded, BackCompatibility_NewOptionalBodyParameterDoesNotAddBackCompatOverload, BackCompatibility_NewRequiredParameterDoesNotAddBackCompatOverload.
Docs — new "Service Method Evolution" section in backward-compatibility.md.

Example

Previous contract:

public virtual ClientResult<string> GetData(int param2, string param1, CancellationToken cancellationToken = default);
public virtual Task<ClientResult<string>> GetDataAsync(int param2, string param1, CancellationToken cancellationToken = default);

Current TypeSpec adds an optional @header param3?: boolean. Generated overloads:

[EditorBrowsable(EditorBrowsableState.Never)]
public virtual ClientResult<string> GetData(int param2, string param1, CancellationToken cancellationToken)
    => this.GetData(param2, param1, default, cancellationToken);

[EditorBrowsable(EditorBrowsableState.Never)]
public virtual Task<ClientResult<string>> GetDataAsync(int param2, string param1, CancellationToken cancellationToken)
    => this.GetDataAsync(param2, param1, default, cancellationToken);

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

Agent-Logs-Url: https://github.com/microsoft/typespec/sessions/bb773994-13fe-4a5a-971a-b594a6d82388 Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com>

pkg-pr-new · 2026-04-28T21:30:12Z

Open in StackBlitz

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

commit: c20d2ae

jorgerangel-msft · 2026-04-28T21:31:57Z

            }

-            var currentMethodSignatures = BuildCurrentMethodSignatures(originalMethods);
+            var materializedMethods = originalMethods as IList<MethodProvider> ?? [.. originalMethods];


@copilot lets move the existing parameter ordering back compat support into a separate private helper.

Extracted into ApplyParameterReorderingForBackCompat in 81e56f3.

jorgerangel-msft · 2026-04-28T21:32:14Z


-            return [.. originalMethods];
+            // Add back-compat overloads for methods that have gained one or more new optional non-body parameter(s)
+            // relative to the last contract. See https://github.com/Azure/azure-sdk-for-net/blob/main/doc/DataPlaneCodeGeneration/ServiceDrivenEvolution.md#a-method-gets-a-new-optional-parameter


@copilot simply this comment and remove the link

Simplified and removed the link in 81e56f3.

jorgerangel-msft · 2026-04-28T21:32:31Z

+        /// For each public/protected method on the last contract that does not have an exact match in the
+        /// current contract, attempts to find a corresponding current method whose parameter list is the
+        /// previous method's parameter list (in the same order) plus one or more additional optional
+        /// non-body parameters. When such a current method is found, a hidden back-compat overload that
+        /// matches the previous signature is added; its body simply delegates to the current method,
+        /// passing default values for the new parameters.
+        ///
+        /// Per https://github.com/Azure/azure-sdk-for-net/blob/main/doc/DataPlaneCodeGeneration/ServiceDrivenEvolution.md#a-method-gets-a-new-optional-parameter
+        /// this back-compat behavior is intentionally restricted to non-body parameters.
+        /// </summary>


@copilot no need for the summary. Remove it

Removed in 81e56f3.

jorgerangel-msft · 2026-04-28T21:34:31Z

+            var existingSignatures = new HashSet<MethodSignature>(MethodSignature.MethodSignatureComparer);
+            foreach (var m in methods)
+            {
+                existingSignatures.Add(m.Signature);
+            }
+            if (CustomCodeView?.Methods != null)
+            {
+                foreach (var m in CustomCodeView.Methods)
+                {
+                    existingSignatures.Add(m.Signature);
+                }
+            }


@copilot it seems there is some overlapping logic between this and BuildCurrentMethodSignatures. CAn we consolidate this and only calculate the signatures once to improve perf?

Consolidated in 81e56f3 — currentMethodSignatures is now built once in BuildMethodsForBackCompatibility and passed into both ApplyParameterReorderingForBackCompat and AddBackCompatOverloadsForNewOptionalParameters. The latter reuses it for the existing-signature check and derives the by-name lookup from its values, so no duplicate signature collection happens.

…dict Agent-Logs-Url: https://github.com/microsoft/typespec/sessions/98e4708e-374c-4348-8b5b-30e4c877bd56 Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com>

jorgerangel-msft · 2026-04-29T16:54:38Z

+Previous version of the client:
+
+```csharp
+public virtual ClientResult<string> GetData(int param2, string param1, CancellationToken cancellationToken = default);


@copilot we need to fix this example. The tsp example you have below has a body param. We should fix it to be
op getData(@query p1: int32, @body body: SampleModel, @query p2?: boolean): string;
And the generated methods should accept a BinaryContent param type for the body.

Fixed in 779d663 — TSP example now uses @body body: SampleModel with @query p1 / @query p2?, and the generated methods accept BinaryContent for the body.

Agent-Logs-Url: https://github.com/microsoft/typespec/sessions/eaa4071b-877d-4406-a1ca-63af4e8c07c5 Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com>

jorgerangel-msft · 2026-04-29T17:29:52Z

    - [Method Parameter Name Preserved from Last Contract](#scenario-method-parameter-name-preserved-from-last-contract)
  - [Content-Type Parameter Ordering](#content-type-parameter-ordering)
    - [Content-Type Before Body Preserved from Last Contract](#scenario-content-type-before-body-preserved-from-last-contract)
+  - [Service Method Evolution](#service-method-evolution)


@copilot this section tag doesn't match the renamed section

Updated the TOC entry to [Client Methods](#client-methods) in eb3aca6.

Agent-Logs-Url: https://github.com/microsoft/typespec/sessions/fdf69480-deaf-4b00-8d8a-e88ad22e8313 Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com>

jorgerangel-msft · 2026-04-29T17:59:35Z

+**Generated Compatibility Methods:**
+
+```csharp
+[EditorBrowsable(EditorBrowsableState.Never)]


@copilot we should include the newly generated client. Include inline csharp comments explaining what each overload is

Updated the example in 12265c0 to include the current generated GetData/GetDataAsync methods alongside the back-compat overloads, with inline C# comments explaining each one.

Agent-Logs-Url: https://github.com/microsoft/typespec/sessions/df3eba50-228a-4ff8-88e1-756b943c65dc Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com>

Initial plan

b6d5faa

Copilot AI assigned Copilot and jorgerangel-msft Apr 28, 2026

Copilot started work on behalf of jorgerangel-msft April 28, 2026 21:01 View session

Copilot AI linked an issue Apr 28, 2026 that may be closed by this pull request

LastContractView - Handle A New Optional Parameter Being Added to a Service Method #7466

Open

Add back-compat overload for new optional non-body parameters

c20d2ae

Agent-Logs-Url: https://github.com/microsoft/typespec/sessions/bb773994-13fe-4a5a-971a-b594a6d82388 Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com>

microsoft-github-policy-service Bot added the emitter:client:csharp Issue for the C# client emitter: @typespec/http-client-csharp label Apr 28, 2026

Copilot AI changed the title ~~[WIP] Add handling for new optional parameter in LastContractView service method~~ [ClientModel] Generate back-compat overload when a service method gains a new optional non-body parameter Apr 28, 2026

Copilot finished work on behalf of jorgerangel-msft April 28, 2026 21:23

Copilot AI requested a review from jorgerangel-msft April 28, 2026 21:23

jorgerangel-msft changed the title ~~[ClientModel] Generate back-compat overload when a service method gains a new optional non-body parameter~~ Generate back-compat overload when a service method gains a new optional non-body parameter Apr 28, 2026

jorgerangel-msft reviewed Apr 28, 2026

View reviewed changes

Copilot started work on behalf of jorgerangel-msft April 28, 2026 21:35 View session

Refactor: extract reorder helper, simplify comments, reuse signature …

81e56f3

…dict Agent-Logs-Url: https://github.com/microsoft/typespec/sessions/98e4708e-374c-4348-8b5b-30e4c877bd56 Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com>

Copilot finished work on behalf of jorgerangel-msft April 28, 2026 21:39

Copilot AI requested a review from jorgerangel-msft April 28, 2026 21:39

jorgerangel-msft reviewed Apr 29, 2026

View reviewed changes

Copilot started work on behalf of jorgerangel-msft April 29, 2026 16:55 View session

Rename docs section to "Client Methods" and fix example with body param

779d663

Agent-Logs-Url: https://github.com/microsoft/typespec/sessions/eaa4071b-877d-4406-a1ca-63af4e8c07c5 Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com>

Copilot finished work on behalf of jorgerangel-msft April 29, 2026 16:57

Copilot AI requested a review from jorgerangel-msft April 29, 2026 16:57

jorgerangel-msft reviewed Apr 29, 2026

View reviewed changes

Copilot started work on behalf of jorgerangel-msft April 29, 2026 17:30 View session

Update TOC anchor to match renamed Client Methods section

eb3aca6

Agent-Logs-Url: https://github.com/microsoft/typespec/sessions/fdf69480-deaf-4b00-8d8a-e88ad22e8313 Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com>

Copilot finished work on behalf of jorgerangel-msft April 29, 2026 17:32

Copilot AI requested a review from jorgerangel-msft April 29, 2026 17:32

jorgerangel-msft reviewed Apr 29, 2026

View reviewed changes

Copilot started work on behalf of jorgerangel-msft April 29, 2026 17:59 View session

Show full generated client with inline comments in docs example

12265c0

Agent-Logs-Url: https://github.com/microsoft/typespec/sessions/df3eba50-228a-4ff8-88e1-756b943c65dc Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com>

Copilot finished work on behalf of jorgerangel-msft April 29, 2026 18:01

Copilot AI requested a review from jorgerangel-msft April 29, 2026 18:01

Conversation

Copilot AI commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Example

Uh oh!

pkg-pr-new Bot commented Apr 28, 2026

Uh oh!

jorgerangel-msft Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

jorgerangel-msft Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

jorgerangel-msft Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

jorgerangel-msft Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jorgerangel-msft Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

jorgerangel-msft Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

jorgerangel-msft Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Apr 28, 2026 •

edited

Loading