Skip to content

docs: reconstruct AppHost SDK migration and required CLI bundle guidance - #1880

Closed
David Fowler (davidfowl) wants to merge 3 commits into
release/17.0from
docs/apphost-sdk-migration-replacement-20261013-f5ab7e34
Closed

David Fowler (davidfowl) wants to merge 3 commits into
release/17.0from
docs/apphost-sdk-migration-replacement-20261013-f5ab7e34

Conversation

@davidfowl

@davidfowl David Fowler (davidfowl) commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Reconstruct the AppHost SDK-removal documentation from the merged contracts in microsoft/aspire#20867, targeting the verified current release/17.0 branch. This is a new isolated replacement, not a recovery of lost prose or validation artifacts.

  • Add the migration guide and ASPIRE012 warning reference, with navigation entries.
  • Document the default Microsoft.NET.Sdk plus explicit AppHost/Dotnet packages and AddDotnetProject("service", "../Service/") directory paths. The new guide uses explained 17.x.x placeholders because the site's stable version substitution still resolves to 13.6.0.
  • Preserve staged SDK/AddProject compatibility and document the explicit IsAspireProjectResource/ReferenceOutputAssembly metadata needed after SDK removal.
  • Correct ASPIRE010 to an unsuppressible bundle opt-out error, retain ASPIRE007 legacy/pre-9 SDK guidance and ASPIRE009 invalid-path remedies, and update configuration and upgrade/release guidance.
  • Cover solution/CI service builds after removing project references, manual central package management/NU1008 adjustments, and file-based AppHost AOT defaults without changing service AOT guidance.

Exactly 12 scoped documentation/navigation files changed. Existing drafts #1853 (AddCSharpApp) and #1804 (testing) remain separate. The shared release notes and diagnostic overview are edited in different sections; this PR doesn't replace those drafts. Visual Studio follow-ups microsoft/aspire#20933 and #20934 are not claimed qualified by documentation or Linux builds. No installed skills-plugin capability is assumed.

Third-party links and affiliations

None. Added links target this documentation site and the Microsoft Aspire GitHub repositories.

Validation

Fresh checks on committed head 830285d00e88d7c628aa15bdb1910a8594597551:

  • Navigation ESLint with zero warnings: passed.
  • Native analytics contracts, redirects, and documentation filetree suites: 3 files, 15 tests passed.
  • Native data-file and skill-digest checks: passed.
  • Generated HTML checks: all 10 changed articles render; 180 internal article links and anchors resolve. Migration contracts, explicit upcoming-release versions, and the existing CLI-bundle anchor are present.
  • git diff --check: passed. Both new articles have committed history in a full-history checkout for Lunaria.
  • Full repository-standard pnpm build:production: failed, exit 137, after 22m57.825s. It generated 32,647 HTML route log entries and completed all 984 image optimizations, then was killed while Starlight was building the Pagefind search index. The environment exposes approximately 8 GiB RAM, no swap, and the cgroup reports oom_kill 1. The native full-site link-validation completion hook was not reached, so neither the full build nor full-site link acceptance is claimed.
  • ASPIRE012 aka.ms help redirect retry: DNS resolution failed (curl exit 6); external redirect publication is unverified.

The initial build was intentionally stopped after discovering that the site's stable version placeholder was inappropriate for the new migration examples. The corrected committed head received the fresh full attempt above; the stopped attempt is not counted as a pass. Logs, patch, and verified Git bundle are preserved separately, but the remote commits and this draft are the persistent deliverable.

Keep this PR as a draft until a sufficiently provisioned native production build completes search indexing and full-site link validation. Documentation checks don't establish service runtime or Windows/Visual Studio qualification.

🤖 Posted by Mona (AI Agent)

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

Copy link
Copy Markdown
Contributor

Frontend HTML artifact ready

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

VS Code: Open PR #1880 artifacts

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

@IEvangelist

Copy link
Copy Markdown
Member

