Размещение и развертывание ASP.NET Core Blazor WebAssembly

Эта статья относится к сценарию развертывания, в котором Blazor приложение размещается на статическом веб-сервере или службе размещения, .NET не используется для обслуживания Blazor приложения. Эта стратегия рассматривается в разделе изолированного развертывания и других статьях этого раздела для служб IIS, служб Azure, Apache, Nginx и GitHub Pages.

Поддерживаются следующие стратегии развертывания:

• Приложение Blazor обслуживается приложением ASP.NET Core. Эта стратегия описана в разделе Размещенное развертывание с использованием ASP.NET Core.
• Приложение Blazor помещается на статическом веб-сервере или службе, где .NET не используется, чтобы обслуживать приложение Blazor. Эта стратегия рассматривается в разделе Автономное развертывание, где приводятся сведения о размещении приложения Blazor WebAssembly в качестве дочернего приложения IIS.
• В приложении ASP.NET Core размещено несколько приложений Blazor WebAssembly. Для получения дополнительной информации см. статью Несколько размещённых приложений ASP.NET CoreBlazor WebAssembly.

При создании Blazor приложения, работающего .Client на клиенте (Blazor Web App проекте или автономном Blazor WebAssembly приложении) и предназначенного для браузеров мобильных устройств, особенно Safari на iOS, может потребоваться снизить максимальный объём памяти приложения с помощью свойства EmccMaximumHeapSize MSBuild. Значение по умолчанию — 2 147 483 648 байт, которое может быть слишком большим и привести к сбою приложения, если оно попытается выделить больше памяти, а браузер откажется её предоставить. В следующем примере значение устанавливается на 268 435 456 байт в файле Program:

При создании приложения, предназначенного для браузеров мобильных устройств, особенно Safari на iOS, возможно, потребуется уменьшить максимальную память для приложения с использованием свойства MSBuild Blazor WebAssembly. Значение по умолчанию — 2 147 483 648 байт, которое может быть слишком большим и привести к сбою приложения, если оно попытается выделить больше памяти, а браузер откажется её предоставить. В следующем примере значение устанавливается на 268 435 456 байт в файле Program:

Webcil — это удобный для интернета формат упаковки сборок .NET, предназначенный для использования Blazor WebAssembly в ограничивающих сетевых средах. Файлы Webcil используют стандартную оболочку WebAssembly, где сборки развертываются как файлы WebAssembly, использующие стандартное .wasm расширение файла.

Webcil — это формат упаковки по умолчанию при публикации Blazor WebAssembly приложения. Чтобы отключить использование Webcil, задайте в файле проекта приложения следующее свойство MSBuild:

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

Blazor полагается на хост для предоставления соответствующих сжатых файлов. При размещении автономного приложения Blazor WebAssembly, возможно, потребуется реализовать дополнительные действия для обслуживания статически сжатых файлов.

Blazor полагается на хост для предоставления соответствующих сжатых файлов. При использовании проекта ASP.NET Core Hosted, хост-проект способен выполнять согласование содержания и предоставлять статически сжатые файлы. При размещении автономного приложения 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

Размещенное развертывание обслуживает приложение Blazor WebAssembly для браузеров из приложения ASP.NET Core, выполняющегося на веб-сервере.

Клиентское приложение Blazor WebAssembly будет опубликовано в папку /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot серверного приложения вместе со статическими веб-ресурсами серверного приложения. Оба приложения развертываются вместе. Веб-сервер, позволяющий размещать приложения ASP.NET Core, является обязательным. Для размещаемого развертывания Visual Studio включает шаблон проекта Blazor WebAssembly Приложение (шаблон blazorwasm, когда используется команда dotnet new) с выбранной опцией Hosted (-ho|--hosted, когда используется команда dotnet new).

Дополнительные сведения см. в следующих статьях:

• Дополнительные сведения о размещении приложения ASP.NET Core и его развертывании см. в разделе Размещение и развертывание приложения ASP.NET Core.
• Развертывание в Службе приложений Azure: Публикация приложения ASP.NET Core в Azure с помощью Visual Studio
• Шаблоны проектов Blazor: структура проектов ASP.NET Core Blazor

