Dela via


ASP.NET Core Blazor uppstart

Anmärkning

Det här är inte den senaste versionen av den här artikeln. För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

Varning

Den här versionen av ASP.NET Core stöds inte längre. Mer information finns i .NET och .NET Core Support Policy. För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

Viktigt!

Den här informationen gäller en förhandsversionsprodukt som kan ändras avsevärt innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som tillhandahålls här.

För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

Den här artikeln beskriver Blazor appstartkonfiguration.

Allmän vägledning om ASP.NET Core-appkonfiguration för utveckling på serversidan finns i Configuration i ASP.NET Core.

Startprocess och konfiguration

Startprocessen för Blazor är automatisk och asynkron via det Blazor skriptet (blazor.*.js), där platshållaren för * är:

  • web för en Blazor Web App
  • server för en Blazor Server app
  • webassembly för en Blazor WebAssembly app

Startprocessen för Blazor är automatisk och asynkron via det Blazor skriptet (blazor.*.js), där platshållaren för * är:

  • server för en Blazor Server app
  • webassembly för en Blazor WebAssembly app

Platsen för skriptet finns i ASP.NET Core Blazor projektstruktur.

Starta Blazormanuellt:

Blazor Web App:

  • Lägg till ett autostart="false" attribut och värde i taggen Blazor<script>.
  • Placera ett skript som anropar Blazor.start() efter taggen Blazor<script> och inuti den avslutande taggen </body>.
  • Placera alternativ för statisk återgivning på serversidan (statisk SSR) i egenskapen ssr.
  • Placera kretsalternativen på serversidan Blazor-SignalR i egenskapen circuit.
  • Placera WebAssembly-alternativ på klientsidan i egenskapen webAssembly.
<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  ...
  Blazor.start({
    ssr: {
      ...
    },
    circuit: {
      ...
    },
    webAssembly: {
      ...
    }
  });
  ...
</script>

Fristående Blazor WebAssembly och Blazor Server:

  • Lägg till ett autostart="false" attribut och värde i taggen Blazor<script>.
  • Placera ett skript som anropar Blazor.start() efter taggen Blazor<script> och inuti den avslutande taggen </body>.
  • Du kan ange ytterligare alternativ i parametern Blazor.start().
<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  ...
  Blazor.start({
    ...
  });
  ...
</script>

I det föregående exemplet representerar platshållaren {BLAZOR SCRIPT} skriptsökvägen och filnamnet för Blazor. Platsen för skriptet finns i ASP.NET Core Blazor projektstruktur.

JavaScript-initierare

JavaScript-initierare (JS) kör logik både före och efter det att en applikation Blazor har laddats. JS initialiserare är användbara i följande scenarier:

  • Anpassa hur en Blazor-app laddas.
  • Initierar bibliotek innan Blazor startar.
  • Konfigurering av Blazor-inställningar.

JS initialiserare identifieras som en del av byggprocessen och importeras automatiskt. Användning av JS initierare tar ofta bort behovet av att manuellt utlösa skriptfunktioner från appen när du använder Razor klassbibliotek (RCLs).

Om du vill definiera en JS initierare lägger du till en JS-modul i projektet med namnet {NAME}.lib.module.js, där platshållaren {NAME} är sammansättningsnamn, biblioteksnamn eller paketidentifierare. Placera filen i projektets webbrot, som vanligtvis är den wwwroot mappen.

För Blazor Web Apps:

  • beforeWebStart(options): Anropas innan Blazor Web App startar. Till exempel används beforeWebStart för att anpassa inläsningsprocessen, loggningsnivån och andra alternativ. Tar emot Blazor- webbalternativen (options).
  • afterWebStarted(blazor): Anropas när alla beforeWebStart löften har gått i uppfyllelse. Till exempel kan afterWebStarted användas för att registrera Blazor händelselyssnare och anpassade händelsetyper. Denna Blazor-instans skickas till afterWebStarted som ett argument (blazor).
  • beforeServerStart(options, extensions): Anropas innan den första serverdriften startas. Tar emot SignalR kretsstartalternativ (options) och eventuella tillägg (extensions) som lades till under publiceringen.
  • afterServerStarted(blazor): Anropas efter att den interaktiva serverns första körning har startats.
  • beforeWebAssemblyStart(options, extensions): Anropas innan den interaktiva WebAssembly-körningen startas. Tar emot de Blazor alternativen (options) och eventuella tillägg (extensions) som har lagts till under publiceringen. Till exempel kan alternativ ange användning av en anpassad startresursinläsare.
  • afterWebAssemblyStarted(blazor): Anropas efter att den interaktiva WebAssembly-runtime har startats.

