Configurar o vinculador para o Blazor do ASP.NET Core

  • Artigo

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:

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 (repositório dotnet/vinculador do 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

Por padrão, a configuração do vinculador 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>
Valor da região Assembly de região mono
all Todos os assemblies incluídos
cjk I18N.CJK.dll
mideast I18N.MidEast.dll
none (padrão) Nenhum
other I18N.Other.dll
rare I18N.Rare.dll
west I18N.West.dll

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