Чтобы развернуть размещенное приложение Blazor WebAssembly в качестве исполняемого файла, зависящего от среды выполнения для определенной платформы (не автономной), используйте следующие рекомендации на основе используемых инструментов.

Автономное развёртывание настроено для сгенерированного профиля публикации.pubxml. Убедитесь, что профиль публикации проекта Server содержит свойство MSBuild <SelfContained>, которому присвоено значение false.

В файле профиля публикации .pubxml в папке Server проекта Properties выполните следующие действия:

<SelfContained>false</SelfContained>

Задайте Идентификатор среды выполнения (RID) с помощью параметра Целевая среда выполнения в области Параметры пользовательского интерфейса Публикация, который создает свойство MSBuild <RuntimeIdentifier> в профиле публикации:

<RuntimeIdentifier>{RID}</RuntimeIdentifier>

В предыдущей конфигурации заполнитель {RID} представляет собой Идентификатор среды выполнения (RID).

Опубликуйте проект Server в конфигурации Выпуск.

Настройте автономное развертывание, указав свойство MSBuild <SelfContained> в секции <PropertyGroup> файла проекта Server, установив его значение на false:

<SelfContained>false</SelfContained>

Задайте Идентификатор среды выполнения (RID), используя любой из указанных ниже подходов:

• Вариант 1. Задайте RID в разделе <PropertyGroup> в файле проекта Server:

  <RuntimeIdentifier>{RID}</RuntimeIdentifier>
  

  В предыдущей конфигурации заполнитель {RID} представляет собой Идентификатор среды выполнения (RID).

  Опубликуйте приложение в конфигурации Release из проекта Server.

  dotnet publish -c Release
  

• Вариант 2: Передайте RID в команде dotnet publish в качестве свойства MSBuild (/p:RuntimeIdentifier), а не с параметром -r|--runtime:

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

  В предыдущей команде заполнитель {RID} представляет собой Идентификатор среды выполнения (RID).

Дополнительные сведения см. в следующих статьях:

• Общие сведения о публикации приложений .NET
• Размещение и развертывание ASP.NET Core

Blazor выполняет обрезку промежуточного языка (IL) в каждой сборке Release, чтобы удалить ненужный код IL из выходных сборок. Дополнительные сведения см. в статье Настройка средства обрезки для ASP.NET Core Blazor.

Blazor выполняет связывание промежуточного языка (IL) в каждой сборке Release, чтобы удалить ненужные части кода IL из выходных сборок. Для получения дополнительной информации см. Настройка компоновщика для ASP.NET Core Blazor.

Этот раздел относится к ASP.NET Core 6.x и 7.x. В ASP.NET Core в .NET 8 или более поздней версии сборки .NET развертываются как файлы WebAssembly (.wasm) с помощью формата файла Webcil. В ASP.NET Core в .NET 8 или более поздней версии этот раздел применяется только в том случае, если формат файла Webcil отключен в файле проекта приложения.

Если брандмауэр, антивирусная программа или сетевое устройство безопасности блокирует передачу файлов библиотеки динамической компоновки (DLL) приложения (.dll), вы можете следовать инструкциям в этом разделе, чтобы изменить расширения имен файлов опубликованных DLL-файлов приложения.

После публикации приложения используйте скрипт оболочки или конвейер сборки DevOps для переименования .dll-файлов для использования другого расширения файла в каталоге опубликованных выходных данных приложения.

В следующих примерах:

• Для обновления расширений файлов используется PowerShell (PS).
• Файлы .dll переименовываются с использованием расширения имени файла .bin из командной строки.
• Файлы, перечисленные в опубликованном Blazor манифесте загрузки с расширением .dll файла, обновляются до .bin расширения файла.
• Если также используются ресурсы service worker, команда PowerShell обновляет файлы .dll, перечисленные в файле service-worker-assets.js, изменяя расширение их имени на .bin.

Чтобы использовать расширение файла, отличное от .bin, замените .bin в приведенных ниже командах нужным расширением файла.

В Windows:

