Udostępnij za pośrednictwem


Hostowanie i wdrażanie platformy ASP.NET Core Blazor WebAssembly

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.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz .NET i .NET Core Support Policy (Zasady obsługi platformy .NET Core). 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.

W tym artykule wyjaśniono, jak hostować i wdrażać Blazor WebAssembly przy użyciu ASP.NET Core, Content Delivery Networks (CDN), serwerów plików i usługi GitHub Pages.

Z modelem hostingu:Blazor WebAssembly

  • Aplikacja Blazor , jej zależności i środowisko uruchomieniowe platformy .NET są pobierane równolegle do przeglądarki.
  • Aplikacja jest wykonywana bezpośrednio w wątku interfejsu użytkownika przeglądarki.

Ten artykuł dotyczy scenariusza wdrażania, w którym Blazor aplikacja jest umieszczana na statycznym serwerze internetowym lub usłudze hostingu, platforma .NET nie jest używana do obsługi Blazor aplikacji. Ta strategia jest omówiona w sekcji Wdrażanie autonomiczne, która zawiera informacje dotyczące hostowania Blazor WebAssembly aplikacji jako aplikacji podrzędnej usług IIS.

Obsługiwane są następujące strategie wdrażania:

  • Aplikacja jest obsługiwana Blazor przez aplikację ASP.NET Core. Ta strategia jest omówiona we wdrożeniu hostowanym w sekcji ASP.NET Core .
  • Aplikacja Blazor jest umieszczana na statycznym serwerze lub usłudze hostingu, gdzie platforma .NET nie jest używana do obsługi Blazor aplikacji. Ta strategia jest omówiona w sekcji Wdrażanie autonomiczne, która zawiera informacje dotyczące hostowania Blazor WebAssembly aplikacji jako aplikacji podrzędnej usług IIS.
  • Aplikacja ASP.NET Core hostuje wiele Blazor WebAssembly aplikacji. Aby uzyskać więcej informacji, zobacz Wiele hostowanych aplikacji ASP.NET CoreBlazor WebAssembly.

Poddomena i hostowanie aplikacji podrzędnych usług IIS

Hosting poddomeny nie wymaga specjalnej konfiguracji aplikacji. Nie musisz konfigurować ścieżki podstawowej aplikacji (<base>tagu w wwwroot/index.htmlprogramie ), aby hostować aplikację w poddomenie.

Hostowanie aplikacji podrzędnych usług IIS wymaga ustawienia ścieżki podstawowej aplikacji. Aby uzyskać więcej informacji i linki krzyżowe do dalszych wskazówek dotyczących hostowania podapliki usług IIS, zobacz Host and deploy ASP.NET Core Blazor.

Zmniejsz maksymalny rozmiar sterty dla niektórych przeglądarek urządzeń przenośnych

Podczas kompilowania Blazor aplikacji uruchamianej na kliencie (.Client projekcie Blazor Web App aplikacji autonomicznej Blazor WebAssembly lub autonomicznej) i przeznaczonych dla przeglądarek urządzeń przenośnych, zwłaszcza w przeglądarce Safari w systemie iOS, może być wymagana maksymalna ilość pamięci dla aplikacji z właściwością EmccMaximumHeapSize MSBuild. Wartość domyślna to 2 147 483 648 bajtów, co może być zbyt duże i powoduje awarię aplikacji, jeśli aplikacja próbuje przydzielić więcej pamięci, a przeglądarka nie udzieliła jej. Poniższy przykład ustawia wartość na 268 435 456 bajtów w Program pliku:

Podczas kompilowania Blazor WebAssembly aplikacji, która jest przeznaczona dla przeglądarek urządzeń przenośnych, zwłaszcza w przeglądarce Safari w systemie iOS, może być wymagana maksymalna ilość pamięci dla aplikacji z właściwością EmccMaximumHeapSize MSBuild. Wartość domyślna to 2 147 483 648 bajtów, co może być zbyt duże i powoduje awarię aplikacji, jeśli aplikacja próbuje przydzielić więcej pamięci, a przeglądarka nie udzieliła jej. Poniższy przykład ustawia wartość na 268 435 456 bajtów w Program pliku:

<EmccMaximumHeapSize>268435456</EmccMaximumHeapSize>

Aby uzyskać więcej informacji na temat właściwości i obiektów docelowych programu Mono/WebAssembly MSBuild, zobacz WasmApp.Common.targets (dotnet/runtime repozytorium GitHub).

Format tworzenia pakietów webcil dla zestawów platformy .NET

Webcil to przyjazny dla sieci Web format tworzenia pakietów dla zestawów .NET przeznaczony do włączania używania Blazor WebAssembly w restrykcyjnych środowiskach sieciowych. Pliki webcil używają standardowej otoki WebAssembly, gdzie zestawy są wdrażane jako pliki zestawu WebAssembly, które używają standardowego .wasm rozszerzenia pliku.

Składnik Webcil jest domyślnym formatem tworzenia pakietów podczas publikowania Blazor WebAssembly aplikacji. Aby wyłączyć używanie elementu Webcil, ustaw następującą właściwość MSBuild w pliku projektu aplikacji:

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

Dostosowywanie sposobu ładowania zasobów rozruchowych

Dostosuj sposób ładowania zasobów rozruchowych przy użyciu interfejsu loadBootResource API. Aby uzyskać więcej informacji, zobacz uruchamianie ASP.NET CoreBlazor.

Kompresja

Po opublikowaniu Blazor WebAssembly aplikacji dane wyjściowe są statycznie kompresowane podczas publikowania, aby zmniejszyć rozmiar aplikacji i usunąć obciążenie związane z kompresją środowiska uruchomieniowego. Używane są następujące algorytmy kompresji:

Blazor korzysta z hosta w celu obsługi odpowiednich skompresowanych plików. W przypadku hostowania aplikacji autonomicznej Blazor WebAssembly może być wymagana dodatkowa praca w celu zapewnienia obsługi statycznie skompresowanych plików:

Blazor korzysta z hosta w celu obsługi odpowiednich skompresowanych plików. W przypadku korzystania z projektu ASP.NET Core HostedBlazor WebAssembly projekt hosta może negocjować zawartość i obsługiwać statycznie skompresowane pliki. W przypadku hostowania aplikacji autonomicznej Blazor WebAssembly może być wymagana dodatkowa praca w celu zapewnienia obsługi statycznie skompresowanych plików:

  • Aby uzyskać informacje o konfiguracji kompresji usług IIS, zobacz sekcję IISweb.config: kompresja Brotli i Gzip.
  • W przypadku hostowania statycznych rozwiązań hostingowych, które nie obsługują statycznie skompresowanych negocjacji zawartości plików, rozważ skonfigurowanie aplikacji do pobierania i dekodowania skompresowanych plików Brotli:

