Skip to content

Fill remaining Aspire 17.0 doc gaps and add 17.0 dashboard captures - #2188

Merged
David Pine (IEvangelist) merged 5 commits into
release/17.0from
ievangelist-whats-new-17-0-coverage
Nov 17, 2026
Merged

David Pine (IEvangelist) merged 5 commits into
release/17.0from
ievangelist-whats-new-17-0-coverage

Conversation

@IEvangelist

@IEvangelist David Pine (IEvangelist) commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Summary

Follow-up to #2177. It carries the gap-fill work that wasn't pushed before #2177 merged. It also restores the What's New breaking-change entries that #2180 dropped when it merged afterward.

I audited all 298 items in the 17.0 changelog and the 17.0 PRs that aren't in it against release/17.0 and the open docs PRs targeting it. These are the remaining gaps.

What's New (whats-new/aspire-17.mdx)

  • New dashboard captures from the 17.0 GA bundle (17.0.0+148071e3), in Comfortable density and in dark and light:
    • The resource table home page.
    • The All resources overview, which is now also the page's resourceImage.
    • Metrics grouped by resource, with the resource list collapsed.
  • New sections:
    • Azure AI client packages, plus a breaking change: Aspire.Azure.AI.OpenAI and Aspire.Azure.AI.Inference are discontinued.
    • A breaking change: the default maximum OTLP request size is now 64 MiB (OpenTelemetry 1.18).
  • Smaller additions:
    • WithTerminal and TerminalOptions graduating to stable.
    • Kubernetes PVC customization.
    • Front Door GetEndpointId.
    • The Blazor Gateway CLI.
    • Exit codes in aspire describe.
    • The aspire update --migrate hint for SDK migration.
  • Restored the breaking-change rows and sections docs: Migrate to AddDotnetProject/DotnetProjectResource and remove Aspire.AppHost.Sdk #2180 removed:
    • Aspire.AppHost.Sdk obsolete.
    • ShowTerminalHost removed.
    • Polyglot feature keys renamed.
    • Let's Encrypt shortcuts removed.
    • AKS identities.
    • Polyglot addNodePool.
    • SQL Server REPL sqlcmd paths.
  • Kept docs: Migrate to AddDotnetProject/DotnetProjectResource and remove Aspire.AppHost.Sdk #2180's revised AddCSharpApp wording.

Docs that were wrong or out of date

  • Entra ID: AddExistingEntraApplication → AddExistingEntraIdApplication, from the 17.0 API review rename.
  • AKS: removed the deleted WithLetsEncryptProduction/WithLetsEncryptStaging from the samples.
  • The aspire secret commands: documented -e/--environment, per-environment storage, and the one-time import of existing user secrets.
  • The ServiceDefaults sample now targets net10.0.

Docs that were missing

  • Azure AI: Aspire.Azure.AI.Extensions.OpenAI and Aspire.Azure.AI.Projects client docs, the compatibility matrix, and migration sections.
  • Kubernetes: cert-manager External Account Binding with WithExternalAccountBinding, the WithAcmeServer directory URLs, and fileKeyRef environment variables.
  • Azure:
    • Front Door GetEndpointId.
    • The Service Bus emulator's WithSqlServer.
    • ACR purge-task behavior, including deletion of untagged manifests.
  • CLI:
    • aspire new --template-path, --template-repository and --template-repository-ref.
    • The template source displayName and defaultValueSource settings.
    • Exit codes in aspire describe.
  • AppHost:

17.0 milestone issues

Third-party links and affiliations

ACME directory URLs for Let's Encrypt, ZeroSSL and Google Trust Services in the AKS cert-manager docs. No affiliations.

Validation

  • bunx vitest run tests/unit/dev-resource-catalog.vitest.test.ts tests/unit/docs-internal-links.vitest.test.ts tests/unit/docs-markdown-link-targets.vitest.test.ts tests/unit/seo-lengths.vitest.test.ts tests/unit/whats-new.vitest.test.ts tests/unit/whats-new-sidebar.vitest.test.ts: 6 files and 37 tests passed. This ran before the rebase onto the docs: Migrate to AddDotnetProject/DotnetProjectResource and remove Aspire.AppHost.Sdk #2180 merge; CI covers the rebased branch.
  • A code-review agent checked the API names, flags, packages and links against microsoft/aspire release/17.0 source. It found one broken link, which is fixed.
  • I didn't run bun run build locally; CI covers it.

