ASP.NET Core Blazor WebAssembly środowisko uruchomieniowe platformy .NET i buforowanie pakietów aplikacji

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Blazor WebAssembly Gdy aplikacja zostanie załadowana w przeglądarce, aplikacja pobiera zasoby rozruchowe z serwera:

• Kod JavaScript do uruchamiania aplikacji
• Środowisko uruchomieniowe i zestawy platformy .NET
• Dane specyficzne dla ustawień regionalnych

BlazorZ wyjątkiem pliku zasobów rozruchowych (blazor.boot.json), pliki środowiska uruchomieniowego platformy .NET i pakietu aplikacji webAssembly są buforowane na klientach. Plik blazor.boot.json zawiera manifest plików tworzących aplikację, które należy pobrać wraz z skrótem zawartości pliku używanej do wykrywania, czy którekolwiek z zasobów rozruchowych uległy zmianie. Blazorbuforuje pobrane pliki przy użyciu interfejsu API pamięci podręcznej przeglądarki.

Podczas Blazor WebAssembly pobierania plików uruchamiania aplikacji program instruuje przeglądarkę, aby przeprowadzała kontrole integralności odpowiedzi. Blazor Wysyła wartości skrótu SHA-256 dla biblioteki DLL (.dll), zestawu WebAssembly (.wasm) i innych plików w blazor.boot.json pliku. Skróty plików buforowanych są porównywane z skrótami w blazor.boot.json pliku. W przypadku plików buforowanych z pasującym skrótem Blazor używa buforowanych plików. W przeciwnym razie pliki są żądane z serwera. Po pobraniu pliku jego skrót jest ponownie sprawdzany pod kątem weryfikacji integralności. Błąd jest generowany przez przeglądarkę, jeśli sprawdzanie integralności pobranego pliku nie powiedzie się.

BlazorAlgorytm "s do zarządzania integralnością plików:

• Zapewnia, że aplikacja nie ryzykuje ładowania niespójnego zestawu plików, na przykład jeśli nowe wdrożenie zostanie zastosowane do serwera internetowego, gdy użytkownik jest w trakcie pobierania plików aplikacji. Niespójne pliki mogą spowodować awarię aplikacji.
• Gwarantuje, że przeglądarka użytkownika nigdy nie buforuje niespójnych lub nieprawidłowych odpowiedzi, co może uniemożliwić uruchamianie aplikacji nawet wtedy, gdy użytkownik ręcznie odświeży stronę.
• Zabezpiecza buforowanie odpowiedzi i nie sprawdza zmian po stronie serwera, dopóki oczekiwane skróty SHA-256 się nie zmienią, więc kolejne obciążenia stron obejmują mniej żądań i zakończą się szybciej.

Jeśli serwer internetowy zwraca odpowiedzi, które nie są zgodne z oczekiwanymi skrótami SHA-256, w konsoli dewelopera przeglądarki zostanie wyświetlony błąd podobny do poniższego przykładu:

Nie można odnaleźć prawidłowego skrótu w atrybucie "integrity" dla zasobu "https://myapp.example.com/_framework/MyBlazorApp.dll" z obliczoną integralnością SHA-256 "IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJY=". Zasób został zablokowany.

W większości przypadków ostrzeżenie nie wskazuje problemu z sprawdzaniem integralności. Zamiast tego ostrzeżenie zwykle oznacza, że istnieje inny problem.

Uwaga

Linki dokumentacji do źródła referencyjnego platformy .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla bieżące programowanie dla następnej wersji platformy .NET. Aby wybrać tag dla określonej wersji, użyj listy rozwijanej Przełącz gałęzie lub tagi. Aby uzyskać więcej informacji, zobacz Jak wybrać tag wersji kodu źródłowego platformy ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Diagnozowanie problemów z integralnością

Podczas kompilowania aplikacji wygenerowany blazor.boot.json manifest opisuje skróty SHA-256 zasobów rozruchowych w momencie wygenerowania danych wyjściowych kompilacji. Sprawdzanie integralności jest sprawdzane tak długo, jak skróty SHA-256 są blazor.boot.json zgodne z plikami dostarczonymi do przeglądarki.

Typowe przyczyny niepowodzenia:

