Skip to content

docs: Migrate to AddDotnetProject/DotnetProjectResource and remove Aspire.AppHost.Sdk - #2180

Merged
David Pine (IEvangelist) merged 13 commits into
release/17.0from
docs/project-resource-v2-guidance
Nov 17, 2026
Merged

David Pine (IEvangelist) merged 13 commits into
release/17.0from
docs/project-resource-v2-guidance

Conversation

@maddymontaquila

@maddymontaquila Maddy Montaquila (maddymontaquila) commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

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

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

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

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.
  • bun run build was not run locally; left to CI.

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Frontend HTML artifact ready

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.

VS Code: Open PR #2180 artifacts

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

Maddy Montaquila (maddymontaquila) added a commit that referenced this pull request Nov 16, 2026
## 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>
krishkhinchi

This comment was marked as spam.

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 migrated Azure sample no longer compiles due to an incompatible generic type argument, and the SDK-free examples lose required AppHost build configuration.

2 open issues
What changed in this PR

Updates aspire.dev guidance for Aspire 17’s path-based .NET resource model and SDK-free C# AppHosts, supporting #2179.

Changes:

  • Migrates documentation examples to AddDotnetProject and testing examples to DotnetProjectResource.
  • Updates upgrade guidance, diagnostics, and navigation for the AppHost SDK migration.
  • Aligns shared snippets, contributor guidance, and the Markdown-rendering test with the new APIs.

Documentation paths below are relative to src/frontend/src/content/docs/; other paths are repository-relative.

