Add test project upgrade guidance to upgrade-aspire page#512
Add test project upgrade guidance to upgrade-aspire page#512
Conversation
Addresses dotnet/docs-aspire#5663 by adding guidance on upgrading Aspire test projects, including updating the Aspire.Hosting.Testing package, verifying project references, and troubleshooting the common 'Projects namespace not found' compilation error. Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
IEvangelist
left a comment
IEvangelist
left a comment
There was a problem hiding this comment.
This PR looks good so far, but let's double check it for accuracy by using the .github/skills/doc-tester/SKILL.md skill. Please also consider all new comments and feedback/suggestions. @copilot
There was a problem hiding this comment.
Pull request overview
Adds upgrade guidance for Aspire test projects to the “Upgrade Aspire” documentation, helping users keep Aspire.Hosting.Testing and AppHost references aligned during upgrades.
Changes:
- Add a new “Upgrade test projects” section with steps for updating
Aspire.Hosting.Testing, validating AppHostProjectReference, and running tests. - Add an additional reminder in “Verify the upgrade” to run
dotnet testwhen test projects exist.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
| dotnet add <your-test-project>.csproj package Aspire.Hosting.Testing | ||
| ``` | ||
|
|
||
| <Aside type="tip"> | ||
| If you're using Central Package Management (CPM), update the version in your _Directory.Packages.props_ file instead. |
There was a problem hiding this comment.
Step 1 says to update Aspire.Hosting.Testing to match the AppHost version, but the command shown doesn't specify a version and will resolve whatever NuGet considers "latest" (which may not match the AppHost/SDK version, especially if users are upgrading to a specific version or using previews). Consider showing the command with an explicit --version (matching Aspire.AppHost.Sdk / the package versions in the solution), or otherwise clarifying that it will update to the latest available.
| dotnet add <your-test-project>.csproj package Aspire.Hosting.Testing | |
| ``` | |
| <Aside type="tip"> | |
| If you're using Central Package Management (CPM), update the version in your _Directory.Packages.props_ file instead. | |
| dotnet add <your-test-project>.csproj package Aspire.Hosting.Testing --version <AppHostVersion> | |
| ``` | |
| <Aside type="tip"> | |
| Use the same version here as your `Aspire.AppHost.Sdk` (for example, `9.1.0`). If you're using Central Package Management (CPM), update the version in your _Directory.Packages.props_ file instead. |
| <Aside type="caution" title="Projects namespace not found?"> | ||
| If your tests fail to compile with an error that the `Projects` namespace doesn't exist, ensure: | ||
|
|
||
| - Your AppHost project uses the [`Aspire.AppHost.Sdk`](/get-started/aspire-sdk/) (for example, `<Project Sdk="Aspire.AppHost.Sdk/13.1">`). |
There was a problem hiding this comment.
This page is an evergreen "Upgrade Aspire" guide, but the troubleshooting Aside hard-codes a specific SDK version (Aspire.AppHost.Sdk/13.1) in the example. That will become incorrect as soon as the latest version changes. Prefer a version placeholder (for example Aspire.AppHost.Sdk/<version>) or wording that points readers to the version currently used in their AppHost project.
| - Your AppHost project uses the [`Aspire.AppHost.Sdk`](/get-started/aspire-sdk/) (for example, `<Project Sdk="Aspire.AppHost.Sdk/13.1">`). | |
| - Your AppHost project uses the [`Aspire.AppHost.Sdk`](/get-started/aspire-sdk/) (for example, `<Project Sdk="Aspire.AppHost.Sdk/<version>">`, where `<version>` matches the SDK version used by your AppHost). |
The upgrade guide at
/whats-new/upgrade-aspire/had no mention of test projects. Users upgrading to Aspire 13.0+ hit a common break: theProjectsnamespace disappears from test projects after the AppHost migrates toAspire.AppHost.Sdk.Changes
Aspire.Hosting.Testing, verify theProjectReferenceto AppHost, and run testsProjectsnamespace resolution failure — the most common upgrade issue — with a checklist of things to verifydotnet testalongsideaspire run🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.