Configurar o vinculador para o Blazor do ASP.NET Core

Este artigo explica como controlar o Vinculador de IL (Linguagem Intermediária) ao criar um aplicativo Blazor.

Blazor WebAssembly executa a vinculação de IL (linguagem intermediária) durante um build para cortar a IL desnecessária dos assemblies de saída do aplicativo. O vinculador é desabilitado ao criar na configuração de Depuração. Os aplicativos devem ser compilados na Configuração de versão para habilitar o vinculador. É recomendável compilar na Versão ao implantar seus aplicativos Blazor WebAssembly.

A vinculação de um aplicativo otimiza o tamanho, mas pode ter efeitos prejudiciais. Aplicativos que usam reflexão ou recursos dinâmicos relacionados podem ser interrompidos quando cortados porque o vinculador não sabe sobre esse comportamento dinâmico e, em geral, não pode determinar quais tipos são necessários para reflexão no runtime. Para cortar esses aplicativos, o vinculador deve ser informado sobre todos os tipos exigidos pela reflexão no código e em pacotes ou estruturas dos quais o aplicativo depende.

Para garantir que o aplicativo cortado funcione corretamente após a implantação, é importante testar builds de versão do aplicativo com frequência durante o desenvolvimento.

A vinculação para aplicativos Blazor pode ser configurada usando estes recursos do MSBuild:

• Configure a vinculação globalmente com uma propriedade MSBuild.
• Controle a vinculação por assembly usando um arquivo de configuração.

Controle a vinculação com uma propriedade MSBuild

A vinculação é habilitada quando um aplicativo é integrado à configuração Release. Para alterar isso, configure a propriedade BlazorWebAssemblyEnableLinking MSBuild no arquivo de projeto:

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

Controlar a vinculação com um arquivo de configuração

Controle a vinculação por assembly fornecendo um arquivo de configuração XML e especificando o arquivo como um item MSBuild no arquivo de projeto:

<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>

Para obter mais informações e exemplos, consulte Formatos de dados (dotnet/runtimerepositório GitHub).

Adicionar um arquivo de configuração do vinculador XML a uma biblioteca

Para configurar o vinculador para uma biblioteca específica, adicione um arquivo de configuração do vinculador XML à biblioteca como um recurso inserido. O recurso inserido deve ter o mesmo nome que o assembly.

No exemplo a seguir, o arquivo LinkerConfig.xml é especificado como um recurso inserido que tem o mesmo nome que o assembly da biblioteca:

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

Configurar o vinculador para internacionalização

A configuração do vinculador do Blazor para aplicativos Blazor WebAssembly remove as informações de internacionalização, exceto nas localidades solicitadas explicitamente. A remoção desses assemblies minimiza o tamanho do aplicativo.

Para controlar quais assemblies I18N são retidos, defina a propriedade MSBuild <BlazorWebAssemblyI18NAssemblies> no arquivo de projeto:

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

Use uma vírgula para separar vários valores (por exemplo: mideast,west).

Para obter mais informações, consulte I18N: Biblioteca de Framework de Internacionalização do Pnetlib (repositório de GitHub mono/mono).

Recursos adicionais

• Práticas recomendadas de desempenho do ASP.NET Core Blazor