Update ATS docs for polyglot APIs by sebastienros · Pull Request #17289 · microsoft/aspire

sebastienros · 2026-05-20T00:05:49Z

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.Description strings. 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, and ats-returns overrides for polyglot-incompatible content, and teaches ATS references to accept compiler-safe cref="!:type:...", method, and field forms. It also adds analyzer rule ASPIREEXPORT015 so new [AspireExport(Description = ...)] usages fail during development, while preserving generated API baseline files.

Fixes: #17068

Checklist

Is this feature complete?
- Yes. Ready to ship.
- No. Follow-up changes expected.
Are you including unit tests for the changes and scenario tests if relevant?
- Yes
- No
Did you add public API?
- Yes
  - If yes, did you have an API Review for it?
    - Yes
    - No
  - Did you add <remarks /> and <code /> elements on your triple slash comments?
    - Yes
    - No
- No
Does the change make any security assumptions or guarantees?
- Yes
  - If yes, have you done a threat model and had a security review?
    - Yes
    - No
- No

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>

github-actions · 2026-05-20T00:08:35Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 17289

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 17289"

Copilot

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 cref values prefixed with !: (so the C# compiler doesn’t validate the custom cref format).
Adds analyzer rule ASPIREEXPORT015 (and tests) to prevent new AspireExport.Description usages, 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>

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>

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>

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>

github-actions · 2026-05-20T17:57:55Z

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.
GitHub was asked to rerun all failed jobs for that attempt, and the rerun is being tracked in the rerun attempt.
The job links below point to the failed attempt jobs that matched the retry-safe transient failure rules.

Tests / Hosting-1 / Hosting-1 (windows-latest) - Job-level runner or infrastructure failure matched the transient allowlist.

IEvangelist · 2026-05-20T19:11:02Z

PR Testing Report

PR Information

PR: Update ATS docs for polyglot APIs #17289 - Update ATS docs for polyglot APIs
Head commit: 48406bfeb454b6b8065a85e574cace8073067828
Tester: GitHub Copilot CLI on Windows

CLI Version Verification

Expected commit: 48406bfeb454b6b8065a85e574cace8073067828
Installed CLI: 13.4.0-pr.17289.g48406bfe
Status: Passed - the dogfood CLI matched the PR head commit suffix.

Changes Analyzed

The PR updates Aspire export/XML documentation metadata across many hosting integration APIs, including ATS-specific XML documentation tags and removal/migration of AspireExportAttribute.Description values.

Test Scenarios Executed

Scenario 1: Dogfood CLI install and version check

Objective: Verify the PR dogfood artifact is available and corresponds to the current PR head.

Result: Passed

Evidence:

Installed from workflow run: https://github.com/microsoft/aspire/actions/runs/26173670340
aspire --version output: 13.4.0-pr.17289.g48406bfe

Scenario 2: Fresh starter app restore/build with PR packages

Objective: Verify the PR CLI can create a new Aspire app using the PR package channel and that the generated AppHost builds successfully.

Steps:

Ran aspire new aspire-starter --name AtsDocsSmoke --output . --non-interactive.
Ran dotnet build .\AtsDocsSmoke.AppHost\AtsDocsSmoke.AppHost.csproj --nologo.

Result: Passed

Evidence:

Template version selected: 13.4.0-pr.17289.g48406bfe
Build result: Build succeeded. with 0 warnings and 0 errors.

Summary

Scenario	Status	Notes
Dogfood CLI install/version check	Passed	Artifact version matched PR head commit suffix.
Fresh starter app restore/build	Passed	Generated AppHost built successfully with PR packages.

Overall Result

Passed for the executable smoke coverage available from the PR dogfood artifacts. I did not find a public CLI command in this build that directly emits the updated ATS/polyglot API documentation metadata, so the PR-specific documentation metadata was verified by diff review rather than a CLI scenario.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

radical

Found 2 issues: one compatibility-doc fallback regression and one stale README example.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-05-21T00:43:35Z

❓ CLI E2E Tests unknown — 96 passed, 0 failed, 2 unknown (commit 215b0fb)

View all recordings

Status	Test	Recording
✅	AddPackageInteractiveWhileAppHostRunningDetached	✅ ▶️ View recording
✅	AddPackageWhileAppHostRunningDetached	✅ ▶️ View recording
✅	AgentCommands_AllHelpOutputs_AreCorrect	✅ ▶️ View recording
✅	AgentInitCommand_DefaultSelection_InstallsDefaultSkills	✅ ▶️ View recording
✅	AgentInitCommand_MigratesDeprecatedConfig	✅ ▶️ View recording
✅	AllPublishMethodsBuildDockerImages	✅ ▶️ View recording
✅	AspireAddPackageVersionToDirectoryPackagesProps	✅ ▶️ View recording
✅	AspireInitSingleFileAppHostRunsViaDotnetRunAppHost	✅ ▶️ View recording
✅	AspireInitWithExistingAppHostDirRecreatesMissingNuGetConfigAndPreservesFiles	✅ ▶️ View recording
❔	AspireInitWithSolutionFileGeneratesAppHostThatBuildsAgainstChannelHive	❔ ▶️ View recording
✅	AspireUpdateRemovesAppHostPackageVersionFromDirectoryPackagesProps	✅ ▶️ View recording
✅	AspireUpdateRemovesOrphanAppHostPackageVersionWhenSdkAlreadyCurrent	✅ ▶️ View recording
✅	Banner_DisplayedOnFirstRun	✅ ▶️ View recording
✅	Banner_DisplayedWithExplicitFlag	✅ ▶️ View recording
✅	Banner_NotDisplayedWithNoLogoFlag	✅ ▶️ View recording
✅	CertificatesClean_RemovesCertificates	✅ ▶️ View recording
✅	CertificatesTrust_WithNoCert_CreatesAndTrustsCertificate	✅ ▶️ View recording
✅	CertificatesTrust_WithUntrustedCert_TrustsCertificate	✅ ▶️ View recording
✅	ConfigSetGet_CreatesNestedJsonFormat	✅ ▶️ View recording
✅	CreateAndRunAspireStarterProject	✅ ▶️ View recording
✅	CreateAndRunAspireStarterProjectWithBundle	✅ ▶️ View recording
✅	CreateAndRunEmptyAppHostProject	✅ ▶️ View recording
✅	CreateAndRunJavaEmptyAppHostProject	✅ ▶️ View recording
✅	CreateAndRunJsReactProject	✅ ▶️ View recording
✅	CreateAndRunPythonReactProject	✅ ▶️ View recording
✅	CreateAndRunTypeScriptEmptyAppHostProject	✅ ▶️ View recording
✅	CreateAndRunTypeScriptStarterProject	✅ ▶️ View recording
✅	CreateJavaAppHostWithViteApp	✅ ▶️ View recording
✅	CreateTypeScriptAppHostWithViteApp_UsesConfiguredToolchain	✅ ▶️ View recording
✅	DashboardRunWithOtelTracesReturnsNoTraces	✅ ▶️ View recording
✅	DeployK8sBasicApiService	✅ ▶️ View recording
✅	DeployK8sWithExternalHelmChart	✅ ▶️ View recording
✅	DeployK8sWithGarnet	✅ ▶️ View recording
✅	DeployK8sWithMongoDB	✅ ▶️ View recording
✅	DeployK8sWithMySql	✅ ▶️ View recording
✅	DeployK8sWithPostgres	✅ ▶️ View recording
✅	DeployK8sWithRabbitMQ	✅ ▶️ View recording
✅	DeployK8sWithRedis	✅ ▶️ View recording
✅	DeployK8sWithSqlServer	✅ ▶️ View recording
✅	DeployK8sWithValkey	✅ ▶️ View recording
✅	DeployTypeScriptAppToKubernetes	✅ ▶️ View recording
✅	DescribeCommandResolvesReplicaNames	✅ ▶️ View recording
✅	DescribeCommandShowsRunningResources	✅ ▶️ View recording
✅	DetachFormatJsonProducesValidJson	✅ ▶️ View recording
✅	DetachFormatJsonProducesValidJsonWhenRestartingExistingInstance	✅ ▶️ View recording
✅	DoListStepsShowsPipelineSteps	✅ ▶️ View recording
✅	DocsCommand_RendersInteractiveMarkdownFromLocalSource	✅ ▶️ View recording
✅	DoctorCommand_DetectsDeprecatedAgentConfig	✅ ▶️ View recording
✅	DoctorCommand_TypeScriptAppHostReportsMissingConfiguredToolchain	✅ ▶️ View recording
✅	DoctorCommand_WithSslCertDir_ShowsTrusted	✅ ▶️ View recording
✅	DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted	✅ ▶️ View recording
✅	GeneratedAspireDevScript_StartsWatchMode_WithConfiguredToolchain	✅ ▶️ View recording
✅	GlobalMigration_HandlesCommentsAndTrailingCommas	✅ ▶️ View recording
✅	GlobalMigration_HandlesMalformedLegacyJson	✅ ▶️ View recording
✅	GlobalMigration_PreservesAllValueTypes	✅ ▶️ View recording
✅	GlobalMigration_SkipsWhenNewConfigExists	✅ ▶️ View recording
✅	GlobalSettings_MigratedFromLegacyFormat	✅ ▶️ View recording
✅	InitTypeScriptAppHost_AugmentsExistingViteRepoAtRoot	✅ ▶️ View recording
✅	InteractiveCSharpInitCreatesExpectedFiles	✅ ▶️ View recording
✅	InvalidAppHostPathWithComments_IsHealedOnRun	✅ ▶️ View recording
✅	JavaScriptHostingApisRunFromTypeScriptAppHost	✅ ▶️ View recording
✅	LatestCliCanStartStableChannelAppHost	✅ ▶️ View recording
✅	LatestCliCanStartStableChannelTypeScriptAppHost	✅ ▶️ View recording
✅	LegacySettingsMigration_AdjustsRelativeAppHostPath	✅ ▶️ View recording
✅	LogLevelTrace_ProducesTraceEntriesInCliLogFile	✅ ▶️ View recording
✅	LogsCommandShowsResourceLogs	✅ ▶️ View recording
✅	OtelLogsReturnsStructuredLogsFromStarterApp	✅ ▶️ View recording
✅	OtelLogsReturnsStructuredLogsFromStarterAppIsolated	✅ ▶️ View recording
✅	PsCommandListsRunningAppHost	✅ ▶️ View recording
✅	PsFormatJsonOutputsOnlyJsonToStdout	✅ ▶️ View recording
✅	PublishJavaScriptPatternsGeneratesExpectedDockerComposeArtifacts	✅ ▶️ View recording
✅	PublishWithConfigureEnvFileUpdatesEnvOutput	✅ ▶️ View recording
✅	PublishWithDockerComposeServiceCallbackSucceeds	✅ ▶️ View recording
✅	PublishWithoutOutputPathUsesAppHostDirectoryDefault	✅ ▶️ View recording
✅	ResourceCommand_FailedExecution_DisplaysAppHostLogPathAndLogContainsEntries	✅ ▶️ View recording
✅	ResourceCommand_FailsWhenInteractionServiceIsRequired	✅ ▶️ View recording
✅	ResourceCommand_SetAndDeleteParameterUpdatesDescribeOutput	✅ ▶️ View recording
✅	RestoreGeneratesSdkFiles	✅ ▶️ View recording
✅	RestoreGeneratesSdkFiles_WithConfiguredToolchain	✅ ▶️ View recording
✅	RestoreRefreshesGeneratedSdkAfterAddingIntegration	✅ ▶️ View recording
✅	RestoreSupportsConfigOnlyHelperPackageAndCrossPackageTypes	✅ ▶️ View recording
✅	RunFromParentDirectory_UsesExistingConfigNearAppHost	✅ ▶️ View recording
❔	RunPublishFailureScenarioAsync	❔ ▶️ View recording
✅	RunReportsSyntaxErrorsForDotNetAppHost	✅ ▶️ View recording
✅	RunReportsSyntaxErrorsForTypeScriptAppHost	✅ ▶️ View recording
✅	SecretCrudOnDotNetAppHost	✅ ▶️ View recording
✅	SecretCrudOnTypeScriptAppHost	✅ ▶️ View recording
✅	StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels	✅ ▶️ View recording
✅	StartAndWaitForTypeScriptSqlServerAppHostWithNativeAssets	✅ ▶️ View recording
✅	StartReportsSyntaxErrorsForDotNetAppHost	✅ ▶️ View recording
✅	StartReportsSyntaxErrorsForTypeScriptAppHost	✅ ▶️ View recording
✅	StopAllAppHostsFromAppHostDirectory	✅ ▶️ View recording
✅	StopJavaPolyglotAppHostUsingApphostDirectory	✅ ▶️ View recording
✅	StopNonInteractiveSingleAppHost	✅ ▶️ View recording
✅	StopTypeScriptPolyglotAppHostUsingApphostDirectory	✅ ▶️ View recording
✅	StopWithNoRunningAppHostExitsSuccessfully	✅ ▶️ View recording
✅	UnAwaitedChainsCompileWithAutoResolvePromises	✅ ▶️ View recording
✅	UpdateProjectChannelToStable_TypeScript_PicksUpStablePackages	✅ ▶️ View recording

_{📹 Recordings uploaded automatically from CI run #26196935730}

…ostic Documents changes from microsoft/aspire#17289: - Update multi-language integration authoring guide to use XML doc comments instead of Description = "..." in all code examples - Add new 'Document your exports' section covering ats-summary, ats-param, ats-returns, ats-remarks, ats-see, and ats-seealso tags - Add ASPIREEXPORT015 to analyzer diagnostics table - Add new aspireexport015.mdx diagnostic reference page - Update diagnostics overview table with ASPIREEXPORT015 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

aspire-repo-bot · 2026-05-21T00:56:11Z

Pull request created: #1027

Generated by PR Documentation Check

aspire-repo-bot · 2026-05-21T00:58:23Z

📝 Documentation has been drafted in microsoft/aspire.dev#1027 targeting release/13.4.

Updated the multi-language integration authoring guide to replace Description = "..." code examples with XML doc comments, and added a new "Document your exports" section covering ats-summary, ats-param, ats-returns, ats-remarks, ats-see, and ats-seealso override tags introduced in this PR. Also added ASPIREEXPORT015 to the analyzer diagnostics table in the authoring guide and the diagnostics overview, and created a new aspireexport015.mdx reference page.

Files changed:

src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx — updated (new "Document your exports" section, updated code examples, ASPIREEXPORT015 in table)
src/frontend/src/content/docs/diagnostics/overview.mdx — updated (added ASPIREEXPORT015 entry)
src/frontend/src/content/docs/diagnostics/aspireexport015.mdx — new diagnostic reference page

Note

This draft PR needs human review before merging.

* Update polyglot ATS API docs 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> * Fix ATS reference kinds 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> * Prune duplicate ATS documentation overrides 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> * Deduplicate internal ATS export docs 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> * Prune close duplicate ATS summaries 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> * Restore C# summaries for ATS exports 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 ATS overrides for polyglot docs 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> * Discover parameterless ATS exports in workflows Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address ATS docs review feedback Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The new ASPIREEXPORT015 analyzer (introduced in microsoft#17289) flags `[AspireExport(Description = ...)]` as an error: polyglot SDK descriptions should come from XML documentation, with <ats-summary> overrides where the C# summary won't render well in polyglot docs. - AddRadiusEnvironment, WithNamespace, WithContainerImage, PublishAsRadiusResource: existing <summary> covers it; drop Description. - WithLegacyContainers: C# summary leans on <c> tags; add <ats-summary> with the polyglot-friendly text from the original Description. - PublishAsRadiusResource: summary references RadiusResourceCustomization (C#-only type); add <ats-summary> for clean polyglot docs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Nell Shamrell <nellshamrell@gmail.com>

…ostic Documents changes from microsoft/aspire#17289: - Update multi-language integration authoring guide to use XML doc comments instead of Description = "..." in all code examples - Add new 'Document your exports' section covering ats-summary, ats-param, ats-returns, ats-remarks, ats-see, and ats-seealso tags - Add ASPIREEXPORT015 to analyzer diagnostics table - Add new aspireexport015.mdx diagnostic reference page - Update diagnostics overview table with ASPIREEXPORT015 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings May 20, 2026 00:05

sebastienros requested review from JamesNK, danegsta, davidfowl, eerhardt, karolz-ms and mitchdenny as code owners May 20, 2026 00:05

Copilot started reviewing on behalf of sebastienros May 20, 2026 00:06 View session

Copilot AI reviewed May 20, 2026

View reviewed changes

sebastienros and others added 2 commits May 19, 2026 17:26

Fix ATS reference kinds

97f2256

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>

Merge origin/main into sebros-polyglot-api-docs

fa9f8f8

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

JamesNK reviewed May 20, 2026

View reviewed changes

Comment thread src/Aspire.Hosting.Azure.AppConfiguration/AzureAppConfigurationExtensions.cs Outdated

Prune duplicate ATS documentation overrides

ac2fd07

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

View reviewed changes

Comment thread src/Aspire.Hosting.Azure.AppConfiguration/AzureAppConfigurationExtensions.cs

sebastienros and others added 2 commits May 19, 2026 18:37

Deduplicate internal ATS export docs

0295b6c

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>

Prune close duplicate ATS summaries

832b899

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

View reviewed changes

sebastienros and others added 2 commits May 20, 2026 08:18

Restore C# summaries for ATS exports

a1a5e79

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 ATS overrides for polyglot docs

48406bf

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>

github-actions Bot mentioned this pull request May 20, 2026

[repo-pulse] 📊 Repo Pulse — Daily Activity Dashboard #16404

Open

sebastienros and others added 3 commits May 20, 2026 14:18

Merge origin/main into sebros-polyglot-api-docs

66a9fa4

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Discover parameterless ATS exports in workflows

2f4d6f7

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Merge origin/main into sebros-polyglot-api-docs

662c88c

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

radical reviewed May 20, 2026

View reviewed changes

Comment thread src/Aspire.Hosting.RemoteHost/AtsCapabilityScanner.cs Outdated

Comment thread src/Aspire.Hosting.RemoteHost/README.md

radical approved these changes May 20, 2026

View reviewed changes

JamesNK approved these changes May 20, 2026

View reviewed changes

Address ATS docs review feedback

215b0fb

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

sebastienros merged commit b84c21d into main May 21, 2026
599 of 603 checks passed

sebastienros deleted the sebastienros/sebros-polyglot-api-docs branch May 21, 2026 00:41

github-actions Bot added this to the 13.4 milestone May 21, 2026

aspire-repo-bot Bot mentioned this pull request May 21, 2026

[docs] Update ATS docs for polyglot APIs and add ATS diagnostics microsoft/aspire.dev#1027

Merged

Conversation

sebastienros commented May 20, 2026

Description

Checklist

Uh oh!

github-actions Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 20, 2026

Uh oh!

IEvangelist commented May 20, 2026

PR Testing Report

PR Information

CLI Version Verification

Changes Analyzed

Test Scenarios Executed

Scenario 1: Dogfood CLI install and version check

Scenario 2: Fresh starter app restore/build with PR packages

Summary

Overall Result

Uh oh!

radical left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 21, 2026

Uh oh!

aspire-repo-bot Bot commented May 21, 2026

Uh oh!

aspire-repo-bot Bot commented May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions Bot commented May 20, 2026 •

edited

Loading