File Description
src/​frontend/​tests/​e2e/​markdown-rendering.spec.ts Matches the migrated contributor example.
whats-new/​upgrade-aspire.mdx Adds Aspire 17 migration guidance.
testing/​write-your-first-test.mdx Uses DotnetProjectResource in tests.
testing/​advanced-scenarios.mdx Migrates registration and test resource types.
reference/​cli/​commands/​aspire-init.mdx Updates generated AppHost descriptions.
languages-and-runtimes/​index.mdx Directs readers to path-based .NET guidance.
ja/​testing/​write-your-first-test.mdx Updates Japanese test code samples.
ja/​integrations/​dotnet/​launch-profiles.mdx Migrates launch-profile code samples.
ja/​get-started/​what-is-aspire.mdx Migrates the introductory registration sample.
ja/​get-started/​troubleshooting.mdx Migrates troubleshooting code samples.
ja/​get-started/​first-app.mdx Migrates starter registration samples.
ja/​get-started/​deploy-first-app.mdx Migrates deployment registration samples.
ja/​get-started/​aspire-mcp-server.mdx Migrates MCP resource samples.
ja/​get-started/​add-aspire-existing-app.mdx Migrates existing-app registration samples.
ja/​fundamentals/​networking-overview.mdx Migrates endpoint-reference samples.
ja/​fundamentals/​http-commands.mdx Migrates HTTP-command samples.
ja/​fundamentals/​custom-resource-urls.mdx Migrates resource URL samples.
ja/​extensibility/​custom-resources.mdx Migrates relationship samples.
ja/​architecture/​resource-model.mdx Migrates resource-model samples.
ja/​app-host/​resource-lifetimes.mdx Migrates lifetime samples.
ja/​app-host/​executable-resources.mdx Migrates backend registration samples.
ja/​app-host/​eventing.mdx Migrates eventing samples.
ja/​app-host/​container-files.mdx Migrates container-file destination samples.
integrations/​security/​zitadel/​zitadel-connect.mdx Migrates web application registration.
integrations/​security/​logto/​logto-host.mdx Migrates web application registration.
integrations/​security/​logto/​logto-get-started.mdx Migrates introductory web samples.
integrations/​reverse-proxies/​ngrok/​ngrok-host.mdx Migrates tunneled API registration.
integrations/​reverse-proxies/​ngrok/​ngrok-get-started.mdx Migrates introductory tunnel samples.
integrations/​overview.mdx Migrates integration overview samples.
integrations/​observability/​seq/​seq-host.mdx Migrates service registration samples.
integrations/​observability/​opentelemetry-collector/​opentelemetry-collector-host.mdx Migrates telemetry-routing samples.
integrations/​observability/​opentelemetry-collector/​opentelemetry-collector-get-started.mdx Migrates introductory collector samples.
integrations/​messaging/​sftp/​sftp-host.mdx Migrates worker registration.
integrations/​messaging/​sftp/​sftp-get-started.mdx Migrates introductory worker samples.
integrations/​messaging/​redpanda/​redpanda-host.mdx Migrates messaging consumer registration.
integrations/​messaging/​redpanda/​redpanda-get-started.mdx Migrates introductory consumer samples.
integrations/​messaging/​posta/​posta-host.mdx Migrates API registration.
integrations/​messaging/​posta/​posta-get-started.mdx Migrates introductory API samples.
integrations/​messaging/​papercut-smtp/​papercut-smtp-host.mdx Migrates mailer registration.
integrations/​messaging/​papercut-smtp/​papercut-smtp-get-started.mdx Migrates introductory mailer samples.
integrations/​messaging/​nats/​nats-host.mdx Migrates NATS consumer samples.
integrations/​messaging/​mosquitto/​mosquitto-host.mdx Migrates MQTT consumer registration.
integrations/​messaging/​mosquitto/​mosquitto-get-started.mdx Migrates introductory MQTT samples.
integrations/​messaging/​listmonk/​listmonk-host.mdx Migrates API registration.
integrations/​messaging/​lavinmq/​lavinmq-host.mdx Migrates worker registration.
integrations/​messaging/​lavinmq/​lavinmq-connect.mdx Migrates connection-string consumer registration.
integrations/​messaging/​activemq/​activemq-host.mdx Migrates broker consumer registration.
integrations/​frameworks/​python.mdx Migrates .NET consumer samples.
integrations/​frameworks/​orleans.mdx Migrates server and client registration.
integrations/​frameworks/​dotnet/​dotnet-get-started.mdx Removes the legacy API comparison.
integrations/​frameworks/​dapr/​dapr-host.mdx Migrates sidecar application registration.
integrations/​frameworks/​bun-apps.mdx Migrates .NET consumer registration.
integrations/​dotnet/​maui.mdx Migrates backend API registration.
integrations/​dotnet/​dotnet-tool-resources.mdx Migrates samples and related guidance link.
integrations/​dotnet/​blazor-get-started.mdx Updates Blazor hosting API references.
integrations/​devtools/​mcp-inspector/​mcp-inspector-get-started.mdx Migrates MCP server registration.
integrations/​devtools/​mailpit/​mailpit-host.mdx Migrates mail consumer samples.
integrations/​devtools/​flagd/​flagd-connect.mdx Migrates feature-flag consumer samples.
integrations/​devtools/​dev-tunnels.mdx Migrates tunneled application samples.
integrations/​devtools/​dab/​dab-host.mdx Migrates web consumer registration.
integrations/​databases/​sqlite/​sqlite-host.mdx Migrates SQLite consumer samples.
integrations/​databases/​sql-server/​sql-server-extensions.mdx Migrates SQL Server consumer samples.
integrations/​databases/​solr/​solr-host.mdx Migrates Solr consumer registration.
integrations/​databases/​seaweedfs/​seaweedfs-host.mdx Migrates storage consumer registration.
integrations/​databases/​seaweedfs/​seaweedfs-get-started.mdx Migrates introductory storage samples.
integrations/​databases/​rustfs/​rustfs-host.mdx Migrates bucket consumer samples.
integrations/​databases/​qdrant/​qdrant-host.mdx Migrates Qdrant consumer samples.
integrations/​databases/​postgres/​postgresql-extensions.mdx Migrates PostgreSQL consumer samples.
integrations/​databases/​mysql/​mysql-extensions.mdx Migrates MySQL consumer samples.
integrations/​databases/​mongodb/​mongodb-extensions.mdx Migrates MongoDB consumer samples.
integrations/​databases/​milvus/​milvus-host.mdx Migrates Milvus consumer samples.
integrations/​databases/​elasticsearch/​elasticsearch-host.mdx Migrates Elasticsearch consumer samples.
integrations/​databases/​elasticsearch/​elasticsearch-extensions.mdx Migrates API registration.
integrations/​databases/​efcore/​sqlite.mdx Migrates SQLite application samples.
integrations/​databases/​efcore/​seed-database.mdx Replaces SDK setup with package references.
integrations/​databases/​efcore/​oracle/​oracle-host.mdx Migrates Oracle consumer samples.
integrations/​databases/​efcore/​azure-sql/​azure-sql-host.mdx Migrates Azure SQL consumer samples.
integrations/​databases/​efcore/​azure-cosmos-db/​azure-cosmos-db-host.mdx Migrates Cosmos DB consumer samples.
integrations/​databases/​duckdb/​duckdb-host.mdx Migrates DuckDB consumer samples.
integrations/​databases/​clickhouse/​clickhouse-host.mdx Migrates ClickHouse consumer samples.
integrations/​databases/​chroma/​chroma-host.mdx Migrates Chroma consumer samples.
integrations/​custom-integrations/​secure-communication.mdx Migrates newsletter service registration.
integrations/​custom-integrations/​hosting-integrations.mdx Migrates samples and package-version guidance.
integrations/​custom-integrations/​client-integrations.mdx Migrates newsletter service registration.
integrations/​compute/​kubernetes.mdx Migrates Kubernetes application samples.
integrations/​compute/​kind/​kind-host.mdx Migrates operator and API registration.
integrations/​cloud/​stripe/​stripe-host.mdx Migrates webhook application samples.
integrations/​cloud/​azure/​role-assignments.mdx Migrates role-assignment consumer samples.
integrations/​cloud/​azure/​overview.mdx Updates resource types and deployment samples.
integrations/​cloud/​azure/​local-provisioning.mdx Migrates web application registration.
integrations/​cloud/​azure/​configure-container-apps.mdx Migrates Container Apps samples.
integrations/​cloud/​azure/​azure-web-pubsub/​azure-web-pubsub-host.mdx Migrates PubSub application samples.
integrations/​cloud/​azure/​azure-virtual-network.mdx Migrates networked API registration.
integrations/​cloud/​azure/​azure-storage-tables/​azure-storage-tables-host.mdx Migrates Tables consumer samples.
integrations/​cloud/​azure/​azure-storage-queues/​azure-storage-queues-host.mdx Migrates Queues consumer samples.
integrations/​cloud/​azure/​azure-sql-database/​azure-sql-database-host.mdx Migrates SQL database consumer samples.
integrations/​cloud/​azure/​azure-service-bus/​azure-service-bus-host.mdx Migrates Service Bus consumer samples.
integrations/​cloud/​azure/​azure-postgresql/​azure-postgresql-host.mdx Migrates PostgreSQL application samples.
integrations/​cloud/​azure/​azure-openai/​azure-openai-host.mdx Migrates Azure OpenAI consumer samples.
integrations/​cloud/​azure/​azure-log-analytics.mdx Migrates monitored service registration.
integrations/​cloud/​azure/​azure-functions/​azure-functions-host.mdx Migrates consumers; retains Functions registration.
integrations/​cloud/​azure/​azure-front-door.mdx Migrates frontend and API registration.
integrations/​cloud/​azure/​azure-data-explorer.mdx Migrates analytics consumer samples.
integrations/​cloud/​azure/​azure-cosmos-db/​azure-cosmos-db-host.mdx Migrates Cosmos DB consumer samples.
integrations/​cloud/​azure/​azure-container-registry/​azure-container-registry-host.mdx Migrates registry role-assignment samples.
integrations/​cloud/​azure/​azure-connector-namespace.mdx Migrates connector worker registration.
integrations/​cloud/​azure/​azure-cache-redis/​azure-cache-redis-host.mdx Migrates Redis consumer samples.
integrations/​cloud/​azure/​azure-application-insights.mdx Migrates monitored application samples.
integrations/​cloud/​azure/​azure-app-configuration/​azure-app-configuration-host.mdx Migrates configuration consumer samples.
integrations/​cloud/​azure/​azure-api-management/​azure-api-management-networking.mdx Migrates networked catalog registration.
integrations/​cloud/​azure/​azure-api-management/​azure-api-management-get-started.mdx Migrates introductory catalog samples.
integrations/​cloud/​azure/​azure-ai-search/​azure-ai-search-host.mdx Migrates search consumer samples.
integrations/​cloud/​azure/​azure-ai-inference/​azure-ai-inference-host.mdx Migrates inference application samples.
integrations/​cloud/​azure/​azure-ai-inference/​azure-ai-inference-get-started.mdx Migrates introductory inference registration.
integrations/​cloud/​azure/​aks/​index.mdx Migrates AKS application samples.
integrations/​cloud/​azure/​ai-compatibility-matrix.mdx Migrates AI consumer samples.
integrations/​cloud/​aws/​overview.mdx Migrates DynamoDB consumer samples.
integrations/​caching/​valkey/​valkey-host.mdx Migrates Valkey consumer samples.
integrations/​caching/​redis-output/​redis-output-host.mdx Migrates output-cache consumer samples.
integrations/​caching/​redis-extensions.mdx Migrates Redis consumer samples.
integrations/​caching/​redis-distributed/​redis-distributed-host.mdx Migrates distributed-cache consumer registration.
integrations/​caching/​garnet/​garnet-host.mdx Migrates Garnet consumer samples.
integrations/​ai/​stable-diffusion-cpp/​stable-diffusion-cpp-host.mdx Migrates image API registration.
integrations/​ai/​stable-diffusion-cpp/​stable-diffusion-cpp-connect.mdx Migrates image API registration.
integrations/​ai/​squad/​squad-host.mdx Migrates API registration.
integrations/​ai/​openai/​openai-host.mdx Migrates OpenAI consumer samples.
integrations/​ai/​ollama/​ollama-host.mdx Migrates Ollama consumer samples.
get-started/​what-is-aspire.mdx Updates file-based AppHost packages and registration.
get-started/​troubleshooting.mdx Migrates troubleshooting samples.
get-started/​first-app.mdx Migrates starter sample and API explanation.
get-started/​deploy-first-app.mdx Migrates deployment samples.
get-started/​aspire-mcp-server.mdx Migrates MCP resource samples.
get-started/​app-host.mdx Updates registration explanations.
fundamentals/​persist-data-volumes.mdx Migrates volume-mounted application samples.
fundamentals/​http-commands.mdx Migrates HTTP-command samples.
fundamentals/​health-checks.mdx Migrates health-check dependency samples.
fundamentals/​environment-variables.mdx Updates registration and service-discovery examples.
fundamentals/​custom-resource-urls.mdx Updates supported types and URL samples.
fundamentals/​container-networking.mdx Migrates container-to-project networking samples.
extensibility/​multi-language-integration-authoring.mdx Migrates custom-command application registration.
extensibility/​interaction-service.mdx Migrates resource-stopped event sample.
extensibility/​custom-resources.mdx Migrates relationship and display-name samples.
diagnostics/​overview.mdx Adds the ASPIRE012 overview entry.
diagnostics/​aspirecsharpapps001.mdx Explains Aspire 17 obsoletion and migration.
diagnostics/​aspire009.mdx Attributes bundle resolution to AppHost builds.
diagnostics/​aspire008.mdx Updates diagnostic project configuration examples.
diagnostics/​aspire007.mdx Adds Aspire 17 configuration guidance.
deployment/​kubernetes/​persistent-volumes.mdx Migrates persistent-volume application samples.
deployment/​kubernetes/​helm-charts.mdx Migrates Helm deployment application samples.
deployment/​kubernetes/​clusters.mdx Migrates cluster deployment samples.
deployment/​kubernetes/​aks.mdx Migrates AKS deployment samples.
deployment/​kubernetes-ingress.mdx Migrates ingress backend samples.
deployment/​kubernetes-ingress-aks.mdx Migrates AKS ingress application samples.
deployment/​kubernetes-gateway-aks.mdx Migrates AKS gateway application samples.
deployment/​environments.mdx Migrates environment configuration samples.
deployment/​deploy-with-aspire.mdx Migrates deployment introduction samples.
deployment/​custom-deployments.mdx Selects resources requiring image builds.
deployment/​azure/​sandboxes.mdx Migrates compute-targeted API samples.
deployment/​azure/​azure-security-best-practices.mdx Migrates security configuration samples.
deployment/​azure/​app-service.mdx Migrates App Service publishing samples.
deployment/​app-lifecycle.mdx Migrates Blazor application registration.
dashboard/​terminal-tape-playback.mdx Removes legacy SDK-directive guidance.
dashboard/​telemetry-after-deployment.mdx Migrates monitored application registration.
dashboard/​explore.mdx Migrates resource display-order samples.
dashboard/​enable-browser-telemetry/​blazor-webassembly.mdx Migrates backend and Blazor Web registration.
community/​contributor-guide.mdx Updates canonical code examples.
app-host/​with-terminal.mdx Migrates terminal-enabled project samples.
app-host/​resource-lifetimes.mdx Migrates project lifetime samples.
app-host/​executable-resources.mdx Migrates backend registration samples.
app-host/​eventing.mdx Migrates eventing application samples.
app-host/​docker-compose-to-apphost-reference.mdx Updates the .NET build mapping.
app-host/​cors-configuration.mdx Migrates API registration samples.
app-host/​container-files.mdx Updates destination guidance and samples.
src/​frontend/​src/​components/​ThreeTierAspire.astro Migrates the three-tier code example.
src/​frontend/​src/​components/​SimpleAppHostCode.shared.ts Migrates shared C# and TypeScript snippets.
src/​frontend/​src/​components/​home/​HomePage.astro Migrates homepage code examples.
src/​frontend/​config/​sidebar/​reference.topics.ts Adds ASPIRE012 navigation.
src/​frontend/​config/​sidebar/​integrations.topics.ts Adds migration and legacy-resource navigation.
src/​frontend/​config/​sidebar/​docs.topics.ts Renames AppHost configuration navigation.
.github/​agents/​release-verifier.agent.md Expands package-version verification guidance.
.agents/​skills/​doc-writer/​references/​integration-documentation.md Migrates templates; removes unused Go variable.
.agents/​skills/​doc-writer/​references/​common-documentation-issues.md Migrates formatting examples.
.agents/​skills/​doc-pr-reviewer/​SKILL.md Updates version and legacy-API review guidance.

