Repository navigation
[.NET] Consume TCGC LRO status metadata and operation ID - #12563
iscai-msft wants to merge 9 commits into
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
commit: |
|
No changes needing a change description found. |
|
/azp run typespec - ci |
|
Azure Pipelines: Successfully started running 1 pipeline(s). |
There was a problem hiding this comment.
🔵 Needs a closer look
Matching shared-package versions and lifecycle validation in Azure/azure-sdk-for-net#64913 require maintainer confirmation beyond what this review can establish.
No open issues 🎉
What changed in this PR
Adds shared support for transporting TCGC long-running operation status metadata and operation-ID selections from the C# emitter into strongly typed generator inputs. This enables the coordinated Azure generator work without adding poller APIs or changing runtime polling behavior.
Changes:
- Preserve ordered selections, typed property paths, shared references, and modeled polling routes.
- Add C# input types and JSON converters while retaining legacy constructor compatibility and skipping unknown metadata fields.
- Add emitter/deserialization regressions and document the custom-generator consumption contract.
| File | Description |
|---|---|
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.Input/test/InputServiceMethodTests.cs |
Tests typed paths, reference identity, ordered IDs, invalid inputs, and legacy compatibility. |
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.Input/src/InputTypes/Serialization/TypeSpecSerialization.cs |
Registers the new metadata converters. |
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.Input/src/InputTypes/Serialization/InputOperationLinkConverter.cs |
Deserializes and validates polling-link sources. |
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.Input/src/InputTypes/Serialization/InputLroStatusMetadataConverter.cs |
Deserializes selected status properties and typed paths. |
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.Input/src/InputTypes/Serialization/InputLroOperationIdMetadataConverter.cs |
Deserializes path-based and property-based ID selections. |
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.Input/src/InputTypes/Serialization/InputLongRunningServiceMetadataConverter.cs |
Loads both collections and skips unknown fields. |
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.Input/src/InputTypes/InputOperationLink.cs |
Represents a polling link’s location and property. |
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.Input/src/InputTypes/InputLroStatusMetadata.cs |
Represents a selected status property and access path. |
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.Input/src/InputTypes/InputLroOperationIdPropertyMetadata.cs |
Represents a monitor-body ID selection. |
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.Input/src/InputTypes/InputLroOperationIdPathMetadata.cs |
Carries the polling link, ID parameter, and monitor route. |
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.Input/src/InputTypes/InputLroOperationIdMetadata.cs |
Adds the shared base type for ID selections. |
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.Input/src/InputTypes/InputLongRunningServiceMetadata.cs |
Exposes metadata collections while preserving existing constructors. |
packages/http-client-csharp/emitter/test/Unit/operation-converter.test.ts |
Tests selection combinations, names, ordering, types, and serialized references. |
packages/http-client-csharp/emitter/src/type/input-service-method.ts |
Defines the TypeScript metadata transport shapes. |
packages/http-client-csharp/emitter/src/lib/type-converter.ts |
Exports model-property conversion for reuse. |
packages/http-client-csharp/emitter/src/lib/operation-converter.ts |
Converts TCGC selections and preserves polling-route and header details. |
packages/http-client-csharp/docs/plugins.md |
Documents metadata semantics, consumer responsibilities, and matching-build requirements. |
Review effort: Balanced
Jorge Rangel (jorgerangel-msft)
left a comment
There was a problem hiding this comment.
thanks for driving this! Do we have a gist or proposal for what the generated output will look like, or is that all covered in Azure/azure-sdk-for-net#64913 ?
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
/azp run typespec - ci |
|
Azure Pipelines: Successfully started running 1 pipeline(s). |
There was a problem hiding this comment.
🟡 Changes recommended
Selected polling metadata can emit types with incorrect naming, usage, or access, trigger generation failures by converting unrelated models, and lose URI expansion styles needed to interpret IDs.
5 open issues
Preserve effective access on selected model and enum types · New Normalize synthesized enums from ownerless monitor selections · New Avoid converting unused polling response models · New Preserve URI template style when deserializing input parameters · New Test ID remapping for spread polling parameters · New
4 resolved since last review
Review effort: Balanced
There was a problem hiding this comment.
🟡 Changes recommended
Standalone LRO selections can lose output usage, enum naming, and internal access, while polling response metadata can depend on method order.
6 open issues
Resolve polling response metadata after converting all clients · New Preserve URI template style when deserializing input parameters Avoid converting unused polling response models Normalize synthesized enums from ownerless monitor selections Preserve effective access on selected model and enum types Test ID remapping for spread polling parameters
Review effort: Balanced
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
Critical issues can omit monitor enum types, cause accessibility compilation errors, and break metadata reads under ahead-of-time compilation.
3 open issues
6 resolved since last review
Resolve polling response metadata after converting all clients Preserve URI template style when deserializing input parameters Avoid converting unused polling response models Normalize synthesized enums from ownerless monitor selections Preserve effective access on selected model and enum types Test ID remapping for spread polling parameters
Review effort: Balanced
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Remove the public PropertyProvider isOutputOnly overload, use Enum.TryParse for operation link locations and path styles, separate LRO metadata enum usage from naming, clarify context registration, and inline the fixture TypeSpec source in the emitter test. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
| const input = sdkContext.__typeCache.types.get(selectedType); | ||
| if (input?.kind === "model" || input?.kind === "enum") { | ||
| input.access ??= "internal"; |
| usedTypeNames.add(name); | ||
| if (!model.isExactName) { | ||
| // ModelProvider may project Request/Response suffixes to Content/Result. | ||
| if (name.endsWith("REQUEST")) usedTypeNames.add(`${name.slice(0, -7)}CONTENT`); |
There was a problem hiding this comment.
I'm wondering if we should just let the generator handle the rename here. A custom visitor can override our rename rules without using the isExactName function.
| foreach (var provider in buildableProviders) | ||
| { | ||
| if (!IsPublicApi(provider) | ||
| if (!(IsPublicApi(provider) || IsInternalLroMetadataType(provider, lroMetadataTypes)) |
There was a problem hiding this comment.
can we validate if we actually need to do this? If I recall, these attributes should only ever be added for providers or types that implement IPersistableModel. From your other PR, I don't think the metadata type falls into that category so technically it should ever be part of buildableProviders ?
|
|
||
| // LRO metadata enums are synthesized by this emitter from TCGC constants, so TCGC does not reserve their names. | ||
| // They must have distinct C# type and output file names without renaming existing types. | ||
| const usedTypeNames = new Set([...clients].map(csharpTypeNameKey)); |
There was a problem hiding this comment.
This reserves the original client names, but TypeSpecSerialization.BuildClientName (TypeSpecSerialization.cs:124-140) renames a deeper Root -> Group -> Child client to GroupChild; a hidden Group monitor selecting child?: "ready" can therefore emit a metadata enum with the same fully qualified name when both use a shared @clientNamespace. Could we resolve this using the final C# client names, ideally in the generator, and add a deeper-subclient regression?
🤖 Generated by Jorge's Copilot



Summary
Shared prerequisite for the coordinated Azure .NET generator change. Preserve TCGC
statusMetadata, typedpropertySegments, and orderedoperationIdselections through the shared TypeScript code model and strongly typed C# input conversion. The Azure companion owns idiomatic generated operation/poller access and runtime integration scenarios; this PR does not add Azure-specific poller APIs or remove SDK customizations.Feature contracts: Azure/typespec-azure#5677, Azure/typespec-azure#5927, Azure/typespec-azure#5782.
Part of Azure/typespec-azure#5996
TCGC is already pinned to
0.74.0, with the stable TypeSpec1.18.0/0.88.0dependency family, by #12552; no redundant dependency bump is needed here. This does not consume result-default changes from Azure/typespec-azure#5837 or endpoint/OAuth configurations from Azure/typespec-azure#5710.Shared consumption contract
InputLongRunningServiceMetadata.StatusMetadata: orderedInputLroStatusMetadataentries withPropertyand typedPropertySegments, rooted atpollingInfo.responseModel. Client/wire names, optionality, selected output type graphs, and shared property references survive serialization.InputLongRunningServiceMetadata.OperationId: orderedInputLroOperationIdPathMetadatathenInputLroOperationIdPropertyMetadatawhen both sources are selected. Property entries preservePropertyand typedPropertySegments. Path entries preserveSource.Location,Source.Property,PathParameter, andPollingPath(the modeled monitor route), so the selected ID need not be the last URI segment.PollingResponseModelrefers to an otherwise emitted polling model and is null for a hidden monitor; selected property paths and required model/enum graphs still survive.PropertyProvideris unchanged; consumers construct selected-property getters with the existing constructor and apply read-only/accessibility viaUpdate.InputPathParameter.StylepreservesSimple,Label,Matrix,Path, andFragment(orUnknownif absent/unrecognized).PollingPathnormalizes RFC6570 operators, so consumers must use the style and serialized name when extracting an ID; the complete polling URL remains unchanged.ModelReaderWritercontext generation; unannotated contexts are unchanged. Distinct hidden-monitor literal enums retain separate identities and avoid collisions with client types and C#-projected model/enum names.Microsoft.TypeSpec.Generator.Inputbuilds. Polling still uses the complete polling URL; extracted IDs do not replace it. The Azure companion must implement latest-response refresh/absence, initial monitor values, failure/cancellation access, URI fallback, and post-rehydration behavior.Validation and boundary
Passed locally:
npm run build, including API extraction.lroandlropaginground trips, typed paths, shared/forward references, ordered ID sources, invalid shapes, and legacy/unknown fields.eng/scripts/Generate.ps1: completed successfully with no tracked generated-source changes, preserving existing public APIs.oxlinton the emitter, C# formatting,git diff --check, andnpm run cop(cop checks passed.).The package's existing
npm run lintscript invokes ESLint without a flat config and fails; the repository-standardoxlintcheck passes. This PR does not claim execution of the new Azure LRO metadata/operation-ID Spector scenarios or their public-accessor lifecycle assertions: those belong to the Azure companion. Existing shared Spector stubs being skipped is not evidence that the new Azure scenarios pass.Customization database handoff
The verified customization read model on
iscai-msft/typespec-azurebranchsdk-customization-metricsat commita3b68e6b480649a754aa6b64455d83b53527d113contains 54 accepted .NET LRO findings across 24 SDK packages: 1 operation-ID facet covered and 53 findings not covered. This audit is copied from the Azure companion PR.Coverage is prospective and depends on the Azure companion: this PR only transports metadata; it does not itself generate consumer-facing poller APIs or runtime behavior, and no handwritten SDK customization is removed. Covered refers only to the ID or auxiliary metadata facet after emitter support ships. Custom terminal states, result projection, and paged LRO results remain not covered. Translation has an ID/metadata facet but is not counted because custom terminal states and paged results remain unsupported. ConfidentialLedger's initial custom header/body selection is not covered by a linked monitor URI/modeled monitor-body selection. Related findings are grouped; each 12-character identifier is a distinct finding.
Azure.AI.Discovery1e35c0826841: L29-L32 L108-L130Replace asynchronous delete with delete-until-resource-404 polling
7e5f04037499: L29-L32 L139-L161Implement a resource-GET delete operation that completes only on HTTP 404
9b345f219483: L12-L60 L163-L177Azure.AI.Discovery761263e71004: L13-L101 L163-L207Replace synchronous create/update with the resource-provisioning operation
80415c0f53f1: L29-L66Replace asynchronous create/update with a provisioning-state operation
e77f38e398d4: L29-L32 L76-L99Azure.AI.DocumentIntelligencecaba7c0e715e: L250-L278@lroOperationIdon the linked monitor operation's ID path parameter; a string-like monitor response property can be annotated separately.Azure.AI.Language.Conversations4a79206e885d: L53-L63Typed synchronous analysis waits and unwraps operation result
bdee245bb3cc: L33-L43Azure.AI.Language.Conversations83f5e4b017ad: L102-L119Synchronous operation-location protocol wrapper
c1a7282128a0: L74-L91Azure.AI.Language.Text67a652b2bfcf: L80-L104Synchronous wait-to-completion wrapper and typed raw-result conversion
da67d8c00d59: L47-L71Azure.AI.Language.Text.Authoring2b041b9f79a6: L229-L252scoped-typed-delete-resources-operation-adapter
3725999aaec8: L194-L224scoped-typed-deploy-operation-adapter
b6d9242e95ad: L158-L188scoped-operation-location-lro-entry-point
f1a69ce514f1: L120-L150 L350-L368scoped-export-delete-operation-adapter
f42751f00c28: L155-L178Azure.AI.Translation.Document6eb9ca22a185: L103-L121 L163-L181 L224-L242async-operation-location-wrapper
cc29acaaa040: L133-L151 L193-L211 L255-L273@lroOperationIdon the linked monitor ID path parameter and@lroStatusMetadataon auxiliary counter/timestamp properties.Azure.Developer.DevCenterdccfb84ae565: L14-L16 L35-L45 L55-L65Model-name-derived typed Dev Box operation wrappers
f58f012832f3: L14-L16 L35-L46 L56-L67Azure.Developer.LoadTesting527c09fd508a: L55-L83 L96-L124Profile-run creation wrapped as LRO
bca84c3409f3: L136-L164 L176-L204File upload wrapped as validation LRO
f42c06a4b7d1: L55-L84 L98-L127Azure.Developer.LoadTestingb10456beae2d: L84-L90Azure.Developer.LoadTestingb16e23a0abeb: L25-L31 L39-L68 L90-L97 L162-L191Azure.Developer.LoadTestingbbb82ef8fb46: L120-L131 L141-L160Azure.ResourceManager.AppContainersa7736398ac7d: L40-L45 L71-L76Azure.ResourceManager.Authorization8249629b516f: L57-L85 L110-L137Azure.ResourceManager.ContainerInstancec65c878e4a27: L15-L17 L24-L55 L62-L93Azure.ResourceManager.ElasticSan7103b7d53961: L177-L200 L221-L244Azure.ResourceManager.EventGridcd25fffe5b92: L125-L161 L167-L203Azure.ResourceManager.GuestConfigurationd25344c2b750: L85-L105 L117-L137Azure.ResourceManager.HybridConnectivityefff7372a29a: L19-L19 L29-L44Azure.ResourceManager.IotHub2880efeaa513: L27-L29 L174-L204 L228-L258Azure.ResourceManager.KeyVaulta76f093fae14: L16-L18 L179-L209 L233-L263Azure.ResourceManager.NewRelicObservability7703ecaa0495: L50-L54 L80-L84Azure.ResourceManager.Resources.Deployments69f899e5876b: L359-L386 L388-L403Azure.ResourceManager.Search6ecf95c151ce: L19-L22 L50-L77 L105-L132Azure.ResourceManager.TrafficManager4f7283c1a167: L228-L255 L260-L287typed-create-initiation-and-operation-result-adapter
919f88605208: L90-L122 L143-L175Azure.Security.ConfidentialLedger38d8586e5736: L366-L383Azure.Security.ConfidentialLedgere0d386222855: L21-L22 L208-L277 L298-L364Azure.Security.KeyVault.Certificates7f423911a9dd: L159-L204 L221-L266Azure.Security.KeyVault.Secrets4f8b65530974: L54-L54 L67-L67Initial recovery properties available before completion
8c1e9854d701: L44-L44 L57-L57Azure.Security.KeyVault.Secrets52c412463499: L18-L18 L71-L72Two-second default asynchronous wait
e7600b4a62de: L18-L18 L81-L82Azure.Security.KeyVault.Secretsafa7814f8490: L78-L91Deleted-resource status polling
dcafca69d828: L88-L104Azure.Security.KeyVault.Secretsba579de21cda: L24-L39Azure.Security.KeyVault.Secretsc054c2859205: L35-L35Secret URI exposed as operation ID
dd95ae7f6bf8: L45-L45Companion validation and follow-ups
The Azure companion validated matching v12 shared artifacts: 378/378 generator tests, two generated netstandard2.0 project builds, and public/internal hidden-monitor metadata and model-serialization runtime scenarios passed. Fresh end-to-end repros passed for same-named hidden-monitor literal selections,
ModelReaderWriterround-tripping an emitted internal polling model,keepAllmetadata getters with internal return types, and client/model name collisions under both default pruning andkeepAll. Request/response model suffix projections preserve the existing model name while disambiguating the metadata enum.With published fixtures, 11/12 real LRO Spector scenarios pass;
StartTranslationWithPathremains blocked by Azure/typespec-azure#6132. All 12/12 pass with that fixture fix applied temporarily and restored afterward. See the companion validation report for the earlier v9 baseline.Publish compatible shared emitter and generator packages for the companion, and rerun against the corrected published fixture. Do not merge independently of the companion's compatible shared-package consumption.
Changeset
No
.chronuschangeset is included, by user decision.@typespec/http-client-csharpis outside the pnpm workspace and is not tracked in.chronus/config.yaml, sochronus verifyrejects a C# entry withinvalid-package-name. A C# changeset was removed for the same reason ine68c1a4eb.