Migrating .NET WebAssembly Apps to .NET 10: A Step-by-Step Guide with Copilot Studio Insights

Overview

Microsoft Copilot Studio recently upgraded its .NET WebAssembly (WASM) engine from .NET 8 to .NET 10, reaping significant performance and developer experience benefits. This tutorial distills their migration process into actionable steps you can apply to your own .NET WASM applications. You'll learn how to update your project, leverage new features like automatic file fingerprinting and the WasmStripILAfterAOT optimization, and avoid common pitfalls. By the end, you'll have a production-ready .NET 10 WASM app with faster load times and simpler deployment.

Prerequisites

• An existing .NET 8 WebAssembly application (e.g., Blazor WASM or a custom .NET WASM app)
• .NET 10 SDK installed (download from dotnet.microsoft.com)
• Basic familiarity with .NET project files (.csproj) and command-line build tools
• A code editor (Visual Studio, VS Code, or Rider)
• Optional: Existing PowerShell or bash scripts for asset fingerprinting (to see what you can remove)

Step-by-Step Instructions

1. Update the Target Framework

Open your project’s .csproj file and change the TargetFramework from net8.0 to net10.0. Also update any RuntimeIdentifier or TargetPlatform references if you target specific WASM profiles. For a standard Blazor WASM project, the change looks like this:

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
  <!-- Other properties -->
</PropertyGroup>

Save the file and run dotnet restore to fetch .NET 10 packages. The Copilot Studio team reported that this single change was the core of their migration—everything else flowed from it.

2. Validate Dependency Compatibility

After updating the target framework, check all NuGet packages for .NET 10 compatibility. Use dotnet list package --outdated to see which packages need updates. The Copilot Studio developers ensured every dependency had a version targeting net10.0. If a package lacks .NET 10 support, consider:

• Updating to a newer version (if available)
• Forking the package and recompiling
• Contacting the maintainer

Common packages like Microsoft.AspNetCore.Components.WebAssembly are updated automatically when you restore from a .NET 10 SDK.

3. Remove Manual Fingerprinting Code

In .NET 8, you likely had a custom script (PowerShell, bash, or build task) to hash WASM assets for cache-busting and integrity. The Copilot Studio team used a PowerShell script that read blazor.boot.json, renamed files with SHA256 hashes, and passed integrity arguments to the JavaScript loader. With .NET 10, all of this is automatic.

Delete your custom renaming script and remove any JavaScript code that explicitly sets the integrity attribute when importing WASM resources. The new dotnet.js runtime handles fingerprinting natively. Your updated deployment pipeline should simply call dotnet publish and serve the output as-is.

If you were manually adding fingerprints to a CDN, update your build configuration to use the published filenames directly. No more post-build steps!

4. (Optional) Enable WebWorker Support with dotnetSidecar

If your app loads the .NET WASM runtime inside a WebWorker (e.g., for offloading heavy computation), set the dotnetSidecar option to true when invoking dotnet.init():

const { setModuleImports, getAssemblyExports } = await DotNet.init({
  dotnetSidecar: true
});

This ensures the runtime initializes correctly in a worker context. The Copilot Studio team noted this as a useful tip for advanced deployments.

5. Leverage WasmStripILAfterAOT (Now Default)

In .NET 10, WasmStripILAfterAOT is enabled by default when you publish with AOT (Ahead-of-Time compilation). This strips the Intermediate Language (IL) from AOT-compiled assemblies, reducing the download size. If you were explicitly setting this property to true in .NET 8, you can remove that line—the default now covers it.

However, if you use a mixed JIT/AOT approach like Copilot Studio (loading JIT for fast startup and AOT for peak performance), be aware that stripped AOT assemblies will differ from their JIT counterparts. This means file deduplication (removing bit-identical files) is less effective. The Copilot Studio team accounts for this by packaging JIT and AOT engines separately and only deduplicating truly identical assets (e.g., satellite assemblies).

To enable AOT publishing, add the following to your .csproj:

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

Then publish with dotnet publish -c Release. You’ll see smaller .wasm files due to IL stripping.

6. Test and Deploy

After building, run your application locally with dotnet run or serve the publish output via a simple HTTP server (e.g., dotnet serve). Check the browser console for any errors related to missing assets or loading failures. Verify that caching behaves as expected (no stale files). If you use a CDN, ensure your cache-control headers are set to use the new fingerprinted filenames. Deploy to a staging environment first—the Copilot Studio team moved their .NET 10 build to production after thorough regression testing.

Common Mistakes

• Forgetting to update all projects in a solution: If your solution has multiple projects (e.g., a shared library), ensure every .csproj targets net10.0. Otherwise, you'll get runtime binding errors.
• Leaving old fingerprinting scripts: Running a manual renaming script on already-fingerprinted files can corrupt asset names. Remove them entirely.
• Ignoring WebWorker contexts: If you use WebWorkers without setting dotnetSidecar, the WASM runtime may hang or throw cryptic errors.
• Assuming all packages are compatible: Some older packages may target only net8.0. Always run dotnet restore carefully and check for NU1701 warnings.
• Not testing with AOT disabled first: If you enable AOT immediately after migration, debugging becomes harder. Keep RunAOTCompilation false until you confirm the JIT build works.
• Overlooking CDN caching: Even with automatic fingerprinting, if your CDN has long cache times, you may need to purge old assets manually after deployment.

Summary

Migrating a .NET 8 WebAssembly application to .NET 10 is straightforward: update the target framework, ensure dependency compatibility, and remove custom fingerprinting code. The WasmStripILAfterAOT default reduces download sizes, and the new automatic fingerprinting simplifies deployment. By following these steps—and avoiding common pitfalls like stale scripts or incompatible packages—you can deliver faster, more maintainable WASM apps, just as Copilot Studio did.

Back to top