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.

[davidfowl]

Hmm, not sure, I just ran it and got this:

Do you have a global.json somewhere?

[Kralizek]

yes, I use this one in the roots of all my projects to avoid accidental upgrade to previews

cat .\global.json
{
  "sdk": {
    "version": "8.0.0",
    "rollForward": "latestMinor"
  }
}

PS: build server works fine, it's my local machine that refuses to build.

[davidfowl]

Run the workload update outside of the global.json context.

[Kralizek]

same same

$ dotnet workload update

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

Successfully updated workload(s): aspire.

$ dotnet workload install aspire

Workload(s) 'aspire' are already installed.
Installing workload version 8.0.401.

Successfully installed workload(s) .

[joperezr]

@Kralizek I know what is going on here. You have the opposite problem that this issue is tracking: you have the Aspire 8.1.0 workload installed, and your project is referencing 8.2.0. For 8.2.0 to build correctly, we need both workload and package reference to match.

The reason why you are still in 8.1.0 of the workload even after running dotnet workload update is because you seem to have opted-in to workload-sets, which will keep you on the versions that match that workload-set, which in this case is 8.1.0 no matter how much you run dotnet workload update. To fix this, you just need to opt-out of workload-set mode in your dotnet installation, in order to allow individual workloads to get updated to a new version. To do that, simply run dotnet workload config --update-mode manifests. After doing that, you should be able to run dotnet workload update again and that should get you updated to 8.2.0. Please give that a try and let us know if that worked.

[Kralizek]

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.

[davidfowl]

@Kralizek did you know you opted into workload sets?

[joperezr]

I'm glad we were able to unblock you. I have edited the top post to also cover this scenario, and posted the solution in there too for folks that run into this.

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

[asimmon]

I want to share my experience upgrading to 8.2.0 so far. It hasn't been great, but I appreciate the efforts to improve it.

We used dotnet workload install aspire in our CI, so when the new version came out, all our CI pipelines failed due to the requirement of using the corresponding 8.2.0 NuGet package.

Knowing that this would prevent us from working on future stories and even publishing a new version of our project, we quickly updated all references to 8.2.0. Later, we found a regression and spent extra time finding a workaround.

After some time, we decided to roll back to 8.1.0. We learned about workload rollback files, which we'll use from now on.

I love that the new workload set works with global.json. However, what I don't like is that I still don't have any idea what will be the .NET Aspire workload version if I use this global.json file:

{
  "sdk": {
    "version": "8.0.401",
    "rollForward": "latestPatch",
    "allowPrerelease": false,
    "workloadVersion": "8.0.401" // ???
  }
}

We're using global.json to maintain our required SDK version with Renovate. We also use Renovate to update our NuGet dependencies. To ensure that we use the .NET Aspire workload that matches the NuGet app host package, we configured Renovate to maintain our rollback.json file:

// custom regex manager
{
  "description": ".NET Aspire workload rollback file (https://github.com/dotnet/aspire/discussions/2230)",
  "customType": "regex",
  "fileMatch": ["^rollback.json$"],
  "matchStringsStrategy": "any",
  "matchStrings": [
    "\"microsoft.net.sdk.aspire\":\\s*\"(?<currentValue>[^/]+)/[^\"]+\"" // matches 8.1.0/8.0.100 for instance
  ],
  "datasourceTemplate": "nuget",
  "versioningTemplate": "nuget",
  "depNameTemplate": "Aspire.Hosting.AppHost"
}

We're using .NET Aspire in a non-conventional way. We ship it as part of a cross-platform CLI tool, which could be considered like Tye but tailored for our local DX needs. We install the .NET Aspire workload as part of our CI/CD pipeline, so it will be more resilient from now on.

We didn't want our developers (especially non-.NET developers) to deal with workloads, so our CLI tool directly downloads the proper workload package from NuGet at runtime. We use reflection to modify the DCP options and override any DCP and dashboard paths set in the assembly metadata.

Our tool uses .NET Aspire as the main orchestrator, and it's been our solution for helping developers working in a distributed environment with many services, many repos, and many teams working with different languages.

Our tool does much more than that, including generating self-signed certificates using mkcert, allowing developers to use custom domains, automatic hosts file maintenance, and automating certificate authority sync for containers to seamlessly trust any self-signed host certificate (mkcert and ASP.NET Core dev cert). I wish we could define Docker extra hosts with .NET Aspire's container resource annotations. (my wish has already been granted)

[DamianEdwards]

@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

[davidfowl]

I wish we could define Docker extra hosts with .NET Aspire's container resource annotations.