- Azure AI: document Aspire.Azure.AI.Extensions.OpenAI and Aspire.Azure.AI.Projects; mark OpenAI/Inference packages discontinued
- Entra ID: AddExistingEntraApplication -> AddExistingEntraIdApplication
- Kubernetes: cert-manager EAB and WithAcmeServer (remove WithLetsEncrypt*), fileKeyRef env vars
- Azure: Front Door GetEndpointId, Service Bus emulator WithSqlServer, ACR purge untagged manifests
- CLI: environment-specific aspire secret, aspire new template options, template displayName/defaultValueSource, describe exit codes
- AppHost: WithRequiredCommand, WithHttpProbe, TypeScript hosting integrations page; dashboard explore notes
- What's new: Azure AI packages, OTLP size change, WithTerminal graduation, PVC customization, and more

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Capture the home page, All resources overview, and metrics (grouped by resource) from the 17.0 dashboard in comfortable density, in dark and light themes.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- Document required parameters rejecting empty values (#2114)
- Expand DisplayOrder and Cosmos DB breaking-change details (#2131, #2130)
- Use flat experimentalPolyglot feature keys in CLI config docs (#1925)

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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The documentation misstates health-check endpoint selection and recommends a Foundry Local registration that drops required /v1/ normalization, sending chat requests to the wrong path.

2 open issues
What changed in this PR

Completes Aspire 17.0 documentation coverage following #2177 and restores breaking-change guidance removed by #2180, while retaining its revised .NET project migration wording.

Changes:

  • Refreshes release notes with dashboard captures, feature additions, and migration guidance.
  • Documents new Azure AI clients, Kubernetes deployment options, and environment-specific CLI secrets.
  • Adds TypeScript integration-authoring guidance and updates AppHost examples, API names, and navigation.
File Description
src/​frontend/​src/​data/​integration-docs.json Maps new Azure AI packages to documentation.
src/​frontend/​src/​content/​docs/​whats-new/​aspire-17.mdx Expands release coverage and restores breaking changes.
src/​frontend/​src/​content/​docs/​reference/​cli/​commands/​aspire-template-source.mdx Documents source labels and prompt defaults.
src/​frontend/​src/​content/​docs/​reference/​cli/​commands/​aspire-secret.mdx Explains environment-specific storage and migration.
src/​frontend/​src/​content/​docs/​reference/​cli/​commands/​aspire-secret-set.mdx Adds environment-specific secret creation guidance.
src/​frontend/​src/​content/​docs/​reference/​cli/​commands/​aspire-secret-path.mdx Documents environment-specific file paths.
src/​frontend/​src/​content/​docs/​reference/​cli/​commands/​aspire-secret-list.mdx Covers environment selection and listing all environments.
src/​frontend/​src/​content/​docs/​reference/​cli/​commands/​aspire-secret-get.mdx Adds environment-specific retrieval examples.
src/​frontend/​src/​content/​docs/​reference/​cli/​commands/​aspire-secret-delete.mdx Adds environment-specific deletion examples.
src/​frontend/​src/​content/​docs/​reference/​cli/​commands/​aspire-new.mdx Documents local and Git template sources.
src/​frontend/​src/​content/​docs/​reference/​cli/​commands/​aspire-describe.mdx Explains resource exit-code display.
src/​frontend/​src/​content/​docs/​integrations/​security/​microsoft-entra-id/​lifecycle-and-permissions.mdx Corrects the existing-registration API name.
src/​frontend/​src/​content/​docs/​integrations/​security/​microsoft-entra-id/​index.mdx Updates the existing-registration API reference.
src/​frontend/​src/​content/​docs/​integrations/​security/​microsoft-entra-id/​existing-registrations.mdx Updates registration examples to the renamed API.
src/​frontend/​src/​content/​docs/​integrations/​security/​microsoft-entra-id/​client-credentials.mdx Updates credential examples to the renamed API.
src/​frontend/​src/​content/​docs/​integrations/​compute/​kubernetes.mdx Adds file-backed environment variable guidance.
src/​frontend/​src/​content/​docs/​integrations/​cloud/​azure/​azure-service-bus/​azure-service-bus-host.mdx Documents emulator SQL Server customization and reuse.
src/​frontend/​src/​content/​docs/​integrations/​cloud/​azure/​azure-openai/​azure-openai-get-started.mdx Introduces the replacement OpenAI client package.
src/​frontend/​src/​content/​docs/​integrations/​cloud/​azure/​azure-openai/​azure-openai-connect.mdx Updates client registration, configuration, and migration.
src/​frontend/​src/​content/​docs/​integrations/​cloud/​azure/​azure-front-door.mdx Documents endpoint resource-ID outputs.
src/​frontend/​src/​content/​docs/​integrations/​cloud/​azure/​azure-container-registry/​azure-container-registry-host.mdx Clarifies purge retention and untagged-manifest deletion.
src/​frontend/​src/​content/​docs/​integrations/​cloud/​azure/​azure-ai-inference/​azure-ai-inference-get-started.mdx Adds discontinued-package migration guidance.
src/​frontend/​src/​content/​docs/​integrations/​cloud/​azure/​azure-ai-inference/​azure-ai-inference-connect.mdx Identifies legacy client guidance and replacement options.
src/​frontend/​src/​content/​docs/​integrations/​cloud/​azure/​azure-ai-foundry/​azure-ai-foundry-connect.mdx Adds cloud deployment and project client guidance.
src/​frontend/​src/​content/​docs/​integrations/​cloud/​azure/​ai-compatibility-matrix.mdx Updates supported AI client pairings.
src/​frontend/​src/​content/​docs/​get-started/​csharp-service-defaults.mdx Updates the custom ServiceDefaults example to .NET 10.
src/​frontend/​src/​content/​docs/​fundamentals/​health-checks.mdx Documents HTTP probes and deployment behavior.
src/​frontend/​src/​content/​docs/​extensibility/​typescript-hosting-integrations.mdx Adds experimental TypeScript integration authoring instructions.
src/​frontend/​src/​content/​docs/​extensibility/​multi-language-integration-authoring.mdx Links to the new TypeScript authoring guide.
src/​frontend/​src/​content/​docs/​diagnostics/​aspirecommand001.mdx Links to current required-command guidance.
src/​frontend/​src/​content/​docs/​deployment/​kubernetes/​aks.mdx Replaces removed ACME helpers and documents account binding.
src/​frontend/​src/​content/​docs/​dashboard/​explore.mdx Explains hidden resources and error badges.
src/​frontend/​src/​content/​docs/​app-host/​executable-resources.mdx Documents required commands and validation callbacks.
src/​frontend/​config/​sidebar/​docs.topics.ts Adds navigation for TypeScript hosting integrations.

Review effort: Balanced

</TabItem>
</Tabs>

By default, a probe targets the resource's first HTTP or HTTPS endpoint; set `endpointName` to choose another. The optional `initialDelaySeconds`, `periodSeconds`, `timeoutSeconds`, `failureThreshold`, and `successThreshold` parameters default to `5`, `5`, `1`, `3`, and `1`, and the path defaults to `/`. Each probe also adds an HTTP health check for the same endpoint and path, so `WaitFor` and the dashboard use it when you run locally.
The client authenticates with Microsoft Entra ID: Aspire uses a development credential locally and managed identity when deployed to Azure. Resolve `OpenAI.OpenAIClient` or `IChatClient` through dependency injection. Use `AddEmbeddingGenerator()` for embedding deployments, and `AddKeyedAzureOpenAIClient` for keyed registrations. For configuration and telemetry options, see [Connect to Azure OpenAI](/integrations/cloud/azure/azure-openai/azure-openai-connect/#configuration).

<Aside type="tip">
To use the same code for Foundry Local and cloud deployments, call `builder.AddOpenAIClientFromConfiguration("chat").AddChatClient()`. It reads the connection string and uses Foundry Local's API key or Microsoft Entra ID for Azure, without an application-side switch.
- Remove 'now stable' and 'Starting with Aspire 17.0' phrasing from evergreen pages
- Use short 'Upgrading to Aspire 17?' notes for discontinued packages and secret storage
- Apply doc-writer prose patterns to new What's new content

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- Use plain code for API names missing from generated API data
- Accept nested-package imports of the .aspire/modules layout in the SDK import check

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

Copy link
Copy Markdown
Contributor

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #2188. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

VS Code: Open PR #2188 artifacts

This comment updates automatically when a new frontend build artifact is uploaded.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants