aspire: Breaking change in 8.2.0 .NET Aspire Workload

Issue building projects referencing 8.1.0 when having 8.2.0 workload installed

As part of our work of removing the requirement for installing the .NET Aspire workload in order to create, build and run .NET Aspire projects in 9.0, we made some significant changes in 8.2.0 which, when installed, will require your AppHost projects to also be updated and reference the 8.2.0 version of the Aspire.Hosting.AppHost package. For people that are hitting issues, our recommendation is to update to 8.2.0 by making sure that your AppHost projects have the following:

<ItemGroup>
  <PackageReference Include="Aspire.Hosting.AppHost" Version="8.2.0" />
</ItemGroup>

We also understand that some people may not be able to update to 8.2.0 immediately, so here are three workarounds to ensure you can continue to build and run your .NET Aspire 8.1.0 projects by either adding some code into your AppHost project, or by “pinning” the version of the .NET Aspire Workload you use to 8.1.0.

Workaround 1: Add the following lines to your AppHost Project file

If you are unable to update to 8.2.0 immediately, you can add the following lines to your AppHost project file to ensure that you are able to continue to build it.

<!-- 
     Given this project is not ready to reference the Aspire.Hosting.AppHost 8.2.0 package,
     the following lines are needed to disable automatic references added by the .NET Aspire
     SDK, as well as to add those references manually.
     **THESE LINES SHOULD BE DELETED AS SOON AS THE PROJECT IS UPDATED TO USE THE 8.2.0 VERSION**
-->
<PropertyGroup>
  <SkipAddAspireDefaultReferences>true</SkipAddAspireDefaultReferences>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Aspire.Dashboard.Sdk.$(NETCoreSdkRuntimeIdentifier)" Version="8.2.0" />
  <PackageReference Include="Aspire.Hosting.Orchestration.$(NETCoreSdkRuntimeIdentifier)" Version="8.2.0" />
</ItemGroup>

Please make sure to delete these lines as soon as you are able to update your references to 8.2.0 or later version.

Workaround 2: If you are using SDK 8.0.400 or later

If you are using SDK 8.0.400 or later, you can pin the version of the .NET Aspire workload to 8.1.0 by using the new workload-set feature by running the following command:

dotnet workload install aspire --version 8.0.401

This will ensure that the .NET Aspire workload that you use, will be the one that comes with the 8.0.401 workload-set, which is the 8.1.0 version.

Workaround 3: If you are using an older SDK

Workload-sets are a new feature, so if you are using an older SDK, the above workaround won’t work for you. You can still pin the version of the .NET Aspire workload to 8.1.0 by making use of rollback files, and here is how you can do that:

  1. Create a file named rollback.json with the following content:
{
  "microsoft.net.sdk.aspire": "8.1.0/8.0.100"
}
  1. Run the following command from the directory where the rollback.json file is located:
dotnet workload update --from-rollback-file ./rollback.json
  1. Finally, run the following command to ensure that the .NET Aspire workload is installed:
dotnet workload install aspire --from-rollback-file ./rollback.json

This will ensure that the .NET Aspire workload that you use, will be the 8.1.0 version, which will allow you to continue to reference the 8.1.0 version of the Aspire.Hosting.AppHost package in your AppHost projects.

We apologize for the inconvenience this may have caused and we are working on providing a better experience by removing the requirement for installing the .NET Aspire workload in order to create, build and run .NET Aspire projects in 9.0.

Issue building projects referencing 8.2.0 when having 8.1.0 workload installed

If you are trying to build and get an error like:

error ASPIRE005: AppHost project requires a newer version of the .NET Aspire Workload to work correctly. Please run `dotnet workload update`. 

It means that you need to install a newer version of the workload in order to build the project. As the error suggests, you can do so by running dotnet workload update. If you have tried running dotnet workload update but you keep having this error in your build, make sure that you:

  1. Have https://api.nuget.org/v3/index.json as one of your sources when running dotnet nuget list source. If you don’t see it, you can add it by running dotnet nuget add source "https://api.nuget.org/v3/index.json".
  2. Ensure you are not “pinned” to a workload-set. When your SDK is in workload-set mode, the versions of the workloads will be pinned to match the ones declared in that workload-set, so even when running dotnet workload update, you will remain pinned to the version you have currently. In order to allow upgrading the Aspire workload, you can opt-out of workload-set mode by running dotnet workload config --update-mode manifests, which would then allow to install the version of .NET Aspire you need by simply running dotnet workload update again.

About this issue

  • Original URL
  • State: closed
  • Created 2 years ago
  • Reactions: 10
  • Comments: 37 (17 by maintainers)

Most upvoted comments

this drives me crazy, what is the solution to this?!

Edit: nvm, in the end it was an issue with my nuget package sources. I had some custom ones

it worked like a charm! thanks @joperezr and @davidfowl for the help 😃

Here is the updated workload list

$  dotnet workload list

Installed Workload Id      Manifest Version      Installation Source
--------------------------------------------------------------------------------
aspire                     8.2.0/8.0.100         SDK 8.0.400, VS 17.11.35222.181

Use `dotnet workload search` to find additional workloads to install.

The plan is that for 9.x, the workload will mostly only contain the .NET Aspire template packs, so by installing it, main benefit will be that you will have our templates installed (and updated) automatically for you. That said, you will still be able to manually install the templates using the install CLI command (dotnet new install), since all of our templates will continue to get pushed to NuGet.org. This means that the only downside of not having the workload will be that this becomes a manual step, as opposed to an automated one.

Update to Aspire 9, you don’t need to use .NET 9 to use the latest Aspire.

@teresaqhoang it looks like your dotnet cli is aware of some package versions that are only available in our dogfooding feeds for some other workloads (might have happened if you build other dotnet repos in the same machine). To fix the error you are hitting, you can try adding this feed to find the package it is complaining about: dotnet nuget add source "https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet8/nuget/v3/index.json" and then trying to update your workloads again. Let me know if you are still hitting issues.

This was exactly it. Thank you @joperezr!

@joperezr That was it! Thanks a lot.

@Kralizek

I didn’t know it. I have no idea how I did it. I suspect it happene when I tried to install the workload doing dotnet workload install aspire --version 8.2.0 but not sure.

Yep that’s it. Running dotnet workload install with a --version parameter opts you into workload sets mode: https://learn.microsoft.com/dotnet/core/tools/dotnet-workload-sets#pin-the-install-command

I didn’t know it. I have no idea how I did it. I suspect it happene when I tried to install the workload doing dotnet workload install aspire --version 8.2.0 but not sure.