ASP.NET Core Blazor Progressive Web Application (PWA)

Ett Blazor progressivt webbprogram (PWA) är ett ensidesprogram (SPA) som använder moderna webbläsar-API:er och funktioner för att bete sig som en skrivbordsapp.

Blazor WebAssembly är en standardbaserad webbappsplattform på klientsidan, så den kan använda valfritt webbläsar-API, inklusive PWA-API:er som krävs för följande funktioner:

• Arbeta offline och läsa in direkt, oberoende av nätverkshastighet.
• Körs i ett eget appfönster, inte bara ett webbläsarfönster.
• Startas från operativsystemets startmeny, dock eller startskärm.
• Ta emot push-meddelanden från en serverdelsserver, även om användaren inte använder appen.
• Uppdateras automatiskt i bakgrunden.

Ordet progressiv används för att beskriva dessa appar eftersom:

• En användare kan först identifiera och använda appen i sin webbläsare som alla andra SPA-program.
• Senare fortsätter användaren att installera det i operativsystemet och aktivera push-meddelanden.

Skapa ett projekt från PWA-mallen

dotnet new blazorwasm -o MyBlazorPwa --pwa

Konvertera en befintlig Blazor WebAssembly app till en PWA

Konvertera en befintlig Blazor WebAssembly app till en PWA enligt vägledningen i det här avsnittet.

I applikationens projektfil:

• Lägg till följande ServiceWorkerAssetsManifest egenskap i en PropertyGroup:

    ...
    <ServiceWorkerAssetsManifest>service-worker-assets.js</ServiceWorkerAssetsManifest>
  </PropertyGroup>
  

• Lägg till följande ServiceWorker objekt i en ItemGroup:

  <ItemGroup>
    <ServiceWorker Include="wwwroot\service-worker.js" 
      PublishedContent="wwwroot\service-worker.published.js" />
  </ItemGroup>
  

Använd någon av följande metoder för att hämta statiska tillgångar:

• Skapa ett separat, nytt PWA-projekt med dotnet new kommandot i ett kommandogränssnitt:

  dotnet new blazorwasm -o MyBlazorPwa --pwa
  

  I föregående kommando -o|--output skapar alternativet en ny mapp för appen med namnet MyBlazorPwa.

  Om du inte konverterar en app för den senaste versionen, använd alternativet . I följande exempel skapas appen för .NET 5:

  dotnet new blazorwasm -o MyBlazorPwa --pwa -f net5.0
  

• Lägg till följande JavaScript i den avslutande </body> taggen omedelbart efter blazor.webassembly.js skripttaggen:

  <script>
    navigator.serviceWorker.register('service-worker.js', { updateViaCache: 'none' });
  </script>
  

  AlternativetupdateViaCache: 'none' säkerställer att:

  • Webbläsaren använder inte cachelagrade versioner av service worker-skriptet.
  • Service Worker-uppdateringar tillämpas på ett tillförlitligt sätt utan att blockeras av HTTP-cachelagring.
  • PWA-program kan uppdatera sina tjänstarbetare mer förutsägbart.

  Detta åtgärdar cachelagringsproblem som kan förhindra att service worker-uppdateringar tillämpas korrekt, vilket är särskilt viktigt för PWA:er som förlitar sig på tjänstarbetare för offlinefunktioner.

Installations- och appmanifest

När användarna besöker en app som skapats med PWA-mallen kan de välja att installera appen på operativsystemets startmeny, docka eller startskärm. Hur det här alternativet visas beror på användarens webbläsare. När du använder skrivbordsbaserade Chromium-baserade webbläsare, till exempel Edge eller Chrome, visas knappen Lägg till i URL-fältet. När användaren har valt knappen Lägg till får de en bekräftelsedialogruta:

På iOS kan besökare installera PWA med safariknappen Dela och alternativet Lägg till på startskärmen . I Chrome för Android bör användarna välja menyknappen i det övre högra hörnet följt av Lägg till Home på skärmen.

När appen har installerats visas den i ett eget fönster utan ett adressfält:

Om du vill anpassa fönstrets rubrik, färgschema, ikon eller annan information kan du läsa manifest.json filen i projektets wwwroot katalog. Schemat för den här filen definieras av webbstandarder. Mer information finns i MDN-webbdokument: Webbappmanifest.

Offlinesupport

Appar som skapats med pwa-mallalternativet har stöd för att köra offline. En användare måste först besöka appen när de är online. Webbläsaren laddar automatiskt ned och cachelagrar alla resurser som krävs för att fungera offline.

Så här ser du hur offlinesupport fungerar:

1. Publicera appen. För mer information, se Hantera och driftsätta ASP.NET Core Blazor.

2. Distribuera appen till en server som stöder HTTPS och få åtkomst till appen i en webbläsare på dess säkra HTTPS-adress.

3. Öppna webbläsarens utvecklingsverktyg och kontrollera att en Service Worker är registrerad för värden på fliken Applikation

   

4. Läs in sidan igen och granska fliken Nätverk . Service Worker eller minnescachen visas som källor för alla sidans tillgångar:

   

5. Kontrollera att webbläsaren inte är beroende av nätverksåtkomst för att läsa in appen:

   • Stäng av webbservern och se hur appen fortsätter att fungera normalt, vilket inkluderar sidbelastningar. På samma sätt fortsätter appen att fungera normalt när det finns en långsam nätverksanslutning.
   • Instruera webbläsaren att simulera offlineläge på fliken Nätverk :

   

Offlinestöd med hjälp av en tjänstarbetare är en webbstandard, inte specifik för Blazor. Mer information om tjänstarbetare finns i MDN-webbdokument: Service Worker API. Mer information om vanliga användningsmönster för servicearbetare finns i Google Web: Service Worker-livscykeln.

BlazorPWA-mallen skapar två service-worker-filer:

• wwwroot/service-worker.js, som används under utveckling.
• wwwroot/service-worker.published.js, som används när appen har publicerats.

Om du vill dela logik mellan de två service worker-filerna bör du överväga följande metod:

• Lägg till en tredje JavaScript-fil för att lagra den gemensamma logiken.
• Använd self.importScripts för att läsa in den gemensamma logiken i båda service worker-filerna.

Cache-first hämtningsstrategi

Den inbyggda service-worker.published.js servicearbetaren löser begäranden med hjälp av en cache-first-strategi . Det innebär att tjänstarbetaren föredrar att returnera cachelagrat innehåll, oavsett om användaren har nätverksåtkomst eller nyare innehåll är tillgängligt på servern.

Cache-first-strategin är värdefull eftersom:

• Det garanterar tillförlitlighet. Nätverksåtkomst är inte ett booleskt tillstånd. En användare är inte bara online eller offline:

  • Användarens enhet kan anta att den är online, men nätverket kan vara så långsamt att det är opraktiskt att vänta på.
  • Nätverket kan returnera ogiltiga resultat för vissa URL:er, till exempel när det finns en intern WIFI-portal som för närvarande blockerar eller omdirigerar vissa begäranden.

  Det är därför webbläsarens navigator.onLine API inte är tillförlitligt och bör inte vara beroende av.

• Det garanterar korrekthet. När du skapar en cache med offlineresurser använder tjänstarbetaren innehållshashning för att garantera att den har hämtat en fullständig och självständig samt konsekvent resursuppsättning vid ett enda ögonblick i tiden. Den här cachen används sedan som en atomisk enhet. Det är ingen idé att be nätverket om nyare resurser, eftersom de enda versioner som krävs är de som redan har cachelagrats. Allt annat riskerar inkonsekvens och inkompatibilitet (till exempel att försöka använda versioner av .NET-sammansättningar som inte kompilerats tillsammans).

För att förhindra att webbläsaren hämtar service-worker-assets.js från sin HTTP-cache, kan du till exempel använda detta för att lösa tillfälliga fel i integritetskontrollen när du distribuerar en ny version av tjänstarbetaren: Registreringen av tjänstarbetaren i wwwroot/index.html använder updateViaCache inställd på none.

<script>
  navigator.serviceWorker.register('/service-worker.js', { updateViaCache: 'none' });