• Odpowiedź serwera internetowego jest błędem (na przykład 404 — Nie znaleziono lub 500 — wewnętrzny błąd serwera) zamiast pliku, którego zażądała przeglądarka. Jest to zgłaszane przez przeglądarkę jako błąd sprawdzania integralności, a nie jako błąd odpowiedzi.
• Coś zmieniło zawartość plików między kompilacją i dostarczaniem plików do przeglądarki. Może się tak zdarzyć:
  • Jeśli ty lub narzędzia kompilacji ręcznie zmodyfikuj dane wyjściowe kompilacji.
  • Jeśli jakiś aspekt procesu wdrażania zmodyfikował pliki. Jeśli na przykład używasz mechanizmu wdrażania opartego na usłudze Git, pamiętaj, że usługa Git w sposób przezroczysty konwertuje zakończenia linii w stylu systemu Windows na zakończenia linii w stylu unix, jeśli zatwierdzisz pliki w systemie Windows i wyewidencjonujesz je w systemie Linux. Zmiana końców wiersza pliku zmienia skróty SHA-256. Aby uniknąć tego problemu, rozważ użycie metody .gitattributes w celu traktowania artefaktów kompilacji jako binary plików.
  • Serwer internetowy modyfikuje zawartość pliku w ramach ich obsługi. Na przykład niektóre sieci dystrybucji zawartości (CDN) automatycznie próbują ujednolicić kod HTML, modyfikując go w ten sposób. Może być konieczne wyłączenie takich funkcji.
• Nie blazor.boot.json można poprawnie załadować pliku lub jest on nieprawidłowo buforowany na kliencie. Typowe przyczyny obejmują jedną z następujących przyczyn:
  • Nieprawidłowo skonfigurowany lub nieprawidłowo skonfigurowany kod dewelopera niestandardowego.
  • Co najmniej jedna nieprawidłowo skonfigurowana warstwa buforowania pośredniego.

Aby zdiagnozować, które z nich mają zastosowanie w Twoim przypadku:

1. Zwróć uwagę, który plik wyzwala błąd, odczytując komunikat o błędzie.
2. Otwórz narzędzia deweloperskie przeglądarki i spójrz na kartę Sieć . W razie potrzeby załaduj ponownie stronę, aby wyświetlić listę żądań i odpowiedzi. Znajdź plik, który wyzwala błąd na tej liście.
3. Sprawdź kod stanu HTTP w odpowiedzi. Jeśli serwer zwraca coś innego niż 200 — OK (lub inny kod stanu 2xx), masz problem po stronie serwera do zdiagnozowania. Na przykład kod stanu 403 oznacza, że występuje problem z autoryzacją, natomiast kod stanu 500 oznacza, że serwer kończy się niepowodzeniem w nieokreślony sposób. Zapoznaj się z dziennikami po stronie serwera, aby zdiagnozować i naprawić aplikację.
4. Jeśli kod stanu to 200 — OK dla zasobu, sprawdź zawartość odpowiedzi w narzędziach deweloperskich przeglądarki i sprawdź, czy zawartość jest zgodna z oczekiwanymi danymi. Na przykład typowym problemem jest błędne skonfigurowanie routingu, aby żądania zwracały index.html dane nawet w przypadku innych plików. Upewnij się, że odpowiedzi na .wasm żądania to pliki binarne zestawu WebAssembly i że odpowiedzi na żądania to pliki binarne zestawów platformy .dll .NET. Jeśli nie, masz problem z routingiem po stronie serwera, aby zdiagnozować.
5. Sprawdź poprawność opublikowanych i wdrożonych danych wyjściowych aplikacji za pomocą skryptu Rozwiązywanie problemów z integralnością programu PowerShell.

Jeśli potwierdzisz, że serwer zwraca wiarygodne poprawne dane, musi istnieć coś innego modyfikujące zawartość między kompilacją i dostarczaniem pliku. Aby zbadać to:

• Sprawdź łańcuch narzędzi kompilacji i mechanizm wdrażania, jeśli modyfikują pliki po skompilowaniu plików. Przykładem tego jest przekształcenie zakończenia wiersza pliku w usłudze Git zgodnie z wcześniejszym opisem.
• Sprawdź konfigurację serwera internetowego lub sieci CDN w przypadku ich skonfigurowania w celu dynamicznego modyfikowania odpowiedzi (na przykład próby ściągnąć kod HTML). Serwer internetowy może zaimplementować kompresję HTTP (na przykład zwracaną content-encoding: br lub content-encoding: gzip), ponieważ nie ma to wpływu na wynik po dekompresji. Jednak nie jest w porządku, aby serwer internetowy modyfikował nieskompresowane dane.

