Skip to content

[docs] Document ASPIRE015 (AspireCliPath overrides AspireCliInvocationMode) - #2110

Draft
aspire-repo-bot[bot] wants to merge 216 commits into
mainfrom
docs/pr-21592-42932767754-1-4c891eda08d58399
Draft

aspire-repo-bot[bot] wants to merge 216 commits into
mainfrom
docs/pr-21592-42932767754-1-4c891eda08d58399

Conversation

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Documents changes from microsoft/aspire#21592

Author: @(PR author per source PR)

Target branch: Targeting release/17.0, the latest release branch on microsoft/aspire.dev, because the source PR has no milestone or release/* base ref to derive a more specific target (candidate_source: fallback_main, target_resolution: latest_release_fallback).

Why: The source PR adds a suppressible ASPIRE015 warning emitted when AspireCliPath overrides an explicit AspireCliInvocationMode of Dnx/DnxPinned. Triggered signal: diagnostic_documentation_changed (docs/list-of-diagnostics.md). The docs site had no page for it.

Changes (1 new page, 2 updated files):

  • New: src/frontend/src/content/docs/diagnostics/aspire015.mdx
  • Updated: src/frontend/src/content/docs/diagnostics/overview.mdx (table row)
  • Updated: src/frontend/config/sidebar/reference.topics.ts (sidebar entry)

Generated by PR Documentation Check for #21592 · copilot · auto · 25 AIC · ⌖ 1.19 AIC · ⊞ 7.4K · ◷

github-actions Bot and others added 30 commits September 30, 2026 20:09
…17.0

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Documents the Hex1b 0.171.0 upgrade's user-facing dashboard terminal
changes: overlay scrollbar with command marks, the Dark/Light terminal
palette control, copyable title/working-directory metadata, and dock
tab drag/keyboard reordering.

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

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

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

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

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

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

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

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

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

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

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

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Documents microsoft/aspire#20746, which adds an Export as Mermaid action to
the dashboard resource graph and a --format mermaid option to aspire
describe / aspire resources.

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

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

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

<!-- Describe what this pull request changes and why. -->

Bring the Aspire brand kit into Community with an overview, logo and
icon downloads, colors and CSS tokens, Poppins and Fira Code typography,
and usage guidance.

- Host SVG assets locally, including user-approved font-independent
wordmark exports with adjusted stacked lettering and a reproducible
generator.
- Require a fresh licensing/usage acknowledgement for each UI download
and provide a wider, scrollable read-only artwork-license dialog.
- Preserve the published Do/Do not wording in responsive cards with
check/cross icons.
- Keep the PowerPoint deck external and link-only. Add its icon, a clear
download CTA, and external-link indicators.
- Point the footer's brand link at the local overview; add Blog under
Resources and the Aspire team email under Community.

Targets `release/17.0`. The user-requested `ci:skip-forbidden-words`
label is applied because preserved brand guidance quotes the discouraged
product name.

**Known validation issue:** one mobile navigation scenario still fails:
after following the presentation anchor from the usage page, the
Download PowerPoint button cannot receive a normal click. Browser logs
show view-transition errors. The initial-load agreement flow passes; the
navigation failure needs investigation.

## Third-party links and affiliations

<!--
List any third-party links added or changed by this pull request and
disclose any
material affiliation with the linked organizations, such as employment,
sponsorship, or ownership. Write "None" if this pull request doesn't add
or
change third-party links.
-->

Resource links include Google Fonts (Poppins), Fontsource (Poppins/Fira
Code), the Fira Code GitHub repository, and the Creative Commons CC0
reference. Brand-repository and presentation links reference
Microsoft-owned resources. The PowerPoint icon uses
`thesvg-color:microsoft-powerpoint`; its MIT notice is retained within
the SVG metadata.

These are source, font, and licensing references, not affiliate links.
No sponsorship or ownership affiliation with these third-party resources
was supplied for this change.

## Validation

<!-- List the checks you ran or explain why validation isn't needed. -->

Local desktop/mobile design iteration completed. Commands below were run
from the repository root:

- `pnpm --dir src\frontend exec astro sync` — passed.
- `pnpm --dir src\frontend exec vitest run --config vitest.config.ts
tests\unit\brand-assets.vitest.test.ts
tests\unit\custom-components.vitest.test.ts
tests\unit\seo-lengths.vitest.test.ts` — passed, 113 tests.
- `pnpm --dir src\frontend exec tsc --ignoreConfig --noEmit --strict
--skipLibCheck --target es2022 --module nodenext src\data\brand.ts` —
passed.
- `pnpm --dir src\frontend exec eslint src\data\brand.ts
scripts\generate-brand-wordmarks.mjs config\sidebar\community.topics.ts
tests\unit\brand-assets.vitest.test.ts
tests\unit\custom-components.vitest.test.ts
tests\typecheck\component-props.contracts.ts
tests\e2e\brand-assets.spec.ts --max-warnings 0` — passed.
- `$env:PLAYWRIGHT_TEST_PORT = '4391'; pnpm --dir src\frontend exec
playwright test brand-assets.spec.ts --workers 1` — 29 passed, 4 failed
before the copy-feedback lifecycle fix.
- `$env:PLAYWRIGHT_TEST_PORT = '4391'; pnpm --dir src\frontend exec
playwright test brand-assets.spec.ts --workers 1 --grep "copies
exact|PowerPoint link"` — 5 passed, 1 failed after the fix. Copying,
exact multiline CSS values, the three-second reset, and success colors
now pass in desktop, tablet, and mobile. The remaining failure is the
mobile navigation scenario described above.

An earlier full `tsc --noEmit` attempt failed on existing
repository-wide configuration/type issues, including Astro component
resolution; the standalone new brand-data check passed. No local
production build was run; production build/search validation is left to
CI.

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…17.0

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

<!-- Describe what this pull request changes and why. -->

- Fix brand external-link icons wrapping onto separate lines or
rendering twice.
- Refine brand card surfaces, spacing, navigation hierarchy, and
wordmark galleries while preserving the existing artwork, guidance, and
download agreements.
- Compact supporting accent swatches and remove repeated filler
descriptions. Match card code to code-block font sizing, group gradient
arguments on one line, and bottom-align gradient Copy buttons.
- Add the composed brand-board OG image to the overview and fix
generated PNG endpoints so advertised image URLs work without trailing
slashes.
- Support a validated build-time `PUBLIC_OG_IMAGE_ORIGIN` for preview
deployments without changing production canonical URLs, with regression
coverage.

**Preview deployment requirement:** Set `PUBLIC_OG_IMAGE_ORIGIN` to the
preview site's public origin before building. This PR does not update or
rebuild the existing Azure deployment; changing a runtime setting alone
will not update already-built metadata.

This PR contains only the follow-up changes on the `release/17.0` base,
not a replay of the previously merged brand implementation. The
contributor guide is unchanged from the base.

## Third-party links and affiliations

<!--
List any third-party links added or changed by this pull request and
disclose any
material affiliation with the linked organizations, such as employment,
sponsorship, or ownership. Write "None" if this pull request doesn't add
or
change third-party links.
-->

None. Existing external resource links are unchanged, including the
link-only PowerPoint deck.

## Validation

<!-- List the checks you ran or explain why validation isn't needed. -->

**Passed: 185 unit tests across four files.**

```powershell
pnpm --dir src\frontend exec vitest run --config vitest.config.ts tests\unit\brand-assets.vitest.test.ts tests\unit\custom-components.vitest.test.ts tests\unit\page-metadata.vitest.test.ts tests\unit\seo-lengths.vitest.test.ts
```

**Passed: scoped ESLint, zero warnings.**

```powershell
pnpm --dir src\frontend exec eslint src\utils\page-metadata.ts src\data\brand.ts tests\unit\brand-assets.vitest.test.ts tests\unit\custom-components.vitest.test.ts tests\unit\page-metadata.vitest.test.ts tests\e2e\brand-assets.spec.ts 'src\pages\og\[...slug].png.ts' --max-warnings 0
```

**Passed: 24 browser tests across desktop, tablet, and mobile.** Covers
advertised 1200×630 PNG social cards, multiline external-link rendering,
brand page accessibility/reflow, and exact copied color/gradient values.

```powershell
$env:PLAYWRIGHT_TEST_PORT='4397'; $env:PUBLIC_OG_IMAGE_ORIGIN='http://127.0.0.1:4397'; pnpm --dir src\frontend exec playwright test brand-assets.spec.ts --grep "social cards|multiline external links|accessible and reflows|copies exact" --workers 1
```

**Passed:** `git diff --check origin/release/17.0...HEAD`.

**Passed: contributor guide restored exactly to the base.**

```powershell
git diff --exit-code origin/release/17.0 -- src\frontend\src\content\docs\community\contributor-guide.mdx
```

The unit/browser/lint results above precede the documentation-only
removal; no application code changed afterward. No local production
build was run. The dev server has been stopped.

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…17.0

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

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
….v2 guidance (#1800)

Documents changes from microsoft/aspire#20608

``@eerhardt``

## Why this is needed

microsoft/aspire#20608 removed the legacy `Aspire.RabbitMQ.Client.v6`
and `Aspire.MongoDB.Driver.v2` packages. The main
`Aspire.RabbitMQ.Client` package now depends on `RabbitMQ.Client` 7.x
directly, and the main `Aspire.MongoDB.Driver` package now depends on
`MongoDB.Driver` 3.x directly — there is no longer a version-suffixed
sibling package for either integration.

The aspire.dev docs never referenced the removed `.v6`/`.v2` packages by
name, but they did describe now-outdated version-split guidance for the
*current* packages (e.g., telling readers to install
`Aspire.RabbitMQ.Client.v7` for RabbitMQ.Client 7.x, or choose between
`Aspire.MongoDB.Driver` and `Aspire.MongoDB.Driver.v3` based on their
MongoDB.Driver version). That guidance is stale now that the main
packages target the newer client library versions directly.

## What changed

- **`integrations/messaging/rabbitmq/rabbitmq-connect.mdx`**: Replaced
the note that `Aspire.RabbitMQ.Client` depends on RabbitMQ.Client 6.8.1
(and to install `Aspire.RabbitMQ.Client.v7` for 7.x) with accurate
guidance that the package depends on RabbitMQ.Client 7.x directly,
noting the historical `.v6` package has been removed.
- **`integrations/databases/mongodb/mongodb-connect.mdx`**: Replaced the
two-package install guidance (choosing between `Aspire.MongoDB.Driver`
for driver 2.x vs `Aspire.MongoDB.Driver.v3` for 3.x) and the
`:::danger` deprecation callout with accurate guidance that the package
depends on MongoDB.Driver 3.x directly, noting the historical `.v2`
package has been removed.
- **`integrations/databases/mongodb/mongodb-get-started.mdx`**: Dropped
the `(or Aspire.MongoDB.Driver.v3)` parenthetical from the client
integration feature bullet.
- **`whats-new/aspire-17.mdx`**: Added the initial Aspire 17.0
release-notes page and documented removal of the legacy packages as a
breaking change, including replacement packages and migration guidance.
- **`config/sidebar/docs.topics.ts`**: Added Aspire 17.0 to the What's
new navigation using the established major-release route,
`/whats-new/aspire-17/`.

The integration guidance was updated in place, and the new Aspire 17.0
release-notes page records the package removal and required migration as
a breaking change.

> Generated by [PR Documentation
Check](https://github.com/microsoft/aspire/actions/runs/36757192904) for
#20608 · copilot · auto · 111.8 AIC · ⌖ 12.3 AIC · ⊞ 20.3K ·
[◷](https://github.com/search?q=repo%3Amicrosoft%2Faspire.dev+%22gh-aw-workflow-id%3A+pr-docs-check%22&type=pullrequests)

<!-- gh-aw-agentic-workflow: PR Documentation Check, engine: copilot,
model: auto, id: 36757192904, workflow_id: pr-docs-check, run:
https://github.com/microsoft/aspire/actions/runs/36757192904 -->

<!-- gh-aw-workflow-id: pr-docs-check -->
<!-- gh-aw-workflow-call-id: microsoft/aspire/pr-docs-check -->

---------

Co-authored-by: aspire-repo-bot[bot] <268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Eric Erhardt <eric.erhardt@microsoft.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
…17.0

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

<!-- Describe what this pull request changes and why. -->

- Keep Aspire 17.0 first in What's new and group previous releases under
collapsed Aspire 13.x and Aspire 9.x sections, newest releases first.
- Save the brand-guidelines acknowledgment in localStorage only after
confirmation, so subsequent asset and presentation downloads do not
prompt again in the same browser.
- Remove PUBLIC_OG_IMAGE_ORIGIN and restore Astro's configured site as
the OG-image base, preserving article-level ogImage overrides.
- Give brand articles explicit titles, include the brandkit search term
in metadata and visible content, and tighten prose against the
documentation-writing guidance.
- Replace the duplicated license file with the current upstream raw
license. Preserve the read-only dialog with on-demand loading, explicit
errors, retries, and a direct-source fallback.

Self-reviewed the complete diff, navigation hierarchy, consent
lifecycle, download destinations, license failure paths, search-index
coverage, and OG metadata behavior.

## Third-party links and affiliations

<!--
List any third-party links added or changed by this pull request and
disclose any
material affiliation with the linked organizations, such as employment,
sponsorship, or ownership. Write "None" if this pull request doesn't add
or
change third-party links.
-->

License links now use
https://raw.githubusercontent.com/microsoft/aspire-brand/main/LICENSE,
the official Microsoft-maintained brand repository, instead of a locally
duplicated license. Existing Google Fonts and Fontsource destinations
are unchanged. No new third-party providers are introduced; no
additional affiliation information was supplied for this change.

## Validation

<!-- List the checks you ran or explain why validation isn't needed. -->

Commands run from src/frontend:

- `pnpm exec eslint config\sidebar\docs.topics.ts src\data\brand.ts
src\utils\page-metadata.ts tests\unit\whats-new-sidebar.vitest.test.ts
tests\unit\page-metadata.vitest.test.ts
tests\unit\brand-assets.vitest.test.ts
tests\unit\custom-components.vitest.test.ts
tests\e2e\brand-assets.spec.ts tests\e2e\site-search.spec.ts
tests\e2e\whats-new-sidebar.spec.ts --max-warnings 0` — passed.
- `pnpm exec vitest run --config vitest.config.ts
tests\unit\whats-new-sidebar.vitest.test.ts
tests\unit\page-metadata.vitest.test.ts
tests\unit\brand-assets.vitest.test.ts
tests\unit\browser-storage.vitest.test.ts
tests\unit\custom-components.vitest.test.ts` — passed, 191 tests across
five files.
- `pnpm exec playwright test brand-assets.spec.ts
whats-new-sidebar.spec.ts site-search.spec.ts --workers=2 --grep
'brand|multiline external links|footer leads|all nine official
SVGs|copies exact color|reports clipboard|remote artwork|current
release'` — passed, 48 tests across desktop/tablet/mobile; three
production Pagefind checks skipped locally and reserved for CI.
- `pnpm exec tsc --noEmit --skipLibCheck --pretty false` — not clean:
existing repository-wide diagnostics include unresolved Astro component
declarations and unrelated configuration/test errors. Targeted typed
ESLint passed; no new errors were found in the changed implementation or
newly added sidebar tests.
- `git diff --check` — passed.

No local production build was run. CI owns the production build and the
new brandkit Pagefind regression test.

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Copilot-Session: 8b981999-6e5c-4dc5-bed9-881858ed56c6
…17.0

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

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

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

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

Merging `main` (`e95a50157ffa8b660f17e6f5cf83c95f34ba2c9c`) into
`release/17.0` hit conflicts that the release sync can't resolve
automatically. This branch holds the merge with the conflicts left for
you to resolve.

### Text conflicts (markers left in the file)

- `src/frontend/tests/typecheck/component-props.contracts.ts`

### Needs a decision (no markers)

Git can't mark these, so this branch currently keeps one side. Review
each and choose deliberately:


To land it:

1. Check out `release-sync/17.0` and resolve each item above without
discarding release-only work.
2. Push the fix, mark the PR ready for review, and wait for checks.
3. Merge with **Create a merge commit**, never squash or rebase. Copying
content alone doesn't repair ancestry.

Release sync is paused while this PR is open. After it merges, verify
`git merge-base --is-ancestor e95a501
origin/release/17.0`; the next push to main resumes syncing.

## Third-party links and affiliations

None

## Validation

Automated merge of `main` into `release/17.0`. Not validated: conflicts
are unresolved.

---------

Co-authored-by: David Pine <david.pine@microsoft.com>
Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Maddy Montaquila <maleger@microsoft.com>
Co-authored-by: Alistair Matthews <alistairwebdojo@live.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Copilot-Session: 0d21fabc-759d-45d9-b1fb-41733ff02aa0
## Summary

Fills gaps between `get-started/aspire-skills.mdx` and the current
`microsoft/aspire-skills` plugin:

- Adds the `aspire-terminals` skill (table, routing guidance, skill file
tree) and names the three canvas extensions.
- Adds Gemini CLI and Cursor CLI install tabs.
- Adds OpenCode V1/V2 HTTP skill catalog configuration.
- Documents `copilot plugin update` / `/plugin update` and the Ollama +
Copilot CLI path.

## Third-party links and affiliations

None. Links are to Microsoft-owned repositories,
raw.githubusercontent.com content for `microsoft/aspire-skills`, and no
new vendor sites.

## Validation

Compared against `microsoft/aspire-skills` README and
`skills/`/`extensions/` contents. Did not run the site build (CI covers
it).

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…pire.AppHost.Sdk (#2180)

## Summary

<!-- Describe what this pull request changes and why. -->

Moves aspire.dev off the legacy
`AddProject`/`AddCSharpApp`/`ProjectResource` APIs onto Aspire 17's
`AddDotnetProject`/`DotnetProjectResource`, and removes the obsolete
`Aspire.AppHost.Sdk`. Tracked in #2179.

**New pages**
- [Migrate to the new
DotnetProjectResource](/integrations/dotnet/migrate-dotnet-project-resource/):
why to upgrade, the agent-skill option, path/launch-profile/type
changes, and removing the AppHost SDK.
- `ASPIRE012` diagnostic (`Aspire.AppHost.Sdk` is obsolete), with
sidebar and overview rows. The `aspire update --migrate` notice from
microsoft/aspire#22340 links to it.

**Evergreen rewrites**
- `dotnet-host` is now the main .NET page. It adds endpoint filtering,
coordinated builds/restore, multithreaded builds, and links to
file-based apps and launch profiles.
- `get-started/aspire-sdk` is now "C# AppHost project configuration".
- C# file-based apps and launch profiles now use `AddDotnetProject`.
- `project-resources` becomes a short "Legacy project resources"
reference, listed in the sidebar below the migration guide. Inbound
links now point to `dotnet-host`.

**Sample sweep (C#/TS/Go)**
- Converted `AddProject<Projects.X>`, `addProject`, and `AddCSharpApp`
across app-host, fundamentals, deployment, get-started, testing,
architecture, and integration pages. This includes Blazor hosting,
WPF/WinForms, and container files.
- Testing samples now use
`CreateResourceBuilder<DotnetProjectResource>`, matching the 17 starter
template.
- Short `:::note[Upgrading to Aspire 17?]` pointers are added only where
readers are likely on the old API.

**Japanese docs**
- Only code fences are converted. Prose is left for the translation
pipeline.

**Out of scope / tracked upstream**
- Historical release notes (except link anchors), Azure Functions
(`AddAzureFunctionsProject`, microsoft/aspire#21345), Blazor gateway
upstream (microsoft/aspire#20837), and MAUI (microsoft/aspire#21350).

Supersedes the ASPIRE012/AppHost SDK parts of #1880 (not its ASPIRE010
changes).

Relates to #2179, microsoft/aspire#22336, microsoft/aspire#22335, and
microsoft/aspire#22340.

**Merge note:** #2085 (ASPIRE014) and #2110 (ASPIRE015) add rows next to
ASPIRE012 in `reference.topics.ts` and `diagnostics/overview.mdx`. If
either merges first, keep both rows in numeric order (011–015).

## Third-party links and affiliations

<!--
List any third-party links added or changed by this pull request and
disclose any
material affiliation with the linked organizations, such as employment,
sponsorship, or ownership. Write "None" if this pull request doesn't add
or
change third-party links.
-->

None

## Validation

<!-- List the checks you ran or explain why validation isn't needed. -->

- `bun run test:unit:twoslash-blocks`: the only failures are the 2
pre-existing `asOptional` ones in
`fundamentals/external-parameters.mdx`. No new failures.
- `bun x vitest run tests/unit/seo-lengths.vitest.test.ts`: passed.
- Local `astro dev`: changed EN and ja pages return 200, and new anchors
resolve.
- Runtime-checked with the .NET 11 SDK: `AddDotnetProject` with
WPF/WinForms, C# Blazor (`AddDotnetProjectBlazorGateway`), and TS Blazor
AppHosts.
- `bun run build` was not run locally; left to CI.

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Karol Zadora-Przylecki <karolz@microsoft.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: karolz-ms <15271049+karolz-ms@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
…2188)

## 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](https://github.com/microsoft/aspire/wiki/17.0-Change-log) 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 #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 #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:
  - `WithRequiredCommand`.
  - `WithHttpProbe`.
- A new [TypeScript hosting
integrations](/extensibility/typescript-hosting-integrations/) page.
  - Dashboard error-badge and hidden-resource notes.

**17.0 milestone issues**
- Closes #2114: documents that required parameters reject empty values,
in [external
parameters](/fundamentals/external-parameters/#optional-parameters) and
as a What's New breaking change.
- Closes #2131, closes #2130: the What's New breaking-change sections
now cover the `MissingFieldException`, `ref`/`out`, reflection and
integration-author impact, plus Cosmos DB `AddKeyedContainer`'s deferred
resolution.
- Closes #2129: already covered by the What's New row and section from
#2177, with before and after values.
- Closes #1925: the CLI config table, configuration steps and Rust note
now use the flat `experimentalPolyglot*` keys, and the colon-key
`--global` workaround is removed.
- #1926 (Go language selector) is already implemented on `release/17.0`:
`Head.astro`, `pivot-selector.ts` and `ApiReference.astro` all handle
`go`.
- #2049 is the automated API-data updater report, not docs content, so
this PR doesn't address it.

## 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 #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.

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Remove the obsolete ShowTerminalHost option and terminal-host telemetry aside. Correct the documented terminal dimensions to 132 columns and 50 rows.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…pHosts (#1959)

Documents changes from microsoft/aspire#21116

Author: ``@davidfowl`` (source PR author per metadata; see source PR)

Targeting `release/17.0` based on the source PR milestone `17.0`
(`target_resolution`: `exact_match`).

## Why
The source PR exports the `WithTerminal` callback to TypeScript AppHosts
so columns and rows can be configured, and removes the
`ASPIRETERMINAL001` experimental diagnostic from `WithTerminal` and
`TerminalOptions`. The docs said TypeScript couldn't configure
dimensions and that `WithTerminal` was experimental.

## Changes (updated existing pages)
- `src/frontend/src/content/docs/app-host/with-terminal.mdx`: TypeScript
`configure` callback example and auto-fit behavior; replaced the
experimental caution with a note; removed the pragma from the C#
examples in that section.
- `src/frontend/src/content/docs/dashboard/terminals.mdx`: removed the
`ASPIRETERMINAL001` pragma from the `WithTerminal` C# example.

Note for the SME: other pragmas on pages that use AppHost-owned
terminals remain intentionally, and the replica example in
`with-terminal.mdx` may still carry one; please check.

> Generated by [PR Documentation
Check](https://github.com/microsoft/aspire/actions/runs/40473856476) for
#21116 · copilot · auto · 29.1 AIC · ⌖ 1.15 AIC · ⊞ 7.1K ·
[◷](https://github.com/search?q=repo%3Amicrosoft%2Faspire.dev+%22gh-aw-workflow-id%3A+pr-docs-check%22&type=pullrequests)

<!-- gh-aw-agentic-workflow: PR Documentation Check, engine: copilot,
model: auto, id: 40473856476, workflow_id: pr-docs-check, run:
https://github.com/microsoft/aspire/actions/runs/40473856476 -->

<!-- gh-aw-workflow-id: pr-docs-check -->
<!-- gh-aw-workflow-call-id: microsoft/aspire/pr-docs-check -->
…k tab reordering (#1801)

Documents changes from microsoft/aspire#20255

``@mitchdenny``

**Target branch**: Targeting `release/17.0` based on the source PR
milestone `17.0` (exact match on `microsoft/aspire.dev`).

## Why

microsoft/aspire#20255 upgraded the dashboard's embedded terminal
integration and added several user-facing dashboard features that
weren't previously documented:

- Scrollbar command marks for supported shells and applications, so
users can jump back to previous commands.
- A title and, when reported, a working directory in resource terminal
views and separate windows, with copy controls and a progress indicator.
- A **Palette** control in the terminal footer, independent of the
dashboard theme.
- Dock tab reordering by drag-and-drop or keyboard, plus scroll buttons
for overflow.

## What changed

- Document how to copy terminal details and navigate command marks,
including the OSC 133 prerequisite and current retention behavior.
- Describe the terminal palette and its relationship to the dashboard
theme.
- Add the dock-tab reordering shortcut and drag-to-reorder guidance.

These changes update the existing `terminals.mdx` guide; no new pages
were created.

## Notes for the reviewer

The original source PR used Hex1b 0.171.0. On `microsoft/aspire`
`release/17.0` at `ada71fb1409066a7082f3a80d20a7d848cab15d8`, the
default command-mark retention follows the backing scrollback text
rather than a 200-mark limit.

Validated the updated page with a local Astro preview and checked the
diff with `git diff --check`. A full site build was not run locally.

> Generated by [PR Documentation
Check](https://github.com/microsoft/aspire/actions/runs/36822838078) for
#20255 · copilot · auto · 95 AIC · ⌖ 18.3 AIC · ⊞ 20.3K ·
[◷](https://github.com/search?q=repo%3Amicrosoft%2Faspire.dev+%22gh-aw-workflow-id%3A+pr-docs-check%22&type=pullrequests)

<!-- gh-aw-agentic-workflow: PR Documentation Check, engine: copilot,
model: auto, id: 36822838078, workflow_id: pr-docs-check, run:
https://github.com/microsoft/aspire/actions/runs/36822838078 -->

<!-- gh-aw-workflow-id: pr-docs-check -->
<!-- gh-aw-workflow-call-id: microsoft/aspire/pr-docs-check -->
Documents changes from microsoft/aspire#20726

``@mitchdenny``

## Target branch

Targeting `release/17.0` based on the source PR milestone `17.0` (exact
match on `microsoft/aspire.dev`).

## Why this is needed

microsoft/aspire#20726 changes dashboard terminal behavior on
disconnect: instead of clearing the terminal when a workload exits or
the connection drops, the dashboard now retains the last screen
(including Sixel/Kitty graphics) and shows a disconnect banner with
recovery actions:

- **Resource terminals**: a **Restart resource** action that uses the
resource's advertised Restart/Start command, with existing confirmation
and read-only checks, and shows the exit code when reported.
- **Docked terminals**: a **Close tab** action that closes only the
owning tab.
- Both: a **Show terminal** action that collapses the banner into a
small top-right disconnect icon, uncovering the retained screen;
selecting the icon reopens recovery actions.
- Both: a **Reconnect terminal** action when automatic retries have
stopped, to retry the connection without restarting the resource.

This is a user-facing dashboard behavior change (triggered signals:
`new_public_type` for the new `TerminalDisconnectedBanner` component,
and `pr_body_has_user_facing_section` for the PR's own "User-facing
usage" walkthrough) with no existing coverage on `microsoft/aspire.dev`,
so documentation is required.

## What changed

Added a new **"Recover from a disconnected terminal"** section to
`src/frontend/src/content/docs/dashboard/terminals.mdx` (an existing
page updated, no new page), placed after "Understand what stops a
terminal" and before "Prerequisites and limitations". It covers:

- The retained terminal screen and the available recovery actions.
- When the resource restart action is available and when the terminal
can be reconnected without a restart.
- The limitation that output can't be selected or copied while
disconnected.

## Files modified

- `src/frontend/src/content/docs/dashboard/terminals.mdx` (updated
existing page)

## Validation

- Verified the recovery controls against the `microsoft/aspire`
`release/17.0` implementation.
- Rendered the updated page locally in Chromium and checked the recovery
section.
- CI passed for the frontend build, validation, and all Playwright
shards.
- `pnpm --dir src/frontend exec prettier --check
src/content/docs/dashboard/terminals.mdx` reports existing formatting
differences in the unchanged baseline.

> Generated by [PR Documentation
Check](https://github.com/microsoft/aspire/actions/runs/38991596876) for
#20726 · copilot · auto · 73.5 AIC · ⌖ 17.7 AIC · ⊞ 20.4K ·
[◷](https://github.com/search?q=repo%3Amicrosoft%2Faspire.dev+%22gh-aw-workflow-id%3A+pr-docs-check%22&type=pullrequests)

<!-- gh-aw-agentic-workflow: PR Documentation Check, engine: copilot,
model: auto, id: 38991596876, workflow_id: pr-docs-check, run:
https://github.com/microsoft/aspire/actions/runs/38991596876 -->

<!-- gh-aw-workflow-id: pr-docs-check -->
<!-- gh-aw-workflow-call-id: microsoft/aspire/pr-docs-check -->
Documents changes from microsoft/aspire#21120

``@mitchdenny``

## Target branch

Targeting `release/17.0` based on the source PR milestone `17.0`.

## Why this change is needed

PR #21120 changes how `aspire terminal attach` and `aspire terminal tape
play` select a replica for a multi-replica resource. Instead of
prompting interactively or requiring a `--replica <index>` flag, the CLI
now requires an exact resource instance ID (discoverable via `aspire ps`
or `aspire describe`). An ambiguous display name without an exact
instance ID now fails explicitly and lists the available instance IDs,
rather than prompting. The legacy `-r, --replica <index>` option is kept
**hidden but functional** for short-term compatibility with older VS
Code extensions and scripts.

The existing docs described the old `--replica`/interactive-picker
behavior, which is now out of date and would mislead readers.

## What changed

-
`src/frontend/src/content/docs/reference/cli/commands/aspire-terminal-attach.mdx`
- Updated the description, `<resource>` argument, and examples to
explain instance-ID based selection.
- Removed the visible `-r, --replica <index>` option and added a note
that it's hidden-but-functional for legacy compatibility.
-
`src/frontend/src/content/docs/reference/cli/commands/aspire-terminal-tape-play.mdx`
- Updated the `<resource>` argument description and frontmatter
description for instance-ID selection.
- Removed the visible `-r, --replica <index>` option and added the same
legacy-compatibility note.
- Updated the example command to use an instance ID instead of
`--replica 0`.
- `src/frontend/src/content/docs/app-host/with-terminal.mdx`
- Updated the multi-replica attach guidance and the VS Code extension
section to describe instance-ID selection instead of `--replica
<index>`.

All three files were existing pages that were updated in place; no new
pages were created.

## Testing

Documentation-only change; no build/test commands were run per
repository guidance for docs-only edits. Changes were reviewed for
consistency with the doc-writer skill conventions (frontmatter,
Starlight `Aside` component usage, cross-references).

> Generated by [PR Documentation
Check](https://github.com/microsoft/aspire/actions/runs/39332850056) for
#21120 · copilot · auto · 81.8 AIC · ⌖ 11.5 AIC · ⊞ 20.4K ·
[◷](https://github.com/search?q=repo%3Amicrosoft%2Faspire.dev+%22gh-aw-workflow-id%3A+pr-docs-check%22&type=pullrequests)

<!-- gh-aw-agentic-workflow: PR Documentation Check, engine: copilot,
model: auto, id: 39332850056, workflow_id: pr-docs-check, run:
https://github.com/microsoft/aspire/actions/runs/39332850056 -->

<!-- gh-aw-workflow-id: pr-docs-check -->
<!-- gh-aw-workflow-call-id: microsoft/aspire/pr-docs-check -->
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Preserve the current dashboard layout and expand its existing Mermaid export section; retain the new CLI format documentation.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…tion) (#1963)

Documents changes from microsoft/aspire#21124

Author: ``@mitchdenny``

Targeting `release/17.0` based on the source PR milestone `17.0` (exact
match).

## Why
The source PR exports the Kubernetes persistent volume
`WithConfiguration` callback through ATS, so TypeScript AppHosts can
customize generated PVCs. The docs didn't cover this.

## Changes
Updated (no new pages):
`src/frontend/src/content/docs/deployment/kubernetes/persistent-volumes.mdx`
- Added `WithConfiguration` / `withConfiguration` to the configuration
methods table.
- Added a "Customize the generated claim" section with C# and TypeScript
examples, storage class empty vs. null semantics, callback ordering,
bounded TypeScript model, and C#-only features.

Triggered signals: `integration_readme_changed`,
`pr_body_has_user_facing_section`, `pr_body_has_cli_flag_mention`.

> Generated by [PR Documentation
Check](https://github.com/microsoft/aspire/actions/runs/40609189241) for
#21124 · copilot · auto · 26.5 AIC · ⌖ 1.14 AIC · ⊞ 7.1K ·
[◷](https://github.com/search?q=repo%3Amicrosoft%2Faspire.dev+%22gh-aw-workflow-id%3A+pr-docs-check%22&type=pullrequests)

<!-- gh-aw-agentic-workflow: PR Documentation Check, engine: copilot,
model: auto, id: 40609189241, workflow_id: pr-docs-check, run:
https://github.com/microsoft/aspire/actions/runs/40609189241 -->

<!-- gh-aw-workflow-id: pr-docs-check -->
<!-- gh-aw-workflow-call-id: microsoft/aspire/pr-docs-check -->
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…1829)

Documents changes from microsoft/aspire#20746

``@mitchdenny``

## Target branch

Targeting `release/17.0` based on the source PR milestone `17.0` (exact
match on `microsoft/aspire.dev`).

## Why this is needed

microsoft/aspire#20746 adds a new **Export as Mermaid** action to the
dashboard's resource graph view, and a corresponding `--format mermaid`
value to the `aspire describe` / `aspire resources` CLI commands.
Neither the dashboard graph-view docs nor the `aspire describe` CLI
reference mentioned this new output format, so users had no documented
way to discover or use it.

## What changed

-
**`src/frontend/src/content/docs/reference/cli/commands/aspire-describe.mdx`**
- Updated the `--format` option description to list `Json`, `Mermaid`,
and `Table`, explaining the Mermaid `flowchart LR` output shape, what's
excluded (parameters, endpoints, configuration values, resource state),
that progress/informational output goes to stderr (so redirection only
captures diagram source), and that `--follow` isn't supported with
Mermaid output.
- Added an example showing `aspire describe --format Mermaid >
resources.mmd`, noting that repeated `>>` invocations produce multiple
diagrams rather than a merged one.

- **`src/frontend/src/content/docs/dashboard/explore.mdx`**
- Extended the existing resource-graph-view section with a paragraph
describing the new **Export as Mermaid** control: it respects the
current search/filters and **Show hidden resources** setting, includes
replica names but not parameters/endpoint values/other configuration,
and offers **Copy to clipboard** and **Download** (`resources.mmd`)
actions.
- Added a cross-reference `Aside` pointing to the `aspire describe` CLI
reference for exporting a graph from the command line.

## Notes

- Pages updated only; no new pages were created.
- Only the two `.mdx` files above were touched — no unrelated edits.

> Generated by [PR Documentation
Check](https://github.com/microsoft/aspire/actions/runs/37427037856) for
#20746 · copilot · auto · 61.6 AIC · ⌖ 14.5 AIC · ⊞ 20.4K ·
[◷](https://github.com/search?q=repo%3Amicrosoft%2Faspire.dev+%22gh-aw-workflow-id%3A+pr-docs-check%22&type=pullrequests)

<!-- gh-aw-agentic-workflow: PR Documentation Check, engine: copilot,
model: auto, id: 37427037856, workflow_id: pr-docs-check, run:
https://github.com/microsoft/aspire/actions/runs/37427037856 -->

<!-- gh-aw-workflow-id: pr-docs-check -->
<!-- gh-aw-workflow-call-id: microsoft/aspire/pr-docs-check -->
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…cret path (#2051)

Documents changes from microsoft/aspire#21323

Author: ``@IEvangelist`` is the workflow actor; source PR author per the
PR metadata.

Targeting `release/17.0` based on the source PR milestone `17.0` (exact
match).

## Why
The source PR makes `aspire secret path` resolve the
environment-specific store without parsing/importing/migrating secrets,
and reports invalid JSON with file path, line/byte position, and repair
guidance. Triggered signals: `cli_command_file_changed`
(SecretPathCommand.cs), `cli_resource_strings_changed`
(SecretCommandStrings.resx), `pr_body_has_cli_flag_mention`,
`pr_body_has_user_facing_section`.

## Changes (updated pages)
- `reference/cli/commands/aspire-secret-path.mdx`: notes that the
command has no side effects and works with malformed secrets.
- `reference/cli/commands/aspire-secret.mdx`: new "Malformed secrets
files" section.

> Generated by [PR Documentation
Check](https://github.com/microsoft/aspire/actions/runs/41870873850) for
#21323 · copilot · auto · 25 AIC · ⌖ 1.17 AIC · ⊞ 7.4K ·
[◷](https://github.com/search?q=repo%3Amicrosoft%2Faspire.dev+%22gh-aw-workflow-id%3A+pr-docs-check%22&type=pullrequests)

<!-- gh-aw-agentic-workflow: PR Documentation Check, engine: copilot,
model: auto, id: 41870873850, workflow_id: pr-docs-check, run:
https://github.com/microsoft/aspire/actions/runs/41870873850 -->

<!-- gh-aw-workflow-id: pr-docs-check -->
<!-- gh-aw-workflow-call-id: microsoft/aspire/pr-docs-check -->
…17.0

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

Consolidates the open `docs-from-code` PRs that cover features from
@IEvangelist's product work or that request their review, all targeting
`release/17.0`, into this single PR. Each PR was checked against its
merged microsoft/aspire source PR and against product `release/17.0`, to
confirm the change shipped in 17.0 and is user-facing rather than an
implementation detail. Accepted text was corrected where the bot's
wording was inaccurate.

| PR(s) | Verdict | Notes |
| --- | --- | --- |
| #2103, #2098, #1967, #2073, #2070 | Accepted with fixes | Go AppHost
conventions, `aspire init`, and VS Code extension. Unrelated e2e test
edits from #2073 were dropped. |
| #1972 | Partially accepted | Only the verified behavior was kept. |
| #2069, #2064, #1829 | Accepted with fixes | Dashboard explore page and
`aspire describe --format Mermaid` |
| #2044 | Partially accepted | The Cards/Home/Graph layout selector text
is outdated, so it was dropped. |
| #1959, #1904, #1835, #1801 | Accepted with fixes | `WithTerminal`
options, the dashboard terminal UX, and TypeScript `configure` |
| #1902 | Accepted with fixes | `dotnet run --operation publish`
guidance |
| #2081 | Accepted with fixes | WSLc limited publish support. The
minimum version is corrected to 3.0.4.0. |
| #2014, #1862, #1809, #1936, #2140, #1997, #2051, #2068, #2022, #1963 |
Accepted with fixes | DCP timeouts, the container tunnel base image,
browser origins, the PVC `WithConfiguration` API, the interaction
service caution, secrets, `aspire update`, and agent init telemetry |
| #2092 | Rejected | Documents implementation details. |
| #2078 | Rejected | Already documented correctly; the proposed text was
wrong. |
| #2110, #2104, #2085, #2094 | Rejected | The product change isn't in
`release/17.0`; it's 17.1-only. Redo these against the next release
branch. |
| #2133 | Rejected for now | Its backport, microsoft/aspire#22219, is
still open, so redo this once it merges. |

Additional consistency fixes:

- **WSLc:** the minimum version is now 3.0.4.0, the source's
`MinimumWslcVersion`, across prerequisites, `aspire doctor`,
configuration, and what's new. The pages now describe limited publish
support and state that Docker Compose isn't supported.
- **`WithTerminal`:** `WithTerminal` and `TerminalOptions` are no longer
`[Experimental]` in 17.0. I removed the stale `ASPIRETERMINAL001`
pragmas and cautions and rewrote the diagnostic page to cover the
terminal APIs that are still experimental.

Closes #2140
Closes #2133
Closes #2110
Closes #2104
Closes #2103
Closes #2098
Closes #2094
Closes #2092
Closes #2085
Closes #2081
Closes #2078
Closes #2073
Closes #2070
Closes #2069
Closes #2068
Closes #2064
Closes #2051
Closes #2044
Closes #2022
Closes #2014
Closes #1997
Closes #1972
Closes #1967
Closes #1963
Closes #1959
Closes #1936
Closes #1904
Closes #1902
Closes #1862
Closes #1835
Closes #1829
Closes #1809
Closes #1801

## Third-party links and affiliations

None. The only added external link is to mermaid.js.org, which the page
already links elsewhere.

## Validation

- I compared each claim with the merged microsoft/aspire source and
checked that it's included in product `release/17.0`, using `gh api
compare` and searches for backport PRs.
- I checked the TypeScript sample against the generated `aspire.d.ts`.
`EndpointReferenceExpression` is an `IValueProvider`.
- I reviewed the full diff by hand for MDX and table formatting,
imports, and anchors. The new `seoTitle` is 58 characters.
- I didn't run any local unit, e2e, or build commands because frontend
dependencies aren't installed locally. CI covers the build, unit, and
e2e checks, including the updated `custom-components.spec.ts` assertion.

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
)

## Summary
<!-- Describe what this pull request changes and why. -->
Documents microsoft/aspire#17980 and the directory-based Azure Functions
debugging support from microsoft/aspire#20943 for `release/17.0`.

- Adds C#, TypeScript, and Go AppHost examples, Node worker
configuration, host storage and Core Tools requirements, and VS Code
debugging guidance.
- Documents generated and custom Dockerfiles, Azure Container Apps
deployment, and considerations for restricted storage/networking
policies.
- Adds the `ASPIREAZUREFUNCTIONS001` diagnostic page and sidebar entry.
The diagnostic is a C# compiler error; the documented pragma and project
`NoWarn` suppressions were verified.

Updated: `azure-functions-host.mdx`, `reference.topics.ts`. Created:
`aspireazurefunctions001.mdx`.

## Third-party links and affiliations
<!--
List any third-party links added or changed by this pull request and
disclose any
material affiliation with the linked organizations, such as employment,
sponsorship, or ownership. Write "None" if this pull request doesn't add
or
change third-party links.
-->
None.

## Validation
<!-- List the checks you ran or explain why validation isn't needed. -->
Validated staging CLI `17.0.0+148071e36dbb16c1cad260dedec2496871b6f49a`
and the matching Aspire VS Code extension; the commit is an ancestor of
the tested `release/17.0` tip.

- `go build -o /tmp/aspire-nodefuncs-go-doc-20261116/sample apphost.go`
— passed for the Go documentation example against the staging-generated
SDK.
- `./node_modules/.bin/tsc -p tsconfig.apphost.json --noEmit` — passed
for the TypeScript documentation example against the staging-generated
SDK.
- `dotnet build
/tmp/aspire-nodefuncs-17-csharp-20261116/NodeFunctionsCSharp.csproj
--no-restore --verbosity quiet` — passed; the C# diagnostic and both
documented suppression mechanisms were also checked in separate builds.
- `"$CLI" start --apphost "$APPHOST" --non-interactive`, followed by
`"$CLI" wait` and `curl --fail
"$FUNCTION_URL/api/proof?name=$REQUEST_ID"` — passed for JavaScript and
TypeScript Functions with each of the three AppHost languages. All six
VS Code source breakpoints were hit, and all six requests succeeded
after continuing. C# used a project-based AppHost; a file-based AppHost
debug launch stalled and remains unverified.
- `"$CLI" publish --apphost "$APPHOST" --output-path "$OUTPUT"
--non-interactive` — passed for all three AppHosts. Azure deployments
and HTTPS invocation passed for all six Functions after adapting
networking and storage to the subscription's policy; the Go deployment
required one retry after a transient subnet update conflict.

> Generated by [PR Documentation
Check](https://github.com/microsoft/aspire/actions/runs/38337214233) for
#17980 · copilot · auto · 140.2 AIC · ⌖ 15.9 AIC · ⊞ 20.4K ·
[◷](https://github.com/search?q=repo%3Amicrosoft%2Faspire.dev+%22gh-aw-workflow-id%3A+pr-docs-check%22&type=pullrequests)

<!-- gh-aw-agentic-workflow: PR Documentation Check, engine: copilot,
model: auto, id: 38337214233, workflow_id: pr-docs-check, run:
https://github.com/microsoft/aspire/actions/runs/38337214233 -->

<!-- gh-aw-workflow-id: pr-docs-check -->
<!-- gh-aw-workflow-call-id: microsoft/aspire/pr-docs-check -->

---------

Co-authored-by: aspire-repo-bot[bot] <268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AJ Matthews <alistairwebdojo@live.com>
Co-authored-by: Sébastien Ros <sebastienros@gmail.com>
Documents changes from microsoft/aspire#22080

Author: ``@joperezr``'s review requested via notify; source PR author
per pr.json.

**Target branch:** Targeting `release/17.0` — the latest release branch
on `microsoft/aspire.dev` — because `release/17.1` (from the source PR
milestone `17.1`) does not exist there (`target_resolution`:
`latest_release_fallback`).

**Why:** `aspire agent init` gained a `--remove-skill-copies` option and
a prompt that deletes stale Aspire skill copies written by older CLIs.
The CLI reference didn't cover it. Triggered signals:
`cli_option_added`, `cli_command_file_changed`,
`cli_resource_strings_changed`, `pr_body_has_cli_flag_mention`.

**Changes (updated page):**
-
`src/frontend/src/content/docs/reference/cli/commands/aspire-agent-init.mdx`:
new "Remove copied Aspire skills" section, `--remove-skill-copies`
option entry, an example, and updated description text. Also notes
`aspire doctor` now warns about copies in the Environment category.

> Generated by [PR Documentation
Check](https://github.com/microsoft/aspire/actions/runs/43505490618) for
#22080 · copilot · auto · 27 AIC · ⌖ 1.18 AIC · ⊞ 7.4K ·
[◷](https://github.com/search?q=repo%3Amicrosoft%2Faspire.dev+%22gh-aw-workflow-id%3A+pr-docs-check%22&type=pullrequests)

<!-- gh-aw-agentic-workflow: PR Documentation Check, engine: copilot,
model: auto, id: 43505490618, workflow_id: pr-docs-check, run:
https://github.com/microsoft/aspire/actions/runs/43505490618 -->

<!-- gh-aw-workflow-id: pr-docs-check -->
<!-- gh-aw-workflow-call-id: microsoft/aspire/pr-docs-check -->

Co-authored-by: aspire-repo-bot[bot] <268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Co-authored-by: Ella Hathaway <ellahathaway@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
ASPIRE015 is a warning, so list it under Warnings next to ASPIRE012.
Add the 'Version introduced: 17.1' badge (microsoft/aspire#21592 ships
in 17.1) and quote the full warning text from the AppHost targets.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@maddymontaquila
Maddy Montaquila (maddymontaquila) force-pushed the docs/pr-21592-42932767754-1-4c891eda08d58399 branch from 20975fc to 5e6aa93 Compare November 17, 2026 17:43
@maddymontaquila

Copy link
Copy Markdown
Contributor

Holding this for 17.1. The source change (microsoft/aspire#21592) shipped on aspire main with milestone 17.1, and the release/17.0 backport (microsoft/aspire#22015) was closed, so the 17.0 SDK never emits this warning. I've converted this to a draft and set the 17.1 milestone. Once a release/17.1 docs branch exists, it should be retargeted there and marked ready. The content is already reviewed and up to date with release/17.0.

@maddymontaquila

Copy link
Copy Markdown
Contributor

Holding this for 17.1. The source change (microsoft/aspire#21592) shipped on aspire main with milestone 17.1, and the release/17.0 backport (microsoft/aspire#22015) was closed, so the 17.0 SDK never emits this warning.

I've converted this to a draft and set the 17.1 milestone. Once a release/17.1 docs branch exists, it should be retargeted there and marked ready. The content is already reviewed and up to date with release/17.0.

@maddymontaquila
Maddy Montaquila (maddymontaquila) changed the base branch from release/17.0 to main November 17, 2026 18:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs-from-code Copilot initiated issue from dotnet/aspire repo

Projects

None yet

Development

Successfully merging this pull request may close these issues.

10 participants