Anmärkning

Äldre JS-initierare (beforeStart, afterStarted) anropas inte som standard i en Blazor Web App. Du kan aktivera äldre initierare så att de körs med alternativet enableClassicInitializers. Exekveringen av äldre initierare är dock oförutsägbar.

<script>
  Blazor.start({ enableClassicInitializers: true });
</script>

På grund av ett ramverksfel i .NET 8 och 9 (dotnet/aspnetcore #54049) måste skriptet Blazor startas manuellt när beforeWebAssemblyStart(options, extensions) eller afterWebAssemblyStarted(blazor) anropas. Om serverappen inte redan startar Blazor manuellt med en WebAssembly-konfiguration (webAssembly: {...}) uppdaterar du komponenten App i serverprojektet med följande.

I Components/App.razortar du bort den befintliga Blazor<script> taggen:

- <script src="_framework/blazor.web.js"></script>

Ersätt taggen <script> med följande markering som startar Blazor manuellt med en WebAssembly-konfiguration (webAssembly: {...}):

<script src="_framework/blazor.web.js" autostart="false"></script>
<script>
    Blazor.start({
        webAssembly: {}
    });
</script>

För Blazor Server, Blazor WebAssemblyoch Blazor Hybrid appar:

  • beforeStart(options, extensions): Anropas innan Blazor startar. Till exempel används beforeStart för att anpassa inläsningsprocessen, loggningsnivån och andra alternativ som är specifika för värdmodellen.
    • På klientsidan tar beforeStart emot de Blazor alternativen (options) och eventuella tillägg (extensions) som lades till under publiceringen. Till exempel kan alternativ ange användning av en anpassad startresursinläsare.
    • På serversidan tar beforeStart emot kretsens SignalR startalternativ (options).
    • I en BlazorWebViewskickas inga alternativ.
  • afterStarted(blazor): Anropas efter att Blazor är redo att ta emot samtal från JS. Till exempel används afterStarted för att initiera bibliotek genom att göra JS interop-anrop och registrera anpassade element. Denna Blazor-instans skickas till afterStarted som ett argument (blazor).

Ytterligare .NET WebAssembly runtime-återanrop:

  • onRuntimeConfigLoaded(config): Anropas när startkonfigurationen laddas ned. Tillåter att appen ändrar parametrar (konfiguration) innan körningen startar (parametern är MonoConfig från dotnet.d.ts):

    export function onRuntimeConfigLoaded(config) {
      // Sample: Enable startup diagnostic logging when the URL contains 
      // parameter debug=1
      const params = new URLSearchParams(location.search);
      if (params.get("debug") == "1") {
        config.diagnosticTracing = true;
      }
    }
    
  • onRuntimeReady({ getAssemblyExports, getConfig }): Anropas efter att .NET WebAssembly-körningen har startats (parametern är RuntimeAPI från dotnet.d.ts):

    export function onRuntimeReady({ getAssemblyExports, getConfig }) {
      // Sample: After the runtime starts, but before Main method is called, 
      // call [JSExport]ed method.
      const config = getConfig();
      const exports = await getAssemblyExports(config.mainAssemblyName);
      exports.Sample.Greet();
    }
    

Båda återanropen kan returnera en Promiseoch man väntar på att löftet ska uppfyllas innan uppstarten fortsätter.

För filnamnet:

  • Om JS initialiserare används som en statisk resurs i projektet, ska du använda formatet {ASSEMBLY NAME}.lib.module.js, där {ASSEMBLY NAME}-platshållaren är appens sammansättningsnamn. Ge till exempel filen namnet BlazorSample.lib.module.js för ett projekt med sammansättningsnamnet BlazorSample. Placera filen i appens wwwroot mapp.
  • JS Om initierarna används från en RCL använder du formatet {LIBRARY NAME/PACKAGE ID}.lib.module.js, där {LIBRARY NAME/PACKAGE ID} platshållaren är projektets biblioteksnamn eller paketidentifierare (<PackageId> värdet i bibliotekets projektfil). Ge till exempel filen namnet RazorClassLibrary1.lib.module.js för en RCL med en paketidentifierare för RazorClassLibrary1. Placera filen i bibliotekets wwwroot mapp.

För Blazor Web Apps:

I det följande exemplet demonstreras JS initialiserare som laddar in anpassade skript både före och efter att Blazor Web App har startat, genom att lägga till dem i <head> i beforeWebStart och afterWebStarted.

export function beforeWebStart() {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'beforeStartScripts.js');
  document.head.appendChild(customScript);
}