Rozwiązywanie problemów ze skryptem programu PowerShell integralności

Użyj skryptu integrity.ps1 programu PowerShell, aby zweryfikować opublikowaną i wdrożona Blazor aplikację. Skrypt jest udostępniany dla programu PowerShell Core 7 lub nowszego jako punkt wyjścia, gdy aplikacja ma problemy z integralnością, których Blazor platforma nie może zidentyfikować. Dostosowanie skryptu może być wymagane dla aplikacji, w tym w przypadku uruchamiania w wersji programu PowerShell nowszej niż wersja 7.2.0.

Skrypt sprawdza pliki w folderze publish i pobierany z wdrożonej aplikacji w celu wykrywania problemów w różnych manifestach zawierających skróty integralności. Te testy powinny wykrywać najczęstsze problemy:

• Plik został zmodyfikowany w opublikowanych danych wyjściowych bez jego realizacji.
• Aplikacja nie została poprawnie wdrożona w obiekcie docelowym wdrożenia lub coś się zmieniło w środowisku docelowym wdrożenia.
• Istnieją różnice między wdrożona aplikacją a danymi wyjściowymi publikowania aplikacji.

Wywołaj skrypt za pomocą następującego polecenia w powłoce poleceń programu PowerShell:

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

W poniższym przykładzie skrypt jest wykonywany w aplikacji uruchomionej lokalnie pod adresem https://localhost:5001/:

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

Symbole zastępcze:

• {BASE URL}: adres URL wdrożonej aplikacji. Wymagany jest ukośnik końcowy (/).
• {PUBLISH OUTPUT FOLDER}: ścieżka do folderu lub lokalizacji aplikacji publish , w której aplikacja jest publikowana na potrzeby wdrożenia.

Uwaga

Podczas klonowania dotnet/AspNetCore.Docs repozytorium integrity.ps1 GitHub skrypt może zostać poddany kwarantannie przez narzędzie Bitdefender lub inny skaner wirusów znajdujący się w systemie. Zazwyczaj plik jest uwięziony przez technologię skanowania heurystycznego skanera wirusów, która jedynie szuka wzorców w plikach, które mogą wskazywać na obecność złośliwego oprogramowania. Aby zapobiec kwarantowaniu pliku przez skaner wirusów, dodaj wyjątek do skanera wirusów przed sklonowaniem repozytorium. Poniższy przykład to typowa ścieżka do skryptu w systemie Windows. Dostosuj ścieżkę zgodnie z potrzebami dla innych systemów. Symbol zastępczy {USER} to segment ścieżki użytkownika.

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

Ostrzeżenie: Tworzenie wyjątków skanera wirusów jest niebezpieczne i powinno być wykonywane tylko wtedy, gdy masz pewność, że plik jest bezpieczny.

Porównywanie sumy kontrolnej pliku z prawidłową wartością sumy kontrolnej nie gwarantuje bezpieczeństwa pliku, ale modyfikowanie pliku w sposób, który utrzymuje wartość sumy kontrolnej, nie jest banalny dla złośliwych użytkowników. W związku z tym sumy kontrolne są przydatne jako ogólne podejście do zabezpieczeń. Porównaj sumę kontrolną pliku lokalnego integrity.ps1 z jedną z następujących wartości:

• SHA256: 32c24cb667d79a701135cb72f6bae490d81703323f61b8af2c7e5e5dc0f0c2bb
• MD5: 9cee7d7ec86ee809a329b5406fbf21a8

Uzyskaj sumę kontrolną pliku w systemie operacyjnym Windows za pomocą następującego polecenia. Podaj ścieżkę i nazwę pliku symbolu zastępczego {PATH AND FILE NAME} i wskaż typ sumy kontrolnej do utworzenia dla symbolu zastępczego {SHA512|MD5} albo SHA256 lub MD5:

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