Uzyskaj dekoder Brotli języka JavaScript z google/brotli repozytorium GitHub. Plik dekodera jest nazwany decode.min.js i znaleziony js w folderze repozytorium.

Uwaga

Jeśli minimalna wersja skryptu decode.js (decode.min.js) zakończy się niepowodzeniem, spróbuj zamiast tego użyć niezminyfikowanej wersji (decode.js).

Zaktualizuj aplikację, aby korzystała z dekodera.

wwwroot/index.html W pliku ustaw wartość autostart false na w Blazortagu <script> :

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

Po Blazortagu <script> i przed tagiem zamykającym </body> dodaj następujący blok kodu <script> JavaScript.

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>

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

Aby uzyskać więcej informacji na temat ładowania zasobów rozruchowych, zobacz uruchamianie ASP.NET CoreBlazor.

Aby wyłączyć kompresję CompressionEnabled , dodaj właściwość MSBuild do pliku projektu aplikacji i ustaw wartość na false:

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

Właściwość CompressionEnabled można przekazać do dotnet publish polecenia przy użyciu następującej składni w powłoce poleceń:

dotnet publish -p:CompressionEnabled=false

Aby wyłączyć kompresję BlazorEnableCompression , dodaj właściwość MSBuild do pliku projektu aplikacji i ustaw wartość na false:

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

Właściwość BlazorEnableCompression można przekazać do dotnet publish polecenia przy użyciu następującej składni w powłoce poleceń:

dotnet publish -p:BlazorEnableCompression=false

Ponowne zapisywanie adresów URL w celu poprawnego routingu

Routing żądań składników strony w Blazor WebAssembly aplikacji nie jest tak prosty, jak routing żądań w Blazor Server aplikacji. Rozważmy aplikację z dwoma Blazor WebAssembly składnikami:

  • Main.razor: Ładuje się w katalogu głównym aplikacji i zawiera link do About składnika (href="About").
  • About.razor: About składnik.

Gdy domyślny dokument aplikacji jest żądany przy użyciu paska adresu przeglądarki (na przykład https://www.contoso.com/):

  1. Przeglądarka wysyła żądanie.
  2. Zwracana jest strona domyślna, czyli zwykle index.html.
  3. index.html uruchamia aplikację.
  4. Router ładuje składnik, a RazorMain składnik jest renderowany.

Na stronie głównej wybranie linku do About składnika działa na kliencie, ponieważ Blazor router uniemożliwia przeglądarce wysyłanie żądania w Internecie do www.contoso.com elementu About i obsługuje sam składnik renderowany About . Wszystkie żądania dla wewnętrznych punktów końcowych w Blazor WebAssembly aplikacji działają tak samo: żądania nie wyzwalają żądań opartych na przeglądarce do zasobów hostowanych przez serwer w Internecie. Router obsługuje żądania wewnętrznie.

Jeśli żądanie zostanie wykonane przy użyciu paska adresu przeglądarki dla www.contoso.com/About, żądanie zakończy się niepowodzeniem. Taki zasób nie istnieje na hoście internetowym aplikacji, więc zostanie zwrócona odpowiedź 404 — Nie znaleziono .

Ponieważ przeglądarki wysyłają żądania do hostów internetowych na stronach po stronie klienta, serwery internetowe i usługi hostingowe muszą ponownie zapisać wszystkie żądania dotyczące zasobów, które nie znajdują się fizycznie na serwerze na index.html stronie. Gdy index.html zostanie zwrócony, router aplikacji Blazor przejmuje i reaguje przy użyciu odpowiedniego zasobu.

Podczas wdrażania na serwerze usług IIS można użyć modułu ponownego zapisywania adresu URL z opublikowanym web.config plikiem aplikacji. Aby uzyskać więcej informacji, zobacz sekcję IIS .

Hostowane wdrożenie za pomocą platformy ASP.NET Core

Hostowane Blazor WebAssembly wdrożenie służy aplikacji do przeglądarek z aplikacji ASP.NET Core działającej na serwerze internetowym.

Aplikacja kliencka Blazor WebAssembly jest publikowana w /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot folderze aplikacji serwera wraz z innymi statycznymi elementami zawartości sieci Web aplikacji serwera. Te dwie aplikacje są wdrażane razem. Wymagany jest serwer internetowy, który może hostować aplikację ASP.NET Core. W przypadku wdrożenia hostowanego program Visual Studio zawiera Blazor WebAssembly szablon projektu aplikacji (blazorwasm szablon podczas korzystania z dotnet new polecenia) z wybraną Hosted opcją (-ho|--hosted w przypadku użycia dotnet new polecenia).

Aby uzyskać więcej informacji, zobacz następujące artykuły:

Hostowane wdrożenie pliku wykonywalnego zależnego od struktury dla określonej platformy

Aby wdrożyć hostowaną Blazor WebAssembly aplikację jako plik wykonywalny zależny od platformy dla określonej platformy (a nie samodzielnej), skorzystaj z poniższych wskazówek opartych na używanym narzędziu.

Visual Studio

Wdrożenie samodzielne jest skonfigurowane dla wygenerowanego profilu publikowania (.pubxml). Upewnij się, że Server profil publikowania projektu zawiera właściwość MSBuild ustawioną <SelfContained> na falsewartość .

W pliku profilu publikowania .pubxml Properties w Server folderze projektu:

<SelfContained>false</SelfContained>

Ustaw identyfikator środowiska uruchomieniowego (RID) przy użyciu ustawienia Docelowego środowiska uruchomieniowego w obszarze Ustawienia interfejsu użytkownika publikowania, który generuje <RuntimeIdentifier> właściwość MSBuild w profilu publikowania:

<RuntimeIdentifier>{RID}</RuntimeIdentifier>

W poprzedniej konfiguracji {RID} symbol zastępczy to identyfikator środowiska uruchomieniowego (RID).

Server Opublikuj projekt w konfiguracji wydania.

Uwaga

Można opublikować aplikację z ustawieniami profilu publikowania przy użyciu interfejsudotnet publish wiersza polecenia platformy .NET, przekazując /p:PublishProfile={PROFILE} polecenie , gdzie {PROFILE} symbol zastępczy jest profilem. Aby uzyskać więcej informacji, zobacz sekcje Publikowanie profilów i folderów publikowania przykładów w artykule Profile publikowania programu Visual Studio (pubxml) dla wdrożenia aplikacji platformy ASP.NET Core. Jeśli przekażesz identyfikator RID w poleceniu, a nie w profilu publikowania, użyj właściwości MSBuild (/p:RuntimeIdentifier) z poleceniem, a nie z opcją -r|--runtime .dotnet publish

.NET CLI

Skonfiguruj wdrożenie samodzielne, umieszczając <SelfContained> właściwość MSBuild w Server pliku projektu ustawionym <PropertyGroup> na wartość false:

<SelfContained>false</SelfContained>

Ważne

Właściwość SelfContained musi zostać umieszczona w Server pliku projektu. Nie można poprawnie dotnet publish ustawić właściwości za pomocą polecenia przy użyciu --no-self-contained opcji lub właściwości /p:SelfContained=falseMSBuild .

Ustaw identyfikator środowiska uruchomieniowego (RID) przy użyciu jednej z następujących metod:

  • Opcja 1. Ustaw identyfikator RID w <PropertyGroup> Server pliku projektu:

    <RuntimeIdentifier>{RID}</RuntimeIdentifier>
    

    W poprzedniej konfiguracji {RID} symbol zastępczy to identyfikator środowiska uruchomieniowego (RID).

    Opublikuj aplikację w konfiguracji wydania z Server projektu:

    dotnet publish -c Release
    
  • Opcja 2. Przekaż identyfikator RID w poleceniu dotnet publish jako właściwość MSBuild (/p:RuntimeIdentifier), a nie z opcją-r|--runtime:

    dotnet publish -c Release /p:RuntimeIdentifier={RID}
    

    W poprzednim poleceniu {RID} symbol zastępczy to identyfikator środowiska uruchomieniowego (RID).

Aby uzyskać więcej informacji, zobacz następujące artykuły:

Hostowane wdrożenie z wieloma Blazor WebAssembly aplikacjami

Aby uzyskać więcej informacji, zobacz Wiele hostowanych aplikacji ASP.NET CoreBlazor WebAssembly.

Wdrożenie autonomiczne

Wdrożenie autonomiczne służy Blazor WebAssembly aplikacji jako zestaw plików statycznych, które są żądane bezpośrednio przez klientów. Każdy statyczny serwer plików może obsługiwać aplikację Blazor .

Zasoby wdrożenia autonomicznego są publikowane w /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot folderze lub bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish\ (w zależności od używanej wersji zestawu .NET SDK), gdzie {TARGET FRAMEWORK} symbol zastępczy jest platformą docelową.

Azure App Service

Blazor WebAssemblyaplikacje można wdrażać w usługach aplikacja systemu Azure w systemie Windows, które hostuje aplikację w usługach IIS.

Wdrażanie aplikacji autonomicznej Blazor WebAssembly w usłudze aplikacja systemu Azure Service dla systemu Linux nie jest obecnie obsługiwane. Zalecamy hostowanie autonomicznej Blazor WebAssembly aplikacji przy użyciu usługi Azure Static Web Apps, która obsługuje ten scenariusz.

Azure Static Web Apps

Użyj jednej z następujących metod wdrażania Blazor WebAssembly aplikacji w usłudze Azure Static Web Apps:

Wdrażanie za pomocą programu Visual Studio

Aby wdrożyć z poziomu programu Visual Studio, utwórz profil publikowania dla usługi Azure Static Web Apps:

  1. Zapisz wszystkie niezapisane prace w projekcie, ponieważ podczas procesu może być wymagane ponowne uruchomienie programu Visual Studio.

  2. W interfejsie użytkownika publikowania programu Visual Studio wybierz pozycję Target Azure Specific Azure Target Azure Static Web Apps (Docelowy element docelowy>>usługi Azure>Static Web Apps), aby utworzyć profil publikowania.

  3. Jeśli składnik Narzędzi usługi Azure WebJobs dla programu Visual Studio nie jest zainstalowany, zostanie wyświetlony monit o zainstalowanie składnika ASP.NET i tworzenia aplikacji internetowych. Postępuj zgodnie z monitami, aby zainstalować narzędzia przy użyciu Instalator programu Visual Studio. Program Visual Studio zamyka i otwiera ponownie automatycznie podczas instalowania narzędzi. Po zainstalowaniu narzędzi zacznij od początku od pierwszego kroku, aby utworzyć profil publikowania.

  4. W konfiguracji profilu publikowania podaj nazwę subskrypcji. Wybierz istniejące wystąpienie lub wybierz pozycję Utwórz nowe wystąpienie. Podczas tworzenia nowego wystąpienia w interfejsie użytkownika tworzenia statycznej aplikacji internetowej w witrynie Azure Portal ustaw źródło szczegółów>wdrożenia na Inne. Przed kontynuowaniem poczekaj na ukończenie wdrożenia w witrynie Azure Portal.

  5. W konfiguracji profilu publikowania wybierz wystąpienie usługi Azure Static Web Apps z grupy zasobów wystąpienia. Wybierz pozycję Zakończ , aby utworzyć profil publikowania. Jeśli program Visual Studio wyświetli monit o zainstalowanie interfejsu wiersza polecenia usługi Static Web Apps (SWA), zainstaluj interfejs wiersza polecenia, postępując zgodnie z monitami. Interfejs wiersza polecenia swa wymaga narzędzia NPM/Node.js (dokumentacja programu Visual Studio).

Po utworzeniu profilu publikowania wdróż aplikację w wystąpieniu usługi Azure Static Web Apps przy użyciu profilu publikowania, wybierając przycisk Publikuj .

Wdrażanie z programu Visual Studio Code

Aby wdrożyć program Visual Studio Code, zobacz Szybki start: tworzenie pierwszej statycznej witryny przy użyciu usługi Azure Static Web Apps.

Wdrażanie z repozytorium GitHub

Aby wdrożyć aplikację z repozytorium GitHub, zobacz Samouczek: tworzenie statycznej aplikacji internetowej za pomocą Blazor usługi Azure Static Web Apps.

IIS

Usługi IIS to statyczny serwer plików dla Blazor aplikacji. Aby skonfigurować usługi IIS do hostowania Blazor, zobacz Tworzenie statycznej witryny internetowej w usługach IIS.

Opublikowane zasoby są tworzone w /bin/Release/{TARGET FRAMEWORK}/publish folderze lub bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish w zależności od używanej wersji zestawu SDK i miejsca, w którym {TARGET FRAMEWORK} symbol zastępczy jest platformą docelową. Hostowanie zawartości publish folderu na serwerze internetowym lub w usłudze hostingu.

web.config

Po opublikowaniu Blazor web.config projektu zostanie utworzony plik z następującą konfiguracją usług IIS:

  • MIME, typy
  • Kompresja HTTP jest włączona dla następujących typów MIME:
    • application/octet-stream
    • application/wasm
  • Reguły modułu ponownego zapisywania adresów URL są ustanawiane:
    • Obsługa podkatalogu, w którym znajdują się zasoby statyczne aplikacji (wwwroot/{PATH REQUESTED}).
    • Utwórz routing rezerwowy SPA, aby żądania dla zasobów innych niż pliki zostały przekierowane do domyślnego dokumentu aplikacji w folderze zasobów statycznych (wwwroot/index.html).

Używanie niestandardowego web.config

Aby użyć pliku niestandardowego web.config :

  1. Umieść plik niestandardowy web.config w folderze głównym projektu.
  2. Opublikuj projekt. Aby uzyskać więcej informacji, zobacz Host and deploy ASP.NET Core Blazor.
  1. Umieść plik niestandardowy web.config w folderze głównym projektu. W przypadku rozwiązania hostowanego Blazor WebAssemblyumieść plik w Server folderze projektu.
  2. Opublikuj projekt. W przypadku rozwiązania hostowanego Blazor WebAssembly opublikuj rozwiązanie z Server projektu. Aby uzyskać więcej informacji, zobacz Host and deploy ASP.NET Core Blazor.

Jeśli generowanie lub przekształcanie zestawu SDK web.config podczas publikowania nie przenosi pliku do opublikowanych zasobów w publish folderze lub modyfikuje konfigurację niestandardową w pliku niestandardowym web.config , należy użyć dowolnego z następujących podejść zgodnie z potrzebami, aby przejąć pełną kontrolę nad procesem:

  • Jeśli zestaw SDK nie generuje pliku, na przykład w aplikacji autonomicznej w lokalizacji lub bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish, w zależności od używanej wersji zestawu SDK i miejsca, w którym {TARGET FRAMEWORK} symbol zastępczy jest strukturą docelową, ustaw <PublishIISAssets> właściwość na true wartość w pliku projektu (.csproj)./bin/Release/{TARGET FRAMEWORK}/publish/wwwroot Blazor WebAssembly Zazwyczaj w przypadku autonomicznych aplikacji WebAssembly jest to jedyne ustawienie wymagane do przeniesienia pliku niestandardowego web.config i uniemożliwienie przekształcenia pliku przez zestaw SDK.

    <PropertyGroup>
      <PublishIISAssets>true</PublishIISAssets>
    </PropertyGroup>
    
  • Wyłącz przekształcenie zestawu SDK web.config w pliku projektu (.csproj):

    <PropertyGroup>
      <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
    </PropertyGroup>
    
  • Dodaj obiekt docelowy niestandardowy do pliku projektu (.csproj), aby przenieść plik niestandardowy web.config . W poniższym przykładzie plik niestandardowy web.config jest umieszczany przez dewelopera w katalogu głównym projektu. web.config Jeśli plik znajduje się w innym miejscu, określ ścieżkę do pliku w pliku w pliku SourceFiles. W poniższym przykładzie określono publish folder z elementem $(PublishDir), ale podaj ścieżkę do DestinationFolder niestandardowej lokalizacji wyjściowej.

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

Instalowanie modułu ponownego zapisywania adresów URL

Moduł ponownego zapisywania adresów URL jest wymagany do ponownego zapisywania adresów URL. Moduł nie jest instalowany domyślnie i nie jest dostępny do zainstalowania jako funkcja usługi roli serwera sieci Web (IIS). Moduł musi zostać pobrany z witryny sieci Web usług IIS. Zainstaluj moduł za pomocą Instalatora platformy internetowej:

  1. Lokalnie przejdź do strony pobierania modułu ponownego zapisywania adresu URL. W przypadku wersji angielskiej wybierz pozycję WebPI , aby pobrać instalatora interfejsu WebPI. W przypadku innych języków wybierz odpowiednią architekturę serwera (x86/x64), aby pobrać instalator.
  2. Skopiuj instalator do serwera. Uruchom instalatora. Wybierz przycisk Zainstaluj i zaakceptuj postanowienia licencyjne. Ponowne uruchomienie serwera nie jest wymagane po zakończeniu instalacji.

Konfigurowanie witryny internetowej

Ustaw ścieżkę fizyczną witryny internetowej do folderu aplikacji. Folder zawiera:

  • web.config Plik używany przez usługi IIS do konfigurowania witryny internetowej, w tym wymagane reguły przekierowania i typy zawartości plików.
  • Folder zasobów statycznych aplikacji.

Hostowanie jako podaplikacja usług IIS

Jeśli autonomiczna aplikacja jest hostowana jako podaplikacja usług IIS, wykonaj jedną z następujących czynności:

  • Wyłącz dziedziczoną procedurę obsługi modułu ASP.NET Core.

    Usuń procedurę obsługi w Blazor opublikowanym web.config pliku aplikacji, dodając sekcję <handlers> do <system.webServer> sekcji pliku:

    <handlers>
      <remove name="aspNetCore" />
    </handlers>
    
  • Wyłącz dziedziczenie sekcji aplikacji głównej (nadrzędnej<system.webServer>) przy użyciu elementu z ustawioną inheritInChildApplications wartością <location> false:

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

    Uwaga

    Wyłączenie dziedziczenia sekcji aplikacji głównej (nadrzędnej <system.webServer> ) jest domyślną konfiguracją opublikowanych aplikacji przy użyciu zestawu .NET SDK.

Usunięcie programu obsługi lub wyłączenie dziedziczenia jest wykonywane oprócz konfigurowania ścieżki podstawowej aplikacji. Ustaw ścieżkę podstawową aplikacji w pliku aplikacji index.html na alias usług IIS używany podczas konfigurowania podapliki w usługach IIS.

Skonfiguruj ścieżkę podstawową aplikacji, postępując zgodnie ze wskazówkami w artykule Host i wdrażanie ASP.NET Core Blazor .

Kompresja Brotli i Gzip

Ta sekcja dotyczy tylko aplikacji autonomicznych Blazor WebAssembly .

Ta sekcja dotyczy tylko aplikacji autonomicznych Blazor WebAssembly . Aplikacje hostowane Blazor używają domyślnego pliku aplikacji web.config ASP.NET Core, a nie pliku połączonego w tej sekcji.

Usługi IIS można skonfigurować za pomocą web.config polecenia , aby obsługiwać skompresowane Blazor zasoby Brotli lub Gzip dla aplikacji autonomicznych Blazor WebAssembly . Przykładowy plik konfiguracji można znaleźć w temacie web.config.

Dodatkowa konfiguracja przykładowego web.config pliku może być wymagana w następujących scenariuszach:

  • Specyfikacja aplikacji wywołuje jedną z następujących metod:
    • Obsługa skompresowanych plików, które nie są skonfigurowane przez przykładowy web.config plik.
    • Obsługa skompresowanych plików skonfigurowanych przez przykładowy web.config plik w formacie nieskompresowanym.
  • Konfiguracja usług IIS serwera (na przykład applicationHost.config) zapewnia domyślne ustawienia usług IIS na poziomie serwera. W zależności od konfiguracji na poziomie serwera aplikacja może wymagać innej konfiguracji usług IIS niż plik przykładowy web.config .

Aby uzyskać więcej informacji na temat plików niestandardowych web.config , zobacz sekcję Używanie niestandardowego web.config .

Rozwiązywanie problemów

Jeśli zostanie odebrany błąd 500 — wewnętrzny błąd serwera, a Menedżer usług IIS zgłasza błędy podczas próby uzyskania dostępu do konfiguracji witryny internetowej, upewnij się, że moduł ponownego zapisywania adresu URL jest zainstalowany. Gdy moduł nie jest zainstalowany, web.config nie można przeanalizować pliku przez usługi IIS. Uniemożliwia to menedżerowi usług IIS ładowanie konfiguracji witryny internetowej i witryny internetowej do obsługi Blazorplików statycznych.

Aby uzyskać więcej informacji na temat rozwiązywania problemów z wdrożeniami usług IIS, zobacz Rozwiązywanie problemów z programem ASP.NET Core w usłudze aplikacja systemu Azure i usługach IIS.

Azure Storage

Hostowanie plików statycznych usługi Azure Storage umożliwia hostowanie aplikacji bezserwerowych Blazor . Obsługiwane są niestandardowe nazwy domen, usługa Azure Content Delivery Network (CDN) i protokół HTTPS.

Gdy usługa blob jest włączona na potrzeby hostowania statycznej witryny internetowej na koncie magazynu:

  • Ustaw nazwę dokumentu indeksu na index.html.
  • Ustaw ścieżkę dokumentu Błąd na index.html. Razor składniki i inne punkty końcowe inne niż pliki nie znajdują się w ścieżkach fizycznych w zawartości statycznej przechowywanej przez usługę blob. Po odebraniu Blazor żądania dla jednego z tych zasobów router powinien obsługiwać błąd 404 — Nie znaleziono wygenerowany przez usługę blob kieruje żądanie do ścieżki dokumentu Błąd. Obiekt index.html blob jest zwracany, a Blazor router ładuje i przetwarza ścieżkę.

Jeśli pliki nie są ładowane w czasie wykonywania z powodu nieodpowiednich typów MIME w nagłówkach plików Content-Type , wykonaj jedną z następujących akcji:

  • Skonfiguruj narzędzia, aby ustawić poprawne typy MIME (Content-Type nagłówki) podczas wdrażania plików.

  • Zmień typy MIME (Content-Type nagłówki) dla plików po wdrożeniu aplikacji.

    W Eksplorator usługi Storage (witryna Azure Portal) dla każdego pliku:

    1. Kliknij plik prawym przyciskiem myszy i wybierz pozycję Właściwości.
    2. Ustaw właściwość ContentType i wybierz przycisk Zapisz .

Aby uzyskać więcej informacji, zobacz Statyczna witryna internetowa hostująca w usłudze Azure Storage.

Nginx

Poniższy nginx.conf plik jest uproszczony, aby pokazać, jak skonfigurować serwer Nginx do wysyłania index.html pliku zawsze, gdy nie może znaleźć odpowiedniego pliku na dysku.

events { }
http {
    server {
        listen 80;

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

W przypadku ustawiania limitu Blazor WebAssembly limit_reqszybkości serii NGINX w usłudze aplikacje mogą wymagać dużej burst wartości parametru w celu uwzględnienia stosunkowo dużej liczby żądań wysyłanych przez aplikację. Początkowo ustaw wartość na co najmniej 60:

http {
    server {
        ...

        location / {
            ...

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

Zwiększ wartość, jeśli narzędzia deweloperskie przeglądarki lub narzędzie ruchu sieciowego wskazuje, że żądania otrzymują kod stanu 503 — Usługa niedostępna .

Aby uzyskać więcej informacji na temat produkcyjnej konfiguracji serwera internetowego Nginx, zobacz Creating NGINX Plus and NGINX Configuration Files (Tworzenie plików konfiguracji NGINX Plus i NGINX).

Apache

Aby wdrożyć aplikację Blazor WebAssembly na platformie Apache:

  1. Utwórz plik konfiguracji apache. Poniższy przykład to uproszczony plik konfiguracji (blazorapp.config):

    <VirtualHost *:80>
        ServerName www.example.com
        ServerAlias *.example.com
    
        DocumentRoot "/var/www/blazorapp"
        ErrorDocument 404 /index.html
    
        AddType application/wasm .wasm
    
        <Directory "/var/www/blazorapp">
            Options -Indexes
            AllowOverride None
        </Directory>
    
        <IfModule mod_deflate.c>
            AddOutputFilterByType DEFLATE text/css
            AddOutputFilterByType DEFLATE application/javascript
            AddOutputFilterByType DEFLATE text/html
            AddOutputFilterByType DEFLATE application/octet-stream
            AddOutputFilterByType DEFLATE application/wasm
            <IfModule mod_setenvif.c>
                BrowserMatch ^Mozilla/4 gzip-only-text/html
                BrowserMatch ^Mozilla/4.0[678] no-gzip
                BrowserMatch bMSIE !no-gzip !gzip-only-text/html
            </IfModule>
        </IfModule>
    
        ErrorLog /var/log/httpd/blazorapp-error.log
        CustomLog /var/log/httpd/blazorapp-access.log common
    </VirtualHost>
    
  1. Utwórz plik konfiguracji apache. Poniższy przykład to uproszczony plik konfiguracji (blazorapp.config):

    <VirtualHost *:80>
        ServerName www.example.com
        ServerAlias *.example.com
    
        DocumentRoot "/var/www/blazorapp"
        ErrorDocument 404 /index.html
    
        AddType application/wasm .wasm
        AddType application/octet-stream .dll
    
        <Directory "/var/www/blazorapp">
            Options -Indexes
            AllowOverride None
        </Directory>
    
        <IfModule mod_deflate.c>
            AddOutputFilterByType DEFLATE text/css
            AddOutputFilterByType DEFLATE application/javascript
            AddOutputFilterByType DEFLATE text/html
            AddOutputFilterByType DEFLATE application/octet-stream
            AddOutputFilterByType DEFLATE application/wasm
            <IfModule mod_setenvif.c>
                BrowserMatch ^Mozilla/4 gzip-only-text/html
                BrowserMatch ^Mozilla/4.0[678] no-gzip
                BrowserMatch bMSIE !no-gzip !gzip-only-text/html
            </IfModule>
        </IfModule>
    
        ErrorLog /var/log/httpd/blazorapp-error.log
        CustomLog /var/log/httpd/blazorapp-access.log common
    </VirtualHost>
    
  1. Umieść plik konfiguracji apache w /etc/httpd/conf.d/ katalogu.

  2. Umieść opublikowane zasoby aplikacji (/bin/Release/{TARGET FRAMEWORK}/publish/wwwrootgdzie {TARGET FRAMEWORK} symbol zastępczy jest strukturą docelową) do /var/www/blazorapp katalogu (lokalizacji określonej DocumentRoot w pliku konfiguracji).

  3. Uruchom ponownie usługę Apache.

Aby uzyskać więcej informacji, zobacz tematy mod_mime oraz mod_deflate.

Usługa GitHub Pages

Domyślna akcja usługi GitHub, która wdraża strony, pomija wdrażanie folderów rozpoczynających się od podkreślenia, na przykład _framework folderu. Aby wdrożyć foldery rozpoczynające się od podkreślenia, dodaj pusty .nojekyll plik do gałęzi Git.

Usługa Git traktuje pliki JavaScript (JS), takie jak blazor.webassembly.js, jako tekst i konwertuje zakończenia wierszy z CRLF (kanał informacyjny powrotu karetki) do LF (kanał informacyjny wiersza) w potoku wdrażania. Te zmiany w JS plikach generują inne skróty plików niż Blazor wysyłane do klienta w blazor.boot.json pliku. Niezgodność powoduje błędy sprawdzania integralności na kliencie. Jednym z podejść do rozwiązania tego problemu jest dodanie .gitattributes pliku z wierszem *.js binary przed dodaniem zasobów aplikacji do gałęzi Git. Wiersz *.js binary konfiguruje usługę Git tak, aby traktować JS pliki jako pliki binarne, co pozwala uniknąć przetwarzania plików w potoku wdrażania. Skróty plików nieprzetworzonych plików są zgodne z wpisami w blazor.boot.json pliku, a testy integralności po stronie klienta są przekazywane. Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor WebAssembly środowisko uruchomieniowe platformy .NET i buforowanie pakietów aplikacji.

Aby obsługiwać ponowne zapisywanie adresów URL, dodaj wwwroot/404.html plik ze skryptem obsługującym przekierowywanie żądania do index.html strony. Przykład można znaleźć w SteveSandersonMS/BlazorOnGitHubPages repozytorium GitHub:

W przypadku korzystania z witryny projektu zamiast witryny organizacji zaktualizuj <base> tag w pliku wwwroot/index.html. Ustaw wartość atrybutu href na nazwę repozytorium GitHub z ukośnikiem końcowym (na przykład /my-repository/). SteveSandersonMS/BlazorOnGitHubPages W repozytorium GitHub baza href jest aktualizowana podczas publikowania.github/workflows/main.yml przez plik konfiguracji.

Uwaga

Repozytorium SteveSandersonMS/BlazorOnGitHubPages GitHub nie jest własnością, nie jest obsługiwane ani obsługiwane przez program .NET Foundation ani firmę Microsoft.

Autonomiczna platforma Docker

Autonomiczna aplikacja jest publikowana Blazor WebAssembly jako zestaw plików statycznych do hostowania przez statyczny serwer plików.

Aby hostować aplikację na platformie Docker:

  • Wybierz kontener platformy Docker z obsługą serwera internetowego, na przykład Ngnix lub Apache.
  • publish Skopiuj zasoby folderów do folderu lokalizacji zdefiniowanego na serwerze internetowym w celu obsługi plików statycznych.
  • Zastosuj dodatkową konfigurację zgodnie z potrzebami, aby obsłużyć aplikację Blazor WebAssembly .

Aby uzyskać wskazówki dotyczące konfiguracji, zobacz następujące zasoby:

Wartości konfiguracji hosta

Blazor WebAssembly aplikacje mogą akceptować następujące wartości konfiguracji hosta jako argumenty wiersza polecenia w czasie wykonywania w środowisku deweloperskich.

Katalog główny zawartości

Argument --contentroot ustawia bezwzględną ścieżkę do katalogu zawierającego pliki zawartości aplikacji (katalog główny zawartości). W poniższych przykładach /content-root-path jest ścieżka główna zawartości aplikacji.

  • Przekaż argument podczas lokalnego uruchamiania aplikacji w wierszu polecenia. W katalogu aplikacji wykonaj następujące polecenie:

    dotnet watch --contentroot=/content-root-path
    
  • Dodaj wpis do pliku aplikacji launchSettings.json w profilu usług IIS Express . To ustawienie jest używane, gdy aplikacja jest uruchamiana z debugerem programu Visual Studio i z wiersza polecenia za dotnet watch pomocą polecenia (lub dotnet run).

    "commandLineArgs": "--contentroot=/content-root-path"
    
  • W programie Visual Studio określ argument w obszarze Właściwości>Debugowanie>argumentów aplikacji. Ustawienie argumentu na stronie właściwości programu Visual Studio powoduje dodanie argumentu launchSettings.json do pliku.

    --contentroot=/content-root-path
    

Podstawa ścieżki

--pathbase Argument ustawia ścieżkę podstawową aplikacji dla aplikacji uruchamianej lokalnie przy użyciu ścieżki adresu URL innego niż główna (<base>tag href jest ustawiony na ścieżkę inną niż / w przypadku przemieszczania i produkcji). W poniższych przykładach /relative-URL-path jest bazą ścieżki aplikacji. Aby uzyskać więcej informacji, zobacz Ścieżka podstawowa aplikacji.

Ważne

W przeciwieństwie do ścieżki podanej do href tagu <base> , nie dołączaj ukośnika końcowego (/) podczas przekazywania wartości argumentu --pathbase . Jeśli ścieżka podstawowa aplikacji jest podana w tagu <base> jako <base href="/CoolApp/"> (zawiera ukośnik końcowy), przekaż wartość argumentu wiersza polecenia jako --pathbase=/CoolApp (bez końcowego ukośnika).

  • Przekaż argument podczas lokalnego uruchamiania aplikacji w wierszu polecenia. W katalogu aplikacji wykonaj następujące polecenie:

    dotnet watch --pathbase=/relative-URL-path
    
  • Dodaj wpis do pliku aplikacji launchSettings.json w profilu usług IIS Express . To ustawienie jest używane podczas uruchamiania aplikacji z debugerem programu Visual Studio i z wiersza polecenia za pomocą dotnet watch polecenia (lub dotnet run).

    "commandLineArgs": "--pathbase=/relative-URL-path"
    
  • W programie Visual Studio określ argument w obszarze Właściwości>Debugowanie>argumentów aplikacji. Ustawienie argumentu na stronie właściwości programu Visual Studio powoduje dodanie argumentu launchSettings.json do pliku.

    --pathbase=/relative-URL-path
    

Adresy URL

Argument --urls ustawia adresy IP lub adresy hostów z portami i protokołami do nasłuchiwania żądań.

  • Przekaż argument podczas lokalnego uruchamiania aplikacji w wierszu polecenia. W katalogu aplikacji wykonaj następujące polecenie:

    dotnet watch --urls=http://127.0.0.1:0
    
  • Dodaj wpis do pliku aplikacji launchSettings.json w profilu usług IIS Express . To ustawienie jest używane podczas uruchamiania aplikacji z debugerem programu Visual Studio i z wiersza polecenia za pomocą dotnet watch polecenia (lub dotnet run).

    "commandLineArgs": "--urls=http://127.0.0.1:0"
    
  • W programie Visual Studio określ argument w obszarze Właściwości>Debugowanie>argumentów aplikacji. Ustawienie argumentu na stronie właściwości programu Visual Studio powoduje dodanie argumentu launchSettings.json do pliku.

    --urls=http://127.0.0.1:0
    

Hostowane wdrożenie w systemie Linux (Nginx)

Skonfiguruj aplikację ForwardedHeadersOptions za pomocą polecenia , aby przekazywać X-Forwarded-For dalej nagłówki i X-Forwarded-Proto , postępując zgodnie ze wskazówkami w temacie Konfigurowanie ASP.NET Core do pracy z serwerami proxy i modułami równoważenia obciążenia.

Aby uzyskać więcej informacji na temat ustawiania ścieżki podstawowej aplikacji, w tym konfiguracji ścieżki podrzędnej aplikacji, zobacz Host and deploy ASP.NET Core Blazor.

Postępuj zgodnie ze wskazówkami dotyczącymi aplikacji ASP.NET Core SignalR z następującymi zmianami:

  • Usuń konfigurację buforowania serwera proxy (proxy_buffering off;), ponieważ ustawienie ma zastosowanie tylko do zdarzeń wysłanych przez serwer (SSE), które nie są istotne dla Blazor interakcji między klientem aplikacji a serwerem.

  • Zmień ścieżkę location z /hubroute (location /hubroute { ... }) na ścieżkę /{PATH} podrzędną aplikacji (location /{PATH} { ... }), gdzie {PATH} symbol zastępczy to ścieżka podrzędna aplikacji.

    Poniższy przykład umożliwia skonfigurowanie serwera dla aplikacji, która odpowiada na żądania w ścieżce /głównej :

    http {
        server {
            ...
            location / {
                ...
            }
        }
    }
    

    Poniższy przykład umożliwia skonfigurowanie ścieżki podrzędnej aplikacji :/blazor

    http {
        server {
            ...
            location /blazor {
                ...
            }
        }
    }
    

Aby uzyskać więcej informacji i wskazówek dotyczących konfiguracji, zapoznaj się z następującymi zasobami:

Konfigurowanie elementu przycinającego

Blazor Wykonuje przycinanie języka pośredniego (IL) dla każdej kompilacji wydania, aby usunąć niepotrzebne il z zestawów wyjściowych. Aby uzyskać więcej informacji, zobacz Configure the Trimmer for ASP.NET Core (Konfigurowanie programu Trimmer dla platformy ASP.NET Core Blazor).

Konfigurowanie konsolidatora

Blazor Program wykonuje łączenie języka pośredniego (IL) dla każdej kompilacji wydania, aby usunąć niepotrzebne il z zestawów wyjściowych. Aby uzyskać więcej informacji, zobacz Konfigurowanie konsolidatora dla platformy ASP.NET Core Blazor.

Zmienianie rozszerzenia nazwy pliku plików DLL

Ta sekcja dotyczy ASP.NET Core 6.x i 7.x. W programie ASP.NET Core na platformie .NET 8 lub nowszym zestawy platformy .NET są wdrażane jako pliki WebAssembly (.wasm) przy użyciu formatu pliku Webcil. W ASP.NET Core na platformie .NET 8 lub nowszym ta sekcja ma zastosowanie tylko wtedy, gdy format pliku webcil został wyłączony w pliku projektu aplikacji.

Jeśli zapora, program antywirusowy lub urządzenie zabezpieczeń sieci blokuje przesyłanie plików biblioteki dynamicznej (DLL) aplikacji (.dll), możesz postępować zgodnie ze wskazówkami w tej sekcji, aby zmienić rozszerzenia nazw plików opublikowanej przez aplikację plików DLL.

Uwaga

Zmiana rozszerzeń nazw plików DLL aplikacji może nie rozwiązać problemu, ponieważ wiele systemów zabezpieczeń skanuje zawartość plików aplikacji, a nie tylko sprawdza rozszerzenia plików.

W przypadku bardziej niezawodnego podejścia w środowiskach, które blokują pobieranie i wykonywanie plików DLL, należy użyć ASP.NET Core na platformie .NET 8 lub nowszej, która pakuje zestawy .NET jako pliki WebAssembly (.wasm) przy użyciu formatu pliku Webcil . Aby uzyskać więcej informacji, zobacz sekcję Format pakietu Webcil dla zestawów .NET w wersji 8.0 lub nowszej tego artykułu.

Istnieją podejścia innych firm do radzenia sobie z tym problemem. Aby uzyskać więcej informacji, zobacz zasoby na stronie Awesome Blazor.

Uwaga

Zmiana rozszerzeń nazw plików DLL aplikacji może nie rozwiązać problemu, ponieważ wiele systemów zabezpieczeń skanuje zawartość plików aplikacji, a nie tylko sprawdza rozszerzenia plików.

W przypadku bardziej niezawodnego podejścia w środowiskach, które blokują pobieranie i wykonywanie plików DLL, wykonaj jedną z następujących metod:

Istnieją podejścia innych firm do radzenia sobie z tym problemem. Aby uzyskać więcej informacji, zobacz zasoby na stronie Awesome Blazor.

Po opublikowaniu aplikacji użyj skryptu powłoki lub potoku kompilacji DevOps, aby zmienić nazwy .dll plików, aby użyć innego rozszerzenia pliku w katalogu opublikowanych danych wyjściowych aplikacji.

W następujących przykładach:

  • Program PowerShell (PS) służy do aktualizowania rozszerzeń plików.
  • .dll Nazwy plików są zmieniane tak, aby używały .bin rozszerzenia pliku z wiersza polecenia.
  • Pliki wymienione w opublikowanym blazor.boot.json .dll pliku z rozszerzeniem pliku są aktualizowane do .bin rozszerzenia pliku.
  • Jeśli zasoby procesu roboczego usługi są również używane, polecenie programu PowerShell aktualizuje .dll pliki wymienione w service-worker-assets.js pliku do .bin rozszerzenia pliku.

Aby użyć innego rozszerzenia pliku niż .bin, zastąp .bin w następujących poleceniach żądanym rozszerzeniem pliku.

W systemie Windows:

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

W poprzednim poleceniu {PATH} symbol zastępczy jest ścieżką do opublikowanego _framework folderu (na przykład .\bin\Release\net6.0\browser-wasm\publish\wwwroot\_framework z folderu głównego projektu).

Jeśli zasoby procesu roboczego usługi są również używane:

((Get-Content {PATH}\service-worker-assets.js -Raw) -replace '.dll"','.bin"') | Set-Content {PATH}\service-worker-assets.js

W poprzednim poleceniu {PATH} symbol zastępczy jest ścieżką do opublikowanego service-worker-assets.js pliku.

W systemie Linux lub macOS:

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

W poprzednim poleceniu {PATH} symbol zastępczy jest ścieżką do opublikowanego _framework folderu (na przykład .\bin\Release\net6.0\browser-wasm\publish\wwwroot\_framework z folderu głównego projektu).

Jeśli zasoby procesu roboczego usługi są również używane:

sed -i 's/\.dll"/.bin"/g' {PATH}/service-worker-assets.js

W poprzednim poleceniu {PATH} symbol zastępczy jest ścieżką do opublikowanego service-worker-assets.js pliku.

Aby rozwiązać problem skompresowanych blazor.boot.json.gz plików i blazor.boot.json.br plików, należy zastosować jedną z następujących metod:

  • Usuń skompresowane blazor.boot.json.gz pliki i blazor.boot.json.br . Kompresja jest wyłączona przy użyciu tego podejścia.
  • Ponownie skompresuj zaktualizowany blazor.boot.json plik.

Powyższe wskazówki dotyczące skompresowanego blazor.boot.json pliku dotyczą również sytuacji, w których są używane zasoby procesu roboczego usługi. Usuń lub ponownie skompresuj service-worker-assets.js.br i service-worker-assets.js.gz. W przeciwnym razie sprawdzanie integralności plików nie powiedzie się w przeglądarce.

Poniższy przykład systemu Windows dla platformy .NET 6 używa skryptu programu PowerShell umieszczonego w katalogu głównym projektu. Poniższy skrypt, który wyłącza kompresję, jest podstawą dalszej modyfikacji, jeśli chcesz ponownie skompresować blazor.boot.json plik.

ChangeDLLExtensions.ps1::

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

Jeśli zasoby procesu roboczego usługi są również używane, dodaj następujące polecenia:

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

W pliku projektu skrypt jest wykonywany po opublikowaniu Release aplikacji dla konfiguracji:

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

Uwaga

Podczas zmieniania nazw i ładowania leniwych tych samych zestawów zobacz wskazówki w temacie Lazy load assemblies in ASP.NET Core ( Wskazówki dotyczące ładowania zestawów z opóźnieniem w systemie ASP.NET Core Blazor WebAssembly).

Zazwyczaj serwer aplikacji wymaga konfiguracji zasobów statycznych w celu obsługi plików przy użyciu zaktualizowanego rozszerzenia. W przypadku aplikacji hostowanej przez usługi IIS dodaj wpis mapy MIME (<mimeMap>) dla nowego rozszerzenia pliku w sekcji zawartości statycznej (<staticContent>) w pliku niestandardowym web.config . W poniższym przykładzie przyjęto założenie, że rozszerzenie pliku zostało zmienione z .dll na .bin:

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

Dołącz aktualizację skompresowanych plików, jeśli kompresja jest używana:

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

Usuń wpis rozszerzenia .dll pliku:

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

Usuń wpisy skompresowanych .dll plików, jeśli kompresja jest używana:

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

Aby uzyskać więcej informacji na temat plików niestandardowych web.config , zobacz sekcję Używanie niestandardowego web.config .

Wcześniejsze uszkodzenie wdrożenia

Zazwyczaj w przypadku wdrożenia:

  • Tylko zmienione pliki są zastępowane, co zwykle skutkuje szybszym wdrożeniem.
  • Istniejące pliki, które nie są częścią nowego wdrożenia, są pozostawione do użycia przez nowe wdrożenie.

W rzadkich przypadkach utrzymujące się pliki z wcześniejszego wdrożenia mogą uszkodzić nowe wdrożenie. Całkowite usunięcie istniejącego wdrożenia (lub lokalnie opublikowanej aplikacji przed wdrożeniem) może rozwiązać problem z uszkodzonym wdrożeniem. Często usunięcie istniejącego wdrożenia wystarczy , aby rozwiązać ten problem, w tym w przypadku potoku kompilacji i wdrażania metodyki DevOps.

Jeśli ustalisz, że wyczyszczenie wcześniejszego wdrożenia jest zawsze wymagane, gdy potok kompilacji i wdrażania metodyki DevOps jest używany, możesz tymczasowo dodać krok do potoku kompilacji, aby usunąć poprzednie wdrożenie dla każdego nowego wdrożenia, dopóki nie rozwiążesz dokładnej przyczyny uszkodzenia.

Rozwiązywanie problemów z błędami sprawdzania integralności

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 bibliotek DLL (.dll), Zestawu WebAssembly (.wasm) i innych plików w blazor.boot.json pliku, które nie są buforowane na klientach. 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.

Aby uzyskać informacje o Blazor WebAssemblyźródle odwołania do rozruchu, zobacz Boot.WebAssembly.ts plik w dotnet/aspnetcore repozytorium GitHub.

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 {USER} zastępczy 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 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 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.