</script>

AlternativetupdateViaCache: 'none' säkerställer att:

• Webbläsaren använder inte cachelagrade versioner av service worker-skriptet.
• Service Worker-uppdateringar tillämpas på ett tillförlitligt sätt utan att blockeras av HTTP-cachelagring.
• PWA-program kan uppdatera sina tjänstarbetare mer förutsägbart.

Detta åtgärdar cachelagringsproblem som kan förhindra att service worker-uppdateringar tillämpas korrekt, vilket är särskilt viktigt för PWA:er som förlitar sig på tjänstarbetare för offlinefunktioner.

Bakgrundsuppdateringar

Som en mental modell kan du tänka på en offline-först PWA som beter sig som en mobilapp som kan installeras. Appen startas omedelbart oavsett nätverksanslutning, men den installerade applogiken kommer från en ögonblicksbild som kanske inte är den senaste versionen.

Blazor PWA-mallen skapar appar som automatiskt försöker uppdatera sig själva i bakgrunden när användaren besöker och har en fungerande nätverksanslutning. Så här fungerar det här:

• Under kompilering genererar projektet ett service worker-resursmanifest med namnet service-worker-assets.js. Manifestet visar alla statiska resurser som appen behöver för att fungera offline, till exempel .NET-sammansättningar, JavaScript-filer och CSS, inklusive deras innehållsshashvärden. Resurslistan läses in av tjänstarbetaren så att den vet vilka resurser som ska cachelageras.
• Varje gång användaren besöker appen begär webbläsaren service-worker.js och service-worker-assets.js i bakgrunden igen. Filerna jämförs byte för byte med den redan installerade befintliga service workern. Om servern returnerar ändrat innehåll för någon av dessa filer försöker servicearbetaren installera en ny version av sig själv.
• När du installerar en ny version av sig själv skapar tjänstarbetaren en ny, separat cache för offlineresurser och börjar fylla i cacheminnet med resurser som anges i service-worker-assets.js. Den här logiken onInstall implementeras i funktionen i service-worker.published.js.
• Processen slutförs när alla resurser läses in utan fel och alla innehållsshashvärden matchar. Om det lyckas anger den nya servicearbetaren ett vänteläge för aktivering. Så snart användaren stänger appen (inga återstående appflikar eller fönster) blir den nya tjänstarbetaren aktiv och används för efterföljande appbesök. Den gamla servicemedarbetaren och cacheminnet tas bort.
• Om processen inte slutförs framgångsrikt, tas den nya instansen av service worker bort. Uppdateringsprocessen görs igen vid användarens nästa besök, när klienten förhoppningsvis har en bättre nätverksanslutning som kan slutföra begäranden.

Anpassa den här processen genom att redigera tjänstens arbetslogik. Inget av ovanstående beteende är specifikt för Blazor men är bara standardupplevelsen som tillhandahålls av PWA-mallalternativet. Mer information finns i MDN-webbdokument: Service Worker API.

Så här löses begäranden

Som beskrivs i avsnittet Cache-first fetch strategy använder standardservicearbetaren en cache-first-strategi, vilket innebär att den försöker leverera cachelagrat innehåll när det är tillgängligt. Om det inte finns något innehåll cachelagrat för en viss URL, till exempel när du begär data från ett serverdels-API, faller tjänstarbetaren tillbaka på en vanlig nätverksbegäran. Nätverksbegäran lyckas om servern kan nås. Den här logiken implementeras inuti onFetch funktionen i service-worker.published.js.

Om appens Razor komponenter förlitar sig på att begära data från serverdels-API:er och du vill tillhandahålla en användarvänlig användarupplevelse för misslyckade begäranden på grund av att nätverket inte är tillgängligt implementerar du logik i appens komponenter. Använd till exempel try/catch runt HttpClient begäranden.

Stöd för server-renderade sidor

Tänk på vad som händer när användaren först navigerar till en URL, till exempel /counter eller någon annan djuplänk i appen. I dessa fall vill du inte returnera innehåll som cachelagrats som /counter, utan i stället behöver webbläsaren läsa in innehållet som cachelagrats som /index.html för att starta din app Blazor WebAssembly. Dessa inledande begäranden kallas för navigeringsbegäranden , till skillnad från:

• subresource begäranden om bilder, formatmallar eller andra filer.
• fetch/XHR begäranden om API-data.

Standardtjänstarbetaren innehåller specialfallslogik för navigeringsbegäranden. Tjänstarbetaren löser begäranden genom att returnera det cachelagrade innehållet för /index.html, oavsett den begärda URL:en. Den här logiken onFetch implementeras i funktionen i service-worker.published.js.

Om din app har vissa URL:er som måste returnera servergenererad HTML och inte levereras från cacheminnet, måste du redigera logiken i din tjänstarbetare. Om alla URL:er som innehåller /Identity/ behöver hanteras som regelbundna onlinebegäranden till servern ändrar service-worker.published.jsonFetch du logiken. Leta upp följande kod:

const shouldServeIndexHtml = event.request.mode === 'navigate';

Ändra koden till följande:

const shouldServeIndexHtml = event.request.mode === 'navigate'
  && !event.request.url.includes('/Identity/');

Om du inte gör det fångar tjänstarbetaren upp begäranden om sådana URL:er oavsett nätverksanslutning och löser dem med hjälp av /index.html.

Lägg till ytterligare slutpunkter för externa autentiseringsprovidrar i kontrollen. I det följande exemplet läggs Google-autentisering /signin-google till i kontrollen:

const shouldServeIndexHtml = event.request.mode === 'navigate'
  && !event.request.url.includes('/Identity/')
  && !event.request.url.includes('/signin-google');

Ingen åtgärd krävs för Development miljön, där innehållet alltid hämtas från nätverket.

Kontrollera cachelagring av tillgångar

Om projektet definierar ServiceWorkerAssetsManifest egenskapen BlazorMSBuild genererar byggverktyget ett service worker-resursmanifest med det angivna namnet. PwA-standardmallen skapar en projektfil som innehåller följande egenskap:

<ServiceWorkerAssetsManifest>service-worker-assets.js</ServiceWorkerAssetsManifest>

Filen placeras i utdatakatalogen wwwroot så att webbläsaren kan hämta den här filen genom att begära /service-worker-assets.js. Om du vill se innehållet i den här filen öppnar /bin/Debug/{TARGET FRAMEWORK}/wwwroot/service-worker-assets.js du i en textredigerare. Redigera dock inte filen eftersom den återskapas i varje version.

Manifestlistorna:

• Alla Blazor-hanterade resurser, till exempel .NET-sammansättningar och .NET WebAssembly-körningsfiler som krävs för att fungera offline.
• Alla resurser för publicering till appens katalog, till exempel bilder, formatmallar och JavaScript-filer, inklusive statiska webbtillgångar som tillhandahålls wwwroot av externa projekt och NuGet-paket.

Du kan styra vilka av dessa resurser som hämtas och cachelagras av tjänstarbetaren genom att redigera logiken i i onInstallservice-worker.published.js. Tjänstarbetaren hämtar och cachelagrar filer som matchar vanliga webbfilnamnstillägg, till exempel .html, .css.js, och .wasm, plus filtyper som är specifika för , till Blazor WebAssemblyexempel .pdb filer (alla versioner) och .dll filer (ASP.NET Core i .NET 7 eller tidigare).

Om du vill inkludera ytterligare resurser som inte finns i appens wwwroot katalog definierar du extra MSBuild-poster ItemGroup , som du ser i följande exempel:

<ItemGroup>
  <ServiceWorkerAssetsManifestItem Include="MyDirectory\AnotherFile.json"
    RelativePath="MyDirectory\AnotherFile.json" AssetUrl="files/AnotherFile.json" />
</ItemGroup>

Metadata AssetUrl anger den basrelativa URL som webbläsaren ska använda när du hämtar resursen till cacheminnet. Detta kan vara oberoende av dess ursprungliga källfilnamn på disken.

Push-meddelanden