Jeśli masz jakiekolwiek powody do obaw, że walidacja sumy kontrolnej nie jest wystarczająco bezpieczna w danym środowisku, zapoznaj się z kierownictwem ds. zabezpieczeń organizacji, aby uzyskać wskazówki.

Aby uzyskać więcej informacji, zobacz Omówienie ochrony przed zagrożeniami według Program antywirusowy Microsoft Defender.

Wyłączanie buforowania zasobów i sprawdzania integralności dla aplikacji innych niż PWA

W większości przypadków nie wyłączaj sprawdzania integralności. Wyłączenie sprawdzania integralności nie rozwiązuje podstawowego problemu, który spowodował nieoczekiwane odpowiedzi i powoduje utratę korzyści wymienionych wcześniej.

Mogą wystąpić przypadki, w których nie można polegać na zwracaniu spójnych odpowiedzi na serwerze sieci Web i nie masz wyboru, ale tymczasowo wyłączyć kontrole integralności do momentu rozwiązania problemu podstawowego.

Aby wyłączyć kontrole integralności, dodaj następujące elementy do grupy właściwości w Blazor WebAssembly pliku projektu aplikacji (.csproj):

<BlazorCacheBootResources>false</BlazorCacheBootResources>

BlazorCacheBootResources Wyłącza Blazorrównież domyślne zachowanie buforowania .dllplików , .wasmi innych plików na podstawie skrótów SHA-256, ponieważ właściwość wskazuje, że skróty SHA-256 nie mogą być oparte na poprawności. Nawet w przypadku tego ustawienia normalna pamięć podręczna HTTP przeglądarki może nadal buforowanie tych plików, ale to, czy tak się stanie, zależy od konfiguracji serwera internetowego i cache-control nagłówków, które obsługuje.

Uwaga

Właściwość BlazorCacheBootResources nie wyłącza sprawdzania integralności dla progresywnych aplikacji internetowych (PWA). Aby uzyskać wskazówki dotyczące aplikacji PWA, zobacz sekcję Wyłączanie sprawdzania integralności dla aplikacji PWA .

Nie można podać wyczerpującej listy scenariuszy, w których jest wymagane wyłączenie sprawdzania integralności. Serwery mogą odpowiadać na żądanie w dowolny sposób poza zakresem Blazor struktury. Platforma udostępnia BlazorCacheBootResources ustawienie umożliwiające uruchamianie aplikacji kosztem utraty gwarancji integralności, którą aplikacja może zapewnić. Ponownie nie zalecamy wyłączania sprawdzania integralności, zwłaszcza w przypadku wdrożeń produkcyjnych. Deweloperzy powinni dążyć do rozwiązania podstawowego problemu integralności, który powoduje niepowodzenie sprawdzania integralności.

Oto kilka ogólnych przypadków, które mogą powodować problemy z integralnością:

• Uruchamianie przy użyciu protokołu HTTP, w którym nie można sprawdzić integralności.
• Jeśli proces wdrażania modyfikuje pliki po opublikowaniu w jakikolwiek sposób.
• Jeśli host modyfikuje pliki w jakikolwiek sposób.

Wyłączanie buforowania zasobów i sprawdzania integralności dla aplikacji PWA

BlazorSzablon progresywnej aplikacji internetowej (PWA) zawiera sugerowany service-worker.published.js plik, który jest odpowiedzialny za pobieranie i przechowywanie plików aplikacji do użytku w trybie offline. Jest to oddzielny proces od normalnego mechanizmu uruchamiania aplikacji i ma własną oddzielną logikę sprawdzania integralności.

service-worker.published.js Wewnątrz pliku znajduje się następujący wiersz:

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

Aby wyłączyć sprawdzanie integralności, usuń integrity parametr, zmieniając wiersz na następujący:

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

Ponownie wyłączenie sprawdzania integralności oznacza utratę gwarancji bezpieczeństwa oferowanych przez kontrolę integralności. Istnieje na przykład ryzyko, że jeśli przeglądarka użytkownika buforuje aplikację w dokładnym momencie wdrożenia nowej wersji, może buforować niektóre pliki ze starego wdrożenia i niektóre z nowego wdrożenia. W takim przypadku aplikacja zostanie zablokowana w stanie uszkodzonym do momentu wdrożenia kolejnej aktualizacji.

Dodatkowe zasoby

Ładowanie zasobu rozruchowego