Skip to content

Add test project upgrade guidance to upgrade-aspire page #512

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Copilot wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add test project upgrade guidance to upgrade-aspire page #512

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cf928e8
Initial plan
Copilot Mar 5, 2026
8a3655b
Add 'Upgrade test projects' section to upgrade-aspire.mdx
Copilot Mar 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions src/frontend/src/content/docs/whats-new/upgrade-aspire.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,52 @@ Please remove the **aspire workload** with the following command:
dotnet workload uninstall aspire
```

## Upgrade test projects

If your solution includes an Aspire test project (one that references [📦 Aspire.Hosting.Testing](https://www.nuget.org/packages/Aspire.Hosting.Testing)), you'll need to update it alongside your AppHost.

<Steps>

1. **Update the `Aspire.Hosting.Testing` package** to match the version of your updated AppHost:

```bash title="Update the testing package"
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.
Comment on lines +84 to +88
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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.

Copilot uses AI. Check for mistakes.
</Aside>

2. **Verify the project reference to the AppHost** exists in your test project:

```xml title="YourApp.Tests.csproj"
<ItemGroup>
<ProjectReference Include="..\YourApp.AppHost\YourApp.AppHost.csproj" />
</ItemGroup>
```

This reference is required for the `Projects` namespace to be generated, which is how `DistributedApplicationTestingBuilder.CreateAsync<Projects.YourApp_AppHost>()` resolves your AppHost.

3. **Run your tests** to verify everything still works:

```bash title="Run tests"
dotnet test
```

</Steps>

<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">`).
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
- 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/&lt;version&gt;">`, where `<version>` matches the SDK version used by your AppHost).

Copilot uses AI. Check for mistakes.
- Your test project has a direct `ProjectReference` to the AppHost `.csproj` file.
- The `Aspire.Hosting.Testing` package version matches your `Aspire.AppHost.Sdk` version.
</Aside>

<LearnMore>
For more information, see [Testing overview](/testing/overview/).
</LearnMore>

## Verify the upgrade

After upgrading, run your application to ensure everything works as expected:
Expand All @@ -80,6 +126,12 @@ After upgrading, run your application to ensure everything works as expected:
aspire run
```

If your solution includes test projects, also run your tests to confirm they pass:

```bash title="Run tests"
dotnet test
```

## Need help?

- 🆘 Stuck? [Join the Discord community](https://discord.com/invite/raNPcaaSj8) for real-time support
Expand Down
Loading