You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
docs: Migrate to AddDotnetProject/DotnetProjectResource and remove Aspire.AppHost.Sdk - #2180
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.
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.
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
None
Validation
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.
The latest frontend build uploaded the frontend-dist artifact for PR #2180. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.
This comment updates automatically when a new frontend build artifact is uploaded.
## Summary
<!-- Describe what this pull request changes and why. -->
Consolidates the retired experimental diagnostic documentation for
Aspire 17.0, superseding the individual PRs against `release/17.0`.
- Marks 14 diagnostic pages as retired in 17.0, retaining their
historical content and guidance for removing suppressions.
- Updates the diagnostics overview and the 17.0 release notes, including
`ASPIREDENO001` and `ASPIRECONNECTIONSTRINGS001`, which don't have
dedicated pages.
- Explains that `ASPIRECOMPUTE002` was only partially graduated:
endpoint-mapping contracts are stable, while persistent-volume APIs
remain experimental.
- Removes retired suppressions and experimental cautions from affected
guides, while retaining the experimental image-building guidance for
`ASPIREPIPELINES003`.
- Notes that `ASPIRECSHARPAPPS001` was retired when `AddCSharpApp`
became obsolete. The broader migration and ProjectResource v2 guidance
is separate in #2180.
The retired diagnostic list was checked against `[Experimental("…")]`
usages in `microsoft/aspire` between `v13.6.5` and `release/17.0`.
Supersedes #1846, #1847, #1851, #1852, #1853, #1854, #1856, #1857,
#2127, #2167, #2168, #2169, #2170, #2171.
## 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. -->
- `git diff --check origin/release/17.0 --
src/frontend/src/content/docs` — passed.
- Frontend validation CI — passed; frontend build CI is pending.
- Local Astro build and tests were not run; Bun and frontend
dependencies were unavailable.
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Maddy Montaquila (maddymontaquila)
changed the title
docs: ProjectResource v2 guidance (AddCSharpApp -> AddDotnetProject)
docs: Migrate to AddDotnetProject/DotnetProjectResource and remove Aspire.AppHost.Sdk
Nov 16, 2026
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
The migrated Azure sample no longer compiles due to an incompatible generic type argument, and the SDK-free examples lose required AppHost build configuration.
…migrate (#22340)
## Description
`aspire update --migrate` printed "Nothing to migrate. The current
project is already using the latest recommended Aspire conventions." for
C# AppHosts that still use `Aspire.AppHost.Sdk`, even though the next
build emits ASPIRE012. Removing the SDK is intentionally approval-gated
and is **not** applied automatically, so this PR only changes the
message.
When no automatic migrations apply and the AppHost still declares
`Aspire.AppHost.Sdk`, the CLI now prints:
> No automatic migrations apply. This AppHost still uses
Aspire.AppHost.Sdk (ASPIRE012), which is obsolete. See
https://aka.ms/aspire/diagnostics/aspire012 for how to migrate.
Detection (`DotNetAppHostProject.UsesObsoleteAppHostSdk`) checks the
AppHost file after the package update ran:
- file-based `apphost.cs`: `#:sdk Aspire.AppHost.Sdk[@Version]` in the
directive preamble (reuses `FallbackProjectParser`)
- project files: `Sdk="Aspire.AppHost.Sdk[/version]"` (incl. multi-SDK
lists), `<Sdk Name="Aspire.AppHost.Sdk" />`, `<Import
Sdk="Aspire.AppHost.Sdk" />`
- respects suppression declared in the AppHost file itself
(`SuppressAspireAppHostSdkObsoleteWarning=true` or `NoWarn` containing
`ASPIRE012`, mirroring the check in `Sdk.in.targets`)
Plain `aspire update` (without `--migrate`) prints nothing when no
migrations are pending, so it is unaffected.
The aka.ms link is the same `HelpLink` used by the ASPIRE012 warning;
the docs page is being added in microsoft/aspire.dev#2180. Related:
#22336.
Fixes#22335
## Checklist
- Is this feature complete?
- [x] Yes. Ready to ship.
- [ ] No. Follow-up changes expected.
- Are you including unit tests for the changes and scenario tests if
relevant?
- [x] Yes
- [ ] No
- Did you add public API?
- [ ] Yes
- [x] No
- Does the change make any security assumptions or guarantees?
- [ ] Yes
- [x] No
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Some migrated examples still use legacy Blazor APIs, omit the required Dotnet package, or reference nonexistent project paths, preventing readers from compiling or running them.
This complete file-based AppHost still declares only Aspire.AppHost.Sdk and Aspire.Hosting.Redis. Neither brings in Aspire.Hosting.Dotnet, where AddDotnetProject is defined, so both new calls fail to compile with CS1061 when readers copy the example. Add the Dotnet package directive to this block's preamble.
The API project is created/referenced as src/Api/MyApp.Api.csproj in step 2 and in the directory tree below. Relative to MyApp.AppHost/Program.cs, this new path instead points to a nonexistent root-level MyApp.Api directory, so the tutorial cannot start the API. Preserve the documented layout with ../src/Api/MyApp.Api.csproj.
The Web project lives under src/Web/MyApp.Web.csproj, as shown by step 2 and the directory tree. This path resolves from MyApp.AppHost to a root-level MyApp.Web directory that the tutorial never creates. Use ../src/Web/MyApp.Web.csproj so the frontend can be located.
The documented worker project is src/Worker/MyApp.Worker.csproj, not a root-level MyApp.Worker/MyApp.Worker.csproj. Because this API now uses the supplied path rather than generated project metadata, readers following the existing setup will get a missing-project failure. Change the path to ../src/Worker/MyApp.Worker.csproj.
The C# sample now adds Api by path with AddDotnetProject, but the lead-in sentence (line 242) still says "A C# AppHost also needs a project reference to Api." That's no longer required, and a migrated AppHost shouldn't add one. Please remove that sentence.
The C# sample now adds the project by path with AddDotnetProject, but the sentence just above it (line 195) still says: "Add a project reference to Agent.csproj in your AppHost before using its generated Projects.Agent type." The sample no longer uses Projects.Agent, and a migrated AppHost shouldn't add that project reference. Readers following the prose will add an unnecessary ProjectReference. Please update or remove that sentence.
Remove the stale Projects.Api reference requirement
The samples now add Api by path, but the introductory prose (line 35) still says "The C# AppHost must reference that project so the Projects.Api type is generated." The C# sample at line 59 no longer uses Projects.Api, so this requirement is now incorrect. Please remove it.
Remove the stale Projects.Api reference instruction
Both samples in this section now add Api by path with addDotnetProject / AddDotnetProject. The introductory sentence (line 31) still says "Reference that project from the C# AppHost to generate Projects.Api." That instruction is stale, because the C# sample at line 54 no longer uses a generated Projects.Api type. Please drop that sentence.
Remove the stale Projects.Api reference instruction
The samples now add Api by path, but the introductory prose (line 48) still ends with "Add a project reference in the C# AppHost to generate Projects.Api." The C# sample at line 71 no longer uses that generated type, so the instruction is stale. Please remove it.
Remove the stale Projects.Api reference instruction
The samples now add Api by path, but the introductory prose (line 33) still tells readers to "Add a project reference in the C# AppHost to generate Projects.Api." The C# sample at line 57 doesn't use Projects.Api anymore, so this step is stale. Please remove it.
The samples now add web by path, but the sentence introducing them (line 35) still says the example assumes "for a C# AppHost, its generated Projects.Web type." The C# sample at line 70 no longer uses Projects.Web, so that assumption is stale. Please remove it.
Addressed all 11 items from that review in 25694c4:
ja add-aspire-existing-app: the file-based AppHost now uses the same packages as the English version (Aspire.Hosting.AppHost and Aspire.Hosting.Dotnet), and the obsolete SDK line and pragma are removed. The project-based paths now use ../src/{Api,Web,Worker}/.... Only the code fences changed.
Removed outdated sentences about adding a project reference or using a generated Projects.* type in cors-configuration, with-terminal, chroma-host, duckdb-host, efcore/sqlite, solr-host, and zitadel-connect.
…2182)
## Summary
Adds a **Try a prerelease build** section to the upgrade guide. It walks
through testing an app against a staging build from start to finish.
Each piece was already documented on a different page, so the section
links back to those references:
1. Update the CLI with `aspire update --self --channel staging`; in CI,
use install-script `--quality staging`.
2. Run `aspire update --channel staging --migrate`. The section explains
what this writes: the `channel` entry in `aspire.config.json`, the
`NuGet.config` staging feed and `Aspire*` source mapping, and the
repo-local `.nugetpackages` folder to add to `.gitignore`. It also notes
that `--migrate` doesn't apply approval-gated changes such as ASPIRE012.
3. Point `aspire docs` at the prerelease docs (`aka.ms/aspire/vnext`) by
setting **both** `docs.llmsTxtUrl` and `docs.api.sitemapUrl`.
4. Verify the switch.
5. Check what the updater skips: inactive central package pins, other
AppHosts, and pinned CI or dev container CLI versions.
6. Switch back to stable, including the stale `NuGet.config` entries
that `aspire update` can leave behind.
Each step reflects what happened when maddymontaquila/aspirifridays was
upgraded from 13.5.3 to 17.0 staging.
The section uses a `<prerelease-host>` placeholder because the
`aka.ms/aspire/vnext` link doesn't pass paths through; for example,
`/llms-full.txt` redirects to Bing.
Fixes#2181. Related: #2133, #2177, #1880, #2180, and
microsoft/aspire#22335.
## Third-party links and affiliations
None
## Validation
- Checked each statement against an actual staging upgrade:
- `aspire.config.json` contained `"channel": "staging"`.
- `NuGet.config` had the darc feed, the `Aspire*` mapping, and
`globalPackagesFolder=.nugetpackages`.
- Both docs keys were exercised against vnext.
- Content-only change to an existing page. It adds no new routes and
links only to pages that already exist on `release/17.0`. CI covers the
build and link checks.
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- Add migration guide for AddProject/AddCSharpApp to AddDotnetProject
- Add ASPIRE012 diagnostic and remove obsolete Aspire.AppHost.Sdk guidance
- Make dotnet-host and related pages evergreen with Aspire 17 pointers
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Convert integration, deployment, fundamentals, testing, and community samples from AddProject/AddCSharpApp to AddDotnetProject, update ProjectResource type references to DotnetProjectResource, and align the markdown rendering e2e expectation.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
… guidance to dotnet-host
- Move endpoint filtering, coordinated builds/restore, and multithreaded builds to dotnet-host
- Trim launch-profile and networking duplication to pointers
- Retitle as Legacy project resources and move it below the migration guide in the sidebar
- Repoint inbound links to dotnet-host
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- Use CreateResourceBuilder<DotnetProjectResource> in testing samples (EN + ja)
- Drop ProjectResource from resource-model built-in types table
- Convert ja code fences from AddProject/addProject/AddCSharpApp to AddDotnetProject; prose left for translators
Co-authored-by: Copilot App <223556219+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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Moves aspire.dev off the legacy
AddProject/AddCSharpApp/ProjectResourceAPIs onto Aspire 17'sAddDotnetProject/DotnetProjectResource, and removes the obsoleteAspire.AppHost.Sdk. Tracked in #2179.New pages
ASPIRE012diagnostic (Aspire.AppHost.Sdkis obsolete), with sidebar and overview rows. Theaspire update --migratenotice from [release/17.0] Report obsolete Aspire.AppHost.Sdk in aspire update --migrate aspire#22340 links to it.Evergreen rewrites
dotnet-hostis 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-sdkis now "C# AppHost project configuration".AddDotnetProject.project-resourcesbecomes a short "Legacy project resources" reference, listed in the sidebar below the migration guide. Inbound links now point todotnet-host.Sample sweep (C#/TS/Go)
AddProject<Projects.X>,addProject, andAddCSharpAppacross app-host, fundamentals, deployment, get-started, testing, architecture, and integration pages. This includes Blazor hosting, WPF/WinForms, and container files.CreateResourceBuilder<DotnetProjectResource>, matching the 17 starter template.:::note[Upgrading to Aspire 17?]pointers are added only where readers are likely on the old API.Japanese docs
Out of scope / tracked upstream
AddAzureFunctionsProject, Migrate Azure Functions integration from ProjectResource to DotnetProjectResource (a.k.a. Project v2) aspire#21345), Blazor gateway upstream (Migrate the Blazor gateway off obsolete AddCSharpApp aspire#20837), and MAUI (Add support for DotnetProjectResource (a.k.a. Project V2) to MAUI integration 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.tsanddiagnostics/overview.mdx. If either merges first, keep both rows in numeric order (011–015).Third-party links and affiliations
None
Validation
bun run test:unit:twoslash-blocks: the only failures are the 2 pre-existingasOptionalones infundamentals/external-parameters.mdx. No new failures.bun x vitest run tests/unit/seo-lengths.vitest.test.ts: passed.astro dev: changed EN and ja pages return 200, and new anchors resolve.AddDotnetProjectwith WPF/WinForms, C# Blazor (AddDotnetProjectBlazorGateway), and TS Blazor AppHosts.bun run buildwas not run locally; left to CI.