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

В этой статье вы узнаете, как размещать и развертывать приложение Blazor WebAssembly с помощью ASP.NET Core, сетей доставки содержимого (CDN), файловых серверов и GitHub Pages.

При использовании модели размещения Blazor WebAssembly:

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

Размещение поддомена и поддомена IIS

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

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

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

<EmccMaximumHeapSize>268435456</EmccMaximumHeapSize>

Дополнительные сведения о свойствах и целевых объектах MSBuild Mono/WebAssembly см. в разделеWasmApp.Common.targets (dotnet/runtimeрепозиторий GitHub).

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

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

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

Сжатие

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

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

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

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

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

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

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

После Blazorтега <script> и перед закрывающим </body> тегом добавьте следующий блок кода <script> JavaScript.

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

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

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

dotnet publish -p:CompressionEnabled=false

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

dotnet publish -p:BlazorEnableCompression=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. Все запросы внутренних конечных точек в Blazor WebAssembly приложении работают так же: запросы не активируют запросы на основе браузера к размещенным на сервере ресурсам в Интернете. Маршрутизатор обрабатывает запросы внутренним образом.

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

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

При развертывании на сервере IIS можно использовать модуль переопределения URL-адресов с опубликованным файлом web.config приложения. Дополнительные сведения см. в описании IIS.

<SelfContained>false</SelfContained>

<RuntimeIdentifier>{RID}</RuntimeIdentifier>

<SelfContained>false</SelfContained>

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

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

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

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

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

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

Служба статических веб-приложений Azure

Используйте один из следующих подходов для развертывания Blazor WebAssembly приложения в Статические веб-приложения Azure:

• Развертывание из Visual Studio
• Развертывание из Visual Studio Code
• Развертывание из GitHub

Развертывание из Visual Studio

Чтобы развернуть из Visual Studio, создайте профиль публикации для Статические веб-приложения Azure:

1. Сохраните все несохраненные работы в проекте, так как в процессе может потребоваться перезапуск Visual Studio.

2. В пользовательском интерфейсе публикации Visual Studio выберите "Целевой>целевой объект> Azure>"Статические веб-приложения Azure чтобы создать профиль публикации.

3. Если компонент средств веб-заданий Azure для Visual Studio не установлен, появится запрос на установку компонента ASP.NET и веб-разработки. Следуйте инструкциям по установке средств с помощью установщика Visual Studio. Visual Studio закрывает и открывается автоматически при установке средств. После установки средств начните с первого шага, чтобы создать профиль публикации.

4. В конфигурации профиля публикации укажите имя подписки. Выберите существующий экземпляр или нажмите кнопку "Создать новый экземпляр". При создании нового экземпляра в пользовательском интерфейсе статического веб-приложения портал Azure задайте для источника сведений>о развертывании значение Other. Дождитесь завершения развертывания в портал Azure, прежде чем продолжить.

5. В конфигурации профиля публикации выберите экземпляр Статические веб-приложения Azure из группы ресурсов экземпляра. Нажмите кнопку "Готово ", чтобы создать профиль публикации. Если Visual Studio запрашивает установку интерфейса командной строки Статические веб-приложения (SWA), установите интерфейс командной строки, следуя инструкциям. Для интерфейса командной строки SWA требуется NPM/Node.js (Документация по Visual Studio).

После создания профиля публикации разверните приложение в Статические веб-приложения Azure экземпляре с помощью профиля публикации, нажав кнопку "Опубликовать".

Развертывание из Visual Studio Code

Сведения о развертывании из Visual Studio Code см. в кратком руководстве по созданию первого статического сайта с помощью Статические веб-приложения Azure.

Развертывание из GitHub

Сведения о развертывании из репозитория GitHub см. в руководстве по созданию статического веб-приложения с Blazor помощью Статические веб-приложения Azure.

IIS

IIS можно использовать как полнофункциональный статический файловый сервер для приложений Blazor. Чтобы настроить IIS для размещения Blazor, перейдите к разделу Развертывание статического веб-сайта на IIS.

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

web.config.

При публикации проекта Blazor создается файл web.config со следующей конфигурацией IIS:

• типы MIME
• Сжатие HTTP включено для следующих типов MIME:
  • application/octet-stream
  • application/wasm
