ASP.NET Core Blazor WebAssembly build tools and ahead-of-time (AOT) compilation

This article describes the build tools for standalone Blazor WebAssembly apps and how to compile an app ahead of deployment with ahead-of-time (AOT) compilation.

.NET WebAssembly build tools

The .NET WebAssembly build tools are based on Emscripten, a compiler toolchain for the web platform.

To install the build tools as a .NET workload, use either of the following approaches:

• For the ASP.NET and web development workload in the Visual Studio installer, select the .NET WebAssembly build tools option from the list of optional components. The option ensures the following:

  • The workload is installed for the latest .NET SDK.
  • When a new version of Visual Studio is released and it contains a new .NET SDK, the option installs the workload for the new SDK.

• Alternatively, execute the following command in an administrative command shell to install the latest workload to the latest .NET SDK available on the system:

  dotnet workload install wasm-tools
  

To target a prior .NET release with a given .NET SDK, install the wasm-tools-net{MAJOR VERSION} workload:

• The {MAJOR VERSION} placeholder is replaced with the major version number of the .NET release you want to target (for example, wasm-tools-net8 for .NET 8).
• Workloads are installed per .NET SDK. Installing the wasm-tools workload for one SDK doesn't make it available to other SDKs on the system.
• You must install the appropriate workload for each .NET SDK version you intend to use.

The following list shows which workload to install for each .NET SDK, depending on the apps that you plan to target. Although multiple rows may contain the same workload name, the workloads always differ slightly for each particular .NET SDK.

• Using the .NET 9 SDK
  • Targeting .NET 9 requires wasm-tools.
  • Targeting .NET 8 requires wasm-tools-net8.
• Using the .NET 8 SDK: Targeting .NET 8 requires wasm-tools.

Ahead-of-time (AOT) compilation

Blazor WebAssembly supports ahead-of-time (AOT) compilation, where you can compile your .NET code directly into WebAssembly. AOT compilation results in runtime performance improvements at the expense of a larger app size.

For guidance on installing the .NET WebAssembly build tools, see ASP.NET Core Blazor WebAssembly build tools and ahead-of-time (AOT) compilation.

To enable WebAssembly AOT compilation, add the <RunAOTCompilation> property set to true to the Blazor WebAssembly app's project file:

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

To compile the app to WebAssembly, publish the app. Publishing the Release configuration ensures the .NET Intermediate Language (IL) linking is also run to reduce the size of the published app:

dotnet publish -c Release

WebAssembly AOT compilation is only performed when the project is published. AOT compilation isn't used when the project is run during development (Development environment) because AOT compilation usually takes several minutes on small projects and potentially much longer for larger projects. Reducing the build time for AOT compilation is under development for future releases of ASP.NET Core.

The size of an AOT-compiled Blazor WebAssembly app is generally larger than the size of the app if compiled into .NET IL:

• Although the size difference depends on the app, most AOT-compiled apps are about twice the size of their IL-compiled versions. This means that using AOT compilation trades off load-time performance for runtime performance. Whether this tradeoff is worth using AOT compilation depends on your app. Blazor WebAssembly apps that are CPU intensive generally benefit the most from AOT compilation.

• The larger size of an AOT-compiled app is due to two conditions:

  • More code is required to represent high-level .NET IL instructions in native WebAssembly.
  • AOT doesn't trim out managed DLLs when the app is published. Blazor requires the DLLs for reflection metadata and to support certain .NET runtime features. Requiring the DLLs on the client increases the download size but provides a more compatible .NET experience.

Performance

For performance guidance, see ASP.NET Core Blazor WebAssembly runtime performance:

• Heap size for some mobile device browsers
• Runtime relinking
• Single Instruction, Multiple Data (SIMD)
• Trim .NET IL after ahead-of-time (AOT) compilation (.NET 8 or later)

Exception handling

<PropertyGroup>
  <WasmEnableExceptionHandling>false</WasmEnableExceptionHandling>
</PropertyGroup>

<PropertyGroup>
  <WasmEnableExceptionHandling>true</WasmEnableExceptionHandling>
</PropertyGroup>

For more information, see the following resources:

• Configuring and hosting .NET WebAssembly applications: EH - Exception handling
• Exception handling

Additional resources

• ASP.NET Core Blazor WebAssembly runtime performance
• ASP.NET Core Blazor WebAssembly native dependencies
• Webcil packaging format for .NET assemblies