export function afterWebStarted() {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'afterStartedScripts.js');
  document.head.appendChild(customScript);
}

Föregående beforeWebStart exempel garanterar bara att det anpassade skriptet läses in innan Blazor startar. Det garanterar inte att ofullbordade löften i skriptet slutförs innan Blazor startar.

För Blazor Server, Blazor WebAssemblyoch Blazor Hybrid appar:

I följande exempel visas JS initieringsskript som importerar anpassade skript före och efter att Blazor har startat, genom att dessa skript läggs till i <head> i beforeStart och afterStarted:

export function beforeStart(options, extensions) {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'beforeStartScripts.js');
  document.head.appendChild(customScript);
}

export function afterStarted(blazor) {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'afterStartedScripts.js');
  document.head.appendChild(customScript);
}

Föregående beforeStart exempel garanterar bara att det anpassade skriptet läses in innan Blazor startar. Det garanterar inte att ofullbordade löften i skriptet slutförs innan Blazor startar.

Anmärkning

MVC- och Razor Pages-appar laddar inte automatiskt JS-initierare. Utvecklarkod kan dock innehålla ett skript för att hämta appens manifest och trigga laddningen av JS-initialiserare.

Exempel på JS initierare finns i följande källor:

Anmärkning

Dokumentationslänkar till .NET-referenskällan läser vanligtvis in lagringsplatsens standardgren, vilket representerar den aktuella utvecklingen för nästa version av .NET. Om du vill välja en tagg för en specifik version använder du listrutan Välj bland grenar eller taggar. Mer information finns i Så här väljer du en versionstagg för ASP.NET Core-källkod (dotnet/AspNetCore.Docs #26205).

Försäkra dig om att bibliotek läses in i en viss ordning

Lägg till anpassade skript till <head> i beforeStart och afterStarted i den ordning de ska laddas.

I följande exempel läses script1.js in innan script2.js och script3.js innan script4.js.

export function beforeStart(options, extensions) {
    var customScript1 = document.createElement('script');
    customScript1.setAttribute('src', 'script1.js');
    document.head.appendChild(customScript1);

    var customScript2 = document.createElement('script');
    customScript2.setAttribute('src', 'script2.js');
    document.head.appendChild(customScript2);
}

export function afterStarted(blazor) {
    var customScript1 = document.createElement('script');
    customScript1.setAttribute('src', 'script3.js');
    document.head.appendChild(customScript1);

    var customScript2 = document.createElement('script');
    customScript2.setAttribute('src', 'script4.js');
    document.head.appendChild(customScript2);
}

Importera ytterligare moduler

Använd import-instruktioner på den översta nivån i filen JS initializers för att importera ytterligare moduler.

additionalModule.js:

export function logMessage() {
  console.log('logMessage is logging');
}

I filen JS initieringar (.lib.module.js):

import { logMessage } from "/additionalModule.js";

export function beforeStart(options, extensions) {
  ...

  logMessage();
}

Importkarta

Import maps stöds av ASP.NET Core och Blazor.

Initiera Blazor när dokumentet är klart

Följande exempel börjar Blazor när dokumentet är klart:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    Blazor.start();
  });
</script>

I det föregående exemplet representerar platshållaren {BLAZOR SCRIPT} skriptsökvägen och filnamnet för Blazor. Platsen för skriptet finns i ASP.NET Core Blazor projektstruktur.

Kedja till Promise som är resultatet av en manuell start

Om du vill utföra ytterligare uppgifter, till exempel JS interop-initiering, använder du then för att länka till Promise som är resultatet av en manuell Blazor appstart:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start().then(function () {
    ...
  });
