Dela via

Komponenter i Prerender ASP.NET Core Razor

Anteckning

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 .

Viktig

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 Razor prerendringsscenarier för serveråtergivna komponenter i Blazor Web Apps.

Prerendering är processen att först återge sidinnehåll på servern utan att aktivera händelsehanterare för renderade kontroller. Servern matar ut HTML-användargränssnittet på sidan så snart som möjligt som svar på den första begäran, vilket gör att appen känns mer dynamisk för användarna. Prerendering kan också förbättra sökmotoroptimering (SEO) genom att återge innehåll för det första HTTP-svaret som sökmotorer använder för att beräkna sidrankning.

Bevara fördefinierat tillstånd

Utan att det förgenererade tillståndet bevaras går tillståndet som används under förgenereringen förlorat och måste återskapas när appen är fullt inladdad. Om något tillstånd skapas asynkront kan användargränssnittet flimra när det förinstallerade användargränssnittet ersätts när komponenten återställs.

Överväg följande PrerenderedCounter1 räknarkomponent. Komponenten anger ett initialt slumpmässigt räknarvärde under förinläsning i OnInitialized livscykelmetoden. När SignalR-anslutningen till klienten har upprättats, renderas komponenten på nytt och det initiala antalsvärdet ersätts när OnInitialized utförs en andra gång.

PrerenderedCounter1.razor:

@page "/prerendered-counter-1"
@rendermode @(new InteractiveServerRenderMode(prerender: true))
@inject ILogger<PrerenderedCounter1> Logger

<PageTitle>Prerendered Counter 1</PageTitle>

<h1>Prerendered Counter 1</h1>

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

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

@code {
    private int currentCount;

    protected override void OnInitialized()
    {
        currentCount = Random.Shared.Next(100);
        Logger.LogInformation("currentCount set to {Count}", currentCount);
    }

    private void IncrementCount() => currentCount++;
}

Kör appen och inspektera loggning från komponenten. Följande är exempelutdata.

Anteckning

Om appen använder interaktiv routning och sidan nås via en intern förbättrad navigering sker inte prerendering. Därför måste du utföra en fullständig sidåterläsning för PrerenderedCounter1-komponenten för att se följande resultat. Mer information finns i avsnittet Interaktiv routning och prerendering .

info: BlazorSample.Components.Pages.PrerenderedCounter1[0]
currentCount set to 41
info: BlazorSample.Components.Pages.PrerenderedCounter1[0]
currentCount set to 92

Det första loggade antalet inträffar under förhandsrendering. Antalet anges igen efter prerendering när komponenten har återskapats. Det finns också ett flimmer i användargränssnittet när antalet uppdateras från 41 till 92.

Om du vill bevara räknarens initiala värde under prerenderingen har Blazor stöd för bevarande av tillstånd på en prerenderad sida med hjälp av PersistentComponentState-tjänsten (och för komponenter som är inbäddade i sidor eller vyer av Razor-sidor eller MVC-appar, Tag Helper för att bevara komponenttillstånd).

Om du vill bevara förrenderat tillstånd använder du [SupplyParameterFromPersistentComponentState] attributet för att bevara tillståndet i egenskaper. Egenskaper med det här attributet sparas automatiskt med hjälp av PersistentComponentState tjänsten under förinläsningen. Tillståndet hämtas när komponenten återges interaktivt eller om tjänsten instansieras.

Som standard serialiseras egenskaperna med serialiseraren System.Text.Json med standardinställningar. Serialiseringen är inte trimmersäker och kräver att de typer som används bevaras. Mer information finns i Konfigurera Trimmer för ASP.NET Core Blazor.

Följande räknarkomponent bevarar räknartillståndet under förinläsningen och hämtar tillståndet för att initiera komponenten:

  • Attributet [SupplyParameterFromPersistentComponentState] tillämpas på CounterState typen (State).
  • Räknarens tillstånd tilldelas när null är i OnInitialized och återställs automatiskt när komponenten renderas interaktivt.

PrerenderedCounter2.razor:

@page "/prerendered-counter-2"
@inject ILogger<PrerenderedCounter2> Logger

<PageTitle>Prerendered Counter 2</PageTitle>

<h1>Prerendered Counter 2</h1>

<p role="status">Current count: @State?.CurrentCount</p>

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

