Repository navigation
[.NET] Consume TCGC LRO operation ID metadata - #12563
iscai-msft wants to merge 10 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>
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>
| 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
fc068e9 to
718e6a0
Compare
Restore the original PR history and keep only TCGC @lroOperationId support. @lroStatusMetadata support moves to a separate PR.
718e6a0 to
f7ea9e3
Compare
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved issues can produce incorrect LRO polling metadata, block generation, and prevent extensions from specifying non-default path styles.
8 open issues
Match monitor property accessibility to the selected property Resolve JSON names independently of XML serialization names · New Match polling parameters by their underlying raw properties · New Avoid traversing unused parameters in polling metadata conversion · New Resolve the JSON wire name for response-body polling links · New Preserve URI-template expansion for polling path parameters · New Expose parameter style in the public constructor · New Add end-to-end coverage for LRO-paging emission · New
Review effort: Balanced
| fromSdkModelProperty(sdkContext, sdkProperty, metadata.pollingInfo.responseModel), | ||
| ); | ||
| // TCGC omits serialization options when the polling model is not otherwise emitted. | ||
| if (property && property.serializedName === undefined && sdkProperty.__raw) { |
| const sdkPathParameters = sdkPollingOperation.parameters.filter( | ||
| (parameter) => | ||
| parameter.kind === "path" && | ||
| parameter.crossLanguageDefinitionId === entry.pathParameter.crossLanguageDefinitionId, |
| const pathParameter = diagnostics.pipe( | ||
| fromParameter(sdkContext, sdkPathParameters[0], rootApiVersions), | ||
| ); |
| const sourceProperty = | ||
| location === InputOperationLinkLocation.ResponseHeader | ||
| ? { ...convertedSource, serializedName: getHeaderFieldName(sdkContext.program, rawSource) } | ||
| : convertedSource; |
| kind: "path", | ||
| source: { location, property: sourceProperty }, | ||
| pathParameter, | ||
| pollingPath: pollingOperation.path, |
| /// <summary> | ||
| /// The URI template expansion style, or <see cref="InputPathParameterStyle.Unknown"/> when unavailable. | ||
| /// </summary> | ||
| public InputPathParameterStyle Style { get; internal set; } |
| lroPagingMethod.lroMetadata = diagnostics.pipe( | ||
| loadLongRunningMetadata(sdkContext, sdkMethod), | ||
| loadLongRunningMetadata(sdkContext, sdkMethod, rootApiVersions), |
There was a problem hiding this comment.
🟡 Changes recommended
Normalized routes and incorrect JSON wire names can prevent polling URL or ID extraction, grouped pollers can fail conversion, public callers cannot set path styles, and numeric strings are incorrectly accepted as enum values.
8 open issues
Reject numeric strings when parsing wire-style names · New Expose parameter style in the public constructor Preserve URI-template expansion for polling path parameters Resolve the JSON wire name for response-body polling links Avoid traversing unused parameters in polling metadata conversion Match polling parameters by their underlying raw properties Resolve JSON names independently of XML serialization names Add end-to-end coverage for LRO-paging emission
1 resolved since last review
Review effort: Balanced
| parameter.Style = Enum.TryParse<InputPathParameterStyle>(style, ignoreCase: true, out var parsedStyle) && Enum.IsDefined(parsedStyle) | ||
| ? parsedStyle | ||
| : InputPathParameterStyle.Unknown; |



Consumes TCGC 0.74.0
@lroOperationIdmetadata in the shared .NET emitter/input model, so the Azure generator can expose the server-issued operation ID through an internalOperationsubclass that overridesOperation.Id.@lroStatusMetadatasupport has been split out into a separate, independent PR. Its original combined snapshot is preserved atiscai-msft:preserve/dotnet-shared-lro-metadata-ffa8e1f9b(ffa8e1f9b33ada0147d7ee92d1f93c07e5e79a98).Feature links:
Part of Azure/typespec-azure#5996
Changes
lroMetadata.operationId, preserving TCGC order:pathselections include the polling linksource(ResponseHeader,ResponseBodyorSelf), the polling operation's own path parameter (the same$refas the polling method parameter) andpollingPath.propertyselections includepropertyand the typedpropertySegments.@encodedName.general-errorand are dropped without discarding valid ones.InputLongRunningServiceMetadata.OperationId(IReadOnlyList<InputLroOperationIdMetadata>), with derived typesInputLroOperationIdPathMetadata(Source,PathParameter,PollingPath) andInputLroOperationIdPropertyMetadata(Property,PropertySegments).InputOperationLink/InputOperationLinkLocation.InputPathParameter.Style/InputPathParameterStyle. Unknown values map toUnknown.Operation<T>/Operation<BinaryData>, and specs without these decorators are unaffected. No new public generated type, property or method comes from these decorators.Validation
LoadsEmittedLroMetadata/tspCodeModel.jsonand covers path, property, both and none; declaration order; cross-client polling; unexposed polling methods and models; link locations; path styles; and malformed input.dotnet format whitespaceare clean.Operation.Idgeneration and Spector validation belong to the Azure companion PR ([.NET] Consume TCGC LRO operation ID Azure/azure-sdk-for-net#64913).No Chronus entry is included because
@typespec/http-client-csharpisn't registered in.chronus/config.yaml.