ASP.NET Core-Blazor WebAssembly hosten en implementeren

In dit artikel wordt uitgelegd hoe u Blazor WebAssembly host en implementeert met behulp van ASP.NET Core, Content Delivery Networks (CDN), bestandsservers en GitHub Pages.

Met het Blazor WebAssembly hostingmodel:

• De Blazor-app, de bijbehorende afhankelijkheden en de .NET-runtime worden parallel naar de browser gedownload.
• De app wordt rechtstreeks uitgevoerd in de browser-UI-thread.

Dit artikel heeft betrekking op het implementatiescenario waarin de Blazor-app wordt geplaatst op een statische hostingwebserver of -service. .NET wordt niet gebruikt voor de Blazor-app. Deze strategie wordt behandeld in de sectie Zelfstandige implementatie, waaronder informatie over het hosten van een Blazor WebAssembly-app als een IIS-sub-app.

Hosting van subdomeinen en IIS-subtoepassingen

Voor het hosten van subdomeinen is geen speciale configuratie van de app vereist. U hoeft het basispad van de app (de <base> tag in wwwroot/index.html) niet te configureren om de app op een subdomein te hosten.

IiS-subtoepassing die als host fungeert voor vereist dat u het basispad van de app moet instellen. Zie Host en implementeer ASP.NET Core Blazorvoor meer informatie en kruiskoppelingen naar verdere richtlijnen voor het hosten van IIS-subtoepassingen.

Maximale heapgrootte verkleinen voor sommige browsers voor mobiele apparaten

Bij het bouwen van een Blazor-app die wordt uitgevoerd op de client (.Client-project van een Blazor Web App- of zelfstandige Blazor WebAssembly-app) en specifiek is gericht op optimalisatie voor browsers op mobiele apparaten, met name Safari op iOS, kan het nodig zijn om het maximale geheugen voor de app aan te passen met de MSBuild-eigenschap EmccMaximumHeapSize. De standaardwaarde is 2.147.483.648 bytes, wat mogelijk te groot is en ertoe leidt dat de app vastloopt als de app probeert meer geheugen toe te wijzen met de browser deze niet kan verlenen. In het volgende voorbeeld wordt de waarde ingesteld op 268.435.456 bytes in het bestand Program:

<EmccMaximumHeapSize>268435456</EmccMaximumHeapSize>

Zie dotnet/runtimevoor meer informatie over Mono/WebAssembly MSBuild-eigenschappen en -doelen.

Indeling van Webcil-verpakkingsformaat voor .NET-assemblies

Webcil is een webvriendelijke verpakkingsindeling voor .NET-assembly's die zijn ontworpen om het gebruik van Blazor WebAssembly in beperkende netwerkomgevingen mogelijk te maken. Webcil-bestanden maken gebruik van een standaard WebAssembly-wrapper, waarbij de assembly's worden geïmplementeerd als WebAssembly-bestanden die gebruikmaken van de standaardbestandsextensie .wasm.

Webcil is de standaardindeling voor pakketten wanneer u een Blazor WebAssembly-app publiceert. Als u het gebruik van Webcil wilt uitschakelen, stelt u de volgende MSBuild-eigenschap in het projectbestand van de app in:

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

Aanpassen hoe opstartbronnen worden geladen

Pas aan hoe opstartbronnen worden geladen met behulp van de loadBootResource-API. Zie ASP.NET Core Blazor startupvoor meer informatie.

Compressie

Wanneer een Blazor WebAssembly-app wordt gepubliceerd, wordt de uitvoer statisch gecomprimeerd tijdens het publiceren om de grootte van de app te verminderen en de overhead voor runtimecompressie te verwijderen. De volgende compressiealgoritmen worden gebruikt:

• Brotli (hoogste niveau)
• Gzip

Blazor vertrouwt erop dat de host de juiste gecomprimeerde bestanden levert. Bij het hosten van een zelfstandige Blazor WebAssembly-app is mogelijk extra werk vereist om ervoor te zorgen dat statisch gecomprimeerde bestanden worden geleverd:

• Zie de sectie web.config voor configuratie van IIS-.
• Bij het hosten van statische hostingoplossingen die geen ondersteuning bieden voor statische gecomprimeerde bestandsinhoudsonderhandeling, kunt u overwegen om de app te configureren voor het ophalen en decoderen van gecomprimeerde Brotli-bestanden:

Haal de JavaScript Brotli-decoder op uit de google/brotli GitHub-opslagplaats. Het minified decoder-bestand heet decode.min.js en bevindt zich in de map js van de opslagplaats.

Notitie

Als de geminimaliseerde versie van het decode.js-script (decode.min.js) mislukt, probeer dan de ongeminimaliseerde versie (decode.js) in plaats daarvan.

Werk de app bij om de decoder te gebruiken.

Stel in het bestand wwwroot/index.htmlautostart op false op de Blazor-tag van <script>:

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

Voeg na Blazor's <script> tag en vóór de afsluitende </body> tag het volgende JavaScript-codeblok <script> toe. Met de volgende functie wordt fetch aangeroepen met cache: 'no-cache' om de cache van de browser bijgewerkt te houden.

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>

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

Zie ASP.NET Core Blazor opstartenvoor meer informatie over het laden van opstartresources.

Als u compressie wilt uitschakelen, voegt u de eigenschap CompressionEnabled MSBuild toe aan het projectbestand van de app en stelt u de waarde in op false:

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

De eigenschap CompressionEnabled kan worden doorgegeven aan de opdracht dotnet publish met de volgende syntaxis in een opdrachtshell:

dotnet publish -p:CompressionEnabled=false

URL's herschrijven voor de juiste routering

Routeringsaanvragen voor paginaonderdelen in een Blazor WebAssembly-app is niet zo eenvoudig als routeringsaanvragen in een Blazor Server-app. Overweeg een Blazor WebAssembly-app met twee onderdelen:

• Main.razor: wordt in de rootdirectory van de app geladen en bevat een koppeling naar de About-component (href="About").
• About.razor: About onderdeel.