Review effort: Balanced

Jose Perez Rodriguez (joperezr) pushed a commit to microsoft/aspire that referenced this pull request Nov 17, 2026
…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>

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.

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

No open issues 🎉

11 previously missed issues

In code that hasn't changed since last review

Medium severity Add the Dotnet package to the file-based AppHost

src/​frontend/​src/​content/​docs/​ja/​get-started/​add-aspire-existing-app.mdx:157

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.

Medium severity Correct the API project path

src/​frontend/​src/​content/​docs/​ja/​get-started/​add-aspire-existing-app.mdx:224

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.

Medium severity Correct the Web project path

src/​frontend/​src/​content/​docs/​ja/​get-started/​add-aspire-existing-app.mdx:229

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.

Medium severity Correct the Worker project path

src/​frontend/​src/​content/​docs/​ja/​get-started/​add-aspire-existing-app.mdx:233

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.

Low severity Remove stale Api project-reference instruction

src/​frontend/​src/​content/​docs/​app-host/​cors-configuration.mdx:253

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.

Low severity Remove stale Agent project-reference instruction

src/​frontend/​src/​content/​docs/​app-host/​with-terminal.mdx:201

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.

Low severity Remove the stale Projects.Api reference requirement

src/​frontend/​src/​content/​docs/​integrations/​databases/​chroma/​chroma-host.mdx:45

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.