</script>

I det föregående exemplet representerar platshållaren {BLAZOR SCRIPT} skriptsökvägen och filnamnet för Blazor. Platsen för skriptet finns i ASP.NET Core Blazor projektstruktur.

Anmärkning

Om du vill att ett bibliotek ska köra ytterligare uppgifter automatiskt när Blazor har startat använder du en JavaScript-initierare. Användning av en JS-initierare kräver inte att bibliotekets konsument sammanlänkar JS-anrop till Blazor:s manuella start.

Ladda startresurser på klientsidan

När en app läses in i webbläsaren laddar appen ned startresurser från servern:

  • JavaScript-kod för att starta appen
  • .NET-körtid och samlingar
  • Platspecifika data

Anpassa hur dessa startresurser läses in med hjälp av loadBootResource-API:et. Funktionen loadBootResource åsidosätter den inbyggda mekanismen för inläsning av startresurser. Använd loadBootResource för följande scenarier:

  • Läs in statiska resurser, till exempel tidszonsdata eller dotnet.wasm, från ett CDN.
  • Läs in komprimerade sammansättningar med hjälp av en HTTP-begäran och dekomprimera dem på klienten för värdar som inte stöder hämtning av komprimerat innehåll från servern.
  • Ge resurser ett alias till ett annat namn genom att omdirigera varje förfrågan om fetch till ett nytt namn.

Anmärkning

Externa källor måste returnera de nödvändiga CORS (Cross-Origin Resource Sharing)--huvudena för att webbläsare ska tillåta laddning av resurser från olika ursprung. CDN:er tillhandahåller vanligtvis de nödvändiga rubrikerna.

loadBootResource parametrar visas i följande tabell.

Parameter Beskrivning
type Resurstypen. Tillåtna typer är: assembly, pdb, dotnetjs, dotnetwasmoch timezonedata. Du behöver bara ange typer för anpassade beteenden. Typer som inte anges för loadBootResource läses in av ramverket enligt deras standardinläsningsbeteenden. Den dotnetjs startresursen (dotnet.*.js) måste antingen returnera null för standardinläsningsbeteende eller en URI för källan till dotnetjs startresurs.
name Namnet på resursen.
defaultUri Resursens relativa eller absoluta URI.
integrity Integritetssträngen som representerar det förväntade innehållet i svaret.

Funktionen loadBootResource kan returnera en URI-sträng för att åsidosätta inläsningsprocessen. I följande exempel hanteras följande filer från bin/Release/{TARGET FRAMEWORK}/wwwroot/_framework från ett CDN på https://cdn.example.com/blazorwebassembly/{VERSION}/:

  • dotnet.*.js
  • dotnet.wasm
  • Tidszonsdata

Platshållaren {TARGET FRAMEWORK} är namnet på målramverket (till exempel net7.0). Platshållaren {VERSION} är den delade ramverksversionen (till exempel 7.0.0).

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        console.log(`Loading: '${type}', '${name}', '${defaultUri}', '${integrity}'`);
        switch (type) {
          case 'dotnetjs':
          case 'dotnetwasm':
          case 'timezonedata':
            return `https://cdn.example.com/blazorwebassembly/{VERSION}/${name}`;
        }
      }
    }
  });
</script>

Fristående Blazor WebAssembly:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      console.log(`Loading: '${type}', '${name}', '${defaultUri}', '${integrity}'`);
      switch (type) {
        case 'dotnetjs':
        case 'dotnetwasm':
        case 'timezonedata':
          return `https://cdn.example.com/blazorwebassembly/{VERSION}/${name}`;
      }
    }
  });
</script>

I det föregående exemplet representerar platshållaren {BLAZOR SCRIPT} skriptsökvägen och filnamnet för Blazor. Platsen för skriptet finns i ASP.NET Core Blazor projektstruktur.

Om du vill anpassa mer än bara URL:er för startresurser kan funktionen loadBootResource anropa fetch direkt och returnera resultatet. I följande exempel läggs ett anpassat HTTP-huvud till i utgående begäranden. Om du vill behålla standardbeteendet för integritetskontroll går du igenom parametern integrity.

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        if (type == 'dotnetjs') {
          return null;
        } else {
          return fetch(defaultUri, {
            cache: 'no-cache',
            integrity: integrity,
            headers: { 'Custom-Header': 'Custom Value' }
          });
        }
      }
    }
  });