• Устанавливаются правила переопределения URL-адресов:
  • Предоставление подкаталога для размещения статических ресурсов приложения (wwwroot/{PATH REQUESTED}).
  • Создание резервной маршрутизации для одностраничного приложения, которая позволяет перенаправлять запросы, относящиеся к нефайловым ресурсам, к документу приложения по умолчанию в папке статических ресурсов (wwwroot/index.html).

Использование пользовательского web.config

Чтобы использовать пользовательский файл web.config:

Если создание или преобразование пакета SDK web.config во время публикации либо не перемещает файл в опубликованные ресурсы в publish папке, либо изменяет настраиваемую конфигурацию в пользовательском web.config файле, используйте любой из следующих подходов, при необходимости, чтобы получить полный контроль над процессом:

• Если пакет SDK не создает файл, например в автономном приложении или в зависимости от того, какая версия пакета SDK используется и где {TARGET FRAMEWORK} заполнитель является целевой платформой, задайте <PublishIISAssets> для true свойства значение в файле проекта (.csproj).bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish/bin/Release/{TARGET FRAMEWORK}/publish/wwwroot Blazor WebAssembly Обычно для автономных приложений WebAssembly это единственный обязательный параметр для перемещения пользовательского web.config файла и предотвращения преобразования файла пакетом SDK.

  <PropertyGroup>
    <PublishIISAssets>true</PublishIISAssets>
  </PropertyGroup>
  

• Отключите преобразование пакета SDK web.config в файле проекта (.csproj):

  <PropertyGroup>
    <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
  </PropertyGroup>
  

• Добавьте пользовательский целевой объект в файл проекта (.csproj) для перемещения пользовательского web.config файла. В следующем примере пользовательский web.config файл помещается разработчиком в корне проекта. web.config Если файл находится в другом месте, укажите путь к файлу.SourceFiles В следующем примере указывается publish папка с $(PublishDir), но укажите путь к DestinationFolder пользовательскому расположению вывода.

  <Target Name="CopyWebConfig" AfterTargets="Publish">
    <Copy SourceFiles="web.config" DestinationFolder="$(PublishDir)" />
  </Target>
  

Установка модуля переопределения URL-адресов

Модуль переопределения URL-адресов нужен, чтобы переопределять URL-адреса. Модуль не устанавливается по умолчанию и недоступен для установки как компонент службы роли веб-сервера (IIS). Модуль необходимо скачать с веб-сайта IIS. Для его установки используйте установщик веб-платформы.

1. Локально перейдите на страницу скачивания модуля переопределения URL-адресов. В англоязычной версии выберите WebPI для скачивания установщика веб-платформы. Для других языков выберите подходящую архитектуру сервера (x86 или x64) для скачивания установщика.
2. Скопируйте установщик на сервер. Запустите установщик. Нажмите кнопку Установить и примите условия лицензионного соглашения. Перезагрузка сервера после завершения установки не требуется.

Настройка веб-сайта

Установите для веб сайта физический путь к папке приложения. Эта папка содержит следующее.

• Файл web.config, который используется службами IIS для настройки веб-сайта, включая необходимые правила перенаправления и типы содержимого файлов.
• Папку статических ресурсов приложения.

Размещение в качестве дочернего приложения IIS

Если автономное приложение размещено как дочернее приложение IIS, выполните одно из следующих действий:

• Отключите наследуемый обработчик модуля ASP.NET Core.

  Удалите обработчик в опубликованном файле web.config приложения Blazor, добавив раздел <handlers> в раздел <system.webServer> в файл:

  <handlers>
    <remove name="aspNetCore" />
  </handlers>
  

• Отключите наследование раздела <system.webServer> от корневого (родительского) приложения, используя <location> со значением false для inheritInChildApplications:

  <?xml version="1.0" encoding="utf-8"?>
  <configuration>
    <location path="." inheritInChildApplications="false">
      <system.webServer>
        <handlers>
          <add name="aspNetCore" ... />
        </handlers>
        <aspNetCore ... />
      </system.webServer>
    </location>
  </configuration>
  

  Примечание.

  Отключение наследования корневого (родительского) раздела <system.webServer> приложения является конфигурацией по умолчанию для опубликованных приложений с использованием пакета SDK для .NET.