Hey, I was just looking at this PR...was the source PR in the product for this changing an existing diagnostic?
Compiler Warning ASPIRE010 | Aspire
This exists today as a warning, if we change the meaning of this in 17.0 - we're making a case where things can get really confusing. I'm not sure I know the right answer, but this could cause a lot of issues.

@alistairmatthews

Alistair Matthews (alistairmatthews) commented Oct 16, 2026 •

Copy link
Copy Markdown
Collaborator

To better understand David Pine (@IEvangelist)'s comment, I got Claude to compare the changes made by this PR to ASPIRE010. Thought it might be helpful here:

Aspect Current release/17.0 After PR #1880
Title Compiler Warning ASPIRE010 Compiler Error ASPIRE010
SEO title "Aspire CLI bundle opt-out warning" "The Aspire CLI bundle is required"
Message Says the project is configured with AspireUseCliBundle=false and offers two choices: set it to true, or suppress ASPIRE010 Says the project requires the CLI bundle, tells you to remove the property or set it to true and install the matching CLI from get.aspire.dev, and says ASPIRE010 can't be suppressed
Default of AspireUseCliBundle false true
When it fires When the property is false or not set (because unset meant false) Only when it's explicitly false. Leaving it unset doesn't trigger it
Scope Not stated C# AppHosts, both package-based ones and those that keep Aspire.AppHost.Sdk
Version history Introduced in 13.5 Same badge, plus: "Introduced as a warning in Aspire 13.5... an error in Aspire 17.0"
How to fix Set the property to true Remove the false setting or set it to true, and install a compatible Aspire CLI (links to the install page)
Suppression Includes a <NoWarn>$(NoWarn);ASPIRE010</NoWarn> example for keeping NuGet-restored dependencies Example removed. It now says NoWarn=ASPIRE010 doesn't suppress the error or make opting out valid
CLI resolution wording The fallback CLI is "paired with the AppHost SDK" The fallback CLI is "paired with Aspire.Hosting.AppHost" (matches the SDK removal)

So, for what it's worth, I think IEvangelist is right - a separate diagnostic would produce less confusion.

Copy link
Copy Markdown
Member

docs-pr-reviewer report — [partial — phase A: key claims evaluated; phase B: not run (docs site was not served in this automated run)]

Recommendation: needs human

Source used: microsoft/aspire main via merged source PR microsoft/aspire#20867 (ASPIRE012 / SDK deprecation); the second cited source (#20933) could not be resolved as a PR (docs PR targets release/17.0; no matching branch checked).
PR status: draft, mergeable, opened 2026-10-13 (not stale); touches 12 files

Phase A — claims

Phase B — doc-tester

Not run; rendering of the changed pages is not browser-checked.

🤖 Posted by aspire.dev - squad (AI Agent)

@IEvangelist

Copy link
Copy Markdown
Member

Following up on the ASPIRE010 compatibility concern: microsoft/aspire#21288 restores ASPIRE010's original suppressible optional-bundle warning for non-C# AppHosts and uses ASPIRE013 for the unsuppressible C# bundle-required error. Please preserve the existing ASPIRE010 warning article and document ASPIRE013 separately, updating the migration/configuration guidance and diagnostic index accordingly. The ASPIRE013 article and https://aka.ms/aspire/diagnostics/aspire013 redirect need to be published and verified before the release ships. Product PR #21288 does not publish the article or configure that redirect.

David Pine (IEvangelist) added a commit to microsoft/aspire that referenced this pull request Nov 6, 2026
## Description

Diagnostic IDs must keep their meaning across releases. #20867 changed
ASPIRE010 from a suppressible warning about optional CLI bundle features
into an unsuppressible error requiring the bundle. Existing suppression
settings and the published diagnostic reference therefore describe a
different contract.

Restore ASPIRE010's original warning text, severity, and help link for
non-C# AppHosts, where opting out remains supported. Introduce ASPIRE013
for the required-bundle error in C# AppHosts, without changing the C#
bundle requirement or ASPIRE012 SDK-obsolescence warning. The two
diagnostics are mutually exclusive.