</script>

Fristående Blazor WebAssembly:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      if (type == 'dotnetjs') {
        return null;
      } else {
        return fetch(defaultUri, {
          cache: 'no-cache',
          integrity: integrity,
          headers: { 'Custom-Header': 'Custom Value' }
        });
      }
    }
  });
</script>

I det föregående exemplet representerar platshållaren {BLAZOR SCRIPT} skriptsökvägen och filnamnet för Blazor. Platsen för skriptet finns i ASP.NET Core Blazor projektstruktur.

När funktionen loadBootResource returnerar nullanvänder Blazor standardinläsningsbeteendet för resursen. Den föregående koden returnerar till exempel null för den dotnetjs startresursen (dotnet.*.js) eftersom dotnetjs startresursen antingen måste returnera null för standardinläsningsbeteende eller en URI för källan för den dotnetjs startresursen.

Funktionen loadBootResource kan också returnera ett Response löfte. Ett exempel finns i Hosta och distribuera ASP.NET Core Blazor WebAssembly.

Mer information finns i ASP.NET Fel vid cachelagring och integritetskontroll av kärnorBlazor WebAssembly.

Kontrollera rubriker i C#-kod

Kontrollera sidhuvuden vid start i C#-kod med hjälp av följande metoder.

I följande exempel tillämpas en innehållssäkerhetsprincip (CSP) på appen via ett CSP-huvud. Platshållaren {POLICY STRING} är CSP-policysträngen. Mer information om CSP:er finns i Framtvinga en innehållssäkerhetsprincip för ASP.NET Core Blazor.

Anmärkning

Det går inte att ange rubriker när svaret har startats. Metoderna i det här avsnittet anger bara rubriker innan svaret startar, så de metoder som beskrivs här är säkra. Mer information finns i IHttpContextAccessor/HttpContext i ASP.NET Core Blazor-appar.

Scenarier på serversidan och förinstallerade scenarier på klientsidan

Använd ASP.NET Core Middleware för att styra samlingen med rubriker.

I filen Program:

I Startup.Configure av Startup.cs:

app.Use(async (context, next) =>
{
    context.Response.Headers.Append("Content-Security-Policy", "{POLICY STRING}");
    await next();
});

I föregående exempel används infogade mellanprogram, men du kan också skapa en anpassad mellanprogramsklass och anropa mellanprogrammet med en tilläggsmetod i filen Program. Mer information finns i Skriv anpassad ASP.NET Core-mellanvara.

Utveckling på klientsidan utan prerendering

Skicka StaticFileOptions till MapFallbackToFile som specificerar svarshuvuden under OnPrepareResponse-fasen.

I Program-filen på serversidan:

I Startup.Configure av Startup.cs:

var staticFileOptions = new StaticFileOptions
{
    OnPrepareResponse = context =>
    {
        context.Context.Response.Headers.Append("Content-Security-Policy", 
            "{POLICY STRING}");
    }
};

...

app.MapFallbackToFile("index.html", staticFileOptions);

Inläsningsindikatorer på klientsidan

En inläsningsindikator visar att appen läses in normalt och att användaren bör vänta tills inläsningen är klar.

Blazor Web App inläsningsindikator

Inläsningsindikatorn som används i Blazor WebAssembly appar finns inte i en app som skapats från Blazor Web App projektmallen. Vanligtvis är en inläsningsindikator inte önskvärd för interaktiva WebAssembly-komponenter eftersom Blazor Web Appklientsidekomponenter förberedrenderas på servern för snabb första inläsning. I situationer med blandat återgivningsläge måste ramverks- eller utvecklarkoden också vara försiktig för att undvika följande problem:

  • Flera indikatorer för inladdning visas på samma renderade sida.
  • När man oavsiktligt tar bort förberenderat innehåll medan .NET WebAssembly-runtime läses in.

En framtida version av .NET kan ge en ramverksbaserad inläsningsindikator. Medan du väntar kan du lägga till en anpassad laddningsindikator till en Blazor Web App.