Precis som andra PWA kan en Blazor WebAssembly PWA ta emot push-meddelanden från en backend-server. Servern kan när som helst skicka push-meddelanden, även om användaren inte aktivt använder appen. Push-meddelanden kan till exempel skickas när en annan användare utför en relevant åtgärd.

Invändningar för offline-PWA

Alla appar bör inte försöka stödja offlineanvändning. Offlinesupport ger betydande komplexitet, men är inte alltid relevant för de användningsfall som krävs.

Offlinesupport är vanligtvis endast relevant:

• Om det primära datalagret är lokalt i webbläsaren. Metoden är till exempel relevant i en app med ett användargränssnitt för en IoT-enhet som lagrar data i localStorage eller IndexedDB.
• Om appen utför en betydande mängd arbete för att hämta och cachelagra data från serverdels-API:et som är relevant för varje användare, så att de kan navigera genom dessa data offline. Om appen måste ha stöd för redigering måste ett system för att spåra ändringar och synkronisera data med serverdelen skapas.
• Om målet är att garantera att appen laddas omedelbart oavsett nätverksvillkor. Implementera en lämplig användarupplevelse kring serverdels-API-begäranden för att visa förloppet för begäranden och beter sig korrekt när begäranden misslyckas på grund av att nätverket inte är tillgängligt.

Dessutom måste offlinekompatibla PWA:er hantera en rad ytterligare komplikationer. Utvecklare bör noggrant bekanta sig med förbehållen i följande avsnitt.

Endast offlinestöd när det publiceras

Under utvecklingen vill du vanligtvis se varje ändring återspeglas direkt i webbläsaren utan att gå igenom en bakgrundsuppdateringsprocess. BlazorDärför aktiverar PWA-mallen endast offlinestöd när den publiceras.

När du skapar en offlinekompatibel app räcker det inte att testa appen i Development miljön. Du måste testa appen i dess publicerade tillstånd för att förstå hur den svarar på olika nätverksvillkor.

Uppdateringen har slutförts efter att användaren har navigerat bort från appen

Uppdateringarna slutförs inte förrän användaren har navigerat bort från appen på alla flikar. Som beskrivs i avsnittet Bakgrundsuppdateringar , när du har distribuerat en uppdatering till appen, hämtar webbläsaren de uppdaterade service worker-filerna för att påbörja uppdateringsprocessen.

Det som förvånar många utvecklare är att även när uppdateringen är klar börjar den inte gälla förrän användaren har navigerat bort på alla flikar. Det räcker inte att uppdatera fliken som visar appen, även om det är den enda fliken som visar appen. Tills din app är helt stängd förblir den nya servicearbetaren i väntande på aktivering. Detta är inte specifikt för Blazor, utan snarare ett standardbeteende för webbplattformen.

Detta stör ofta utvecklare som försöker testa uppdateringar av sina service workers eller offline-cachelagrade resurser. Om du checkar in webbläsarens utvecklarverktyg kan du se något som liknar följande:

Så länge listan över "klienter", som är flikar eller fönster som visar din app, inte är tom, fortsätter processen att vänta. Anledningen till att servicearbetare gör detta är för att garantera konsekvens. Konsekvens innebär att alla resurser hämtas från samma atomiska cacheminne.

När du testar ändringar kan det vara praktiskt att välja länken "skipWaiting" enligt föregående skärmbild och sedan läsa in sidan igen. Du kan automatisera detta för alla användare genom att koda din tjänstarbetare för att hoppa över "väntande"-fasen och aktivera omedelbart vid uppdatering. Om du hoppar över väntefasen ger du upp garantin för att resurser alltid hämtas konsekvent från samma cacheinstans.

Användare kan köra valfri historisk version av appen

Webbutvecklare förväntar sig vanligtvis att användarna bara kör den senaste distribuerade versionen av sin webbapp, eftersom det är normalt i den traditionella webbdistributionsmodellen. En PWA med offlineprioritering liknar dock mer en native mobilapp, där användarna inte nödvändigtvis kör den senaste versionen.