Update the product diagnostic list and migration guide, and cover
enabled/disabled bundles, C#/non-C# applicability, both warning IDs in
NoWarn, and the complete set of emitted Aspire diagnostics.

Related documentation discussion:
microsoft/aspire.dev#1880. That documentation PR
should preserve the ASPIRE010 warning reference and document ASPIRE013
separately. Publishing the ASPIRE013 article and configuring
https://aka.ms/aspire/diagnostics/aspire013 are coordinated
documentation follow-ups; this product PR does not publish the site or
configure the redirect.

### User-facing usage

For a C# AppHost, this continues to fail the build, now with `error
ASPIRE013` rather than a repurposed ASPIRE010:

```xml
<PropertyGroup>
  <AspireUseCliBundle>false</AspireUseCliBundle>
</PropertyGroup>
```

For a non-C# AppHost, opting out emits the original `warning ASPIRE010`,
which remains suppressible with `<NoWarn>$(NoWarn);ASPIRE010</NoWarn>`.
Adding either ASPIRE010 or ASPIRE013 to NoWarn does not bypass the C#
requirement.

### Validation

- `.\restore.cmd` — passed.
- `dotnet build
tests\Aspire.Hosting.Sdk.Tests\Aspire.Hosting.Sdk.Tests.csproj
--no-restore --verbosity quiet` — passed, with four NU1902/NU1903 audit
warnings for System.Security.Cryptography.Pkcs 10.0.12. No dependency
versions are changed by this PR.
- Native Microsoft.Testing.Platform execution — passed, 14/14 tests:

```powershell
& .\artifacts\bin\Aspire.Hosting.Sdk.Tests\Debug\net10.0\Aspire.Hosting.Sdk.Tests.exe --filter-method "*.CliBundleDiagnosticsRespectLanguageAndWarningSuppression" --filter-method "*.AppHostSdkEmitsObsoleteWarning" --filter-method "*.AppHostSdkObsoleteWarningCanBeSuppressed" --filter-method "*.MinimumSdkVersionErrorDoesNotFireForNonSdkAppHost" --filter-method "*.ComputeRunArgumentsDoesNotUseAspireCliWhenCliBundleIsDisabled" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"
```

- `git diff --check` — passed.
- The initial `dotnet test` invocation below built the project but timed
out in a child MSBuild invocation and was stopped. Retrying the
diagnostic matrix with NuGet audit disabled also timed out and was
stopped. Running the same selected tests with the built native MTP
executable succeeded as recorded above.

```powershell
dotnet test --project tests\Aspire.Hosting.Sdk.Tests\Aspire.Hosting.Sdk.Tests.csproj --no-launch-profile -- --filter-method "*.CliBundleDiagnosticsRespectLanguageAndWarningSuppression" --filter-method "*.AppHostSdkEmitsObsoleteWarning" --filter-method "*.AppHostSdkObsoleteWarningCanBeSuppressed" --filter-method "*.MinimumSdkVersionErrorDoesNotFireForNonSdkAppHost" --filter-method "*.ComputeRunArgumentsDoesNotUseAspireCliWhenCliBundleIsDisabled" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"
```

Full solution and cross-platform validation were not run locally.

Fixes # (issue)

## 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
    - If yes, did you have an API Review for it?
      - [ ] Yes
      - [ ] No
- Did you add `<remarks />` and `<code />` elements on your triple slash
comments?
      - [ ] Yes
      - [ ] No
  - [x] No
- Does the change make any security assumptions or guarantees?
  - [ ] Yes
    - If yes, have you done a threat model and had a security review?
      - [ ] Yes
      - [ ] No
  - [x] No

---------

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

Copy link
Copy Markdown
Contributor

Closing as superseded. This PR now conflicts with release/17.0, and its content has landed elsewhere:

The only piece without a direct counterpart is the standalone migrate-apphost-sdk.mdx. release/17.0 covers migration in migrate-dotnet-project-resource.mdx instead.

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.

4 participants