Поделиться через

ASP.NET Core .NET сбои кэширования и проверки целостности наборов Blazor WebAssembly

  • Статья

Примечание.

Это не последняя версия этой статьи. Для текущего релиза смотрите версию .NET 9 этой статьи.

Предупреждение

Эта версия ASP.NET Core больше не поддерживается. Дополнительные сведения см. в политике поддержки .NET и .NET Core. Для текущего релиза смотрите версию .NET 9 этой статьи.

Это важно

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

Для текущего релиза смотрите версию .NET 9 этой статьи.

В этой статье объясняется, как Blazor WebAssembly кэширует среду выполнения и пакет приложений WebAssembly .NET, а также как диагностировать и устранять ошибки целостности.

Blazor WebAssembly Когда приложение загружается в браузере, приложение загружает ресурсы загрузки с сервера:

  • Код JavaScript для инициализации приложения
  • Среда выполнения и сборки .NET
  • Локализованные данные

За исключением файла манифеста загрузки Blazor (dotnet.boot.js в .NET 10 и более поздних версиях, blazor.boot.json в более ранних версиях .NET 10), среда выполнения WebAssembly .NET и файлы пакета приложений кэшируются на клиентах. Конфигурация Blazor загрузки содержит манифест файлов, составляющих приложение, которое должно быть загружено вместе с хэшом содержимого файла, которое используется для определения того, изменились ли какие-либо из ресурсов загрузки. Blazor кэширует скачанные файлы с помощью API кэша браузера.

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

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

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

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

Не удалось найти допустимый дайджест в атрибуте 'integrity' для ресурса 'https://myapp.example.com/_framework/MyBlazorApp.dll' с вычисленной целостностью SHA-256 'IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJY='. Ресурс заблокирован.

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

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

Примечание.

Ссылки в документации на справочные материалы по .NET обычно загружают основную ветвь репозитория, которая представляет собой текущую разработку для следующего выпуска .NET. Чтобы выбрать тег для конкретного релиза, используйте раскрывающийся список Переключение ветвей или тегов. Дополнительные сведения см. в статье Выбор тега версии исходного кода ASP.NET Core (dotnet/AspNetCore.Docs #26205).

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

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

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

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

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

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

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

  • Изучите цепочку инструментов сборки и механизм развертывания на случай, если файлы изменяются после сборки. Выше описан пример таких изменений, связанный с преобразованием концов строк в файлах при работе с Git.
  • Изучите конфигурацию веб-сервера или CDN на предмет возможного динамического изменения ответов (например, попытка минимизировать 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 , в котором приложение публикуется для развертывания.

Примечание.

При клонировании репозитория GitHub dotnet/AspNetCore.Docs скрипт integrity.ps1 может быть помещен в карантин программой Bitdefender или другой программой поиска вирусов, присутствующей в системе. Обычно файл перехватывается технологией эвристического сканирования программы поиска вирусов, которая просто ищет в файлах шаблоны, которые могут указывать на присутствие вредоносных программ. Чтобы программа поиска вирусов не поместила файл в карантин, добавьте исключение в программу перед клонированием репозитория. Ниже представлен типичный путь к скрипту для системы Windows. При необходимости измените путь для других систем. Плейсхолдер {USER} — это сегмент пути пользователя.

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

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

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

  • SHA256: 32c24cb667d79a701135cb72f6bae490d81703323f61b8af2c7e5e5dc0f0c2bb
  • MD5: 9cee7d7ec86ee809a329b5406fbf21a8

Получите контрольную сумму файла в ОС Windows с помощью указанной ниже команды. Укажите путь и имя файла для заполнителя {PATH AND FILE NAME}, а также тип контрольной суммы, которую нужно создать для заполнителя {SHA512|MD5}, SHA256 или MD5:

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

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

Для получения дополнительной информации см. в разделе «Обзор защиты от угроз с помощью программы Microsoft Defender Антивирус».

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

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

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

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

<BlazorCacheBootResources>false</BlazorCacheBootResources>

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

Примечание.

Свойство BlazorCacheBootResources не отключает проверку целостности для прогрессивных веб-приложений (PWA). Чтобы получить рекомендации по работе с PWA, см. раздел Отключение проверки целостности для PWA.

Мы не можем предоставить исчерпывающий список сценариев, в которых требуется отключение проверки целостности. Серверы могут отвечать на запрос произвольным образом, что выходит за рамки платформы 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));

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