Interaktiv WebAssembly-återgivning per komponent med prerendering

Det här scenariot gäller för interaktiv WebAssembly-återgivning per komponent (@rendermode InteractiveWebAssembly tillämpas på enskilda komponenter).

Skapa en ContentLoading komponent i Layout mappen för appen .Client som anropar OperatingSystem.IsBrowser:

  • När false visas, visa en inläsningsindikator.
  • När truerenderar du den begärda komponentens innehåll.

För att ladda in CSS-stilar till indikatorn, lägg till formaten i <head> innehållet med HeadContent komponenten. För mer information, se Kontrollera innehållet i huvudet i ASP.NET Core Blazor appar.

Layout/ContentLoading.razor:

@if (!RendererInfo.IsInteractive)
{
    <!-- OPTIONAL ...
    <HeadContent>
        <style>
            ...
        </style>
    </HeadContent>
    -->
    <progress id="loadingIndicator" aria-label="Content loading…"></progress>
}
else
{
    @ChildContent
}

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}
@if (!OperatingSystem.IsBrowser())
{
    <!-- OPTIONAL ...
    <HeadContent>
        <style>
            ...
        </style>
    </HeadContent>
    -->
    <progress id="loadingIndicator" aria-label="Content loading…"></progress>
}
else
{
    @ChildContent
}

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}

Om du inte redan har en Layout mapp i .Client projektet lägger du till namnområdet för Layout mappen i _Imports.razor filen. I följande exempel är BlazorSample.Clientprojektets namnområde :

@using BlazorSample.Client.Layout

I en komponent som implementerar interaktiv WebAssembly-återgivning omsluter du komponentens Razor-markering med komponenten ContentLoading. I följande exempel visas metoden med den Counter komponenten i en app som skapats från Blazor Web App-projektmallen.

Pages/Counter.razor:

@page "/counter"
@rendermode InteractiveWebAssembly

<PageTitle>Counter</PageTitle>

<ContentLoading>
    <h1>Counter</h1>

    <p role="status">Current count: @currentCount</p>

    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
</ContentLoading>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

Interaktiv global WebAssembly-återgivning med pre-rendering

Det här scenariot gäller global interaktiv WebAssembly-återgivning med prerendering (@rendermode="InteractiveWebAssembly" på komponenterna HeadOutlet och Routes i komponenten App ).

Skapa en ContentLoading komponent i Layout mappen för appen .Client som anropar RendererInfo.IsInteractive:

  • När false visas, visa en inläsningsindikator.
  • När truerenderar du den begärda komponentens innehåll.

För att ladda in CSS-stilar till indikatorn, lägg till formaten i <head> innehållet med HeadContent komponenten. För mer information, se Kontrollera innehållet i huvudet i ASP.NET Core Blazor appar.

Layout/ContentLoading.razor:

@if (!RendererInfo.IsInteractive)
{
    <!-- OPTIONAL ...
    <HeadContent>
        <style>
            ...
        </style>
    </HeadContent>
    -->
    <progress id="loadingIndicator" aria-label="Content loading…"></progress>
}
else
{
    @ChildContent
}

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}
@if (!OperatingSystem.IsBrowser())
{
    <!-- OPTIONAL ...
    <HeadContent>
        <style>
            ...
        </style>
    </HeadContent>
    -->
    <progress id="loadingIndicator" aria-label="Content loading…"></progress>
}
else
{
    @ChildContent
}

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}

Om du inte redan har en Layout mapp i .Client projektet lägger du till namnområdet för Layout mappen i _Imports.razor filen. I följande exempel är BlazorSample.Clientprojektets namnområde :

@using BlazorSample.Client.Layout

I komponenten MainLayout (Layout/MainLayout.razor) i .Client projektet omsluter du Body egenskapen (@Body) med komponenten ContentLoading :

I Layout/MainLayout.razor:

+ <ContentLoading>
    @Body
+ </ContentLoading>

Global interaktiv WebAssembly-återgivning utan förhandsrendering