Low severity Remove the stale Projects.Api reference instruction

src/​frontend/​src/​content/​docs/​integrations/​databases/​duckdb/​duckdb-host.mdx:41

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.

Low severity Remove the stale Projects.Api reference instruction

src/​frontend/​src/​content/​docs/​integrations/​databases/​efcore/​sqlite.mdx:58

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.

Low severity Remove the stale Projects.Api reference instruction

src/​frontend/​src/​content/​docs/​integrations/​databases/​solr/​solr-host.mdx:43

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.

Low severity Remove the stale Projects.Web assumption

src/​frontend/​src/​content/​docs/​integrations/​security/​zitadel/​zitadel-connect.mdx:49

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.

2 resolved since last review

Review effort: Max

@karolz-ms

Copy link
Copy Markdown
Contributor

Copilot Address issues mentioned in review #2180 (review)

Copilot AI commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Copilot Address issues mentioned in review #2180 (review)

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.

David Pine (IEvangelist) pushed a commit that referenced this pull request Nov 17, 2026
…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>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
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>
…gent guidance

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

Convert tutorial, troubleshooting, MCP, console app, resource model, and
resource hierarchy samples plus homepage/AppHost builder components from
AddProject/addProject to AddDotnetProject/addDotnetProject. Tutorial
AppHost code now matches the Aspire 17 starter template, and console-apps
installs Aspire.Hosting.Dotnet.

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>
…tnetProject

- Blazor hosting/connect/get-started use AddBlazorWasmApp and AddDotnetProjectBlazorGateway (validated in C# and TS AppHosts)
- WPF/WinForms registration uses AddDotnetProject with TS/C#/Go tabs
- container-files samples use AddDotnetProject
- Fix 13.6 release notes anchor

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>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
…Projects.* prose

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@IEvangelist
David Pine (IEvangelist) merged commit c555a13 into release/17.0 Nov 17, 2026
17 checks passed
@IEvangelist
David Pine (IEvangelist) deleted the docs/project-resource-v2-guidance branch November 17, 2026 03:02
David Pine (IEvangelist) added a commit that referenced this pull request Nov 17, 2026
…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>
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.

6 participants