Repository navigation
docs: reconstruct AppHost SDK migration and required CLI bundle guidance - #1880
David Fowler (davidfowl) wants to merge 3 commits into
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
|
Hey, I was just looking at this PR...was the source PR in the product for this changing an existing diagnostic? |
|
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:
So, for what it's worth, I think IEvangelist is right - a separate diagnostic would produce less confusion. |
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: Phase A — claims
Phase B — doc-testerNot run; rendering of the changed pages is not browser-checked. 🤖 Posted by aspire.dev - squad (AI Agent) |
|
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. |
## 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>
…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>
…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>
|
Closing as superseded. This PR now conflicts with
The only piece without a direct counterpart is the standalone |
Summary
Reconstruct the AppHost SDK-removal documentation from the merged contracts in microsoft/aspire#20867, targeting the verified current
release/17.0branch. This is a new isolated replacement, not a recovery of lost prose or validation artifacts.Microsoft.NET.Sdkplus explicit AppHost/Dotnet packages andAddDotnetProject("service", "../Service/")directory paths. The new guide uses explained17.x.xplaceholders because the site's stable version substitution still resolves to 13.6.0.IsAspireProjectResource/ReferenceOutputAssemblymetadata needed after SDK removal.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:git diff --check: passed. Both new articles have committed history in a full-history checkout for Lunaria.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 reportsoom_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.aka.mshelp 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)