Удаление обработчика или отключение наследования выполняется вместе с настройкой базового пути приложения. Задайте базовый путь приложения в файле index.html приложения как псевдоним IIS, используемый при настройке дочернего приложения в IIS.

Настройте базовый путь приложения, следуя инструкциям в статье "Узел" и разверните ASP.NET Core Blazor .

Алгоритмы сжатия Brotli и Gzip

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

В следующих сценариях, возможно, потребуется дополнительно настроить пример файла web.config:

• Спецификация приложения вызывает любой из следующих вариантов:
  • обслуживание сжатых файлов, которые не настраиваются в примере файла web.config;
  • обслуживание сжатых файлов, настроенных в примере файла web.config в несжатом формате.
• Конфигурация IIS сервера (например, applicationHost.config) предоставляет значения IIS по умолчанию на уровне сервера. Требуемая для приложения конфигурация IIS может отличаться от представленной в примере файла web.config. Это зависит от конфигурации на уровне сервера.

Дополнительные сведения о пользовательских web.config файлах см. в разделе "Использование пользовательского web.config ".

Устранение неполадок

Если получено сообщение 500 — Internal Server Error (внутренняя ошибка сервера), а диспетчер служб IIS возвращает ошибки при попытке получить доступ к конфигурации веб сайта, убедитесь, что установлен модуль переопределения URL-адресов. Если модуль не установлен, IIS не может проанализировать файл web.config. Это предотвращает загрузку конфигурации веб сайта диспетчером служб IIS и передачу статических файлов Blazor c веб-сайта.

Дополнительные сведения об устранении неполадок развертывания в службах IIS см. в разделе Устранение неполадок ASP.NET Core в Службе приложений Azure и IIS.

Хранилище Azure

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

Если служба BLOB-объектов настроена для размещения статических веб-сайтов в учетной записи хранения:

• Задайте для параметра Имя документа индекса значение index.html.
• Задайте для параметра Путь к документу с ошибкой значение index.html. Компоненты Razor и другие конечные точки, не являющиеся файлами, не имеют физических путей в статическом содержимом, хранящемся в службе BLOB-объектов. При получении запроса для одного из этих ресурсов, который должен обрабатываться маршрутизатором Blazor, ошибка 404 - Объект не найден, создаваемая службой BLOB-объектов, перенаправляет запрос, используя путь к документу с ошибкой. При этом возвращается большой двоичный объект index.html, и маршрутизатор Blazor загружает и обрабатывает путь.

Если файлы не загружаются во время выполнения из-за недопустимых типов MIME в заголовках файлов Content-Type, выполните одно из следующих действий:

• Настройте средства для установки правильных типов MIME (заголовков Content-Type) при развертывании файлов.

• Измените типы MIME (заголовки Content-Type) для файлов после развертывания приложения.

  В Обозревателе службы хранилища (портал Azure) для каждого файла сделайте следующее:

  1. Щелкните правой кнопкой мыши файл и выберите Свойства.
  2. Укажите значение для параметра ContentType и нажмите кнопку Сохранить.

Дополнительные сведения см. в руководстве по размещению статических веб-сайтов в службе хранилища Azure.

Nginx

Следующий файл nginx.conf упрощен для демонстрации того, как настроить Nginx для отправки файла index.html, когда не удается найти соответствующий файл на диске.

events { }
http {
    server {
        listen 80;

        location / {
            root      /usr/share/nginx/html;
            try_files $uri $uri/ /index.html =404;
        }
    }
}

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

http {
    server {
        ...

        location / {
            ...

            limit_req zone=one burst=60 nodelay;
        }
    }
}

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

Дополнительные сведения о конфигурации веб-сервера Nginx в рабочей среде см. в разделе Создание файлов конфигурации NGINX Plus и NGINX.

Apache

Чтобы развернуть приложение в Blazor WebAssembly Apache, выполните действия.

1. Поместите файл конфигурации Apache в /etc/httpd/conf.d/ каталог.

2. Поместите опубликованные ресурсы приложения (где {TARGET FRAMEWORK} заполнитель является целевой платформой) в /var/www/blazorapp каталог (/bin/Release/{TARGET FRAMEWORK}/publish/wwwrootрасположение, указанное DocumentRoot в файле конфигурации).

3. Перезапустите службу Apache.

Дополнительные сведения см. в разделах mod_mime и mod_deflate.

