ASP.NET Core-Blazor WebAssembly hosten en implementeren

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 en andere artikelen in dit knooppunt voor IIS-, Azure-services, Apache, Nginx en GitHub Pages.

De volgende implementatiestrategieën worden ondersteund:

• De Blazor-app wordt geleverd door een ASP.NET Core-app. Deze strategie wordt behandeld in de sectie Gehoste implementatie met ASP.NET Core.
• De Blazor-app wordt geplaatst op een statische hostingwebserver of -service, waarbij .NET niet wordt gebruikt om de Blazor-app te bedienen. Deze strategie wordt behandeld in de sectie Zelfstandige implementatie, waaronder informatie over het hosten van een Blazor WebAssembly-app als een IIS-sub-app.
• Een ASP.NET Core-app fungeert als host voor meerdere Blazor WebAssembly-apps. Zie Meerdere gehoste ASP.NET Core Blazor WebAssembly-appsvoor meer informatie.

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:

Bij het bouwen van een Blazor WebAssembly-app die zich richt op browsers voor mobiele apparaten, met name Safari op iOS, kan het nodig zijn om het maximale geheugen voor de app te verlagen 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:

Webcil-pakketformaat 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>

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:

Blazor vertrouwt erop dat de host de juiste gecomprimeerde bestanden levert. Wanneer u een ASP.NET Core HostedBlazor WebAssembly-project gebruikt, kan het hostproject inhoudsonderhandeling uitvoeren en de statisch gecomprimeerde bestanden leveren. Bij het hosten van een zelfstandige Blazor WebAssembly-app is mogelijk extra werk vereist om ervoor te zorgen dat statisch gecomprimeerde bestanden worden geleverd:

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:

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

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

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

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

dotnet publish -p:BlazorEnableCompression=false

Gehoste implementatie met ASP.NET Core

Een gehoste implementatie levert de Blazor WebAssembly-app vanaf een ASP.NET Core-app die op een webserver draait aan browsers.

De client-Blazor WebAssembly-app wordt gepubliceerd in de /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot map van de server-app, samen met andere statische webassets van de server-app. De twee apps worden samen geïmplementeerd. Een webserver die een ASP.NET Core-app kan hosten, is vereist. Voor een gehoste implementatie bevat Visual Studio de Blazor WebAssembly App-projectsjabloon (blazorwasm sjabloon bij gebruik van de opdracht dotnet new) met de optie Hosted geselecteerd (-ho|--hosted wanneer u de opdracht dotnet new gebruikt).

Zie de volgende artikelen voor meer informatie:

• ASP.NET Core-app hosten en implementeren: Host en implementeren ASP.NET Core
• Implementatie in Azure App Service: een ASP.NET Core-app publiceren naar Azure met Visual Studio
• Blazor projectsjablonen: ASP.NET Core Blazor projectstructuur

Gehoste implementatie van een frameworkafhankelijk uitvoerbaar bestand voor een specifiek platform

Als u een gehoste Blazor WebAssembly-app wilt implementeren als een frameworkafhankelijk uitvoerbaar bestand voor een specifiek platform (niet zelfstandig) gebruikt u de volgende richtlijnen op basis van de hulpprogramma's die worden gebruikt.

Visual Studio

Een zelfstandige-implementatie is geconfigureerd voor een gegenereerd publicatieprofiel (.pubxml). Controleer of het publicatieprofiel van het Server project de eigenschap <SelfContained> MSBuild bevat die is ingesteld op false.

In het .pubxml publiceerprofielbestand in de Server-map van het Properties-project:

<SelfContained>false</SelfContained>

Stel de Runtime Identifier (RID) in met behulp van de Target Runtime instelling in de Instellingen sectie van de Publiceren gebruikersinterface, waarmee de <RuntimeIdentifier> MSBuild-eigenschap in het publicatieprofiel wordt gegenereerd:

<RuntimeIdentifier>{RID}</RuntimeIdentifier>

In de voorgaande configuratie is de tijdelijke aanduiding {RID} de Runtime Identifier (RID).

Publiceer het Server project in de Release-configuratie.

.NET CLI

Configureer een zelfstandige-implementatie door de <SelfContained> MSBuild-eigenschap in <PropertyGroup> in het projectbestand van het Server-project te plaatsen en in te stellen op false.

<SelfContained>false</SelfContained>

Stel de RID- (Runtime Identifier) in met behulp van van de volgende methoden:

