Breaking change in 8.2.0 .NET Aspire Workload

[joperezr]

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"
}

2. Run the following command from the directory where the rollback.json file is located:

dotnet workload update --from-rollback-file ./rollback.json

3. 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.

[KennethHoff]

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

What does this mean? Will the workload be deprecated come 9.0? It always felt weird how I had to tell everyone to write this random line in the CLI (one that nobody has ever heard of; "dotnet workloads? What's that?") just to run what otherwise looks to be a standard .Net app.

Other than "create, build and run", what other things does it do? Creating the Manifest? Publishing via AZD?

[joperezr]

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.

[joperezr]

Updated the top post to introduce a new preferred workaround (Workaround 1: Add the following lines to your AppHost Project file). This workaround would be preferred as it won't require you to pin the version of the workload you are using.

[Kralizek]

Still unable to build.

$ dotnet workload install aspire

Workload(s) 'aspire' are already installed.

Successfully installed workload(s) .

$ dotnet workload list

Workload version: 8.0.401

Installed Workload Id      Installation Source
----------------------------------------------
aspire                     SDK 8.0.400

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

$ dotnet build
  Determining projects to restore...
  All projects are up-to-date for restore.
C:\Users\Renato\.nuget\packages\aspire.hosting.apphost\8.2.0\build\Aspire.Hosting.AppHost.targets(251,5): error ASPIRE005: AppHost project requires a newer version of the .
NET Aspire Workload to work correctly. Please run `dotnet workload update`. [C:\Users\Renato\Development\ProjectX\tools\AppHost\AppHost.csproj]
  ...

Build FAILED.

C:\Users\Renato\.nuget\packages\aspire.hosting.apphost\8.2.0\build\Aspire.Hosting.AppHost.targets(251,5): error ASPIRE005: AppHost project requires a newer version of the .
NET Aspire Workload to work correctly. Please run `dotnet workload update`. [C:\Users\Renato\Development\ProjectX\tools\AppHost\AppHost.csproj]
    0 Warning(s)
    1 Error(s)

[davidfowl]

@Kralizek did you run dotnet workload update?

[Kralizek]

yes.

$ dotnet workload update

Updated advertising manifest microsoft.net.workloads.
Installing workload version 8.0.401.

Successfully updated workload(s): aspire.

Also tried with --no-cache an uninstalling and installing the workloads

SDK updated via winget and also via visual studio installer.

[davidfowl]

What nuget feeds do you have configured

[Kralizek]

$ dotnet nuget list source
Registered Sources:
  1.  Local [Enabled]
      C:\Users\Renato\Development\LocalPackageStore
  2.  github-kralizek [Enabled]
      https://nuget.pkg.github.com/kralizek/index.json
  3.  nuget.org [Enabled]
      https://api.nuget.org/v3/index.json
  4.  Microsoft Visual Studio Offline Packages [Enabled]
      C:\Program Files (x86)\Microsoft SDKs\NuGetPackages\

[davidfowl]

@Kralizek This issue details how to avoid/delay the 8.2.0 update. Did you perform those steps and then try to update to 8.2.0?

[Kralizek]

no, updated directly to 8.2.0.