Страницы GitHub

Действие GitHub Actions по умолчанию, которое развертывает страницы и пропускает развертывание папок, начинающихся с символа подчеркивания, например, папки _framework. Чтобы развернуть папки, начинающиеся с символа подчеркивания, добавьте пустой файл .nojekyll в ветвь Git.

Git обрабатывает файлы JavaScript (JS), например blazor.webassembly.js, как текстовые и преобразуют окончание строки из CRLF в LF в конвейере развертывания. Эти изменения в файлах JS создают хэши файлов, которые отличаются от того, что Blazor отправляет клиенту в файле blazor.boot.json. Несоответствия приводят к сбоям проверки целостности на клиенте. Одним из подходов к решению этой проблемы является добавление файла .gitattributes со строкой *.js binary перед добавлением ресурсов приложения в ветвь Git. Строка *.js binary настраивает Git для обработки файлов JS как двоичных файлов, что позволяет избежать обработки файлов в конвейере развертывания. Хэши необработанных файлов соответствуют записям в файле blazor.boot.json, а проверки целостности на стороне клиента выполняются успешно. Дополнительные сведения см. в разделе ASP.NET Среда выполнения .NET Core Blazor WebAssembly и кэширование пакета приложений.

Чтобы обеспечить переопределение URL-адресов, добавьте файл wwwroot/404.html со скриптом, который производит перенаправление запроса на страницу index.html. Пример см. в репозитории SteveSandersonMS/BlazorOnGitHubPagesGitHub:

• wwwroot/404.html
• Пример работающего веб-сайта

При использовании сайта проекта вместо сайта организации следует обновить тег <base> в файле wwwroot/index.html. Задайте для имени репозитория GitHub значение атрибута href с косой чертой в конце (например, /my-repository/). SteveSandersonMS/BlazorOnGitHubPages В репозитории GitHub база href обновляется при публикации.github/workflows/main.yml в файле конфигурации.

Автономное использование Docker

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

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

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

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

• Раздел Nginx или раздел Apache этой статьи
• Документация по Docker

Значения конфигурации узла

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

Корневой каталог содержимого

Аргумент --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 укажите аргумент в меню Свойства>Отладка>Аргументы приложения. Задание аргумента на странице свойств Visual Studio добавляет его в файл launchSettings.json.

  --contentroot=/content-root-path
  

Базовый путь

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

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

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

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

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

• В Visual Studio укажите аргумент в меню Свойства>Отладка>Аргументы приложения. Задание аргумента на странице свойств Visual Studio добавляет его в файл launchSettings.json.

  --pathbase=/relative-URL-path
  

URL-адреса

Аргумент --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 укажите аргумент в меню Свойства>Отладка>Аргументы приложения. Задание аргумента на странице свойств Visual Studio добавляет его в файл launchSettings.json.

  --urls=http://127.0.0.1:0
  

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

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