• Optie 1: stel de RID in een <PropertyGroup> in het projectbestand van het Server project in:

  <RuntimeIdentifier>{RID}</RuntimeIdentifier>
  

  In de voorgaande configuratie is de tijdelijke aanduiding {RID} de Runtime Identifier (RID).

  Publiceer de app in de releaseconfiguratie vanuit het Server project:

  dotnet publish -c Release
  

• Optie 2: geef de RID door in de opdracht dotnet publish als de eigenschap MSBuild (/p:RuntimeIdentifier), niet met de optie -r|--runtime:

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

  In het voorgaande commando is de tijdelijke aanduiding {RID} de Runtime Identifier (RID).

Zie de volgende artikelen voor meer informatie:

• overzicht van .NET-toepassingspublicaties
• Hosten en ASP.NET Core- implementeren

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.

Linker configureren

Blazor voert koppeling van Intermediate Language (IL) uit bij elke Release-build om onnodige IL uit de uitvoerassemblages te verwijderen. Zie De Linker configureren voor ASP.NET Core Blazorvoor meer informatie.

De bestandsnaamextensie van DLL-bestanden wijzigen

Deze sectie is van toepassing op .NET 5 tot en met .NET 7. In .NET 8 of hoger worden .NET-assembly's geïmplementeerd als WebAssembly-bestanden (.wasm) met behulp van de webcilbestandsindeling.

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.

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, kunt u kiezen uit een van de volgende benaderingen:

• Gebruik .NET 8 of hoger, waarmee .NET-assembly's worden verpakt als WebAssembly-bestanden (.wasm) met behulp van de webcilbestandsindeling . Voor meer informatie, zie de sectie Webcil-pakketten voor .NET-assembly's in een .NET 8- of latere versie van dit artikel.
• Gebruik in .NET 6 of hoger een aangepaste implementatie-indeling.

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 opstartmanifest met een .dll bestandsextensie, worden bijgewerkt naar de .bin bestandsextensie.
• 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.

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

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

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

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

Ga op een van de volgende manieren te werk om het gecomprimeerde blazor.boot.json bestand aan te pakken:

• Hercomprimeer het bijgewerkte blazor.boot.json bestand, waardoor nieuwe blazor.boot.json.gz en blazor.boot.json.br bestanden worden geproduceerd. (Recommended)
• Verwijder de gecomprimeerde blazor.boot.json.gz- en blazor.boot.json.br-bestanden. (Compressie is uitgeschakeld met deze methode.)

Voor het gecomprimeerde bestand van service-worker-assets.js moet u een van de volgende methoden gebruiken:

• Hercomprimeer het bijgewerkte service-worker-assets.js bestand, waardoor nieuwe service-worker-assets.js.br en service-worker-assets.js.gz bestanden worden geproduceerd. (Recommended)
• Verwijder de gecomprimeerde service-worker-assets.js.gz- en service-worker-assets.js.br-bestanden. (Compressie is uitgeschakeld met deze methode.)

Als u de extensiewijziging in Windows in .NET 6/7 wilt automatiseren, gebruikt de volgende methode een PowerShell-script 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 en service-worker-assets.js bestand opnieuw wilt comprimeren als de app een Progressive Web App (PWA) is. Het pad naar de publish map wordt doorgegeven aan het script wanneer het wordt uitgevoerd.

ChangeDLLExtensions.ps1::

param([string]$filepath)
dir $filepath\wwwroot\_framework | rename-item -NewName { $_.name -replace ".dll\b",".bin" }
((Get-Content $filepath\wwwroot\_framework\blazor.boot.json -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\wwwroot\_framework\blazor.boot.json
Remove-Item $filepath\wwwroot\_framework\blazor.boot.json.gz
Remove-Item $filepath\wwwroot\_framework\blazor.boot.json.br

Als service worker-assets ook worden gebruikt omdat de app een Progressive Web App (PWA) is, voegt u de volgende opdrachten toe:

((Get-Content $filepath\wwwroot\service-worker-assets.js -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\wwwroot\service-worker-assets.js
Remove-Item $filepath\wwwroot\service-worker-assets.js.gz
Remove-Item $filepath\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)'}&quot;" />
</Target>

Na het publiceren van de app, handmatig opnieuw comprimeren blazor.boot.jsonen service-worker-assets.js indien gebruikt, om compressie opnieuw in te schakelen.

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 voor meer informatie over aangepaste web.config bestanden.