托管和部署 ASP.NET Core Blazor WebAssembly

本文涉及的部署方案是这样的：Blazor 应用放置在静态托管 Web 服务器或服务上，.NET 不用于为 Blazor 应用提供服务。 此策略在 IIS、Azure 服务、Apache、Nginx 和 GitHub Pages 的此节点中的“ 独立部署 ”部分和其他文章中介绍。

支持以下部署策略：

• Blazor 应用由 ASP.NET Core 应用提供服务。 使用 ASP.NET Core 进行托管部署部分中介绍了此策略。
• Blazor 应用位于静态托管 Web 服务器或服务中，其中未使用 .NET 对 Blazor 应用提供服务。 独立部署部分介绍了此策略，包括有关将 Blazor WebAssembly 应用作为 IIS 子应用托管的信息。
• ASP.NET Core 应用托管多个 Blazor WebAssembly 应用。 有关详细信息，请参阅多个托管的 ASP.NET Core Blazor WebAssembly 应用。

当生成在客户端上运行的 Blazor 应用（.Client 的 Blazor Web App 项目或独立的 Blazor WebAssembly 应用）并面向移动设备浏览器（尤其是 iOS 上的 Safari）时，可能需要使用 MSBuild 属性 EmccMaximumHeapSize 减少应用的最大内存。 默认值为 2,147,483,648 字节，该值可能太大，如果应用尝试分配更多内存，而浏览器无法授予，则可能会导致应用崩溃。 以下示例将 Program 文件中的值设置为 268,435,456 字节：

生成面向移动设备浏览器（尤其是 iOS 上的 Safari）的 Blazor WebAssembly 应用时，可能需要使用 MSBuild 属性 EmccMaximumHeapSize 减少应用的最大内存。 默认值为 2,147,483,648 字节，该值可能太大，如果应用尝试分配更多内存，而浏览器无法授予，则可能会导致应用崩溃。 以下示例将 Program 文件中的值设置为 268,435,456 字节：

.NET 程序集的 Webcil 打包格式

Webcil 是一种适用于 .NET 程序集的 Web 友好打包格式，旨在支持在限制性网络环境中使用 Blazor WebAssembly。 Webcil 文件使用标准 WebAssembly 包装器，其中程序集部署为使用标准 .wasm 文件扩展名的 WebAssembly 文件。

发布 Blazor WebAssembly 应用时，Webcil 是默认打包格式。 若要禁用 Webcil，请在应用的项目文件中设置以下 MS Build 属性：

<PropertyGroup>
  <WasmEnableWebcil>false</WasmEnableWebcil>
</PropertyGroup>

Blazor 依赖于主机提供适当的压缩文件。 托管 Blazor WebAssembly 独立应用时，可能需要额外的工作来确保提供静态压缩文件：

Blazor 依赖于主机提供适当的压缩文件。 使用 ASP.NET Core 托管的 项目时，主机项目能够执行内容协商并提供静态压缩文件。 托管 Blazor WebAssembly 独立应用时，可能需要额外的工作来确保提供静态压缩文件：

Blazor Web App:

<script type="module">
  import { BrotliDecode } from './decode.min.js';
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        if (type !== 'dotnetjs' && ___location.hostname !== 'localhost' && type !== 'configuration' && type !== 'manifest') {
          return (async function () {
            const response = await fetch(defaultUri + '.br', { cache: 'no-cache' });
            if (!response.ok) {
              throw new Error(response.statusText);
            }
            const originalResponseBuffer = await response.arrayBuffer();
            const originalResponseArray = new Int8Array(originalResponseBuffer);
            const decompressedResponseArray = BrotliDecode(originalResponseArray);
            const contentType = type === 
              'dotnetwasm' ? 'application/wasm' : 'application/octet-stream';
            return new Response(decompressedResponseArray, 
              { headers: { 'content-type': contentType } });
          })();
        }
      }
    }
  });
</script>

独立 Blazor WebAssembly：

若要禁用压缩，请将 CompressionEnabled MSBuild 属性添加到应用的项目文件，并将值设置为 false：

<PropertyGroup>
  <CompressionEnabled>false</CompressionEnabled>
</PropertyGroup>

可在命令行界面中使用以下语法将 CompressionEnabled 属性传递给 dotnet publish 命令：

dotnet publish -p:CompressionEnabled=false

若要禁用压缩，请将 BlazorEnableCompression MSBuild 属性添加到应用的项目文件，并将值设置为 false：

<PropertyGroup>
  <BlazorEnableCompression>false</BlazorEnableCompression>
</PropertyGroup>

可在命令行界面中使用以下语法将 BlazorEnableCompression 属性传递给 dotnet publish 命令：

dotnet publish -p:BlazorEnableCompression=false

使用 ASP.NET Core 进行托管部署