Det här scenariot gäller för global Interactive WebAssembly-återgivning utan föråtergivning (@rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" på komponenterna HeadOutlet och Routes i komponenten App ).

Lägg till en JavaScript-initierare i appen. I följande exempel på JavaScript-modulens filnamn {ASSEMBLY NAME} är platshållaren sammansättningsnamnet för serverprojektet (till exempel BlazorSample). Mappen wwwroot där modulen placeras är wwwroot mappen i projektet på serversidan, inte projektet .Client .

I följande exempel används en progress indikator som inte anger den faktiska förloppet för att leverera startresurser på klientsidan till klienten, men det fungerar som en allmän metod för vidareutveckling om du vill att förloppsindikatorn ska visa den faktiska förloppet för inläsning av appens startresurser.

wwwroot/{ASSEMBLY NAME}.lib.module.js:

export function beforeWebStart(options) {
  var progress = document.createElement("progress");
  progress.id = 'loadingIndicator';
  progress.ariaLabel = 'Blazor loading…';
  progress.style = 'position:absolute;top:50%;left:50%;margin-right:-50%;' +
    'transform:translate(-50%,-50%);';
  document.body.appendChild(progress);
}

export function afterWebAssemblyStarted(blazor) {
  var progress = document.getElementById('loadingIndicator');
  progress.remove();
}

På grund av ett ramverksfel i .NET 8 och 9 (dotnet/aspnetcore #54049) måste skriptet Blazor startas manuellt. Om serverappen inte redan startar Blazor manuellt med en WebAssembly-konfiguration (webAssembly: {...}) uppdaterar du komponenten App i serverprojektet med följande.

I Components/App.razortar du bort den befintliga Blazor<script> taggen:

- <script src="_framework/blazor.web.js"></script>

Ersätt taggen <script> med följande markering som startar Blazor manuellt med en WebAssembly-konfiguration (webAssembly: {...}):

<script src="_framework/blazor.web.js" autostart="false"></script>
<script>
    Blazor.start({
        webAssembly: {}
    });
</script>

Om du märker en kort fördröjning mellan borttagningen av inläsningsindikatorn och återgivningen av den första sidan kan du garantera att indikatorn tas bort efter återgivningen genom att anropa för att indikatorn ska tas bort i OnAfterRenderAsync livscykelmetoden för antingen komponenterna MainLayout eller Routes . För mer information och ett exempel på kod, se Dokumentera en metod för en laddningsindikator som fungerar med global interaktiv WebAssembly utan förbelysning (dotnet/AspNetCore.Docs #35111).

Blazor WebAssembly förlopp för inläsning av app

Projektmallen innehåller skalbar vektorgrafik (SVG) och textindikatorer som visar appens inläsningsförlopp.

Förloppsindikatorerna implementeras med HTML och CSS med hjälp av två anpassade CSS-egenskaper (variabler) som tillhandahålls av Blazor:

  • --blazor-load-percentage: Procentandelen appfiler som läses in.
  • --blazor-load-percentage-text: Procentandelen appfiler som läses in, avrundade till närmaste heltal.

Med hjälp av de föregående CSS-variablerna kan du skapa anpassade förloppsindikatorer som matchar appens formatering.

I följande exempel:

  • resourcesLoaded är en omedelbar räkning av resurser som läses in under appstarten.
  • totalResources är det totala antalet resurser som ska laddas.
const percentage = resourcesLoaded / totalResources * 100;
document.documentElement.style.setProperty(
  '--blazor-load-percentage', `${percentage}%`);
document.documentElement.style.setProperty(
  '--blazor-load-percentage-text', `"${Math.floor(percentage)}%"`);

Standardindikatorn för cirkelrunt förlopp implementeras i HTML i filen wwwroot/index.html.

<div id="app">
    <svg class="loading-progress">
        <circle r="40%" cx="50%" cy="50%" />
        <circle r="40%" cx="50%" cy="50%" />
    </svg>
    <div class="loading-progress-text"></div>
</div>

Information om hur du granskar projektmallens markering och formatering för standardstatusindikatorerna finns i referenskällan ASP.NET Core:

Anmärkning

Dokumentationslänkar till .NET-referenskällan läser vanligtvis in lagringsplatsens standardgren, vilket representerar den aktuella utvecklingen för nästa version av .NET. Om du vill välja en tagg för en specifik version använder du listrutan Välj bland grenar eller taggar. Mer information finns i Så här väljer du en versionstagg för ASP.NET Core-källkod (dotnet/AspNetCore.Docs #26205).

I stället för att använda standardindikatorn för rundat förlopp visar följande exempel hur du implementerar en linjär förloppsindikator.

Lägg till följande formatmallar i wwwroot/css/app.css:

.linear-progress {
    background: silver;
    width: 50vw;
    margin: 20% auto;
    height: 1rem;
    border-radius: 10rem;
    overflow: hidden;
    position: relative;
}

.linear-progress:after {
    content: '';
    position: absolute;
    inset: 0;
    background: blue;
    scale: var(--blazor-load-percentage, 0%) 100%;
    transform-origin: left top;
    transition: scale ease-out 0.5s;
}

En CSS-variabel (var(...)) används för att skicka värdet för --blazor-load-percentage till egenskapen scale för ett blått pseudoelement som anger inläsningsförloppet för appens filer. När appen laddas uppdateras --blazor-load-percentage automatiskt, vilket dynamiskt förändrar förloppsindikatorns utseende.

I wwwroot/index.htmltar du bort standardindikatorn för SVG-avrundning i <div id="app">...</div> och ersätter den med följande markering:

<div class="linear-progress"></div>

Konfigurera .NET WebAssembly-körtidsmiljön

I avancerade programmeringsscenarier används configureRuntime-funktionen med dotnet värdskriptskapare för att konfigurera .NET WebAssembly-runtime-miljön. Till exempel anger dotnet.withEnvironmentVariable en miljövariabel som:

  • Konfigurerar .NET WebAssembly-miljön.
  • Ändrar beteendet för ett C-bibliotek.

Anmärkning

En dokumentationsbegäran väntar på dotnet/runtime GitHub-lagringsplatsen för mer information om miljövariabler som konfigurerar .NET WebAssembly-körningen eller påverkar beteendet för C-bibliotek. Även om dokumentationsbegäran väntar finns mer information och korslänkar till ytterligare resurser i begäran , fråga/begäran om dokumentation om .NET WASM-körmiljövariabler (dotnet/runtime #98225).

Funktionen configureRuntime kan också användas för att aktivera integrering med en webbläsarprofilerare.

För platshållarna i följande exempel som anger en miljövariabel:

  • Platshållaren {BLAZOR SCRIPT} är skriptets sökväg och filnamn Blazor. Platsen för skriptet finns i ASP.NET Core Blazor projektstruktur.
  • Platshållaren {NAME} är miljövariabelns namn.
  • Platshållaren {VALUE} är miljövariabelns värde.

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      configureRuntime: dotnet => {
        dotnet.withEnvironmentVariable("{NAME}", "{VALUE}");
      }
    }
  });
</script>

Fristående Blazor WebAssembly:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    configureRuntime: dotnet => {
      dotnet.withEnvironmentVariable("{NAME}", "{VALUE}");
    }
  });
