ASP.NET Среда выполнения .NET Core Blazor WebAssembly и кэширование пакетов приложений

  • Статья

Примечание.

Это не последняя версия этой статьи. В текущем выпуске см . версию .NET 8 этой статьи.

Внимание

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

В текущем выпуске см . версию .NET 8 этой статьи.

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

  • Код JavaScript для начальной загрузки приложения
  • Среда выполнения и сборки .NET
  • Данные определенного языкового стандарта

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

Когда Blazor WebAssembly скачивает файлы запуска для приложения, браузеру получает инструкции выполнить проверку целостности для ответов. Blazorотправляет хэш-значения SHA-256 для DLL (), WebAssembly (.dll.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='. Ресурс заблокирован.

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

Примечание.

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

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

При создании приложения сгенерированный манифест 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 , в котором приложение публикуется для развертывания.

Примечание.

При клонировании репозитория 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

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

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

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

<BlazorCacheBootResources>false</BlazorCacheBootResources>

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

Примечание.

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

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

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

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

Отключение кэширования ресурсов и целостности проверка для ЦП

Шаблон 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));

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

Дополнительные ресурсы

Загрузка ресурса