Configure the Linker for ASP.NET Core Blazor

By Luke Latham

Important

Blazor WebAssembly in preview

Blazor Server is supported in ASP.NET Core 3.0. Blazor WebAssembly is in preview for ASP.NET Core 3.1.

Blazor performs Intermediate Language (IL) linking during a build to remove unnecessary IL from the app's output assemblies.

Control assembly linking using either of the following approaches:

Disable linking with a MSBuild property

Linking is enabled by default when an app is built, which includes publishing. To disable linking for all assemblies, set the BlazorLinkOnBuild MSBuild property to false in the project file:

<PropertyGroup>
  <BlazorLinkOnBuild>false</BlazorLinkOnBuild>
</PropertyGroup>

Control linking with a configuration file

Control linking on a per-assembly basis by providing an XML configuration file and specifying the file as a MSBuild item in the project file:

<ItemGroup>
  <BlazorLinkerDescriptor Include="Linker.xml" />
</ItemGroup>

Linker.xml:

<?xml version="1.0" encoding="UTF-8" ?>
<!--
  This file specifies which parts of the BCL or Blazor packages must not be
  stripped by the IL Linker even if they aren't referenced by user code.
-->
<linker>
  <assembly fullname="mscorlib">
    <!--
      Preserve the methods in WasmRuntime because its methods are called by 
      JavaScript client-side code to implement timers.
      Fixes: https://github.com/aspnet/Blazor/issues/239
    -->
    <type fullname="System.Threading.WasmRuntime" />
  </assembly>
  <assembly fullname="System.Core">
    <!--
      System.Linq.Expressions* is required by Json.NET and any 
      expression.Compile caller. The assembly isn't stripped.
    -->
    <type fullname="System.Linq.Expressions*" />
  </assembly>
  <!--
    In this example, the app's entry point assembly is listed. The assembly
    isn't stripped by the IL Linker.
  -->
  <assembly fullname="MyCoolBlazorApp" />
</linker>

For more information, see IL Linker: Syntax of xml descriptor.

Configure the linker for internationalization

By default, Blazor's linker configuration for Blazor WebAssembly apps strips out internationalization information except for locales explicitly requested. Removing these assemblies minimizes the app's size.

To control which I18N assemblies are retained, set the <MonoLinkerI18NAssemblies> MSBuild property in the project file:

<PropertyGroup>
  <MonoLinkerI18NAssemblies>{all|none|REGION1,REGION2,...}</MonoLinkerI18NAssemblies>
</PropertyGroup>
Region Value Mono region assembly
all All assemblies included
cjk I18N.CJK.dll
mideast I18N.MidEast.dll
none (default) None
other I18N.Other.dll
rare I18N.Rare.dll
west I18N.West.dll

Use a comma to separate multiple values (for example, mideast,west).

For more information, see I18N: Pnetlib Internationalization Framework Libary (mono/mono GitHub repository).