microsoft / microsoft/typespec

[Mgmt Generator] Preserve original parameter names in ModelFactory when properties are renamed via @@clientName

Open
#10,462 1 comment 0 reactions 0 assignees View on GitHub
emitter:client:csharp
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

## Summary

The mgmt generator's backward-compatibility feature for property renames (via `@@clientName`) should also detect parameter-name changes in the corresponding model factory methods, and preserve the old parameter names automatically.

## Background

When a flattened property is renamed via `@@clientName(SpecModel.field, "NewName", "csharp")` to mitigate an API surface change, two things happen on the generated SDK side:

1. The property on the data model gets the new name. We use a `[Obsolete]` + `[EditorBrowsable(Never)]` partial-class shim to re-introduce the old name. ✅
2. The corresponding parameter in the static `ModelFactory` method is also renamed (to the camelCase form of the new property name). ❌

Item (2) is not flagged by ApiCompat (parameter name changes are not binary-breaking), but it IS source-breaking for any consumer using the **named-argument** call form, e.g.:

```csharp
ArmFooModelFactory.FooData(profileType: CertificateProfileType.PublicTrust);
```

After the rename, this call no longer compiles because the parameter is now `certificateProfileType`. To preserve source compatibility, we currently have to copy the entire generated factory method into a custom partial class with the old parameter name (see workaround below).

## Repro

Real example: `Azure.ResourceManager.ArtifactSigning`
- Spec rename: `@@clientName(CertificateProfileProperties.profileType, "CertificateProfileType", "csharp");` (azure-rest-api-specs#42594)
- Generated factory method parameter changed from `profileType` to `certificateProfileType`.
- Workaround in azure-sdk-for-net commit (forthcoming) — full method copy in `src/Custom/ArmArtifactSigningModelFactory.cs`.

## Proposal

When the generator encounters a rename produced by `@@clientName` on a property and that property feeds a generated `ModelFactory` parameter:

- **Option A** (preferred): Keep the old parameter name on the model factory method by default. The parameter name is a documentation/convenience identifier — it does not need to match the renamed property.
- **Option B**: Allow `@@clientName` to specify a separate parameter-name override for the model factory.
- **Option C**: Emit BOTH parameter names somehow (overload / alias) — likely not feasible without overload ambiguity.

## Workaround today

For each renamed property, hand-copy the generated factory method into a partial class with the old parameter name. The generator's CustomCodeView correctly suppresses the duplicate when the signatures differ only by parameter name. No `[CodeGenSuppress]` is needed.

## Affected packages (current cleanup pass)

Same set as the lift-to-nullable mitigation:
artifactsigning, trustedsigning, billingbenefits, certificateregistration, cosmosdbforpostgresql, costmanagement, resources/Policy, workloadssapvirtualinstance.

## Acceptance

- The generator preserves parameter names for renamed properties (or provides a clean opt-in).
- Existing custom workarounds can be deleted.
- A regression test under `eng/packages/http-client-csharp-mgmt` covers the scenario.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.