</script>

Anmärkning

.NET-runtime-instansen kan nås med hjälp av .NET WebAssembly Runtime API (Blazor.runtime). Appens byggkonfiguration kan till exempel hämtas med hjälp av Blazor.runtime.runtimeBuildInfo.buildConfiguration.

Mer information om .NET WebAssembly-körningskonfigurationen finns i -körningens TypeScript-definitionsfil (dotnet.d.ts) på dotnet/runtime GitHub-lagringsplatsen.

Anmärkning

Dokumentationslänkar till .NET-referenskällan läser vanligtvis in lagringsplatsens standardgren, vilket representerar den aktuella utvecklingen för nästa version av .NET. Om du vill välja en tagg för en specifik version använder du listrutan Välj bland grenar eller taggar. Mer information finns i Så här väljer du en versionstagg för ASP.NET Core-källkod (dotnet/AspNetCore.Docs #26205).

Inaktivera förbättrad navigering och formulärhantering

Det här avsnittet gäller för Blazor Web Apps.

Om du vill inaktivera förbättrad navigerings- och formulärhanteringanger du disableDomPreservation till true för Blazor.start:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    ssr: { disableDomPreservation: true }
  });
</script>

I det föregående exemplet representerar platshållaren {BLAZOR SCRIPT} skriptsökvägen och filnamnet för Blazor. Platsen för skriptet finns i ASP.NET Core Blazor projektstruktur.

Ytterligare resurser