@code {
    [SupplyParameterFromPersistentComponentState]
    public CounterState? State { get; set; }

    protected override void OnInitialized()
    {
        if (State is null)
        {
            State = new() { CurrentCount = Random.Shared.Next(100) };
            Logger.LogInformation("CurrentCount set to {Count}", 
                State.CurrentCount);
        }
        else
        {
            Logger.LogInformation("CurrentCount restored to {Count}", 
                State.CurrentCount);
        }
    }

    private void IncrementCount()
    {
        if (State is not null)
        {
            State.CurrentCount++;
        }
    }

    public class CounterState
    {
        public int CurrentCount { get; set; }
    }
}

När komponenten körs anges CurrentCount endast en gång under förberedande rendering. Värdet återställs när komponenten återställs. Följande är exempelutdata.

Anteckning

Om appen använder interaktiv routning och sidan nås via en intern förbättrad navigering sker inte prerendering. Därför måste du utföra en fullständig sidåterläsning för komponenten för att se följande utdata. Mer information finns i avsnittet Interaktiv routning och prerendering .

info: BlazorSample.Components.Pages.PrerenderedCounter2[0]
CurrentCount set to 96
info: BlazorSample.Components.Pages.PrerenderedCounter2[0]
CurrentCount restored to 96

I följande exempel serialiserar tillståndet för flera komponenter av samma typ:

  • Egenskaper som kommenteras med [SupplyParameterFromPersistentComponentState] attributet serialiseras och deserialiseras under prerendering.
  • Direktivattributet@key används för att säkerställa att tillståndet är korrekt associerat med komponentinstansen.
  • Egenskapen Element initieras i OnInitialized livscykelmetoden för att undvika null-referensfel, på samma sätt som nullreferenser undviks för frågeparametrar och formulärdata.

PersistentChild.razor:

<div>
    <p>Current count: @Element.CurrentCount</p>
    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
</div>

@code {
    [SupplyParameterFromPersistentComponentState]
    public State Element { get; set; }

    protected override void OnInitialized()
    {
        Element ??= new State();
    }

    private void IncrementCount()
    {
        Element.CurrentCount++;
    }

    private class State
    {
        public int CurrentCount { get; set; }
    }
}

Parent.razor:

@page "/parent"

@foreach (var element in elements)
{
    <PersistentChild @key="element.Name" />
}

I följande exempel serialiseras tillståndet för en beroendeinjektionstjänst:

  • Egenskaper som kommenteras med [SupplyParameterFromPersistentComponentState] attributet serialiseras under prerendering och deserialiseras när appen blir interaktiv.
  • Metoden AddPersistentService används för att registrera tjänsten för beständighet. Återgivningsläget krävs eftersom återgivningsläget inte kan härledas från tjänsttypen. Använd något av följande värden:
    • RenderMode.Server: Tjänsten är tillgänglig för återgivningsläget för interaktiv server.
    • RenderMode.Webassembly: Tjänsten är tillgänglig för interaktivt WebAssembly-återgivningsläge.
    • RenderMode.InteractiveAuto: Tjänsten är tillgänglig för både återgivningslägena interaktiv server och interaktiv webassembly om en komponent återges i något av dessa lägen.
  • Tjänsten löses under initieringen av ett interaktivt återgivningsläge och egenskaperna som kommenteras med [SupplyParameterFromPersistentComponentState] attributet deserialiseras.

Anteckning

Endast bevarande av avgränsade tjänster stöds.

CounterService.cs:

public class CounterService
{
    [SupplyParameterFromPersistentComponentState]
    public int CurrentCount { get; set; }

    public void IncrementCount()
    {
        CurrentCount++;
    }
}

I Program.cs:

builder.Services.AddPersistentService<CounterService>(RenderMode.InteractiveAuto);

Serialiserade egenskaper identifieras från den faktiska tjänstinstansen:

  • Med den här metoden kan du markera en abstraktion som en beständig tjänst.
  • Gör att faktiska implementeringar kan vara interna eller olika typer.
  • Stöder delad kod i olika sammansättningar.
  • Resulterar i att varje instans visar samma egenskaper.