托管部署通过在 Web 服务器上运行的 ASP.NET Core 应用为浏览器提供 Blazor WebAssembly 应用。

客户端 Blazor WebAssembly 应用与服务器应用的其他任何静态 Web 资产一起发布到服务器应用的 /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot 文件夹。 这两个应用一起部署。 需要能够托管 ASP.NET Core 应用的 Web 服务器。 对于托管部署，Visual Studio 会在选择 Blazor WebAssembly 选项（使用 命令时为 blazorwasm）的情况下，包含 dotnet new 应用项目模板（使用 Hosted 命令时为 -ho|--hosted 模板）。

如需了解更多信息，请参阅以下文章：

• ASP.NET Core 应用托管和部署：托管和部署 ASP.NET Core
• Azure 应用服务部署：通过 Visual Studio 将 ASP.NET Core 应用发布到 Azure
• Blazor 项目模板：ASP.NET Core Blazor 项目结构

针对特定平台的依赖于框架的可执行文件的托管部署

若要将托管的 Blazor WebAssembly 应用部署为针对特定平台的依赖于框架的可执行文件（非自包含），请根据所使用的工具利用以下指南。

Visual Studio

为生成的发布配置文件 () 配置了.pubxml部署。 确认 Server 项目的发布配置文件包含设置为 <SelfContained> 的 false MSBuild 属性。

在 .pubxml 项目的 Server 文件夹中的 Properties 发布配置文件中：

<SelfContained>false</SelfContained>

使用“发布”UI 的“设置”区域中的“目标运行时”设置来设置运行时标识符 (RID)，这会生成发布配置文件中的 MSBuild 属性：

<RuntimeIdentifier>{RID}</RuntimeIdentifier>

在上述配置中，{RID} 占位符是运行时标识符 (RID)。

在“发布”配置中发布 Server 项目。

.NET 命令行界面 (CLI)

通过将 MSBuild 属性置于 <SelfContained> 项目的项目文件中的 <PropertyGroup> 中并将其设置为 Server，来配置false部署：

<SelfContained>false</SelfContained>

使用以下任一方法设置运行时标识符 (RID)：

• 选项 1：在 <PropertyGroup> 项目的项目文件中的 Server 中设置 RID：

  <RuntimeIdentifier>{RID}</RuntimeIdentifier>
  

  在上述配置中，{RID} 占位符是运行时标识符 (RID)。

  在 Server 项目的“发布”配置中发布应用：

  dotnet publish -c Release
  

• 选项 2：将 dotnet publish 命令中的 RID 作为 MSBuild 属性 (/p:RuntimeIdentifier) 传递，而不是使用 -r|--runtime 选项：

  dotnet publish -c Release /p:RuntimeIdentifier={RID}
  

  在上述命令中，{RID} 占位符是运行时标识符 (RID)。

如需了解更多信息，请参阅以下文章：

• .NET 应用程序发布概述
• 托管和部署 ASP.NET Core

配置裁边器

Blazor 对每个发布版本执行中间语言 (IL) 剪裁，以从输出程序集中删除不必要的 IL。 有关详细信息，请参阅配置适用于 ASP.NET Core Blazor 的裁边器。

配置链接器

Blazor 对每个发布版本执行中间语言 (IL) 链接，以从输出程序集中删除不必要的 IL。 有关详细信息，请参阅为 ASP.NET Core Blazor 配置链接器。

更改 DLL 文件的文件扩展名

本部分适用于 .NET 5 到 .NET 7。 在 .NET 8 或更高版本中，.NET 程序集使用 Webcil 文件格式部署为 WebAssembly 文件（.wasm）。

如果防火墙、防病毒程序或网络安全设备阻止了应用的动态链接库 (DLL) 文件 (.dll) 的传输，你可以按照本部分中的指导，更改应用的已发布 DLL 文件的文件扩展名。

更改应用的 DLL 文件的文件扩展名可能无法解决问题，因为许多安全系统会扫描应用文件的内容，而不仅仅是检查文件扩展名。

若要在阻止下载和执行 DLL 文件的环境中使用更可靠的方法，请采用以下方法之一：

• 使用 .NET 8 或更高版本，它使用 Webcil 文件格式将 .NET 程序集打包为 WebAssembly 文件（.wasm）。 有关详细信息，请参阅本文的 .NET 8 或更高版本中的 .NET 程序集的 Webcil 打包格式 部分。
• 在 .NET 6 或更高版本中，使用 自定义部署布局。

有第三方的方法来处理这个问题。 有关详细信息，请参阅 Awesome Blazor 中的资源。

发布应用后，使用 shell 脚本或 DevOps 生成管道将 .dll 文件重命名，以在应用的已发布输出的目录中使用其他文件扩展名。

在以下示例中：

