設定 ASP.NET Core Blazor 的連結器

發行項
11/12/2024

本文說明如何在建置 Blazor 應用程式時，控制中繼語言 (IL) 連結器。

Blazor WebAssembly 會在組建期間執行中繼語言 (IL) 連結，以從應用程式的輸出組件中修剪不必要的 IL。在偵錯設定中建置時，連結器會遭到停用。應用程式必須在發行設定中建置，才能啟用連結器。建議您在部署 Blazor WebAssembly 應用程式時於發行中建置。

連結應用程式會針對大小進行最佳化，但可能會有不良影響。使用反映或相關動態功能的應用程式可能會在修剪時中斷，因為連結器不了解此動態行為，而且無法判斷一般情況下，執行階段反映所需的類型。若要修剪這類應用程式，連結器必須了解在程式碼和應用程式相依的套件或架構中反映所需的任何類型。

為了確保修剪的應用程式在部署後正常運作，請務必在開發時定期測試應用程式的發行組建。

您可以使用下列 MSBuild 功能，來設定 Blazor 應用程式的連結：

使用 MSBuild 屬性來全域設定連結。
使用設定檔來根據組件控制連結。

使用 MSBuild 屬性控制連結

在 Release 設定中內建應用程式時，會啟用連結。若要變更此連結，請在專案檔中設定 BlazorWebAssemblyEnableLinking MSBuild 屬性：

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

使用組態檔控制連結

透過提供 XML 設定檔，並將此檔案指定為專案檔中的 MSBuild 項目，即可根據組件控制連結：

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

如需詳細資訊和範例，請參閱數據格式（dotnet/runtimeGitHub 存放庫）。

將 XML 連結器設定檔新增至程式庫

若要設定特定程式庫的連結器，請將 XML 連結器設定檔新增至程式庫作為內嵌資源。內嵌資源的名稱必須與組件相同。

在下列範例中，會將 LinkerConfig.xml 檔案指定為內嵌資源，其名稱與程式庫的組件相同：

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

設定國際化的連結器

Blazor WebAssembly 應用程式的 Blazor 連結器設定會去除國際化資訊，但明確要求的地區除外。移除這些組件可將應用程式的大小降到最低。

若要控制要保留哪些 I18N 組件，請在專案檔中設定 <BlazorWebAssemblyI18NAssemblies> MSBuild 屬性：

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

區域值	Mono 區域組件
`all`	包含的所有組件
`cjk`	`I18N.CJK.dll`
`mideast`	`I18N.MidEast.dll`
`none` (預設值)	無
`other`	`I18N.Other.dll`
`rare`	`I18N.Rare.dll`
`west`	`I18N.West.dll`

使用逗號分隔多個值 (例如，mideast,west)。

如需詳細資訊，請參閱 I18N：Pnetlib 國際化架構程式庫 (mono/mono GitHub 存放庫)。

其他資源

ASP.NET Core Blazor 效能最佳做法

共用方式為

設定 ASP.NET Core Blazor 的連結器

使用 MSBuild 屬性控制連結

使用組態檔控制連結

將 XML 連結器設定檔新增至程式庫

設定國際化的連結器

其他資源

其他資源