https://learn.microsoft.com/en-us/dotnet/api/aspire.hosting.containerresourcebuilderextensions.withcontainerruntimeargs?view=dotnet-aspire-8.0

[Emil-Granbom]

I have the Aspire 8.1.0 workload installed, and and I'm trying to udate the workload to 8.2. I have tried to opt-out of workload-set mode in my dotnet installation by running dotnet workload config --update-mode manifests. It doesn't matter dotnet workload update still doesn't work.

❯ dotnet workload config --update-mode manifests Successfully updated workload install mode to use manifests. ❯ dotnet workload update -s nuget.org

Advertising manifest not updated. Manifest package for microsoft.net.sdk.android doesn't exist. Advertising manifest not updated. Manifest package for microsoft.net.sdk.ios doesn't exist. Advertising manifest not updated. Manifest package for microsoft.net.sdk.maccatalyst doesn't exist. Advertising manifest not updated. Manifest package for microsoft.net.sdk.macos doesn't exist. Advertising manifest not updated. Manifest package for microsoft.net.sdk.maui doesn't exist. Advertising manifest not updated. Manifest package for microsoft.net.sdk.tvos doesn't exist. Advertising manifest not updated. Manifest package for microsoft.net.workload.mono.toolchain.current doesn't exist. Advertising manifest not updated. Manifest package for microsoft.net.workload.emscripten.current doesn't exist. Advertising manifest not updated. Manifest package for microsoft.net.workload.emscripten.net6 doesn't exist. Advertising manifest not updated. Manifest package for microsoft.net.workload.emscripten.net7 doesn't exist. Advertising manifest not updated. Manifest package for microsoft.net.workload.mono.toolchain.net6 doesn't exist. Advertising manifest not updated. Manifest package for microsoft.net.workload.mono.toolchain.net7 doesn't exist. Advertising manifest not updated. Manifest package for microsoft.net.sdk.aspire doesn't exist.

Successfully updated workload(s): android aspire ios maccatalyst maui-windows.

❯ dotnet workload list

Installed Workload Id Manifest Version Installation Source

android 34.0.113/8.0.100 SDK 8.0.400, VS 17.11.35222.181 aspire 8.1.0/8.0.100 SDK 8.0.400, VS 17.11.35222.181 ios 17.5.8020/8.0.100 SDK 8.0.400, VS 17.11.35222.181 maccatalyst 17.5.8020/8.0.100 SDK 8.0.400, VS 17.11.35222.181 maui-windows 8.0.72/8.0.100 SDK 8.0.400, VS 17.11.35222.181

I don't understand why it says that the source is SDK 8.0.400. I have 8.0.401 installed

❯ dotnet sdk check

.NET SDKs:

Version Status

8.0.400 Patch 8.0.401 is available. 8.0.401 Up to date.

[teresaqhoang]

My project references 8.2.0 and I also tried to opt-out of workload-set mode by running dotnet workload config --update-mode manifests but still got the following error during rebuild:

Workload update failed: One or more errors occurred. 
(Version 34.0.130 of package microsoft.android.sdk.windows.msi.x64 is not found in NuGet feeds...)

What worked for me:

I got the build running after installing the latest VS preview version: Visual Studio Preview (microsoft.com) (v17.12 with .NET 9)

Then from the project directory, ran:

dotnet workload restore
dotnet workload update

Then restarted VS and rebuild was successful.

[joperezr]

@Emil-Granbom can you try using the full nuget org feed url to see if that works? dotnet workload update -s https://api.nuget.org/v3/index.json? I don't think that using just nuget.org will be able to transleta into the actual feed.

[joperezr]

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

[Emil-Granbom]

@joperezr That was it! Thanks a lot.

[teresaqhoang]

@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!

[dxm223]

Our CI pipeline failed in relation. We are using .net 8 tooling with aspire packages specified to 8.1. I am able to use the workaround. We never previously ran any --version commands manually. Our CI pipeline was running 'dotnet workload restore' and is now using 'dotnet workload install aspire --version 8.0.401' along w/ the csproj SkipAddAspireDefaultReferences flag.

[sturlath]

I had tried everything already mentioned (and refresh/restart/etc.) until running the following

dotnet workload update -s https://api.nuget.org/v3/index.json

The nuget url is in my feed

[abratv]

why so intrusive, calling dotnet update workload install 8.1.0 lol

[abratv]

ok i have it working

there is nuget authorization issue with private package, so go here %appdata%\NuGet\ remove your private package from there (put it back later) this is old issue that the team never fix

open your project, right click open in terminal dotnet workload update, this also install maui stuff :( it should work without error, it should install 8.2 version

close visual studio, re-open everything should work again