Хостинг и развертывание ASP.NET Core Blazor WebAssembly

В этой статье объясняется, как размещать и развертывать Blazor WebAssembly приложения.

При использовании модели хостинга Blazor WebAssembly:

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

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

Blazor WebAssembly Локальное обслуживание приложения для тестирования

Многие серверы с открытым исходным кодом и коммерческими HTTP-серверами могут обслуживать опубликованное Blazor WebAssembly приложение локально. Для простого HTTP-сервера командной строки рекомендуется использовать средство natemcmaster/dotnet-serve .NET.

Warning

Средство natemcmaster/dotnet-serve .NET не принадлежит Майкрософт и не распространяется ни на какое соглашение о поддержке или лицензию Майкрософт. Используйте осторожность при использовании стороннего средства, особенно для тестирования сценариев безопасности. Убедитесь, что средство соответствует официальным спецификациям и принимает рекомендации по обеспечению безопасности. Сохраните текущую версию средства, чтобы получить последние исправления ошибок.

Размещение поддомена и подприложения IIS

Для размещения поддомена не требуется специальная конфигурация приложения. Вам не нужно настраивать базовый путь приложения (тег <base> в wwwroot/index.html) для размещения приложения в поддомене.

Для размещения подприложений IIS действительно требуется установить базовый путь приложения. Дополнительные сведения и перекрестные ссылки на дополнительные рекомендации по размещению вложенных приложений IIS см. в разделе Host и развертывание ASP.NET Core Blazor.

Уменьшение максимального размера кучи для некоторых браузеров мобильных устройств

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

<EmccMaximumHeapSize>268435456</EmccMaximumHeapSize>

Дополнительные сведения о свойствах и целях MSBuild для Mono/WebAssembly см. в разделе (репозиторий на GitHub).

Формат упаковки Webcil для сборок .NET

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

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

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

Настройка способа загрузки загрузочных ресурсов

Настройте способ загрузки загрузочных ресурсов с помощью API loadBootResource. Дополнительные сведения см. в разделе ASP.NET Core Blazor startup.

Compression

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

• Brotli (высший уровень)
• Gzip

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

• Сведения о конфигурации сжатия IIS web.config см. в разделе IIS: сжатие Brotli и Gzip.
• При размещении на статических сервисах хостинга, которые не поддерживают переговоры о содержимом для статически сжатых файлов, рассмотрите возможность настройки приложения для извлечения и декодирования сжатых файлов Brotli.

Получите декодатор JavaScript Brotli из репозитория google/brotli GitHub. Сокращенный файл декодера называется decode.min.js и находится в папке js репозитория.

Note

Если сокращенная версия скрипта decode.js (decode.min.js) не работает, попробуйте вместо нее использовать не сокращенную версию (decode.js).

обновите приложение для использования декодера.

В файле wwwroot/index.html установите для autostart значение false в теге Blazor элемента <script>:

<script src="_framework/blazor.webassembly.js" autostart="false"></script>

После тега Blazor<script> и перед закрывающим тегом </body> добавьте следующий блок JavaScript-кода <script>. Следующая функция вызывает fetch с cache: 'no-cache' для обновления кэша браузера.

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:

