Update ATS docs for polyglot APIs#17289
Open
sebastienros wants to merge 8 commits into
Open
Conversation
Move AspireExport descriptions into XML/ATS documentation and add polyglot-safe ATS overrides for exported APIs. Add analyzer coverage to prevent new AspireExport Description usage and update generated TypeScript snapshots. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
sebastienros
requested review from
JamesNK,
danegsta,
davidfowl,
eerhardt,
karolz-ms and
mitchdenny
as code owners
Contributor
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 17289Or
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 17289" |
Contributor
There was a problem hiding this comment.
Pull request overview
Updates Aspire’s ATS-exported API documentation so it can be consumed by polyglot SDKs (TypeScript, etc.) by moving “human” docs out of AspireExport.Description and into XML docs with ATS override tags, and by extending ATS reference parsing to accept compiler-safe cref="!:..." forms.
Changes:
- Replaces many
[AspireExport(Description=...)]usages with XML doc overrides like<ats-summary>,<ats-param>, and<ats-returns>. - Updates ATS reference parsing to allow
crefvalues prefixed with!:(so the C# compiler doesn’t validate the customcrefformat). - Adds analyzer rule
ASPIREEXPORT015(and tests) to prevent newAspireExport.Descriptionusages, and updates TypeScript codegen snapshots/tests accordingly.
Reviewed changes
Copilot reviewed 193 out of 195 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/Aspire.Hosting.RemoteHost.Tests/AttributeDataReaderTests.cs | Updates expectations to reflect AspireExport.Description no longer being used for docs. |
| tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/WithRedisSpecificCapability.verified.txt | Snapshot updated for documentation moving from Description to XML-derived summary. |
| tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/WithPersistenceCapability.verified.txt | Snapshot updated for documentation moving from Description to XML-derived summary. |
| tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/WithOptionalStringCapability.verified.txt | Snapshot updated for documentation moving from Description to XML-derived summary. |
| tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/HostingAddContainerCapability.verified.txt | Snapshot updated for new ATS doc formatting and ATS references. |
| tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/AddTestRedisCapability.verified.txt | Snapshot updated to remove capability Description and rely on XML-derived docs. |
| tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/AtsTypeScriptCodeGeneratorTests.cs | Aligns tests with Description being null and XML docs becoming the source of truth. |
| tests/Aspire.Hosting.Analyzers.Tests/AspireExportAnalyzerTests.cs | Adds coverage for new ASPIREEXPORT015 and updates prior tests away from Description. |
| src/Aspire.Hosting/UserSecrets/IUserSecretsManager.cs | Moves exported doc text into <ats-summary> and removes AspireExport.Description. |
| src/Aspire.Hosting/RequiredCommandResourceExtensions.cs | Moves exported doc text into <ats-summary> and removes AspireExport.Description. |
| src/Aspire.Hosting/Publishing/BeforePublishEvent.cs | Adds ATS parameter overrides using compiler-safe !:type: references. |
| src/Aspire.Hosting/Publishing/AfterPublishEvent.cs | Adds ATS parameter overrides using compiler-safe !:type: references. |
| src/Aspire.Hosting/ProjectResourceBuilderExtensions.cs | Replaces AspireExport.Description with ATS XML doc overrides on polyglot exports. |
| src/Aspire.Hosting/Pipelines/PipelineStepFactoryExtensions.cs | Replaces AspireExport.Description with ATS XML doc overrides. |
| src/Aspire.Hosting/Pipelines/PipelineStepFactoryContext.cs | Adds ATS summary override for polyglot docs. |
| src/Aspire.Hosting/Pipelines/PipelineStep.cs | Moves export descriptions into ATS XML docs for projections and methods. |
| src/Aspire.Hosting/Pipelines/PipelineEditor.cs | Moves export descriptions into ATS XML docs for polyglot callbacks. |
| src/Aspire.Hosting/Pipelines/PipelineConfigurationContext.cs | Moves export descriptions into ATS XML docs for callback-facing projections. |
| src/Aspire.Hosting/Pipelines/DistributedApplicationPipelineExtensions.cs | Moves export description into ATS XML docs. |
| src/Aspire.Hosting/ParameterResourceBuilderExtensions.cs | Replaces AspireExport.Description with ATS summaries/returns for polyglot exports. |
| src/Aspire.Hosting/OtlpConfigurationExtensions.cs | Replaces AspireExport.Description with ATS summary for polyglot export. |
| src/Aspire.Hosting/McpServerResourceBuilderExtensions.cs | Adds ATS summary/returns and removes AspireExport.Description. |
| src/Aspire.Hosting/IDistributedApplicationBuilder.cs | Adds ATS summary/returns for exported interface + Build() export. |
| src/Aspire.Hosting/ExternalServiceBuilderExtensions.cs | Moves polyglot-export doc text into ATS XML docs. |
| src/Aspire.Hosting/ExecutableResourceBuilderExtensions.cs | Adds ATS summary/returns/params and removes AspireExport.Description. |
| src/Aspire.Hosting/DistributedApplicationExecutionContextOptions.cs | Adds ATS summary override for polyglot docs. |
| src/Aspire.Hosting/DistributedApplication.cs | Adds ATS summary/returns and removes AspireExport.Description on polyglot exports. |
| src/Aspire.Hosting/ContainerRegistryResourceBuilderExtensions.cs | Moves polyglot-export doc text into ATS XML docs. |
| src/Aspire.Hosting/Ats/UserSecretsExports.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting/Ats/NotificationExports.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting/Ats/ModelExports.cs | Moves exported doc text into ATS XML docs (including polyglot-friendly returns text). |
| src/Aspire.Hosting/Ats/ExecutionConfigurationExports.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting/Ats/EventingExports.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting/Ats/CoreExports.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting/Ats/AspireExportAttribute.cs | Re-documents Description as compatibility metadata and updates examples to ATS XML docs. |
| src/Aspire.Hosting/ApplicationModel/ResourceUrlsEditor.cs | Moves exported doc text into ATS XML docs for editor methods/properties. |
| src/Aspire.Hosting/ApplicationModel/ResourceUrlsCallbackContext.cs | Moves exported doc text into ATS XML docs for callback context projections. |
| src/Aspire.Hosting/ApplicationModel/ResourceStoppedEvent.cs | Adds ATS param overrides for polyglot-friendly type references. |
| src/Aspire.Hosting/ApplicationModel/ResourceCommandAnnotation.cs | Adds ATS summary overrides that reference related exported members. |
| src/Aspire.Hosting/ApplicationModel/ReferenceExpression.cs | Moves exported doc text into ATS XML docs for methods/builders. |
| src/Aspire.Hosting/ApplicationModel/LogFacade.cs | Moves exported doc text into ATS XML docs for logging facade. |
| src/Aspire.Hosting/ApplicationModel/InitializeResourceEvent.cs | Adds ATS param overrides for polyglot-friendly type references. |
| src/Aspire.Hosting/ApplicationModel/ExecutionConfigurationBuilderExtensions.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting/ApplicationModel/EnvironmentEditor.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting/ApplicationModel/EnvironmentCallbackContext.cs | Moves exported doc text into ATS XML docs for callback context projections. |
| src/Aspire.Hosting/ApplicationModel/EndpointReference.cs | Moves exported doc text into ATS XML docs, adds ATS params/returns for polyglot types. |
| src/Aspire.Hosting/ApplicationModel/ConnectionStringAvailableEvent.cs | Adds ATS summary/param overrides for polyglot-friendly type references. |
| src/Aspire.Hosting/ApplicationModel/CommandLineArgsEditor.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting/ApplicationModel/CommandLineArgsCallbackAnnotation.cs | Moves exported doc text into ATS XML docs for callback context projections. |
| src/Aspire.Hosting/ApplicationModel/BeforeStartEvent.cs | Adds ATS param overrides for polyglot-friendly type references. |
| src/Aspire.Hosting/ApplicationModel/BeforeResourceStartedEvent.cs | Adds ATS param overrides for polyglot-friendly type references. |
| src/Aspire.Hosting/ApplicationModel/AspireStoreExtensions.cs | Moves exported doc text into ATS XML docs and adds ATS param/returns overrides. |
| src/Aspire.Hosting/ApplicationModel/AfterResourcesCreatedEvent.cs | Adds ATS param overrides for polyglot-friendly type references. |
| src/Aspire.Hosting.Yarp/ConfigurationBuilder/YarpCluster.cs | Moves exported doc text into ATS XML docs for cluster configuration methods. |
| src/Aspire.Hosting.Yarp/ConfigurationBuilder/Transforms/RequestHeadersTransformExtensions.cs | Moves exported doc text into ATS XML docs for transform helpers. |
| src/Aspire.Hosting.Yarp/ConfigurationBuilder/Transforms/QueryTransformExtensions.cs | Moves exported doc text into ATS XML docs for transform helpers. |
| src/Aspire.Hosting.Yarp/ConfigurationBuilder/Transforms/PathTransformExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns references. |
| src/Aspire.Hosting.Yarp/ConfigurationBuilder/Transforms/HttpMethodTransformExtensions.cs | Moves exported doc text into ATS XML docs for transform helpers. |
| src/Aspire.Hosting.Yarp/ConfigurationBuilder/Transforms/ForwardedTransformExtensions.cs | Moves exported doc text into ATS XML docs for transform helpers. |
| src/Aspire.Hosting.Valkey/ValkeyBuilderExtensions.cs | Moves exported doc text into ATS XML docs with ATS param/returns overrides. |
| src/Aspire.Hosting.Testing/DistributedApplicationHostingTestingExtensions.cs | Moves exported doc text into ATS XML docs for testing exports. |
| src/Aspire.Hosting.Seq/SeqBuilderExtensions.cs | Moves exported doc text into ATS XML docs with ATS param/returns overrides. |
| src/Aspire.Hosting.RemoteHost/README.md | Updates docs to describe ATS XML doc override tags and compiler-safe !:... cref prefix. |
| src/Aspire.Hosting.RemoteHost/AtsCapabilityScanner.cs | Strips the !: prefix when parsing ATS cref references. |
| src/Aspire.Hosting.RabbitMQ/RabbitMQBuilderExtensions.cs | Moves exported doc text into ATS XML docs with ATS param/returns overrides. |
| src/Aspire.Hosting.Qdrant/QdrantBuilderExtensions.cs | Moves exported doc text into ATS XML docs with ATS param/returns overrides. |
| src/Aspire.Hosting.PostgreSQL/PostgresDatabaseResource.cs | Adds ATS summary override for a child resource type. |
| src/Aspire.Hosting.Orleans/OrleansServiceClientExtensions.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting.Oracle/OracleDatabaseResource.cs | Adds ATS summary override for a child resource type. |
| src/Aspire.Hosting.OpenAI/OpenAIExtensions.cs | Moves exported doc text into ATS XML docs and adds ATS param overrides. |
| src/Aspire.Hosting.Nats/NatsBuilderExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.MySql/MySqlDatabaseResource.cs | Adds ATS summary override for a child resource type. |
| src/Aspire.Hosting.MongoDB/MongoDBDatabaseResource.cs | Adds ATS summary override for a child resource type. |
| src/Aspire.Hosting.Milvus/MilvusDatabaseResource.cs | Adds ATS summary override for a child resource type. |
| src/Aspire.Hosting.Maui/MauiWindowsExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Maui/MauiProjectResourceExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Maui/MauiOtlpExtensions.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting.Maui/MauiMacCatalystExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Maui/MauiiOSExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Maui/MauiAndroidExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Kubernetes/KubernetesServiceExtensions.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting.Kubernetes/KubernetesResource.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting.Kubernetes/KubernetesNodePoolResource.cs | Adds ATS summary override for child resource type and references related API. |
| src/Aspire.Hosting.Kubernetes/KubernetesManifestResource.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting.Kubernetes/KubernetesHelmChartExtensions.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting.Kubernetes/KubernetesAspireDashboardResourceBuilderExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Kubernetes/HelmChartOptions.cs | Adds ATS summary override and moves method descriptions into ATS XML docs. |
| src/Aspire.Hosting.Keycloak/KeycloakResource.cs | Adds ATS param override for polyglot-friendly null wording. |
| src/Aspire.Hosting.Kafka/KafkaBuilderExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Integration.Analyzers/AspireExportAnalyzer.Diagnostics.cs | Adds ASPIREEXPORT015 descriptor and registers it as supported. |
| src/Aspire.Hosting.Integration.Analyzers/AnalyzerReleases.Unshipped.md | Documents ASPIREEXPORT015 in analyzer release notes. |
| src/Aspire.Hosting.GitHub.Models/GitHubModelsExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Garnet/GarnetBuilderExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentBuilderExtension.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting.Foundry/FoundryExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.EntityFrameworkCore/EFResourceBuilderExtensions.cs | Moves exported doc text into ATS XML docs for polyglot export. |
| src/Aspire.Hosting.EntityFrameworkCore/EFMigrationResourceBuilderExtensions.cs | Adds ATS param overrides and moves polyglot-export descriptions into ATS XML docs. |
| src/Aspire.Hosting.Docker/DockerComposeServiceExtensions.cs | Moves exported doc text into ATS XML docs for polyglot export. |
| src/Aspire.Hosting.Docker/DockerComposeResourceExtensions.cs | Moves exported doc text into ATS XML docs for polyglot exports. |
| src/Aspire.Hosting.Docker/DockerComposeAspireDashboardResourceBuilderExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.DevTunnels/DevTunnelResourceBuilderExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Browsers/BrowserLogsBuilderExtensions.cs | Moves export description into ATS XML docs with detailed ATS param/returns overrides. |
| src/Aspire.Hosting.Azure/Provisioning/AzureProvisionerExtensions.cs | Moves export description into ATS XML docs. |
| src/Aspire.Hosting.Azure/IAzureResource.cs | Adds ATS summary override for polyglot docs. |
| src/Aspire.Hosting.Azure/ExistingAzureResourceExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Azure/AzureUserAssignedIdentityExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Azure/AzureResourceInfrastructure.cs | Adds ATS summary override for polyglot docs. |
| src/Aspire.Hosting.Azure/AzureResourceExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Azure/AzureProvisioningResourceExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Azure/AzureEnvironmentResourceExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Azure/AzureBicepResourceExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Azure/AzureBicepResource.cs | Adds ATS param override for polyglot-friendly type reference. |
| src/Aspire.Hosting.Azure.WebPubSub/AzureWebPubSubExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Azure.Sql/AzureSqlDatabaseResource.cs | Adds ATS summary override for child resource type. |
| src/Aspire.Hosting.Azure.SignalR/AzureSignalRExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Azure.ServiceBus/AzureServiceBusTopicResource.cs | Adds ATS summary override for exported resource type. |
| src/Aspire.Hosting.Azure.ServiceBus/AzureServiceBusSubscriptionResource.cs | Adds ATS summary override for exported resource type. |
| src/Aspire.Hosting.Azure.ServiceBus/AzureServiceBusQueueResource.cs | Adds ATS summary override for exported resource type. |
| src/Aspire.Hosting.Azure.Search/AzureSearchExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Azure.Redis/AzureManagedRedisExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Azure.PostgreSQL/AzurePostgresExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Azure.OperationalInsights/AzureLogAnalyticsWorkspaceExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Azure.Network/AzurePublicIPAddressExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Azure.Network/AzurePrivateEndpointExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Azure.Network/AzureNetworkSecurityPerimeterExtensions.cs | Moves exported doc text into ATS XML docs and adds ATS param references. |
| src/Aspire.Hosting.Azure.Network/AzureNetworkSecurityGroupExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Azure.Network/AzureNatGatewayExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Azure.Kusto/AzureKustoReadWriteDatabaseResourceExtensions.cs | Moves exported doc text into ATS XML docs with ATS param override. |
| src/Aspire.Hosting.Azure.Kusto/AzureKustoReadWriteDatabaseResource.cs | Adds ATS summary override for exported resource type. |
| src/Aspire.Hosting.Azure.Kusto/AzureKustoBuilderExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Azure.Kubernetes/AzureKubernetesIngressExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Azure.Kubernetes/AzureCertManagerExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Azure.KeyVault/AzureKeyVaultResourceExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Azure.Functions/DurableTask/DurableTaskResourceExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Azure.Functions/AzureFunctionsProjectResourceExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Azure.FrontDoor/AzureFrontDoorExtensions.cs | Moves exported doc text into ATS XML docs with ATS returns overrides. |
| src/Aspire.Hosting.Azure.EventHubs/AzureEventHubResource.cs | Adds ATS summary override for exported resource type. |
| src/Aspire.Hosting.Azure.CognitiveServices/AzureOpenAIExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Azure.AppService/AzureAppServicePolyglotCustomization.cs | Moves exported doc text into ATS XML docs for polyglot customization entrypoints. |
| src/Aspire.Hosting.Azure.AppService/AzureAppServiceEnvironmentExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Azure.AppService/AzureAppServiceComputeResourceExtensions.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting.Azure.ApplicationInsights/AzureApplicationInsightsExtensions.cs | Moves exported doc text into ATS XML docs with ATS params/returns overrides. |
| src/Aspire.Hosting.Azure.AppContainers/ContainerAppExtensions.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting.Azure.AppContainers/AzureContainerAppProjectExtensions.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting.Azure.AppContainers/AzureContainerAppPolyglotCustomization.cs | Moves exported doc text into ATS XML docs for polyglot customization entrypoints. |
| src/Aspire.Hosting.Azure.AppContainers/AzureContainerAppExecutableExtensions.cs | Moves exported doc text into ATS XML docs. |
| src/Aspire.Hosting.Azure.AppContainers/AzureContainerAppContainerExtensions.cs | Moves exported doc text into ATS XML docs. |
Use field and method ATS references for enum members and methods called out in review comments. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
JamesNK
reviewed
May 20, 2026
Remove ATS summary, parameter, and return overrides when the standard XML documentation already provides the same content for polyglot docs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
JamesNK
reviewed
May 20, 2026
Comment on lines
140
to
+147
| /// <summary> | ||
| /// Adds a named volume for the data folder to an Azure App Configuration emulator resource. | ||
| /// </summary> | ||
| /// <param name="builder">The builder for the <see cref="AzureAppConfigurationEmulatorResource"/>.</param> | ||
| /// <param name="name">The name of the volume. Defaults to an auto-generated name based on the application and resource names.</param> | ||
| /// <returns>A builder for the <see cref="AzureAppConfigurationEmulatorResource"/>.</returns> | ||
| [AspireExport(Description = "Adds a data volume for the App Configuration emulator")] | ||
| /// <ats-summary>Adds a data volume for the App Configuration emulator</ats-summary> | ||
| [AspireExport] |
Member
There was a problem hiding this comment.
The summaries here are still very close:
Adds a named volume for the data folder to an Azure App Configuration emulator resource.
vs
Adds a data volume for the App Configuration emulator.
Why do they need to be different?
Promote plain ATS summaries into the standard XML summary for internal polyglot-only exports and keep ATS summaries only when the standard summary uses references. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Remove ATS summary overrides that duplicate standard XML summaries closely enough for ATS to use the standard documentation directly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
JamesNK
reviewed
May 20, 2026
Comment on lines
+203
to
+205
| /// Assigns the specified roles to the given resource, granting it the necessary permissions | ||
| /// on the target Azure App Configuration resource. This replaces the default role assignments for the resource. | ||
| /// Assigns App Configuration roles to a resource |
Member
There was a problem hiding this comment.
Why is the shorter summary better? Is there a length limit in polygot scenarios?
Comment on lines
153
to
+160
| /// <summary> | ||
| /// Configures the host port for the Azure App Configuration emulator is exposed on instead of using randomly assigned port. | ||
| /// </summary> | ||
| /// <param name="builder">Builder for the Azure App Configuration emulator container</param> | ||
| /// <param name="port">The port to bind on the host. If <see langword="null"/> is used, a random port will be assigned.</param> | ||
| /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns> | ||
| [AspireExport(Description = "Sets the host port for the App Configuration emulator")] | ||
| /// <ats-summary>Sets the host port for the App Configuration emulator</ats-summary> | ||
| [AspireExport] |
Member
There was a problem hiding this comment.
Why not have the summary/description be Configures the host port for the Azure App Configuration emulator is exposed on instead of using randomly assigned port.?
What I'm getting at with all these comments is I don't see why they'd ever be different. The only scenario I can think of is if the .NET doc comment summary references types with <see cerf="..." />. In those cases the type ref could be converted to text, or if that type isn't exposed as ATS then provide a ats-summary override.
| internal static class AzureContainerAppPolyglotCustomization | ||
| { | ||
| [AspireExport("configureContainerAppScale", MethodName = "configureScale", Description = "Configures supported Azure Container App scale settings.")] | ||
| /// <ats-summary>Configures supported Azure Container App scale settings.</ats-summary> |
Member
There was a problem hiding this comment.
If there is only an ats-summary, what about just having <Summary> tags? That way it works with .NET tooling.
Comment on lines
-5
to
+6
| Description: Redis-specific configuration, | ||
| Documentation: { | ||
| Summary: Pattern 3: Tests concrete type with inheritance. This targets TestRedisResource directly (extends ContainerResource). Should expand to TestRedisResource AND any types that inherit from it. | ||
| Summary: Redis-specific configuration |
Member
There was a problem hiding this comment.
I assume this is ok and the description defaults to the summary if not provided?
Restore original C# summaries for exported members that do not need ATS-specific summary text, and keep ATS summaries only when the original summary contains C# reference tags. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add targeted ATS documentation overrides where C# references and examples leaked into generated polyglot docs, and update generated codegen snapshots. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
|
Re-running the failed jobs in the CI workflow for this pull request because 1 job was identified as retry-safe transient failures in the CI run attempt.
|
Contributor
|
❓ CLI E2E Tests unknown — 94 passed, 0 failed, 2 unknown (commit View all recordings
📹 Recordings uploaded automatically from CI run #26173670340 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
ATS now generates public API documentation for polyglot SDKs, so exported C# docs need language-neutral metadata instead of C#-specific XML shapes or
AspireExport.Descriptionstrings. This updates the exported API docs to use XML/ATS documentation tags that can be consumed by TypeScript and other generated SDKs.This change moves export descriptions into XML docs, adds targeted
ats-summary,ats-param, andats-returnsoverrides for polyglot-incompatible content, and teaches ATS references to accept compiler-safecref="!:type:...",method, andfieldforms. It also adds analyzer ruleASPIREEXPORT015so new[AspireExport(Description = ...)]usages fail during development, while preserving generated API baseline files.Fixes: #17068
Checklist
<remarks />and<code />elements on your triple slash comments?