feat: back compat support for method param types

[jorgerangel-msft]

Extends method back-compat to preserve source + binary compatibility when a service method's parameters evolve. For each public/protected last-contract method that changed in a recoverable way, a hidden (EditorBrowsable.Never) overload reproducing the previous signature is generated that delegates to the current method.

Scenarios now supported:

• Value-type parameter nullability removed (T? → T) — adds a hidden overload with the previous nullable signature that forwards via .Value, guarded by Argument.AssertNotNull (also covers extensible enums, matched by name).
• Nullable optional parameter became required — adds a hidden reduced-arity overload that drops the parameter and delegates with its previous default, so omit-callers still compile.

fixes: #11223

[github-actions]

No changes needing a change description found.

[pkg-pr-new]

Open in StackBlitz

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

commit: 4f250b2

[Copilot]

Pull request overview

This PR extends the C# generator’s method back-compat logic to handle additional signature evolution cases (beyond “new optional parameters”), specifically around nullable value-type parameters becoming non-nullable and nullable optional parameters becoming required, while adding targeted unit/golden tests and logging categories.

Changes:

• Add generation of hidden back-compat overloads for T? -> T value-type parameter nullability removal and for nullable parameters that changed from optional to required (via reduced-arity overloads).
• Introduce signature comparison that can optionally include nullability, and use it to avoid duplicate/incorrect overload classification.
• Add/extend tests and expected outputs covering the new back-compat scenarios and cross-pass interactions.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Utilities/BackCompatHelperTests.cs	New unit tests for the new back-compat detection helpers.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TypeProviderTests.cs	New integration/golden-style tests validating emitted overloads for the new scenarios.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilityUnwrapsRelaxedNullableSharedParameterInOptionalOverload/NullabilityAndOptionalChangeType.cs	Last-contract source stub used by the new cross-pass test.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilityUnwrapsRelaxedNullableSharedParameterInOptionalOverload.cs	Expected generated output for the cross-pass case (unwrap .Value forwarding).
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilityAddsOverloadForRelaxedNullableValueTypeParameter/NullabilityChangeType.cs	Last-contract source stub for the T? -> T overload case.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilityAddsOverloadForRelaxedNullableValueTypeParameter.cs	Expected generated output for the nullability-change overload.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilityAddsOverloadForNullableParameterThatBecameRequired/OptionalityChangeType.cs	Last-contract source stub for the optional-to-required nullable parameter case.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilityAddsOverloadForNullableParameterThatBecameRequired.cs	Expected generated output for the reduced-arity optionality-restoration overload.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Utilities/BackCompatHelper.cs	Core implementation: unified overload selection + new detection/build helpers + improved logging.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Providers/TypeProvider.cs	Switch to the new unified back-compat overload entrypoint.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Primitives/MethodSignatureBase.cs	Add a comparer variant that includes nullability in parameter type matching.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Primitives/CSharpType.cs	Add AreNamesEqual(..., checkNullability) helper to support nullability-aware comparisons.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/EmitterRpc/Emitter.cs	Map new back-compat categories to readable debug strings.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/EmitterRpc/BackCompatibilityChangeCategory.cs	Add new categories for nullability-change and optionality-restoration overload additions.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (3)

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Utilities/BackCompatHelper.cs:376

• Same accessibility check issue for candidates: candidateIsAccessible doesn’t exclude Private-flagged modifiers. Use MethodProviderHelpers.IsPublicApi so private protected candidates don’t participate in match selection.

                    var candidateSignature = candidate.Signature;
                    bool candidateIsAccessible = (candidateSignature.Modifiers & (MethodSignatureModifiers.Public | MethodSignatureModifiers.Protected)) != 0;

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Utilities/BackCompatHelper.cs:362

• AddBackCompatOverloads treats any method with Public or Protected flags as eligible, but it doesn’t exclude Private (e.g. private protected), unlike the new centralized MethodProviderHelpers.IsPublicApi check used elsewhere. This can cause back-compat overloads to be generated for non-public-API methods.

                if ((previousSignature.Modifiers & (MethodSignatureModifiers.Public | MethodSignatureModifiers.Protected)) == 0 ||
                    !currentMethodsByName.TryGetValue(previousSignature.Name, out var candidates))

packages/http-client-csharp/generator/docs/backward-compatibility.md:968

• This statement is no longer accurate now that some back-compat overloads intentionally preserve defaults (e.g., when the current method makes all previous parameters required, or for certain nullability/optionality shims). Consider rewording to indicate defaults are stripped only when needed to avoid ambiguity.