Wanneer het standaarddocument van de app wordt aangevraagd met behulp van de adresbalk van de browser (bijvoorbeeld https://www.contoso.com/):

1. De browser doet een aanvraag.
2. De standaardpagina wordt geretourneerd. Dit is meestal index.html.
3. index.html initialiseert de app.
4. Router onderdeel wordt geladen en het RazorMain onderdeel wordt weergegeven.

Op de hoofdpagina werkt het selecteren van de koppeling naar het About-component op de client omdat de Blazor router de browser ervan weerhoudt een verzoek te doen op internet naar www.contoso.com voor About en het weergegeven About-component zelf aflevert. Alle aanvragen voor interne eindpunten binnen de Blazor WebAssembly-app werken op dezelfde manier: aanvragen activeren geen browsergebaseerde aanvragen naar server-gehoste bronnen op het internet. De router verwerkt de aanvragen intern.

Als een aanvraag wordt gedaan met behulp van de adresbalk van de browser voor www.contoso.com/About, mislukt de aanvraag. Er bestaat geen dergelijke resource op de internethost van de app. Er wordt dus een 404 - Niet gevonden antwoord geretourneerd.

Omdat browsers aanvragen indienen bij internetgebaseerde hosts voor pagina's aan de clientzijde, moeten webservers en hostingaanbieders alle aanvragen voor middelen die niet fysiek op de server staan naar de index.html-pagina herschrijven. Wanneer index.html wordt geretourneerd, neemt de router van de app Blazor het over en verzendt de juiste resource.

Wanneer u implementeert op een IIS-server, kunt u de URL-module herschrijven met het gepubliceerde web.config-bestand van de app. Zie de sectie IIS voor meer informatie.

Zelfstandige implementatie

Een zelfstandige implementatie dient de Blazor WebAssembly-app als een set statische bestanden die rechtstreeks door clients worden aangevraagd. Elke statische bestandsserver kan de Blazor-app bedienen.

Zelfstandige implementatieassets worden gepubliceerd in de map /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot of bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish\ (afhankelijk van de versie van de .NET SDK die wordt gebruikt), waarbij de tijdelijke aanduiding {TARGET FRAMEWORK} het doelframework is.

Azure App Service

Blazor WebAssembly apps kunnen worden geïmplementeerd in Azure App Services in Windows, die als host fungeert voor de app op IIS-.

Het implementeren van een zelfstandige Blazor WebAssembly-app in Azure App Service voor Linux wordt momenteel niet ondersteund. Het is raadzaam om een zelfstandige Blazor WebAssembly-app te hosten met behulp van Azure Static Web Apps, dat dit scenario ondersteunt.

Azure Static Web Apps

Gebruik een van de volgende methoden om een Blazor WebAssembly-app te implementeren in Azure Static Web Apps:

• implementeren vanuit Visual Studio
• Implementeren vanuit Visual Studio Code
• implementeren vanuit GitHub

Implementeren vanuit Visual Studio

Als u wilt implementeren vanuit Visual Studio, maakt u een publicatieprofiel voor Azure Static Web Apps:

1. Sla niet-opgeslagen werk in het project op, omdat het opnieuw opstarten van Visual Studio mogelijk vereist is tijdens het proces.

2. Selecteer in de gebruikersinterface van Visual Studio PublishTarget>Azure>Specific Target>Azure Static Web Apps om een profielte maken.

3. Als het onderdeel Azure WebJobs Tools voor Visual Studio niet is geïnstalleerd, verschijnt er een prompt om het ASP.NET- en webontwikkelingsonderdeel te installeren. Volg de aanwijzingen om de hulpprogramma's te installeren met behulp van het Installatieprogramma van Visual Studio. Visual Studio wordt automatisch gesloten en opnieuw geopend tijdens het installeren van de hulpprogramma's. Nadat de hulpprogramma's zijn geïnstalleerd, begint u opnieuw bij de eerste stap om het publicatieprofiel te maken.

4. Stel in de configuratie van het publicatieprofiel de naam van het abonnement in. Selecteer een bestaand exemplaar of selecteer Een nieuw exemplaar maken. Wanneer u een nieuw exemplaar maakt in de Statische web-app maken ui van de Azure-portal, stelt u de details van de -implementatie in>Bron in op Andere. Wacht tot de implementatie is voltooid in Azure Portal voordat u doorgaat.

5. Kies in de configuratie van het publicatieprofiel het Azure Static Web Apps-exemplaar uit de resourcegroep van het exemplaar. Selecteer Voltooien om het publicatieprofiel te maken. Als Visual Studio wordt gevraagd om de SWA-CLI (Static Web Apps) te installeren, installeert u de CLI door de aanwijzingen te volgen. De SWA CLI vereist NPM/Node.js (Visual Studio-documentatie).

Nadat het publicatieprofiel is gemaakt, implementeert u de app in het Azure Static Web Apps-exemplaar met behulp van het publicatieprofiel door de knop Publiceren te selecteren.

Implementeren vanuit Visual Studio Code

Zie Quickstart: Uw eerste statische site bouwen met Azure Static Web Appsom te implementeren vanuit Visual Studio Code.

Implementeren vanuit GitHub

Zie zelfstudie: Een statische web-app bouwen met Blazor in Azure Static Web Appsvoor implementatie vanuit een GitHub-opslagplaats.

IIS

IIS is een geschikte statische bestandsserver voor Blazor apps. Zie Blazorom IIS te configureren voor het hosten van .

Gepubliceerde assets worden gemaakt in de map /bin/Release/{TARGET FRAMEWORK}/publish of bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish, afhankelijk van welke versie van de SDK wordt gebruikt en waar de tijdelijke aanduiding {TARGET FRAMEWORK} het doelframework is. Host de inhoud van de map publish op de webserver of hostingservice.

web.config

Wanneer een Blazor project wordt gepubliceerd, wordt er een web.config-bestand gemaakt met de volgende IIS-configuratie:

• MIME-typen
• HTTP-compressie is ingeschakeld voor de volgende MIME-typen:
  • application/octet-stream
  • application/wasm
• Moduleregels voor het herschrijven van URL's zijn tot stand gebracht:
  • Bedient de submap waar de statische assets van de app zich bevinden (wwwroot/{PATH REQUESTED}).
  • Spa-terugvalroutering maken zodat aanvragen voor niet-bestandsassets worden omgeleid naar het standaarddocument van de app in de map met statische activa (wwwroot/index.html).

Een aangepaste web.config gebruiken

Een aangepast web.config-bestand gebruiken:

1. Plaats het aangepaste web.config bestand in de hoofdmap van het project.
2. Publiceer het project. Zie Host en implementeer ASP.NET Core Blazorvoor meer informatie.

Als de web.config-generatie of -transformatie van de SDK tijdens het publiceren het bestand niet verplaatst naar gepubliceerde assets in de publish-map of de aangepaste configuratie wijzigt in uw aangepaste web.config-bestand, gebruik dan een van de volgende benaderingen om het proces volledig te beheren:

• Als de SDK het bestand niet genereert, bijvoorbeeld in een zelfstandige Blazor WebAssembly-app op /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot of bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish, afhankelijk van welke versie van de SDK wordt gebruikt en waar de {TARGET FRAMEWORK} tijdelijke aanduiding het doelframework is, stelt u de eigenschap <PublishIISAssets> in op true in het projectbestand (.csproj). Meestal voor zelfstandige WebAssembly-apps is dit de enige vereiste instelling om een aangepast web.config-bestand te verplaatsen en transformatie van het bestand door de SDK te voorkomen.

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

• Schakel de web.config transformatie van de SDK uit in het projectbestand (.csproj):

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

• Voeg een aangepast doel toe aan het projectbestand (.csproj) om een aangepast web.config-bestand te verplaatsen. In het volgende voorbeeld wordt het aangepaste web.config bestand door de ontwikkelaar in de hoofdmap van het project geplaatst. Als het web.config bestand zich elders bevindt, geeft u het pad naar het bestand op in SourceFiles. In het volgende voorbeeld wordt de map publish met $(PublishDir)opgegeven, maar geeft u een pad op naar DestinationFolder voor een aangepaste uitvoerlocatie.

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

De URL-herschrijfmodule installeren

De URL-rewritemodule is nodig om URL's te herschrijven. De module is niet standaard geïnstalleerd en is niet beschikbaar voor installatie als een rolservicefunctie voor webservers (IIS). De module moet worden gedownload van de IIS-website. Gebruik het webplatforminstallatieprogramma om de module te installeren:

1. Navigeer lokaal naar de pagina voor het downloaden van de URL Rewrite Module. Selecteer voor de Engelse versie WebPI- om het WebPI-installatieprogramma te downloaden. Selecteer voor andere talen de juiste architectuur voor de server (x86/x64) om het installatieprogramma te downloaden.
2. Kopieer het installatieprogramma naar de server. Voer het installatieprogramma uit. Selecteer de knop Installeren en accepteer de licentievoorwaarden. Opnieuw opstarten van de server is niet vereist nadat de installatie is voltooid.

De website configureren

Stel het fysieke pad van de website in op de map van de app. De map bevat:

• Het web.config-bestand dat DOOR IIS wordt gebruikt om de website te configureren, inclusief de vereiste omleidingsregels en bestandstypen.
• De map met statische bestanden van de app.

Hosting als een IIS subapp

Als een zelfstandige app wordt gehost als een IIS-sub-app, voert u een van de volgende handelingen uit:

• Schakel de overgenomen ASP.NET Core Module-handler uit.

  Verwijder de handler in het gepubliceerde Blazor-bestand van de web.config-app door een <handlers> sectie toe te voegen aan de sectie <system.webServer> van het bestand:

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

• Schakel overname van de <system.webServer> sectie van de hoofd-app uit met behulp van een <location> element met inheritInChildApplications ingesteld op 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>
  

  Notitie

  Het uitschakelen van overname van de hoofd-app (bovenliggende) <system.webServer> sectie is de standaardconfiguratie voor gepubliceerde apps met behulp van de .NET SDK.

Het verwijderen van de handler of het uitschakelen van overerving wordt uitgevoerd naast het configureren van het basispad van de app . Stel het basispad van de app in het index.html-bestand van de app in op de IIS-alias die wordt gebruikt bij het configureren van de sub-app in IIS.

Configureer het basispad van de app door de richtlijnen in de Host te volgen en ASP.NET Core Blazor artikel te implementeren.

Brotli- en Gzip-compressie

Deze sectie is alleen van toepassing op zelfstandige Blazor WebAssembly-apps.

IIS kan worden geconfigureerd via web.config voor Brotli-gecomprimeerde of Gzip-gecomprimeerde Blazor-assets voor zelfstandige Blazor WebAssembly-apps. Zie web.configvoor een voorbeeldconfiguratiebestand.

In de volgende scenario's is mogelijk aanvullende configuratie van het web.config-bestand vereist:

• De specificatie van de app roept een van de volgende aan:
  • Gecomprimeerde bestanden leveren die niet door voorbeeldbestand web.config zijn geconfigureerd.
  • Gecomprimeerde bestanden aanbieden zoals geconfigureerd door het voorbeeldbestand web.config in ongecomprimeerde vorm.
• De IIS-configuratie van de server (bijvoorbeeld applicationHost.config) biedt iis-standaardinstellingen op serverniveau. Afhankelijk van de configuratie op serverniveau vereist de app mogelijk een andere IIS-configuratie dan wat het voorbeeld web.config bestand bevat.

Zie de sectie web.config gebruiken voor meer informatie over aangepaste -bestanden.

Probleemoplossing

Als een 500 - Interne serverfout wordt ontvangen en IIS-beheer fouten genereert bij het openen van de configuratie van de website, controleert u of de URL-herschrijfmodule is geïnstalleerd. Wanneer de module niet is geïnstalleerd, kan het web.config bestand niet worden geparseerd door IIS. Dit voorkomt dat IIS Manager de configuratie van de website laadt en dat de website de statische bestanden van Blazordient.

Zie Problemen met ASP.NET Core in Azure App Service en IIS-oplossen voor meer informatie over het oplossen van problemen met implementaties in IIS.

Azure Storage

Azure Storage het hosten van statische bestanden staat serverloze Blazor app-hosting toe. Aangepaste domeinnamen, het Azure Content Delivery Network (CDN) en HTTPS worden ondersteund.

Wanneer de blob-service is ingeschakeld voor het hosten van statische websites in een opslagaccount:

• Stel de naam van het indexdocument in op index.html.
• Stel het foutdocumentpad in op index.html. Razor onderdelen en andere niet-bestandseindpunten bevinden zich niet op fysieke paden in de statische inhoud die is opgeslagen door de blobservice. Wanneer een aanvraag voor een van deze resources wordt ontvangen die de Blazor router moet verwerken, stuurt de 404 - Niet gevonden fout die is gegenereerd door de blobservice de aanvraag naar het pad van het foutdocument. De index.html blob wordt geretourneerd en de Blazor router laadt en verwerkt het pad.

Als bestanden tijdens runtime niet worden geladen vanwege ongepaste MIME-typen in de Content-Type headers van de bestanden, voert u een van de volgende acties uit:

• Configureer uw hulpprogramma's om de juiste MIME-typen (Content-Type headers) in te stellen wanneer de bestanden worden geïmplementeerd.

• Wijzig de MIME-typen (Content-Type headers) voor de bestanden nadat de app is geïmplementeerd.

  In Storage Explorer (Azure Portal) voor elk bestand:

  1. Klik met de rechtermuisknop op het bestand en selecteer Eigenschappen.
  2. Stel de ContentType- in en selecteer de knop Opslaan.

Zie Statische website hosten in Azure Storagevoor meer informatie.

Nginx

Het volgende nginx.conf bestand is vereenvoudigd om te laten zien hoe u Nginx configureert om het index.html-bestand te verzenden wanneer er geen bijbehorend bestand op schijf kan worden gevonden.

events { }
http {
    server {
        listen 80;

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

Bij het instellen van de NGINX-burstsnelheidslimiet met limit_req, is voor Blazor WebAssembly apps mogelijk een grote burst parameterwaarde vereist om het relatief grote aantal aanvragen van een app aan te kunnen. Stel in eerste instantie de waarde in op ten minste 60:

http {
    server {
        ...

        location / {
            ...

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

Verhoog de waarde als hulpprogramma's voor browserontwikkelaars of een hulpprogramma voor netwerkverkeer aangeeft dat aanvragen een 503 - Service niet beschikbaar statuscode ontvangen.

Zie NGINX Plus- en NGINX-configuratiebestanden makenvoor meer informatie over de configuratie van Nginx-webservers.

Apache

Een Blazor WebAssembly-app implementeren in Apache:

1. Maak het Apache-configuratiebestand. Het volgende voorbeeld is een vereenvoudigd configuratiebestand (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. Plaats het Apache-configuratiebestand in de /etc/httpd/conf.d/ map.

2. Plaats de gepubliceerde assets van de app (/bin/Release/{TARGET FRAMEWORK}/publish/wwwroot, waarbij de tijdelijke aanduiding {TARGET FRAMEWORK} het doelframework is) in de /var/www/blazorapp map (de locatie die is opgegeven voor DocumentRoot in het configuratiebestand).

3. Start de Apache-service opnieuw op.

Zie mod_mime en mod_deflatevoor meer informatie.

GitHub Pages

De volgende richtlijnen voor Implementaties van GitHub Pages van Blazor WebAssembly-apps laten concepten zien met een live-hulpprogramma dat is geïmplementeerd op GitHub Pages. Het hulpprogramma wordt gebruikt door de ASP.NET Core-documentatieauteurs om kruisverwijzingskoppelingen (XREF) te maken naar API-documentatie voor artikel Markdown:

• BlazorWebAssemblyXrefGenerator voorbeeld-app (blazor-samples/BlazorWebAssemblyXrefGenerator)
• Live Xref Generator-website

GitHub Pages-instellingen

• Acties>Algemeen
  • Actiemachtigingen
    • Ondernemingsacties toestaan, niet-ondernemingsacties en herbruikbare werkstromen selecteren> Ingeschakeld (geselecteerd)
    • Acties toestaan die zijn gemaakt door GitHub> Ingeschakeld (geselecteerd)
    • Acties en herbruikbare werkstromen toestaan>stevesandersonms/ghaction-rewrite-base-href@v1,
  • werkstroommachtigingen>machtigingen voor het lezen van repository-inhoud en pakketten
• Pages>Bouwen en implementatie
  • Bron>GitHub Actions
  • Geselecteerde werkstroom: statische HTML- en baseer het script voor de statische implementatieactie op het Xref Generator-static.yml-bestand voor het hulpprogramma Xref Generator. De configuratie in het bestand wordt beschreven in de volgende sectie.
  • Aangepast domein: Stel in of u een aangepast domein wilt gebruiken, dat niet wordt gedekt door deze richtlijnen. Zie Een aangepast domein configureren voor uw GitHub Pages-sitevoor meer informatie.
  • Afdwingen van HTTPS> ingeschakeld (geselecteerd)

Configuratie van statische implementatiescripts

Xref Generator static.yml-bestand

Configureer de volgende vermeldingen in het script voor uw implementatie:

• Publicatiemap (PUBLISH_DIR): Gebruik het pad naar de map van de opslagplaats waar de Blazor WebAssembly-app wordt gepubliceerd. De app wordt gecompileerd voor een specifieke .NET-versie en het padsegment voor de versie moet overeenkomen. Voorbeeld: BlazorWebAssemblyXrefGenerator/bin/Release/net9.0/publish/wwwroot is het pad voor een app die de net9.0Target Framework Moniker (TFM) gebruikt voor de .NET 9.0 SDK
• Push-pad (on:push:paths): Stel het push-pad in zodat deze overeenkomt met de map van de opslagplaats van de app, met een jokerteken **. Voorbeeld: BlazorWebAssemblyXrefGenerator/**
• .NET SDK-versie (dotnet-version via de actions/setup-dotnet Action): Op dit moment is het niet mogelijk de versie in te stellen op 'laatste' (zie 'latest' toestaan als dotnet-version (actions/setup-dotnet #497) om te stemmen voor de functieaanvraag). Stel de SDK-versie in ten minste zo hoog als de frameworkversie van de app.
• Publicatiepad (dotnet publish opdracht): Stel het pad naar de publicatiemap in op de opslagplaatsmap van de app. Voorbeeld: dotnet publish BlazorWebAssemblyXrefGenerator -c Release
• Basis-HREF (base_href voor de SteveSandersonMS/ghaction-rewrite-base-href-actie): Stel de basis-href voor de app in op de naam van de opslagplaats. Voorbeeld: de eigenaar van de opslagplaats van het Blazor voorbeeld is dotnet. De naam van de opslagplaats van het Blazor voorbeeld is blazor-samples. Wanneer het hulpprogramma Xref Generator wordt geïmplementeerd op GitHub Pages, is het webadres gebaseerd op de naam van de opslagplaats (https://dotnet.github.io/blazor-samples/). De basis href van de app is /blazor-samples/, die wordt ingesteld op base_href voor de ghaction-rewrite-base-href actie, zodat er naar de wwwroot/index.html<base>-tag van de app geschreven kan worden wanneer de app wordt geïmplementeerd. Zie Host en implementeer ASP.NET Core Blazorvoor meer informatie.

Op de GitHub-hostende Ubuntu-server (nieuwste) is een versie van de .NET SDK vooraf geïnstalleerd. U kunt de actions/setup-dotnet actie stap uit het static.yml script verwijderen als de vooraf geïnstalleerde .NET SDK voldoende is om de app te compileren. Om te bepalen welke .NET SDK voor ubuntu-latestis geïnstalleerd:

1. Ga naar de sectie Beschikbare afbeeldingen van de actions/runner-images GitHub-opslagplaats.
2. Zoek de ubuntu-latest-afbeelding, de eerste tabelrij.
3. Selecteer de koppeling in de kolom Included Software.
4. Scroll naar beneden naar de sectie .NET Tools om de .NET Core SDK te zien die met de afbeelding is geïnstalleerd.

Opmerkingen bij de implementatie

De standaard GitHub Action, waarmee pagina's worden geïmplementeerd, slaat de implementatie van mappen over die beginnen met onderstrepingsteken, bijvoorbeeld de _framework map. Als u mappen wilt implementeren die beginnen met onderstrepingsteken, voegt u een leeg .nojekyll bestand toe aan de hoofdmap van de opslagplaats van de app. Voorbeeld: Xref Generator .nojekyll-bestand

Voer deze stap uit vóór de eerste implementatie van de app: Git JavaScript-bestanden (JS) behandelt, zoals blazor.webassembly.js, als tekst en converteert regeleinden van CRLF (regelterugloopfeed) naar LF (regelfeed) in de implementatiepijplijn. Deze wijzigingen in JS bestanden produceren verschillende bestands-hashes dan Blazor verzendt naar de client in het blazor.boot.json bestand. Afwijkingen leiden tot fouten bij integriteitscontroles bij de client. Een benadering voor het oplossen van dit probleem is het toevoegen van een .gitattributes bestand met *.js binary regel voordat u de assets van de app toevoegt aan de Git-vertakking. De *.js binary regel configureert Git om JS bestanden te behandelen als binaire bestanden, waardoor de bestanden in de implementatiepijplijn niet worden verwerkt. De bestandshashes van de niet-verwerkte bestanden komen overeen met de vermeldingen in het blazor.boot.json-bestand en de integriteitscontroles aan de clientzijde slagen. Voor meer informatie, zie ASP.NET Core Blazor WebAssembly .NET runtime en app-bundel caching. Voorbeeld: Xref Generator .gitattributes-bestand

Url-herschrijven afhandelen op basis van Single Page Apps for GitHub Pages (rafrex/spa-github-pages GitHub-opslagplaats):

• Voeg een wwwroot/404.html-bestand toe met een script waarmee de aanvraag wordt omgeleid naar de pagina index.html. Voorbeeld: Xref Generator 404.html-bestand
• Voeg in wwwroot/index.htmlhet script toe aan de inhoud van <head>. Voorbeeld: Xref Generator index.html-bestand

GitHub Pages biedt geen systeemeigen ondersteuning voor het gebruik van met Brotli gecomprimeerde resources. Brotli gebruiken:

• Voeg het wwwroot/decode.js script toe aan de map wwwroot van de app. Voorbeeld: Xref Generator decode.js-bestand

• Voeg de <script> tag toe om het decode.js script in het wwwroot/index.html bestand direct boven de <script> tag te laden waarmee het Blazor script wordt geladen. Voorbeeld: Xref Generator index.html-bestand

  • Stel autostart="false" in voor het Blazor WebAssembly-script.
  • Voeg het loadBootResource script toe na de <script> tag waarmee het Blazor WebAssembly script wordt geladen. Voorbeeld: Xref Generator index.html-bestand

• Voeg robots.txt en sitemap.txt bestanden toe om SEO te verbeteren. Voorbeelden: Xref Generator robots.txt-bestand, Xref Generator sitemap.txt bestand

Zelfstandig met Docker

Een zelfstandige Blazor WebAssembly-app wordt gepubliceerd als een set statische bestanden die worden gehost door een statische bestandsserver.

De app hosten in Docker:

• Kies een Docker-container met webserverondersteuning, zoals Ngnix of Apache.
• Kopieer de publish mapassets naar een locatiemap die is gedefinieerd op de webserver voor het leveren van statische bestanden.
• Pas indien nodig aanvullende configuratie toe om de Blazor WebAssembly-app te bedienen.

Zie de volgende bronnen voor configuratierichtlijnen:

• sectie van Nginx of sectie van Apache van dit artikel
• Docker-documentatie

Hostconfiguratiewaarden

De Blazor WebAssembly apps kunnen de volgende hostconfiguratiewaarden als opdrachtregelargumenten accepteren tijdens de uitvoeringstijd in de ontwikkelomgeving.

Inhoudsbasis

Met het argument --contentroot wordt het absolute pad ingesteld naar de map die de inhoudsbestanden van de app bevat (hoofdmap van de inhoud). In de volgende voorbeelden is /content-root-path het hoofdpad voor de inhoud van de app.

• Geef het argument door wanneer u de app lokaal uitvoert bij een opdrachtprompt. Voer in de map van de app het volgende uit:

  dotnet watch --contentroot=/content-root-path
  

• Voeg een vermelding toe aan het launchSettings.json-bestand van de app in het profiel IIS Express. Deze instelling wordt gebruikt wanneer de app wordt uitgevoerd met het Visual Studio Debugger en vanaf een opdrachtprompt met dotnet watch (of dotnet run).

  "commandLineArgs": "--contentroot=/content-root-path"
  

• Geef in Visual Studio het argument op in Eigenschappen>Foutopsporing>Toepassingsargumenten. Als u het argument instelt op de eigenschappenpagina van Visual Studio, wordt het argument toegevoegd aan het bestand launchSettings.json.

  --contentroot=/content-root-path
  

Padbasis

Met het argument --pathbase wordt het basispad van de app ingesteld voor een app die lokaal wordt uitgevoerd met een niet-hoofd-relatief URL-pad (de <base> tag href is ingesteld op een ander pad dan / voor fasering en productie). In de volgende voorbeelden is /relative-URL-path het basispad van de app. Zie app-basispadvoor meer informatie.

Belangrijk

In tegenstelling tot het pad dat is opgegeven voor href van de <base>-tag, moet u geen afsluitende slash (/) opnemen bij het doorgeven van de waarde van het --pathbase argument. Als het basispad van de app wordt opgegeven in de tag <base> als <base href="/CoolApp/"> (inclusief een afsluitende slash), geeft u de waarde van het opdrachtregelargument door als --pathbase=/CoolApp (geen afsluitende slash).

• Geef het argument door wanneer u de app lokaal uitvoert bij een opdrachtprompt. Voer in de map van de app het volgende uit:

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

• Voeg een vermelding toe aan het launchSettings.json-bestand van de app in het profiel IIS Express. Deze instelling wordt gebruikt bij het uitvoeren van de app met het Visual Studio Debugger en vanaf een opdrachtprompt met dotnet watch (of dotnet run).

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

• Geef in Visual Studio het argument op in Eigenschappen>Foutopsporing>Toepassingsargumenten. Als u het argument instelt op de eigenschappenpagina van Visual Studio, wordt het argument toegevoegd aan het bestand launchSettings.json.

  --pathbase=/relative-URL-path
  

URL's

Het argument --urls stelt de IP-adressen of hostadressen in met poorten en protocollen om te luisteren naar aanvragen.

• Geef het argument door wanneer u de app lokaal uitvoert bij een opdrachtprompt. Voer in de map van de app het volgende uit:

  dotnet watch --urls=http://127.0.0.1:0
  

• Voeg een vermelding toe aan het launchSettings.json-bestand van de app in het profiel IIS Express. Deze instelling wordt gebruikt bij het uitvoeren van de app met het Visual Studio Debugger en vanaf een opdrachtprompt met dotnet watch (of dotnet run).

  "commandLineArgs": "--urls=http://127.0.0.1:0"
  

• Geef in Visual Studio het argument op in Eigenschappen>Foutopsporing>Toepassingsargumenten. Als u het argument instelt op de eigenschappenpagina van Visual Studio, wordt het argument toegevoegd aan het bestand launchSettings.json.

  --urls=http://127.0.0.1:0
  

De trimmer configureren

Bij elke release-build voert Blazor Intermediate Language (IL) trimming uit om onnodige IL uit de uitvoerassemblies te verwijderen. Zie De trimmer configureren voor ASP.NET Core Blazorvoor meer informatie.

De bestandsnaamextensie van DLL-bestanden wijzigen

Deze sectie is van toepassing op ASP.NET Core 6.x en 7.x. In ASP.NET Core in .NET 8 of hoger worden .NET-assembly's geïmplementeerd als WebAssembly-bestanden (.wasm) met behulp van de webcilbestandsindeling. In ASP.NET Core in .NET 8 of hoger is deze sectie alleen van toepassing als de webcilbestandsindeling is uitgeschakeld in het projectbestand van de app.

Als een firewall, antivirusprogramma of netwerkbeveiligingsapparaat de overdracht van de DLL-bestanden (Dynamic Link Library) van de app (.dll) blokkeert, kunt u de richtlijnen in deze sectie volgen om de bestandsnaamextensies van de gepubliceerde DLL-bestanden van de app te wijzigen.

Notitie

Als u de bestandsnaamextensies van de DLL-bestanden van de app wijzigt, wordt het probleem mogelijk niet opgelost omdat veel beveiligingssystemen de inhoud van de bestanden van de app scannen, niet alleen bestandsextensies controleren.

Voor een krachtigere benadering in omgevingen die het downloaden en uitvoeren van DLL-bestanden blokkeren, gebruikt u ASP.NET Core in .NET 8 of hoger, waarmee .NET-assembly's worden verpakt als WebAssembly-bestanden (.wasm) met behulp van de Webcil--bestandsindeling. Voor meer informatie, zie de sectie Webcil-verpakkingsformaat voor .NET-assembly's in een versie 8.0 of later van dit artikel.

Er bestaan benaderingen van derden voor het oplossen van dit probleem. Zie de resources op Awesome Blazorvoor meer informatie.

Nadat u de app hebt gepubliceerd, gebruikt u een shellscript of DevOps-buildpijplijn om de naam van .dll bestanden te wijzigen om een andere bestandsextensie te gebruiken in de map van de gepubliceerde uitvoer van de app.

In de volgende voorbeelden:

• PowerShell (PS) wordt gebruikt om de bestandsextensies bij te werken.
• .dll-bestanden worden hernoemd door de .bin-bestandsextensie te gebruiken vanaf de opdrachtregel.
• Bestanden die worden vermeld in het gepubliceerde blazor.boot.json-bestand met een .dll bestandsextensie, worden bijgewerkt naar de bestandsextensie .bin.
• Als service worker-assets ook worden gebruikt, werkt een PowerShell-opdracht de .dll bestanden bij die worden vermeld in het service-worker-assets.js-bestand naar de bestandsextensie .bin.

Als u een andere bestandsextensie dan .binwilt gebruiken, vervangt u .bin in de volgende opdrachten door de gewenste bestandsextensie.

In 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

In de voorgaande opdracht is de tijdelijke aanduiding {PATH} het pad naar de gepubliceerde _framework map (bijvoorbeeld .\bin\Release\net6.0\browser-wasm\publish\wwwroot\_framework uit de hoofdmap van het project).

"Als serviceworker-assets ook in gebruik zijn:"

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

In de voorgaande opdracht is {PATH} de tijdelijke aanduiding voor het pad naar het gepubliceerde service-worker-assets.js-bestand.

In Linux of 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

In de voorgaande opdracht is de tijdelijke aanduiding {PATH} het pad naar de gepubliceerde _framework map (bijvoorbeeld .\bin\Release\net6.0\browser-wasm\publish\wwwroot\_framework uit de hoofdmap van het project).

"Als serviceworker-assets ook in gebruik zijn:"

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

In de voorgaande opdracht is {PATH} de tijdelijke aanduiding voor het pad naar het gepubliceerde service-worker-assets.js-bestand.

Ga op een van de volgende manieren te werk om de gecomprimeerde blazor.boot.json.gz- en blazor.boot.json.br-bestanden aan te pakken:

• Verwijder de gecomprimeerde blazor.boot.json.gz- en blazor.boot.json.br-bestanden. Compressie is uitgeschakeld met deze methode.
• Hercomprim het bijgewerkte blazor.boot.json-bestand.

De voorgaande richtlijnen voor het gecomprimeerde blazor.boot.json-bestand zijn ook van toepassing wanneer service worker-assets worden gebruikt. Verwijder of recomprimeer service-worker-assets.js.br en service-worker-assets.js.gz. Anders mislukken controles voor bestandsintegriteit in de browser.

In het volgende Windows-voorbeeld voor .NET 6 wordt een PowerShell-script gebruikt dat in de hoofdmap van het project wordt geplaatst. Het volgende script, waarmee compressie wordt uitgeschakeld, is de basis voor verdere wijzigingen als u het blazor.boot.json-bestand opnieuw wilt comprimeren.

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

Als er ook gebruik wordt gemaakt van serviceworker-assets, voeg dan de volgende commando's toe:

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

In het projectbestand wordt het script uitgevoerd na het publiceren van de app voor de Release-configuratie:

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

Notitie

Als u dezelfde assembly's hernoemt en lui laadt, raadpleegt u de richtlijnen in Lui laden van assembly's in ASP.NET Core Blazor WebAssembly.

Normaal gesproken vereist de server van de app statische assetconfiguratie om de bestanden te verwerken met de bijgewerkte extensie. Voor een app die wordt gehost door IIS, voegt u een MIME-kaartvermelding (<mimeMap>) toe voor de nieuwe bestandsextensie in de sectie statische inhoud (<staticContent>) in een aangepast web.config-bestand. In het volgende voorbeeld wordt ervan uitgegaan dat de bestandsextensie wordt gewijzigd van .dll in .bin:

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

Neem een update op voor gecomprimeerde bestanden als compressie wordt gebruikt:

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

Verwijder de vermelding voor de bestandsextensie .dll:

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

Verwijder vermeldingen voor gecomprimeerde .dll bestanden als compressie wordt gebruikt:

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

Zie de sectie web.config gebruiken voor meer informatie over aangepaste -bestanden.

Eerdere inzetcorruptie

Doorgaans bij de implementatie:

• Alleen de bestanden die zijn gewijzigd, worden vervangen, wat meestal resulteert in een snellere implementatie.
• Bestaande bestanden die geen deel uitmaken van de nieuwe implementatie, blijven aanwezig voor gebruik door de nieuwe implementatie.

In zeldzame gevallen kunnen blijvende bestanden van een vorige implementatie een nieuwe implementatie verstoren. Het volledig verwijderen van de bestaande implementatie (of lokaal gepubliceerde app voorafgaand aan de implementatie) kan het probleem met een beschadigde implementatie oplossen. Vaak is het verwijderen van de bestaande implementatie zodra voldoende is om het probleem op te lossen, waaronder voor een DevOps-build- en implementatiepijplijn.

Als u vaststelt dat het wissen van een eerdere implementatie altijd vereist is wanneer een DevOps-build- en implementatiepijplijn wordt gebruikt, kunt u tijdelijk een stap toevoegen aan de build-pijplijn om de vorige implementatie voor elke nieuwe implementatie te verwijderen totdat u de exacte oorzaak van de beschadiging oplost.

Integriteitscontrolefouten oplossen

Wanneer Blazor WebAssembly de opstartbestanden van een app downloadt, wordt de browser geïnstrueerd om integriteitscontroles uit te voeren op de antwoorden. Blazor verzendt SHA-256-hashwaarden voor DLL (.dll), WebAssembly (.wasm) en andere bestanden in het blazor.boot.json-bestand, die niet in de cache worden opgeslagen op clients. De bestands-hashes van bestanden in de cache worden vergeleken met de hashes in het blazor.boot.json bestand. Voor bestanden in de cache met een overeenkomende hash gebruikt Blazor de bestanden in de cache. Anders worden bestanden aangevraagd vanaf de server. Nadat een bestand is gedownload, wordt de hash opnieuw gecontroleerd op integriteitsvalidatie. Er wordt een fout gegenereerd door de browser als de integriteitscontrole van een gedownload bestand mislukt.

Blazoralgoritme voor het beheren van bestandsintegriteit:

• Zorgt ervoor dat de app geen inconsistente set bestanden laadt, bijvoorbeeld als er een nieuwe implementatie wordt toegepast op uw webserver terwijl de gebruiker bezig is met het downloaden van de toepassingsbestanden. Inconsistente bestanden kunnen leiden tot een defecte app.
• Zorgt ervoor dat de browser van de gebruiker nooit inconsistente of ongeldige antwoorden in de cache opgeslagen, waardoor de app niet kan worden gestart, zelfs als de gebruiker de pagina handmatig vernieuwt.
• Maakt het veilig om de antwoorden in de cache op te slaan en niet te controleren op wijzigingen aan de serverzijde totdat de verwachte SHA-256-hashes zelf veranderen, zodat de volgende paginabelastingen minder aanvragen omvatten en sneller worden voltooid.

Als de webserver antwoorden retourneert die niet overeenkomen met de verwachte SHA-256-hashes, wordt er een fout weergegeven die lijkt op het volgende voorbeeld in de ontwikkelaarsconsole van de browser:

Kan geen geldige samenvatting vinden in het kenmerk Integriteit voor resourcehttps://myapp.example.com/_framework/MyBlazorApp.dllmet berekende SHA-256-integriteit 'IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJJY='. De resource is geblokkeerd.

In de meeste gevallen geeft de waarschuwing geen probleem aan met integriteitscontrole. In plaats daarvan betekent de waarschuwing meestal dat er een ander probleem bestaat.

Voor de opstartreferentiebron van Blazor WebAssembly, zie het bestand Boot.WebAssembly.ts in de GitHub-opslagplaats dotnet/aspnetcore.

Notitie

Documentatiekoppelingen naar .NET-referentiebron laden meestal de standaardbranch van de opslagplaats, die de huidige ontwikkeling vertegenwoordigt voor de volgende release van .NET. Als u een tag voor een specifieke release wilt selecteren, gebruikt u de Switch branches of tags vervolgkeuzelijst. Zie Een versietag selecteren van ASP.NET Core-broncode (dotnet/AspNetCore.Docs #26205)voor meer informatie.

Integriteitsproblemen diagnosticeren

Wanneer een app is gebouwd, beschrijft het gegenereerde blazor.boot.json manifest de SHA-256-hashes van opstartbronnen op het moment dat de build-uitvoer wordt geproduceerd. De integriteitscontrole slaagt zolang de SHA-256-hashes in blazor.boot.json overeenkomen met de bestanden die bij de browser worden afgeleverd.

Veelvoorkomende redenen waarom dit mislukt, zijn onder andere:

• Het antwoord van de webserver is een fout (bijvoorbeeld een 404 - Niet gevonden of een 500 - Interne serverfout) in plaats van het bestand dat de browser heeft aangevraagd. Dit wordt door de browser gerapporteerd als een integriteitscontrolefout en niet als reactiefout.
• Er is iets veranderd in de inhoud van de bestanden tussen de build en levering van de bestanden in de browser. Dit kan gebeuren:
  • Als u of de hulpprogramma's de build-uitvoer handmatig wijzigen.
  • Als een bepaald aspect van het implementatieproces de bestanden heeft gewijzigd. Als u bijvoorbeeld een implementatiemechanisme op basis van Git gebruikt, moet u er rekening mee houden dat Git transparant lijneinden van Windows-stijl converteert naar unix-stijl lijneinden als u bestanden doorvoert in Windows en ze uitcheckt in Linux. Als u de einden van de bestandslijn wijzigt, worden de SHA-256-hashes gewijzigd. U kunt dit probleem voorkomen door gebruik te maken van .gitattributes om buildartefacten te behandelen als binary bestanden.
  • De webserver wijzigt de bestandsinhoud als onderdeel van het leveren ervan. Sommige CDN's (Content Distribution Networks) proberen bijvoorbeeld automatisch minify HTML, waardoor deze wordt gewijzigd. Mogelijk moet u dergelijke functies uitschakelen.
• Het blazor.boot.json bestand kan niet correct worden geladen of wordt onjuist in de cache op de client opgeslagen. Veelvoorkomende oorzaken zijn een van de volgende:
  • Aangepaste ontwikkelaarscode is onjuist geconfigureerd of defect.
  • Een of meer verkeerd geconfigureerde tussenliggende cachelagen.

Ga als volgt te werk om te diagnosticeren welke van deze van toepassing is in uw geval:

1. Let op welk bestand de fout activeert door het foutbericht te lezen.
2. Open de ontwikkelhulpprogramma's van uw browser en kijk op het tabblad Network. Laad de pagina zo nodig opnieuw om de lijst met aanvragen en antwoorden weer te geven. Zoek het bestand dat de fout in die lijst activeert.
3. Controleer de HTTP-statuscode in het antwoord. Als de server iets anders retourneert dan 200 - OK (of een andere 2xx-statuscode), hebt u een probleem aan de serverzijde om te diagnosticeren. Statuscode 403 betekent bijvoorbeeld dat er een autorisatieprobleem is, terwijl statuscode 500 betekent dat de server op een niet-opgegeven manier mislukt. Raadpleeg de logboeken aan de serverzijde om de app vast te stellen en op te lossen.
4. Als de statuscode is 200 - OK voor de resource, bekijkt u de antwoordinhoud in de ontwikkelhulpprogramma's van de browser en controleert u of de inhoud overeenkomt met de verwachte gegevens. Een veelvoorkomend probleem is bijvoorbeeld het onjuist configureren van routering, zodat aanvragen uw index.html gegevens retourneren, zelfs voor andere bestanden. Zorg ervoor dat antwoorden op .wasm aanvragen binaire webassembly-bestanden zijn en dat antwoorden op .dll aanvragen binaire .NET-assemblybestanden zijn. Zo niet, dan hebt u een routeringsprobleem aan de serverzijde dat gediagnosticeerd moet worden.
5. Probeer de gepubliceerde en geïmplementeerde uitvoer van de app te valideren met de Integriteitsproblemen met powerShell-script oplossen.

Als u bevestigt dat de server plausibel juiste gegevens retourneert, moet er iets anders zijn dat de inhoud wijzigt tussen het bouwen en leveren van het bestand. Ga als volgt te werk om dit te onderzoeken:

• Bekijk de build toolchain en het implementatiemechanisme voor het geval ze bestanden wijzigen nadat de bestanden zijn gemaakt. Een voorbeeld hiervan is wanneer Git bestandslijneinden transformeert, zoals eerder is beschreven.
• Bekijk de webserver- of CDN-configuratie voor het geval ze zijn ingesteld om reacties dynamisch te wijzigen (bijvoorbeeld om HTML te minificeren). Het is prima voor de webserver om HTTP-compressie te implementeren (bijvoorbeeld het retourneren van content-encoding: br of content-encoding: gzip), omdat dit geen invloed heeft op het resultaat na decomprimatie. Het is echter niet prima voor de webserver om de niet-gecomprimeerde gegevens te wijzigen.

Problemen met integriteit van PowerShell-script oplossen

Gebruik het integrity.ps1 PowerShell-script om een gepubliceerde en geïmplementeerde Blazor-app te valideren. Het script wordt geleverd voor PowerShell Core 7 of hoger als uitgangspunt wanneer de app integriteitsproblemen heeft die het Blazor framework niet kan identificeren. Aanpassing van het script is mogelijk vereist voor uw apps, inclusief als het wordt uitgevoerd op een versie van PowerShell hoger dan versie 7.2.0.

Het script controleert de bestanden in de map publish en de bestanden die zijn gedownload van de geïmplementeerde app om problemen te detecteren in de verschillende manifesten die integriteitshashes bevatten. Deze controles moeten de meest voorkomende problemen detecteren:

• U hebt een bestand in de gepubliceerde uitvoer gewijzigd zonder dit te realiseren.
• De app is niet correct geïmplementeerd op het implementatiedoel of er is iets gewijzigd in de omgeving van het implementatiedoel.
• Er zijn verschillen tussen de geïmplementeerde app en de uitvoer van het publiceren van de app.

Roep het script aan met de volgende opdracht in een PowerShell-opdrachtshell:

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

In het volgende voorbeeld wordt het script uitgevoerd op een lokaal uitgevoerde app op https://localhost:5001/:

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

Tijdelijke aanduidingen:

• {BASE URL}: de URL van de geïmplementeerde app. Er is een slash aan het eind (/) vereist.
• {PUBLISH OUTPUT FOLDER}: het pad naar de publish map of locatie van de app waar de app is gepubliceerd voor implementatie.

Notitie

Bij het klonen van de dotnet/AspNetCore.Docs GitHub-opslagplaats kan het integrity.ps1 script in quarantaine worden geplaatst door Bitdefender of een andere virusscanner die aanwezig is op het systeem. Meestal wordt het bestand gevangen door de heuristiek scannen van een virusscanner technologie, die alleen zoekt naar patronen in bestanden die de aanwezigheid van malware kunnen aangeven. Als u wilt voorkomen dat de virusscanner het bestand in quarantaine krijgt, voegt u een uitzondering toe aan de virusscanner voordat u de opslagplaats kloont. Het volgende voorbeeld is een typisch pad naar het script op een Windows-systeem. Pas het pad zo nodig aan voor andere systemen. De plaatsaanduiding {USER} is het padsegment van de gebruiker.

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

Waarschuwing: Het maken van virusscanner-uitzonderingen is gevaarlijk en mag alleen worden uitgevoerd wanneer u zeker weet dat het bestand veilig is.

Het vergelijken van de controlesom van een bestand met een geldige controlesomwaarde garandeert geen bestandsveiligheid, maar het wijzigen van een bestand op een manier die een controlesomwaarde onderhoudt, is niet triviaal voor kwaadwillende gebruikers. Daarom zijn controlesommen nuttig als algemene beveiligingsbenadering. Vergelijk de controlesom van het lokale integrity.ps1-bestand met een van de volgende waarden:

• SHA256: 32c24cb667d79a701135cb72f6bae490d81703323f61b8af2c7e5e5dc0f0c2bb
• MD5: 9cee7d7ec86ee809a329b5406fbf21a8

Haal de controlesom van het bestand op in het Windows-besturingssysteem met de volgende opdracht. Geef het pad en de bestandsnaam op voor de tijdelijke aanduiding {PATH AND FILE NAME} en geef het type controlesom aan om te produceren voor de tijdelijke aanduiding {SHA512|MD5}, of SHA256 of MD5.

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

Als u zorgen hebt dat de controlesomvalidatie niet veilig genoeg is in uw omgeving, raadpleegt u het beveiligingsbeheer van uw organisatie voor hulp.

Zie Overzicht van bedreigingsbeveiliging door Microsoft Defender Antivirusvoor meer informatie.

Integriteitscontrole uitschakelen voor niet-PWA-apps

Schakel in de meeste gevallen de integriteitscontrole niet uit. Het uitschakelen van integriteitscontrole lost het onderliggende probleem dat de onverwachte reacties heeft veroorzaakt niet op en leidt ertoe dat de eerder vermelde voordelen verloren gaan.

Er kunnen gevallen zijn waarin de webserver niet kan worden vertrouwd om consistente antwoorden te retourneren en u geen keuze hebt om integriteitscontroles tijdelijk uit te schakelen totdat het onderliggende probleem is opgelost.

Als u integriteitscontroles wilt uitschakelen, voegt u het volgende toe aan een eigenschapsgroep in het projectbestand van de Blazor WebAssembly-app (.csproj):

<BlazorCacheBootResources>false</BlazorCacheBootResources>

BlazorCacheBootResources schakelt ook het standaardgedrag van Blazorvoor het opslaan van de .dll, .wasmen andere bestanden uit op basis van hun SHA-256-hashes, omdat de eigenschap aangeeft dat de SHA-256-hashes niet kunnen worden vertrouwd op juistheid. Zelfs met deze instelling kan de normale HTTP-cache van de browser deze bestanden nog steeds in de cache opslaan, maar of dit gebeurt, is afhankelijk van de configuratie van uw webserver en de cache-control headers die deze dient.

Notitie

Met de eigenschap BlazorCacheBootResources worden integriteitscontroles voor Progressive Web Applications (PBA's)niet uitgeschakeld. Zie de sectie Integriteitscontrole uitschakelen voor PWA's voor richtlijnen met betrekking tot PWA's.

We kunnen geen volledige lijst met scenario's opgeven waarin het uitschakelen van integriteitscontrole is vereist. Servers kunnen een aanvraag op willekeurige manieren beantwoorden buiten het bereik van het Blazor framework. Het framework biedt de BlazorCacheBootResources instelling waarmee de app kan worden uitgevoerd ten koste van verlies van een garantie voor integriteit die de appkan bieden. We raden u ook niet aan integriteitscontrole uit te schakelen, met name voor productie-implementaties. Ontwikkelaars moeten proberen het onderliggende integriteitsprobleem op te lossen waardoor integriteitscontrole mislukt.

Enkele algemene gevallen die integriteitsproblemen kunnen veroorzaken, zijn:

• Wordt uitgevoerd op HTTP waar integriteit niet kan worden gecontroleerd.
• Als uw implementatieproces de bestanden wijzigt nadat het op een of andere manier is gepubliceerd.
• Als uw host de bestanden op een of andere manier wijzigt.

Integriteitscontrole voor PWA's uitschakelen

BlazorPWA-sjabloon (Progressive Web Application) bevat een voorgesteld service-worker.published.js-bestand dat verantwoordelijk is voor het ophalen en opslaan van toepassingsbestanden voor offlinegebruik. Dit is een afzonderlijk proces van het normale opstartmechanisme voor apps en heeft een eigen afzonderlijke logica voor integriteitscontrole.

In het service-worker.published.js-bestand is de volgende regel aanwezig:

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

Als u integriteitscontrole wilt uitschakelen, verwijdert u de parameter integrity door de regel te wijzigen in het volgende:

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

Als u integriteitscontrole uitschakelt, verliest u de veiligheidsgaranties die worden geboden door integriteitscontrole. Er bestaat bijvoorbeeld een risico dat als de browser van de gebruiker de app op het exacte moment dat u een nieuwe versie implementeert, bepaalde bestanden van de oude implementatie en sommige bestanden uit de nieuwe implementatie in de cache opslaat. Als dat gebeurt, loopt de app vast in een verbroken status totdat u een verdere update implementeert.