Som ett alternativ till att använda den deklarativa modellen för att bevara tillståndet med [SupplyParameterFromPersistentComponentState] attributet kan du använda PersistentComponentState tjänsten direkt, vilket ger större flexibilitet för komplexa scenarier för tillståndsbeständighet. Anropa PersistentComponentState.RegisterOnPersisting för att registrera ett återanrop för att bevara komponenttillståndet under förinläsningen. Tillståndet hämtas när komponenten återges interaktivt. Gör anropet i slutet av initieringskoden för att undvika ett potentiellt låsningstillstånd under appavstängningen.

Följande exempel på räknarkomponent bevarar räknartillståndet under förbearbetning och återhämtar tillståndet för att initiera komponenten.

PrerenderedCounter3.razor:

@page "/prerendered-counter-3"
@implements IDisposable
@inject ILogger<PrerenderedCounter3> Logger
@inject PersistentComponentState ApplicationState

<PageTitle>Prerendered Counter 3</PageTitle>

<h1>Prerendered Counter 3</h1>

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

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

@code {
    private int currentCount;
    private PersistingComponentStateSubscription persistingSubscription;

    protected override void OnInitialized()
    {
        if (!ApplicationState.TryTakeFromJson<int>(
            nameof(currentCount), out var restoredCount))
        {
            currentCount = Random.Shared.Next(100);
            Logger.LogInformation("currentCount set to {Count}", currentCount);
        }
        else
        {
            currentCount = restoredCount!;
            Logger.LogInformation("currentCount restored to {Count}", currentCount);
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistCount);
    }

    private Task PersistCount()
    {
        ApplicationState.PersistAsJson(nameof(currentCount), currentCount);

        return Task.CompletedTask;
    }

    private void IncrementCount() => currentCount++;

    void IDisposable.Dispose() => persistingSubscription.Dispose();
}

När komponenten körs anges currentCount endast en gång under förberedande rendering. Värdet återställs när komponenten återställs. Följande är exempelutdata.

Anteckning

Om appen använder interaktiv routning och sidan nås via en intern förbättrad navigering sker inte prerendering. Därför måste du utföra en fullständig sidåterläsning för komponenten för att se följande utdata. Mer information finns i avsnittet Interaktiv routning och prerendering .

info: BlazorSample.Components.Pages.PrerenderedCounter3[0]
currentCount set to 96
info: BlazorSample.Components.Pages.PrerenderedCounter3[0]
currentCount restored to 96

Om du vill bevara förinstallerat tillstånd bestämmer du vilket tillstånd som ska sparas med hjälp av PersistentComponentState-tjänsten. PersistentComponentState.RegisterOnPersisting registrerar ett återanrop för att bevara komponenttillståndet under förinläsningen. Tillståndet hämtas när komponenten återges interaktivt. Gör anropet i slutet av initieringskoden för att undvika ett potentiellt låsningstillstånd under appavstängningen.

Följande exempel på räknarkomponent bevarar räknartillståndet under förbearbetning och återhämtar tillståndet för att initiera komponenten.

PrerenderedCounter2.razor:

@page "/prerendered-counter-2"
@implements IDisposable
@inject ILogger<PrerenderedCounter2> Logger
@inject PersistentComponentState ApplicationState

<PageTitle>Prerendered Counter 2</PageTitle>

<h1>Prerendered Counter 2</h1>

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

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

@code {
    private int currentCount;
    private PersistingComponentStateSubscription persistingSubscription;

    protected override void OnInitialized()
    {
        if (!ApplicationState.TryTakeFromJson<int>(
            nameof(currentCount), out var restoredCount))
        {
            currentCount = Random.Shared.Next(100);
            Logger.LogInformation("currentCount set to {Count}", currentCount);
        }
        else
        {
            currentCount = restoredCount!;
            Logger.LogInformation("currentCount restored to {Count}", currentCount);
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistCount);
    }

    private Task PersistCount()
    {
        ApplicationState.PersistAsJson(nameof(currentCount), currentCount);

        return Task.CompletedTask;
    }

    void IDisposable.Dispose() => persistingSubscription.Dispose();

    private void IncrementCount() => currentCount++;
}

När komponenten körs anges currentCount endast en gång under förberedande rendering. Värdet återställs när komponenten återställs. Följande är exempelutdata.

Anteckning

Om appen använder interaktiv routning och sidan nås via en intern förbättrad navigering sker inte prerendering. Därför måste du utföra en fullständig sidåterläsning för komponenten för att se följande utdata. Mer information finns i avsnittet Interaktiv routning och prerendering .