((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\_framework\wwwroot\service-worker-assets.js
Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\wwwroot\service-worker-assets.js.gz
Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\wwwroot\service-worker-assets.js.br

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

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

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

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

Повреждение до развертывания

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

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

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

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

Устранение проблем с проверкой целостности

Когда Blazor WebAssembly скачивает файлы запуска для приложения, браузеру получает инструкции выполнить проверку целостности для ответов. Blazor отправляет хэш-значения SHA-256 для DLL (.dll), WebAssembly (.wasm) и других файлов в файле blazor.boot.json, который не кэшируется в клиентах. Хэши кэшированных файлов сравниваются с хэшами в файле blazor.boot.json. Для кэшированных файлов с совпадающим хэшем Blazor использует кэшированные файлы. В противном случае файлы запрашиваются с сервера. После скачивания файла его хэш снова проверяется на целостность. Браузер генерирует ошибку, если проверка целостности скачанного файла не удалась.

Алгоритм Blazor для управления целостностью файлов:

• Гарантирует, что приложение не будет загружать несогласованный набор файлов, например, если новое развертывание применяется к вашему веб-серверу, пока пользователь скачивает файлы приложения. Использование несогласованных файлов может привести к неправильной работе приложения.
• Гарантирует, что браузер пользователя никогда не будет кэшировать несогласованные или недопустимые ответы, что может помешать запуску приложения, даже если пользователь вручную обновляет страницу.
• Делает безопасным кэширование ответов и не проверяет изменения на стороне сервера до тех пор, пока не изменятся сами ожидаемые хэши SHA-256, поэтому последующие загрузки страниц включают меньше запросов и выполняются быстрее.

Если веб-сервер возвращает ответы, не соответствующие ожидаемым хэшам SHA-256, в консоли разработчика браузера отобразится примерно такая ошибка:

Failed to find a valid digest in the 'integrity' attribute for resource 'https://myapp.example.com/_framework/MyBlazorApp.dll' with computed SHA-256 integrity 'IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJY='. Ресурс заблокирован.

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

Справочный источник загрузки Blazor WebAssembly доступен в файле Boot.WebAssembly.ts в репозитории dotnet/aspnetcore в GitHub.

Диагностика проблем целостности

При создании приложения сгенерированный манифест blazor.boot.json описывает хэши SHA-256 ваших ресурсов загрузки на момент создания выходных данных сборки. Проверка целостности проходит успешно до тех пор, пока хэши SHA-256 в blazor.boot.json соответствуют переданным в браузер файлам.

Распространенные причины сбоя:

• Веб-сервер возвращает не запрошенный браузером файл, а информацию об ошибке (например, 404 - Not Found (не найдено) или 500 - Internal Server Error (внутренняя ошибка сервера)). В браузере этот ответ проявляется как ошибка проверки целостности, но не как ошибка ответа.
• Содержимое файлов по какой-либо причине изменилось в период между их сборкой и доставкой в браузер. Это может произойти:
  • Если вы вручную или с помощью средств сборки изменили выходные данные сборки.
  • Если какие-то аспекты процесса развертывания изменили файлы. Например, при использовании механизма развертывания на основе Git важно помнить, что Git прозрачно преобразует концы строк из стиля Windows в стиль UNIX, если вы фиксируете файлы из Windows, а затем получаете их в Linux. Изменение концов строк в файле приводит к изменению хэша SHA-256. Чтобы избежать этой проблемы, можно применить .gitattributes, чтобы артефакты сборки воспринимались как файлы binary;
  • Если веб-сервер изменяет содержимое файла при его обработке. Например, некоторые сети доставки содержимого (CDN) автоматически пытаются уменьшить размер HTML-файлов, неизбежно изменяя их. Возможно, вам придется отключить эти функции.
• Файл blazor.boot.json не загружается должным образом или неправильно кэшируется в клиенте. Распространенные причины включают одно из следующих причин:
  • Неправильно настроенный или неисправный пользовательский код разработчика.
  • Один или несколько неправильно настроенных промежуточных уровней кэширования.

Чтобы определить причину для конкретной ситуации, сделайте следующее.

1. Узнайте, какой файл вызывает ошибку, прочитав сообщение об ошибке.
2. Откройте средства разработчика браузера и перейдите на вкладку "Сеть ". При необходимости перезагрузите страницу, чтобы просмотреть список запросов и ответов. Найдите в этом списке файл, который вызвал ошибку.
3. Проверьте код состояния в ответе HTTP. Если сервер возвращает любой ответ, кроме 200 — OK или другого кода из диапазона 2xx, значит проблему нужно диагностировать на стороне сервера. Например, код состояния 403 означает проблему с авторизацией, а код состояния 500 — неопределенную ошибку в работе сервера. Просмотрите журналы на стороне сервера, чтобы диагностировать и исправить приложение.
4. Если для ресурса возвращается код состояния 200 — ОK, проверьте содержимое ответа с помощью средств разработчика в браузере и убедитесь, что это содержимое соответствует ожиданиям. Например, довольно часто ошибка в настройке маршрутизации приводит к тому, что запросы возвращают страницу index.html даже при обращении к другим файлам. Убедитесь, что в ответ на запросы .wasm возвращаются двоичные файлы WebAssembly, а в ответ на запросы .dll — двоичные файлы сборки .NET. В противном случае проблему нужно диагностировать на стороне сервера.
5. Попытайтесь проверить выходные данные опубликованного и развернутого приложения с помощью скрипта PowerShell для устранения проблем целостности.

Если вы убедились, что сервер возвращает данные в предположительно правильном формате, значит что-то еще изменяет содержимое файлов в период между сборкой и доставкой. Для анализа этой ситуации сделайте следующее:

• Изучите цепочку инструментов сборки и механизм развертывания, чтобы исключить операции изменения файлов после сборки. Выше описан пример таких изменений, связанный с преобразованием концов строк в файлах при работе с Git.
• Изучите конфигурацию веб-сервера или сети доставки содержимого, чтобы исключить динамическое изменение ответов в них (например, для уменьшения размера HTML-файлов). При этом сжатие HTTP (например, в формате content-encoding: br или content-encoding: gzip) на стороне веб-сервера считается допустимым, так как не влияет на результат после распаковки. Но совершенно недопустимы изменения несжатых данных на веб-сервере.

Скрипт PowerShell для устранения проблем целостности

Используйте в PowerShell скрипт integrity.ps1 для проверки опубликованного и развернутого приложения Blazor. Скрипт предоставляется для PowerShell Core 7 или более поздней версии в качестве начальной точки, если в приложении есть проблемы с целостностью, которые платформа Blazor не может распознать. Для приложений может потребоваться настройка скрипта, в том числе при запуске в PowerShell более поздней версии, чем версия 7.2.0.

Скрипт проверяет файлы, расположенные в папке publish и скачанные из развернутого приложения, чтобы обнаружить проблемы в разных манифестах, содержащих хэши целостности. При этих проверках должны быть обнаружены наиболее распространенные проблемы:

• Вы изменили файл в опубликованных выходных данных, не зная этого.
• Приложение было неправильно развернуто в целевом объекте развертывания или что-то изменилось в среде целевого объекта развертывания.
• Данные развернутого приложения и выходные данные публикации приложения отличаются.

Вызовите скрипт в командной оболочке PowerShell с помощью следующей команды:

.\integrity.ps1 {BASE URL} {PUBLISH OUTPUT FOLDER}

В следующем примере сценарий выполняется в локально запущенном приложении в https://localhost:5001/:

.\integrity.ps1 https://localhost:5001/ C:\TestApps\BlazorSample\bin\Release\net6.0\publish\

Заполнители:

• {BASE URL}: URL-адрес развернутого приложения. Требуется завершающая косая черта (/).
• {PUBLISH OUTPUT FOLDER}: Путь к папке или расположению приложения publish , в котором приложение публикуется для развертывания.

C:\Users\{USER}\Documents\GitHub\AspNetCore.Docs\aspnetcore\blazor\host-and-deploy\webassembly\_samples\integrity.ps1

CertUtil -hashfile {PATH AND FILE NAME} {SHA256|MD5}

Отключение проверки целостности для приложений, не относящихся к PWA

В большинстве случаев проверку целостности отключать не нужно. Отключение проверки целостности не решает основную проблему, которая вызывает непредвиденные ответы, и приводит к потере описанных выше преимуществ.

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

Для этого добавьте следующий фрагмент в группу свойств в файле проекта .csproj приложения Blazor WebAssembly:

<BlazorCacheBootResources>false</BlazorCacheBootResources>

BlazorCacheBootResources также отключает Blazorповедение кэширования по умолчанию для .dll, .wasm и других файлов на основе хэшей SHA-256, так как это свойство запрещает доверять правильности хэшей SHA-256. Даже при включенном параметре стандартный кэш HTTP браузера может кэшировать эти файлы, но этим поведением можно управлять через конфигурацию веб-сервера и заголовков cache-control, которые он возвращает.

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

Несколько общих сценариев, которые могут вызвать проблемы с целостностью:

• Выполнение через HTTP, когда нельзя проверить целостность.
• Если ваш процесс развертывания каким-либо образом изменяет файлы после публикации.
• Если ваш узел каким-либо образом изменяет файлы.

Отключение проверки целостности для PWA

Шаблон Blazor для прогрессивного веб-приложения (PWA) содержит рекомендуемый файл service-worker.published.js, который отвечает за получение и хранение файлов приложений для автономного использования. Этот процесс отличается от обычного механизма запуска приложения и использует собственную логику проверки целостности.

В файле service-worker.published.js есть следующая строка:

.map(asset => new Request(asset.url, { integrity: asset.hash }));

Чтобы отключить проверку целостности, удалите параметр integrity из этой строки, заменив ее следующим текстом:

.map(asset => new Request(asset.url));

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