How to Upgrade Your .NET WebAssembly App to .NET 10: A Copilot Studio Case Study

Introduction

Upgrading a .NET WebAssembly (WASM) application to the latest framework version can unlock performance gains and simplify your deployment pipeline. Microsoft's Copilot Studio team recently moved their .NET WASM engine from .NET 8 to .NET 10, and the results were impressive—automatic fingerprinting, smaller AOT outputs, and a smoother overall build. This guide walks you through the same steps they followed, using their real-world experience as a blueprint. Whether you're building a Blazor app or a custom WASM runtime, these steps will help you leverage the new features in .NET 10.

How to Upgrade Your .NET WebAssembly App to .NET 10: A Copilot Studio Case Study — Source: devblogs.microsoft.com

What You Need

.NET 10 SDK (or later) installed on your development machine
An existing .NET 8 WebAssembly project (like a Blazor WebAssembly app)
All project dependencies declared in your .csproj files
Familiarity with the dotnet publish command
Access to your CI/CD pipeline (to update deployment scripts)

Step-by-Step Guide

Step 1: Update the Target Framework

Open each .csproj file in your solution and change the <TargetFramework> element from net8.0 (or whatever version you're using) to net10.0. For example:

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
</PropertyGroup>

This tells the SDK to compile against the .NET 10 base class libraries and runtime. Copilot Studio's team found this was the only change required in their project files—everything else flowed from there.

Step 2: Verify Dependency Compatibility

Run dotnet restore to ensure all NuGet packages are compatible with .NET 10. Most packages targeting .NET 8 or later will work without changes, but you should check for any that explicitly target an older framework. If a package isn't compatible, update it to the latest version or seek an alternative. Copilot Studio's migration was straightforward because their dependencies were already up-to-date. If you get build errors, review the package's documentation or contact the maintainer.

Step 3: Remove Custom Fingerprinting Scripts

In .NET 8, many WASM apps (including Copilot Studio) used manual asset fingerprinting for cache-busting and integrity. They had to read the blazor.boot.json manifest, rename files with a SHA256 hash via PowerShell, and pass integrity arguments from JavaScript. With .NET 10's automatic fingerprinting (enabled by default), you can delete all that custom code. The dotnet.js runtime now imports resources directly with fingerprints embedded in filenames, and integrity is validated automatically. Look for:

Any custom PowerShell or bash scripts that rename WASM assets
JavaScript code that manually requests resources with an integrity parameter
References to a custom blazor.boot.json parser

Remove those entirely. Copilot Studio's team was able to delete an entire renaming script and simplify their client-side resource loader. Existing caching logic (like service worker caching) still works unchanged because the fingerprints update automatically.

Tip: If you load the .NET WASM runtime inside a WebWorker, set dotnetSidecar = true when calling Blazor.start(). This ensures proper initialization in a worker context.

Step 4: Enable Ahead-of-Time (AOT) Compilation (Optional but Recommended)

To get maximum execution speed, enable AOT compilation. In your project file, add:

<PropertyGroup>
  <RunAOTCompilation>true</RunAOTCompilation>
  <WasmStripILAfterAOT>true</WasmStripILAfterAOT>
</PropertyGroup>

In .NET 10, WasmStripILAfterAOT defaults to true for AOT builds, stripping the Intermediate Language (IL) after compilation to reduce output size. Copilot Studio uses a hybrid approach: they ship both a JIT engine (for fast startup) and an AOT engine (for best steady-state performance) in the same NPM package. At runtime, JIT loads first to handle initial interactions, then control hands off to AOT once it's ready. Because stripping IL makes AOT assemblies different from JIT ones, the two no longer share identical files—so deduplication logic must be adjusted. If you use a similar dual-engine strategy, plan to separate your JIT and AOT assets accordingly.

Step 5: Publish and Test

Run dotnet publish -c Release to generate the .NET 10 build. Test your application thoroughly, especially:

Asset loading times—they should be faster due to automatic fingerprinting removing the need for custom JavaScript delays.
Startup performance—AOT builds should launch quickly, and JIT fallback works seamlessly.
Functionality of any Blazor components or WASM modules.

Copilot Studio deployed their .NET 10 build into production shortly after testing. If you see any issues, double-check that your deployment pipeline didn't retain old fingerprinting scripts. The new build should work with standard dotnet publish output without modifications.

Conclusion & Tips

Upgrading to .NET 10 for WebAssembly is surprisingly simple for most projects. The key takeaways from Copilot Studio's migration:

Delete custom fingerprinting—.NET 10 handles it automatically. Save your CI/CD pipeline from unnecessary complexity.
Leverage WasmStripILAfterAOT—Smaller downloads mean faster page loads, especially on slow networks.
Consider a dual-engine approach—JIT for first interaction, AOT for later performance. But be mindful of file deduplication when stripping IL.
Test thoroughly—While the upgrade is minimal, edge cases around worker threads and custom loaders can arise. Enable logging if needed.

By following these steps, you can bring the same performance and simplicity improvements to your own .NET WASM applications. For more details, refer to the official .NET 10 WebAssembly documentation or review the Copilot Studio case study (linked at the beginning of this guide).