info: BlazorSample.Components.Pages.PrerenderedCounter2[0]
currentCount set to 96
info: BlazorSample.Components.Pages.PrerenderedCounter2[0]
currentCount restored to 96

Genom att initiera komponenter med samma tillstånd som används under förinläsningen körs eventuella dyra initieringssteg bara en gång. Det renderade användargränssnittet matchar också det förinstallerade användargränssnittet, så inget flimmer förekommer i webbläsaren.

Det beständiga förinstallerade tillståndet överförs till klienten, där det används för att återställa komponenttillståndet. Under återgivning på klientsidan (CSR, InteractiveWebAssembly) exponeras data i webbläsaren och får inte innehålla känslig, privat information. Under interaktiv återgivning på serversidan (interaktiv SSR, InteractiveServer), säkerställer ASP.NET Core Data Protection att data överförs på ett säkert sätt. Återgivningsläget InteractiveAuto kombinerar WebAssembly och serverinteraktivitet, så det är viktigt att beakta dataexponeringen för webbläsaren, som i fallet med CSR.

Komponenter inbäddade i sidor och vyer (Razor Pages/MVC)

För komponenter som bäddas in i en sida eller vy av en Razor Pages- eller MVC-app måste du lägga till hjälpverktyget För att bevara komponenttillstånd med <persist-component-state /> HTML-taggen i den avslutande </body> taggen i appens layout. Detta krävs endast för Razor Pages- och MVC-appar. För mer information, se Tagghjälp för att bevara komponenttillståndet i ASP.NET Core.

Pages/Shared/_Layout.cshtml:

<body>
    ...

    <persist-component-state />
</body>

Interaktiv routning och prerendering

När den Routes komponenten inte definierar ett återgivningsläge använder appen interaktivitet och navigering per sida/komponent. Med hjälp av navigering per sida/komponent hanteras intern† navigering genom förbättrad routning när appen blir interaktiv. †Internal i den här kontexten innebär att URL-målet för navigeringshändelsen är en Blazor slutpunkt i appen.

Tjänsten PersistentComponentState fungerar bara vid den inledande sidinläsningen och inte vid förbättrade interna sidnavigeringshändelser.

Om appen utför en fullständig (icke-utökad) navigering till en sida med beständiga komponenttillstånd görs det beständiga tillståndet tillgängligt för appen att använda när den blir interaktiv.

Om en interaktiv krets redan har upprättats och en förbättrad navigering utförs på en sida med beständiga komponenttillstånd , görs inte tillståndet tillgängligt i den befintliga kretsen för komponenten som ska användas. Det finns ingen prerendering för den interna sidbegäran och PersistentComponentState-tjänsten är inte medveten om att en förbättrad navigering har inträffat. Det finns ingen mekanism för att leverera tillståndsuppdateringar till komponenter som redan körs på en befintlig krets. Anledningen till detta är att Blazor endast stöder överföring av tillstånd från servern till klienten när körtiden initieras, inte efter att körtiden har startat.

Ytterligare arbete med det Blazor ramverket för att hantera det här scenariot övervägs för .NET 10 (november 2025). Mer information och community-diskussion om lösningar som inte stöds‡finns i Support persistent component state across enhanced page navigations (dotnet/aspnetcore #51584). ‡Lösningar som inte stöds sanktioneras inte av Microsoft för användning i Blazor appar. Använd paket, metoder och kod från tredje part på egen risk.

Om du avaktiverar förbättrad navigering, vilket minskar prestandan men också undviker problemet med inläsningstillstånd med PersistentComponentState för interna sidbegäranden, täcks detta i ASP.NET Core Blazor-routning och navigering.

Vägledning för förberendering

Vägledning för föråtergivning organiseras i Blazor-dokumentationen efter ämnesområde. Följande länkar täcker all vägledning för förberendering i dokumentationen efter ämne:

För .NET 7 eller tidigare, se Blazor WebAssembly ytterligare scenarier för säkerhet: Förberedning med autentisering. När du har sett innehållet i det här avsnittet, återställ listrutan för att välja version för dokumentationsartikeln till den senaste .NET-versionen för att säkerställa att dokumentationssidorna laddas för den senaste versionen vid efterföljande besök.