ASP.NET 核心 Blazor WebAssembly 建置工具和預先 (AOT) 編譯

  • 發行項

注意

這不是這篇文章的最新版本。 如需目前版本，請參閱本文的 .NET 8 版本。

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

如需目前版本，請參閱本文的 .NET 8 版本。

本文說明獨立 Blazor WebAssembly 應用程式的建置工具，以及如何在部署前使用預先 (AOT) 編譯來編譯應用程式。

雖然本文主要著重於獨立 Blazor WebAssembly 應用程式，但某些行動裝置瀏覽器的堆積大小一節也適用於 Blazor Web 應用程式的用戶端專案 (.Client)。

.NET WebAssembly 組建工具

.NET WebAssembly 組建工具是以 Web 平台的編譯器工具鏈 Emscripten 為基礎。 若要安裝組建工具，請使用下列其中一種方法：

  • 針對 Visual Studio 安裝程式中的 ASP.NET 和 Web 開發工作負載，請從選用元件清單中選取 [.NET WebAssembly 組建工具] 選項。
  • 在系統管理命令殼層中執行 dotnet workload install wasm-tools。

注意

適用於 .NET 6 專案的 .NET WebAssembly 組建工具

wasm-tools 工作負載會安裝最新版本的組建工具。 不過，目前的組建工具版本與使用 .NET 6 組建的現有專案不相容。 使用必須同時支援 .NET 6 和更新版本的組建工具的專案必須使用多重目標。

使用 .NET 7 SDK 開發應用程式時，請在 .NET 6 專案中使用 wasm-tools-net6 工作負載。 若要安裝 wasm-tools-net6 工作負載，請從系統管理命令殼層執行下列命令：

dotnet workload install wasm-tools-net6

預先 (AOT) 編譯

Blazor WebAssembly 支援預先 (AOT) 編譯，您可以在其中直接將 .NET 程式碼編譯成 WebAssembly。 AOT 編譯會導致執行階段的效能獲得改善，但代價是應用程式會比較大。

若未啟用 AOT 編譯，Blazor WebAssembly 應用程式會使用 WebAssembly 中所實作、具有部分 Just-In-Time (JIT) 執行階段支援的 .NET 中繼語言 (IL) 解譯器在瀏覽器中執行，這個解譯器的非正式稱呼是 Jiterpreter。 因為要解譯 .NET IL 程式碼，應用程式的執行速度一般會比在沒有任何 IL 解譯的伺服器端 .NET JIT 執行階段上執行時來得慢。 AOT 編譯解決這個效能問題的方法是，將應用程式的 .NET 程式碼直接編譯到 WebAssembly，以便瀏覽器能以原生方式執行 WebAssembly。 AOT 效能獲得改善後，所執行的工作需要 CPU 密集運算的應用程式也會獲得大幅的效能改善。 使用 AOT 編譯的缺點是，經過 AOT 編譯的應用程式一般會比其進行 IL 解譯的對照項目還大，因此在首次要求下載時，通常需要較長的時間才能下載到用戶端。

若未啟用 AOT 編譯，Blazor WebAssembly 應用程式會使用 WebAssembly 中所實作的 .NET 中繼語言 (IL) 解譯器在瀏覽器中執行。 因為要解譯 .NET 程式碼，應用程式的執行速度一般會比在伺服器端 .NET Just-In-Time (JIT) 執行階段上執行時來得慢。 AOT 編譯解決這個效能問題的方法是，將應用程式的 .NET 程式碼直接編譯到 WebAssembly，以便瀏覽器能以原生方式執行 WebAssembly。 AOT 效能獲得改善後，所執行的工作需要 CPU 密集運算的應用程式也會獲得大幅的效能改善。 使用 AOT 編譯的缺點是，經過 AOT 編譯的應用程式一般會比其進行 IL 解譯的對照項目還大，因此在首次要求下載時，通常需要較長的時間才能下載到用戶端。

如需安裝 .NET WebAssembly 建置工具的指引，請參閱 ASP.NET Core Blazor WebAssembly 建置工具和預先 (AOT) 編譯。

若要啟用 WebAssembly AOT 編譯，請將設定為 true 的 <RunAOTCompilation> 屬性新增至 Blazor WebAssembly 應用程式的專案檔：

<PropertyGroup>
  <RunAOTCompilation>true</RunAOTCompilation>
</PropertyGroup>

若要將應用程式編譯至 WebAssembly，請發行應用程式。 發行 Release 組態可確保 .NET 中繼語言 (IL) 連結也會執行，以減少所發行應用程式的大小：

dotnet publish -c Release

只有在發行專案時，才會執行 WebAssembly AOT 編譯。 在開發期間 (Development 環境) 執行專案時不會使用 AOT 編譯，因為小型專案的 AOT 編譯通常需要幾分鐘的時間，大型專案的 AOT 編譯則可能需要多上許多的時間。 未來的 ASP.NET Core 版本正在開發減少 AOT 編譯建置時間的方法。