Som beskrivs i avsnittet Bakgrundsuppdateringar fortsätter varje befintlig användare att använda en tidigare version för minst ett ytterligare besök när du har distribuerat en uppdatering till din app eftersom uppdateringen sker i bakgrunden och inte aktiveras förrän användaren därefter navigerar bort. Dessutom är den tidigare versionen som används inte nödvändigtvis den tidigare versionen som du distribuerade. Den tidigare versionen kan vara vilken tidigare version som helst, beroende på när användaren senast slutförde en uppdatering.

Detta kan vara ett problem om klientdelen och serverdelen i din app kräver ett avtal om schemat för API-begäranden. Du får inte distribuera bakåtkompatibla API-schemaändringar förrän du kan vara säker på att alla användare har uppgraderat. Alternativt kan du blockera användare från att använda inkompatibla äldre versioner av appen. Det här scenariokravet är detsamma som för interna mobilappar. Om du distribuerar en icke-bakåtkompatibel ändring av server-API:er bryts klientappen för användare som ännu inte har uppdaterat.

Distribuera om möjligt inte bakåtkompatibilitetsbrytande ändringar till dina bakomliggande API:er. Om du måste göra det kan du överväga att använda Standard Service Worker-API:er, till exempel ServiceWorkerRegistration , för att avgöra om appen är up-to-date, och om inte, för att förhindra användning.

Interferens med server-renderade sidor

Om du vill kringgå servicearbetarens beteende att returnera innehåll för alla navigeringsbegäranden kan du, enligt beskrivningen i avsnittet /index.html, redigera logiken i din tjänstarbetare.

Allt innehåll i service worker-tillgångsmanifestet cachelagras

Enligt beskrivningen i avsnittet Kontrollera cachelagring av tillgångar genereras filen service-worker-assets.js under bygget och visar en lista över alla tillgångar som tjänstarbetaren ska hämta och cachelagra.

Eftersom den här listan innehåller allt som skickas till wwwroot, inklusive innehåll som tillhandahålls av externa paket och projekt, måste du vara noga med att inte lägga för mycket innehåll där. wwwroot Om katalogen innehåller miljontals bilder försöker tjänstarbetaren hämta och cachelagrar dem alla, vilket förbrukar överdriven bandbredd och troligen inte slutförs.

Implementera godtycklig logik för att styra vilken delmängd av manifestets innehåll som ska hämtas och cachelagras genom att redigera onInstall funktionen i service-worker.published.js.

Interaktion med autentisering

PWA-mallen kan användas tillsammans med autentisering. En offlinekompatibel PWA kan också stödja autentisering när användaren har en inledande nätverksanslutning.

När en användare inte har någon nätverksanslutning kan de inte autentisera eller hämta åtkomsttoken. Försök att besöka inloggningssidan utan nätverksåtkomst resulterar i ett "nätverksfel"-meddelande. Du måste utforma ett användargränssnittsflöde som gör att användaren kan utföra användbara uppgifter offline utan att försöka autentisera användaren eller hämta åtkomsttoken. Du kan också utforma appen så att den misslyckas korrekt när nätverket inte är tillgängligt. Om appen inte kan utformas för att hantera dessa scenarier kanske du inte vill aktivera offlinesupport.

När en app som är utformad för online- och offlineanvändning är online igen:

• Appen kan behöva etablera en ny åtkomsttoken.
• Appen måste identifiera om en annan användare är inloggad i tjänsten så att den kan tillämpa åtgärder på användarens konto som gjordes när de var offline.

Så här skapar du en PWA-offlineapp som interagerar med autentisering:

• AccountClaimsPrincipalFactory<TAccount> Ersätt med en fabrik som lagrar den senast inloggade användaren och använder den lagrade användaren när appen är offline.
• Spara åtgärder medan appen är offline och tillämpa dem när appen återvänder online.
• Rensa den lagrade användaren under utloggningen.

Exempelappen CarChecker visar föregående metoder. Se följande delar av appen:

• OfflineAccountClaimsPrincipalFactory (Client/Data/OfflineAccountClaimsPrincipalFactory.cs)
• LocalVehiclesStore (Client/Data/LocalVehiclesStore.cs)
• LoginStatus komponent (Client/Shared/LoginStatus.razor)

Ytterligare resurser