<script type="module">
  import { BrotliDecode } from './decode.min.js';
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      if (type !== 'dotnetjs' && location.hostname !== 'localhost' && type !== 'configuration') {
        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>

Дополнительные сведения о загрузке загрузочных ресурсов см. в разделе ASP.NET Core Blazor startup.

Чтобы отключить сжатие, добавьте свойство CompressionEnabled MSBuild в файл проекта приложения и задайте для него значение false.

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

Свойство CompressionEnabled можно передать в команду dotnet publish с помощью следующего синтаксиса в командной оболочке.

dotnet publish -p:CompressionEnabled=false

Переписывание URL-адресов для правильной маршрутизации

Запросы маршрутизации для компонентов страниц в Blazor WebAssembly приложении не так просто, как запросы маршрутизации в Blazor Server приложении. Рассмотрим сценарий с приложением Blazor WebAssembly с двумя компонентами:

• Main.razor: загружается в корне приложения и содержит ссылку на About компонент (href="About").
• About.razor: компонент About.

При запросе документа приложения по умолчанию в адресной строке браузера (например, https://www.contoso.com/):

1. Браузер отправляет запрос.
2. Возвращается страница по умолчанию; обычно это index.html.
3. Страница index.html обеспечивает начальную загрузку приложения.
4. Router компонент загружается, а RazorMain компонент отрисовывается.

На странице Main возможность выбора ссылки на компонент About доступна на клиентском компьютере, так как маршрутизатор Blazor не разрешает браузеру сделать запрос в Интернете к www.contoso.com для About и сам обрабатывает отображенный компонент About. Все запросы внутренних конечных точек в приложении работают одинаково: запросы через браузер не активируют запросы к размещенным на сервере ресурсам в Интернете. Маршрутизатор обрабатывает запросы внутренним образом.

Если запрос www.contoso.com/About сделан с помощью адресной строки браузера, он завершится ошибкой. Такой ресурс не существует на интернет-узле приложения, поэтому возвращается ответ 404 — Not Found (не найдено).

Поскольку браузеры выполняют запросы к интернет-узлам для клиентских страниц, веб-серверам и службам хостинга необходимо переписывать все запросы к ресурсам, которые физически отсутствуют на сервере, на страницу index.html. Когда возвращается index.html, маршрутизатор Blazor приложения принимает управление и отвечает нужным ресурсом.

При развертывании на сервере IIS можно использовать модуль переопределения URL-адресов с опубликованным файлом web.config приложения. Дополнительные сведения см. в статье Host и развертывание ASP.NET Core Blazor WebAssembly с помощью IIS.

Автономное развертывание

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

Автономные ресурсы развертывания публикуются в папке /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot или bin/Release/{TARGET FRAMEWORK}/browser-wasm/publish, где {TARGET FRAMEWORK} является целевой платформой.

Публикация без HTML-документа

Если приложение не использует HTML-документ, созданный в рамках процесса сборки и публикации .NET, негде разместить карту импорта. Например, этот сценарий возникает при публикации автономного Blazor приложения для использования приложением JavaScript/SPA через Blazor пользовательский элемент.

Чтобы избежать проблем с загрузкой ресурсов приложения на клиенте, отключите фингерпринтинг для и blazor.webassembly.js путем удаления свойства dotnet.js MSBuild (или установите его в значение <OverrideHtmlAssetPlaceholders>) в файле проекта приложения (false).

Служба приложений Azure

приложения Blazor WebAssembly можно развернуть в службах приложений Azure в Windows, где приложение размещается на IIS.

Развертывание автономного приложения Blazor WebAssembly в Служба приложений Azure для Linux в настоящее время не поддерживается. Мы рекомендуем разместить автономное приложение Blazor WebAssembly с помощью Статические веб-приложения Azure, которое поддерживает этот сценарий.

Автономная работа с Docker

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

Чтобы разместить приложение в Docker, выполните следующие действия.

• Выберите контейнер Docker с поддержкой веб-сервера, например Nginx или Apache.
• Скопируйте активы папки publish в папку, определенную на веб-сервере для размещения статических файлов.
• При необходимости примените дополнительную конфигурацию для обслуживания Blazor WebAssembly приложения.

Инструкции по настройке см. в следующих ресурсах:

• Статьи Nginx или Apache
• Документация по Docker

Значения конфигурации хоста

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

Корень содержимого

Аргумент --contentroot задает абсолютный путь к каталогу, где находятся файлы содержимого приложения (корневой каталог содержимого). В следующих примерах /content-root-path — это путь к корневому каталогу содержимого приложения.

• Передайте этот аргумент при локальном запуске приложения в командной строке. Перейдите в каталог приложения и выполните следующую команду:

  dotnet watch --contentroot=/content-root-path
  

• Добавьте запись в файл приложения launchSettings.json в профиле IIS Express. Этот параметр используется при запуске приложения с отладчиком Visual Studio и из командной строки с dotnet watch (или dotnet run).

  "commandLineArgs": "--contentroot=/content-root-path"
  

• В Visual Studio укажите аргумент в Properties>Debug>Application arguments. При задании аргумента на странице свойств Visual Studio аргумент добавляется в файл launchSettings.json.

  --contentroot=/content-root-path
  

Базовый путь

Аргумент --pathbase задает базовый путь приложения для локального выполнения с некорневым относительным путем URL (в теге <base> переменная href задана с путем, отличным от / для промежуточной и рабочей среды). В следующих примерах /relative-URL-path — это базовый путь приложения. Дополнительные сведения см. в разделе ASP.NET Core Blazor базовый путь приложения.

Important

В отличие от пути, заданного через href в теге <base>, не ставьте завершающую косую черту (/) когда передаёте значение аргумента --pathbase. Если основной путь приложения задан в теге <base> как <base href="/CoolApp/"> (включая косую черту в конце), передайте значение аргумента командной строки как --pathbase=/CoolApp (без косой черты в конце).

• Передайте этот аргумент при локальном запуске приложения в командной строке. Перейдите в каталог приложения и выполните следующую команду:

  dotnet watch --pathbase=/relative-URL-path
  

• Добавьте запись в файл приложения launchSettings.json в профиле IIS Express. Этот параметр используется при запуске приложения с отладчиком Visual Studio и из командной строки с dotnet watch (или dotnet run).

  "commandLineArgs": "--pathbase=/relative-URL-path"
  

• В Visual Studio укажите аргумент в Properties>Debug>Application arguments. Задание аргумента на странице свойств Visual Studio добавляет аргумент в файл launchSettings.json.

  --pathbase=/relative-URL-path
  

Дополнительные сведения см. в разделе ASP.NET Core Blazor базовый путь приложения.

URLs

Аргумент --urls задает IP-адреса или адреса узлов с портами и протоколами для прослушивания запросов.

• Передайте этот аргумент при локальном запуске приложения в командной строке. Перейдите в каталог приложения и выполните следующую команду:

  dotnet watch --urls=http://127.0.0.1:0
  

• Добавьте запись в файл приложения launchSettings.json в профиле IIS Express. Этот параметр используется при запуске приложения с отладчиком Visual Studio и из командной строки с dotnet watch (или dotnet run).

  "commandLineArgs": "--urls=http://127.0.0.1:0"
  

• В Visual Studio укажите аргумент в Properties>Debug>Application arguments. Задание аргумента на странице свойств Visual Studio добавляет аргумент в файл launchSettings.json.

  --urls=http://127.0.0.1:0
  

Настройка средства обрезки

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

Нарушение данных перед развертыванием

Обычно при развертывании:

• Заменяются только измененные файлы, что обычно приводит к ускорению развертывания.
• Существующие файлы, не являющиеся частью нового развертывания, остаются на месте для использования в новом развертывании.

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

Если вы определили, что очистка до развертывания всегда требуется при использовании конвейера сборки и развертывания DevOps, можно временно добавить шаг в конвейер сборки, чтобы удалить прежнее развертывание для каждого нового развертывания, пока не будет устранена точная причина повреждения.