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

Overview

Microsoft Copilot Studio recently upgraded its .NET WebAssembly (WASM) engine from .NET 8 to .NET 10, delivering performance improvements and simplifying deployment. This tutorial walks you through the same upgrade path, highlighting key changes like automatic asset fingerprinting and enabled IL stripping for AOT builds. Whether you maintain a Blazor WASM app or a custom .NET WASM runtime, you'll learn how to migrate smoothly and avoid common pitfalls.

Prerequisites

• Existing .NET 8 WASM application – You should have a working project targeting net8.0 and using .NET WASM (e.g., Blazor WebAssembly).
• .NET 10 SDK – Install the latest .NET 10 preview or release SDK from dotnet.microsoft.com.
• Basic familiarity with .NET, C#, and WebAssembly – Understanding of AOT vs JIT compilation and asset integrity is helpful.
• Version control – Backup your project before making changes.

Step-by-Step Instructions

1. Update Target Framework

1. Open your project file (.csproj).
2. Change the TargetFramework property from net8.0 to net10.0.

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

Save the file and rebuild the solution. If any NuGet packages are incompatible, update them to versions that support .NET 10 (check each package's release notes).

2. Audit and Update Dependencies

Run dotnet list package --outdated to identify packages that need updating. Pay special attention to:

• Microsoft.NET.Sdk.WebAssembly.Pack – This is now integrated into the .NET 10 SDK; you may be able to remove explicit version references.
• Fingerprinting custom scripts – If you previously implemented custom SHA-256 renaming (like Copilot Studio did), you can now remove that logic.
• Client-side resource loaders – Remove any manual integrity argument passed from JavaScript when loading WASM assets.

3. Leverage Automatic Fingerprinting

In .NET 8, many teams (including Copilot Studio) had to:

• Parse blazor.boot.json to enumerate assets.
• Run a custom script to rename files with SHA-256 hashes.
• Explicitly set integrity attributes in JavaScript.

In .NET 10, this is now automatic. When you publish, each asset filename includes a unique fingerprint. Integrity is validated by the runtime without any extra configuration. Simply publish as usual:

dotnet publish -c Release

You can delete any custom PowerShell or Node.js scripts that handled renaming. The dotnet.js file will load resources directly, and the old integrity parameter is no longer needed.

4. Enable Improved AOT Builds (WasmtStripILAfterAOT)

.NET 10 enables WasmStripILAfterAOT by default for AOT builds. This strips the Intermediate Language (IL) from AOT-compiled methods, reducing output size. If you are using AOT (e.g., WasmEnableAOT = true), no change is needed for the stripping—it happens automatically.

Note if you ship both JIT and AOT assets (like Copilot Studio): Because stripped AOT assemblies no longer match JIT assemblies, you may lose deduplication opportunities. Plan to either accept slightly larger package size or implement custom deduplication logic for shared assets that are bit-for-bit identical.

5. Special Consideration for WebWorker Usage

If you initialize the .NET WASM runtime inside a WebWorker, set dotnetSidecar = true during initialization to ensure correct behavior in worker contexts. See the Microsoft documentation for details.

Common Mistakes

• Forgetting to remove custom fingerprinting scripts – Leaving old renaming logic can cause duplicate files or broken integrity checks.
• Ignoring dependency compatibility – Some third-party packages may not yet support .NET 10. Always verify with dotnet list package --vulnerable or check the package's GitHub.
• Overlooking the WebWorker setting – If you use a WebWorker and omit dotnetSidecar, the runtime may fail to load correctly.
• Assuming deduplication still works with AOT stripping – When mixing JIT and AOT, stripped IL means fewer identical files. Test your deployment package size.
• Not testing production publishing – Always run a full dotnet publish -c Release and verify the output works in a representative browser.

Summary

Upgrading to .NET 10 for WebAssembly apps is straightforward: update the target framework, update dependencies, and remove any custom asset-manipulation scripts. Automatic fingerprinting and default IL stripping simplify deployment and reduce output size. Follow the steps above to migrate your app like Copilot Studio did, and avoid common pitfalls by testing thoroughly. The result is faster load times and less maintenance overhead.