經過 AOT 編譯的 Blazor WebAssembly 應用程式，其大小一般會大於編譯至 .NET IL 的應用程式所具有的大小：

  • 雖然大小差異取決於應用程式，但大部分經過 AOT 編譯的應用程式都會有其 IL 編譯版本兩倍左右的大小。 這表示使用 AOT 編譯是拿載入階段的效能換得執行階段的效能。 此權衡結果是否值得您使用 AOT 編譯取決於您的應用程式。 一般來說，需要 CPU 密集運算的 Blazor WebAssembly 應用程式可從 AOT 編譯獲得做大的好處。

  • 經過 AOT 編譯的應用程式之所以會比較大，是兩個情況所造成的：

    • 需要更多程式碼才能在原生 WebAssembly 中呈現高階 .NET IL 指令。
    • 在發行應用程式時，AOT 不會修剪受控 DLL。 Blazor 需要 DLL 以供反映中繼資料使用，以及支援特定的 .NET 執行階段功能。 用戶端上需要 DLL 會增加下載大小，但可提供更相容的 .NET 體驗。

注意

關於 Mono/WebAssembly MSBuild 屬性和目標，請參閱 WasmApp.Common.targets (dotnet/runtime GitHub 存放庫)。 常見 MSBuild 屬性的官方文件是按照 Document blazor msbuild configuration options (dotnet/docs #27395)進行規劃的。

在預先 (AOT) 編譯後修剪 .NET IL

WasmStripILAfterAOT MSBuild 選項可讓您在執行 WebAssembly 的 AOT 編譯後移除已編譯方法的 .NET 中繼語言 (IL)，以減少 _framework 資料夾的大小。

在應用程式的專案檔中：

<PropertyGroup>
  <RunAOTCompilation>true</RunAOTCompilation>
  <WasmStripILAfterAOT>true</WasmStripILAfterAOT>
</PropertyGroup>

此設定會修剪大部分已編譯方法的 IL 程式碼，包括來自程式庫的方法和應用程式中的方法。 並非所有已編譯的方法都可加以修剪，因為 .NET 解譯器在執行階段仍需要某些方法。

若要回報修剪選項的問題，請在 dotnet/runtime GitHub 存放庫上提出問題。

若修剪屬性阻止您的應用程式正常執行，請將其停用：

<WasmStripILAfterAOT>false</WasmStripILAfterAOT>

某些行動裝置瀏覽器的堆積大小

建置在用戶端上執行，且以行動裝置瀏覽器 (尤其是 iOS 上的 Safari) 為目標的 Blazor 應用程式時，可能需要使用 MSBuild 屬性 EmccMaximumHeapSize 來減少應用程式的最大記憶體。 如需詳細資訊，請參閱裝載和部署 ASP.NET Core Blazor WebAssembly。

執行階段重新連結

Blazor WebAssembly 應用程式的其中一個最大部分是，使用者的瀏覽器首次存取應用程式時所必須下載的 WebAssembly 型 .NET 執行階段 (dotnet.wasm)。 重新連結 .NET WebAssembly 執行階段會修剪未使用的執行階段程式碼，進而改善下載速度。

要重新連結執行階段，就必須安裝 .NET WebAssembly 建置工具。 如需詳細資訊，請參閱 ASP.NET Core Blazor 的工具。

安裝 .NET WebAssembly 建置工具後，系統會在 Release 組態中有已發行的應用程式時自動執行執行階段重新連結。 在停用全球化時，大小會明顯縮減。 如需詳細資訊，請參閱 ASP.NET Core Blazor 全球化和當地語系化。

重要

執行階段重新連結會修剪類別執行個體的 JavaScript-invokable .NET 方法，除非方法有受到保護。 如需詳細資訊，請參閱在 ASP.NET Core Blazor 中從 JavaScript 函式呼叫 .NET 方法。

單指令多資料 (SIMD)

WebAssembly 單指令多資料 (SIMD) 可以使用單一指令，平行對多個資料片段執行作業，以改善向量化計算的輸送量。 SIMD 預設為啟用。

若要停用 SIMD，例如，以舊瀏覽器或行動裝置上不支援 SIMD 的瀏覽器為目標時，請將應用程式專案檔中的 <WasmEnableSIMD> 屬性設定為 false (.csproj)：

<PropertyGroup>
  <WasmEnableSIMD>false</WasmEnableSIMD>
</PropertyGroup>

如需詳細資訊，請參閱設定和裝載 .NET WebAssembly 應用程式：SIMD - 單指令多資料，並請注意，指導未指定版本且適用於最新的公開版本。

WebAssembly 單指令多資料 (SIMD) 可以使用單一指令，平行對多個資料片段執行作業，以改善向量化計算的輸送量。 SIMD 預設為停用。

若要啟用 SIMD，請在應用程式的專案檔 (.csproj) 中將 <WasmEnableSIMD> 屬性設定為 true：

<PropertyGroup>
  <WasmEnableSIMD>true</WasmEnableSIMD>
</PropertyGroup>

如需詳細資訊，請參閱設定和裝載 .NET WebAssembly 應用程式：SIMD - 單指令多資料，並請注意，指導未指定版本且適用於最新的公開版本。

例外狀況處理

預設會啟用例外狀況處理。 若要停用例外狀況處理，請在應用程式的專案檔 (.csproj) 中新增值為 false 的 <WasmEnableExceptionHandling> 屬性：

<PropertyGroup>
  <WasmEnableExceptionHandling>false</WasmEnableExceptionHandling>
</PropertyGroup>

若要啟用 WebAssembly 例外狀況處理，請在應用程式的專案檔 (.csproj) 中新增值為 true 的 <WasmEnableExceptionHandling> 屬性：

<PropertyGroup>
  <WasmEnableExceptionHandling>true</WasmEnableExceptionHandling>
</PropertyGroup>

其他資源