dir {PATH} | rename-item -NewName { $_.name -replace ".dll\b",".bin" }
((Get-Content {PATH}\dotnet.boot.js -Raw) -replace '.dll"','.bin"') | Set-Content {PATH}\dotnet.boot.js

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

В приведенной выше команде заполнитель {PATH} представляет собой путь к опубликованной папке _framework (например, .\bin\Release\{TFM}\browser-wasm\publish\wwwroot\_framework из корневой папки проекта, где заполнитель {TFM} является идентификатором целевой платформы (TFM)).

Если рабочие ресурсы службы также используются, так как приложение является прогрессивным веб-приложением (PWA):

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

В предыдущей команде заполнитель {PATH} — это путь к опубликованному файлу service-worker-assets.js.

В Linux или macOS:

for f in {PATH}/*; do mv "$f" "`echo $f | sed -e 's/\.dll/.bin/g'`"; done
sed -i 's/\.dll"/.bin"/g' {PATH}/dotnet.boot.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

В предыдущей команде {PATH} заполнитель обозначает путь к опубликованной папке _framework (например, .\bin\Release\{TFM}\browser-wasm\publish\wwwroot\_framework от корневой папки проекта), где {TFM} заполнитель соответствует моникеру целевого фреймворка (TFM).

Если рабочие ресурсы службы также используются, так как приложение является прогрессивным веб-приложением (PWA):

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

В предыдущей команде заполнитель {PATH} — это путь к опубликованному файлу service-worker-assets.js.

Для сжатых файлов dotnet.boot.js.gz и dotnet.boot.js.br используйте один из следующих подходов:

• Удалите сжатые файлы dotnet.boot.js.gz и dotnet.boot.js.br. Сжатие отключено с помощью этого подхода.
• Выполните повторное сжатие обновленного файла dotnet.boot.js.

Предыдущие рекомендации для сжатого файла dotnet.boot.js также применимы при использовании ресурсов служебного работника. Выполните удаление или повторное сжатие файлов service-worker-assets.js.br и service-worker-assets.js.gz. иначе проверка целостности файлов в браузере завершится ошибкой.

В следующем примере Windows для .NET 6 или более поздней версии используется сценарий PowerShell, размещенный в корне проекта. Следующий сценарий, который отключает сжатие, является основой для дальнейшего изменения, если вы хотите повторно сжать файл dotnet.boot.js. Передайте путь приложения и TFM в скрипт.

ChangeDLLExtensions.ps1::

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

Перекомпрессируйте dotnet.boot.js, чтобы снова включить сжатие.

Для сжатых файлов blazor.boot.json.gz и blazor.boot.json.br используйте один из следующих подходов:

• Удалите сжатые файлы blazor.boot.json.gz и blazor.boot.json.br. Сжатие отключено с помощью этого подхода.
• Выполните повторное сжатие обновленного файла blazor.boot.json.

Предыдущие рекомендации для сжатого файла blazor.boot.json также применимы при использовании ресурсов служебного работника. Выполните удаление или повторное сжатие файлов service-worker-assets.js.br и service-worker-assets.js.gz. иначе проверка целостности файлов в браузере завершится ошибкой.

В следующем примере Windows для .NET 6 до .NET 9 используется скрипт PowerShell, размещенный в корне проекта. Следующий сценарий, который отключает сжатие, является основой для дальнейшего изменения, если вы хотите повторно сжать файл blazor.boot.json. Передайте путь приложения и TFM в скрипт.

ChangeDLLExtensions.ps1::

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

Повторно сожмите blazor.boot.json, чтобы снова включить сжатие.

Если рабочие ресурсы службы также используются, так как приложение является прогрессивным веб-приложением (PWA), добавьте следующие команды:

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

Повторное сжатие service-worker-assets.js .

В файле проекта скрипт выполняется после публикации приложения для конфигурации Release:

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

Как правило, серверу приложения требуется настройка статического ресурса для обслуживания файлов с обновленным расширением. Для приложения, размещенного в IIS, добавьте запись карты MIME (<mimeMap>) для нового расширения файла в разделе статического содержимого (<staticContent>) в пользовательском файле 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».