Configurer l’éditeur de liens pour ASP.NET Core Blazor

Cet article explique comment contrôler l’éditeur de liens de langage intermédiaire (IL) lors de la création d’une application Blazor.

Blazor WebAssembly effectue une liaison de langage intermédiaire (IL) pendant un build pour supprimer le langage intermédiaire inutile des assemblys de sortie de l’application. L’éditeur de liens est désactivé lors de la génération dans la configuration Debug. Les applications doivent être générées dans la configuration Release pour activer l’éditeur de liens. Nous vous recommandons de les générer dans Release lors du déploiement de vos applications Blazor WebAssembly.

La liaison d’une application optimise la taille, mais peut avoir des effets néfastes. Les applications qui utilisent la réflexion ou les fonctionnalités dynamiques associées peuvent s’interrompre lorsqu’elles sont découpées, car l’éditeur de liens ne connaît pas ce comportement dynamique et ne peut en général pas déterminer les types requis pour la réflexion au moment de l’exécution. Pour découper ces applications, l’éditeur de liens doit être informé de tous les types requis par la réflexion dans le code et dans les packages ou infrastructures dont dépend l’application.

Pour vous assurer que l’application découpée fonctionne correctement une fois déployée, il est important de tester fréquemment les builds Release de l’application lors du développement.

La liaison pour les applications Blazor peut être configurée à l’aide des fonctionnalités MSBuild suivantes :

• Configurer la liaison globalement avec une propriété MSBuild.
• Contrôler la liaison pour chaque assembly avec un fichier de configuration.

Contrôler la liaison avec une propriété MSBuild

La liaison est activée lorsqu’une application est intégrée à la configuration Release. Pour modifier cela, configurez la propriété MSBuild BlazorWebAssemblyEnableLinking dans le fichier projet :

<PropertyGroup>
  <BlazorWebAssemblyEnableLinking>false</BlazorWebAssemblyEnableLinking>
</PropertyGroup>

Contrôler la liaison avec un fichier de configuration

Contrôlez la liaison pour chaque assembly en fournissant un fichier de configuration XML et en spécifiant le fichier en tant qu’élément MSBuild dans le fichier projet :

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

LinkerConfig.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/dotnet/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>

Pour plus d’informations et d’exemples, consultez Formats de données (référentiel GitHub dotnet/linker).

Ajouter un fichier de configuration de l’éditeur de liens XML à une bibliothèque

Afin de configurer l’éditeur de liens pour une bibliothèque spécifique, vous devez ajouter un fichier de configuration de l’éditeur de liens XML dans la bibliothèque en tant que ressource incorporée. La ressource incorporée doit avoir le même nom que l’assembly.

Dans l’exemple suivant, le fichier LinkerConfig.xml est spécifié en tant que ressource incorporée portant le même nom que l’assembly de la bibliothèque:

<ItemGroup>
  <EmbeddedResource Include="LinkerConfig.xml">
    <LogicalName>$(MSBuildProjectName).xml</LogicalName>
  </EmbeddedResource>
</ItemGroup>

Configurer l’éditeur de liens pour l’internationalisation

La configuration de l’éditeur de liens de Blazor pour les applications Blazor WebAssembly supprime les informations d’internationalisation, à l’exception des paramètres régionaux explicitement demandés. La suppression de ces assemblys réduit la taille de l’application.

Pour contrôler les assemblys I18N qui sont conservés, définissez la propriété MSBuild <BlazorWebAssemblyI18NAssemblies> dans le fichier projet :

<PropertyGroup>
  <BlazorWebAssemblyI18NAssemblies>{all|none|REGION1,REGION2,...}</BlazorWebAssemblyI18NAssemblies>
</PropertyGroup>

Utilisez une virgule pour séparer plusieurs valeurs (par exemple mideast,west).

Pour plus d’informations, consultez I18N : bibliothèque Pnetlib Internationalization Framework (référentiel GitHub mono/mono).

Ressources supplémentaires

• Meilleures pratiques d’ASP.NET Core Blazor en matière de performances