• PowerShell (PS) 用于更新文件扩展名。
• .dll 文件将重命名，以使用命令行中的 .bin 文件扩展名。
• 已发布的Blazor启动清单中列出的文件，其文件扩展名为.dll，将被更新为.bin文件扩展名。
• 如果服务辅助角色资产也正在使用中，PowerShell 命令会将 .dll 文件中列出的 service-worker-assets.js 文件更新为 .bin 文件扩展名。

若要使用不同于 .bin 的文件扩展名，请在以下命令将 .bin 替换为所需的文件扩展名。

dir {PATH} | rename-item -NewName { $_.name -replace ".dll\b",".bin" }

((Get-Content {PATH}\blazor.boot.json -Raw) -replace '.dll"','.bin"') | Set-Content {PATH}\blazor.boot.json

((Get-Content {PATH}\service-worker-assets.js -Raw) -replace '.dll"','.bin"') | Set-Content {PATH}\service-worker-assets.js

for f in {PATH}/*; do mv "$f" "`echo $f | sed -e 's/\.dll/.bin/g'`"; done

sed -i 's/\.dll"/.bin"/g' {PATH}/blazor.boot.json

sed -i 's/\.dll"/.bin"/g' {PATH}/service-worker-assets.js

若要解决压缩 blazor.boot.json 文件的问题，请采用以下任一方法：

• 重新压缩更新 blazor.boot.json 的文件，生成新 blazor.boot.json.gz 文件和 blazor.boot.json.br 文件。 （推荐）
• 删除压缩的 blazor.boot.json.gz 和 blazor.boot.json.br 文件。 （使用此方法禁用压缩。

对于 渐进式 Web 应用（PWA）的压缩 service-worker-assets.js 文件，请采用以下任一方法：

• 重新压缩更新 service-worker-assets.js 的文件，生成新 service-worker-assets.js.br 文件和 service-worker-assets.js.gz 文件。 （推荐）
• 删除压缩的 service-worker-assets.js.gz 和 service-worker-assets.js.br 文件。 （使用此方法禁用压缩。

若要在 .NET 6/7 中自动执行 Windows 上的扩展更改，以下方法使用放置在项目的根目录下的 PowerShell 脚本。 以下脚本会禁用压缩功能，如果应用是渐进式 Web 应用（PWA），希望重新压缩 blazor.boot.json 文件和 service-worker-assets.js 文件时，可在此基础上进行进一步修改。 当脚本执行时，文件夹的路径publish会传递给脚本。

ChangeDLLExtensions.ps1::

param([string]$filepath)
dir $filepath\wwwroot\_framework | rename-item -NewName { $_.name -replace ".dll\b",".bin" }
((Get-Content $filepath\wwwroot\_framework\blazor.boot.json -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\wwwroot\_framework\blazor.boot.json
Remove-Item $filepath\wwwroot\_framework\blazor.boot.json.gz
Remove-Item $filepath\wwwroot\_framework\blazor.boot.json.br

如果服务工作线程资源也在使用，因为该应用是 渐进式 Web 应用（PWA），请运行以下命令：

((Get-Content $filepath\wwwroot\service-worker-assets.js -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\wwwroot\service-worker-assets.js
Remove-Item $filepath\wwwroot\service-worker-assets.js.gz
Remove-Item $filepath\wwwroot\service-worker-assets.js.br

在项目文件中，在为 Release 配置发布应用后执行脚本：

<Target Name="ChangeDLLFileExtensions" AfterTargets="AfterPublish" Condition="'$(Configuration)'=='Release'">
  <Exec Command="powershell.exe -command &quot;&amp; {.\ChangeDLLExtensions.ps1 '$(SolutionDir)'}&quot;" />
</Target>

发布应用后，手动重新压缩 blazor.boot.json， service-worker-assets.js 如果使用，则重新启用压缩。

通常，应用的服务器需要静态资产配置才能提供具有更新扩展名的文件。 对于由 IIS 托管的应用，请在自定义 <mimeMap> 文件的静态内容部分 (<staticContent>) 为新文件扩展名添加 MIME 映射条目 (web.config)。 以下示例假定文件扩展名从 .dll 更改为 .bin：

<staticContent>
  ...
  <mimeMap fileExtension=".bin" mimeType="application/octet-stream" />
  ...
</staticContent>

如果正在进行压缩，请包含压缩文件的更新：

<mimeMap fileExtension=".bin.br" mimeType="application/octet-stream" />
<mimeMap fileExtension=".bin.gz" mimeType="application/octet-stream" />

删除 .dll 文件扩展名的条目：

- <mimeMap fileExtension=".dll" mimeType="application/octet-stream" />

如果正在进行.dll，请删除压缩后的 文件的条目：

- <mimeMap fileExtension=".dll.br" mimeType="application/octet-stream" />
- <mimeMap fileExtension=".dll.gz" mimeType="application/octet-stream" />

有关自定义web.config文件的详细信息，请参阅自定义web.config部分的用法。