Aracılığıyla paylaş

Önceden oluştur ASP.NET Core Razor bileşenleri

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 9 sürümüne bakın.

Önemli

Bu bilgiler, ticari olarak piyasaya sürülmeden önce önemli ölçüde değiştirilebilen bir yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.

Geçerli sürüm için bu makalenin .NET 9 sürümüne bakın.

Bu makalede, Razor bileşenlerinin sunucu tarafından işlendiği Blazor Web App içindeki ön işleme senaryoları açıklanmaktadır.

Ön kayıt , işlenen denetimler için olay işleyicilerini etkinleştirmeden başlangıçta sunucudaki sayfa içeriğini işleme işlemidir. Sunucu, uygulamanın kullanıcılara daha duyarlı hissetmesini sağlayan ilk isteğe yanıt olarak sayfanın HTML kullanıcı arabirimini mümkün olan en kısa sürede verir. Ön kayıt, arama motorlarının sayfa derecesini hesaplamak için kullandığı ilk HTTP yanıtının içeriğini işleyerek Arama Altyapısı İyileştirmesini (SEO) da geliştirebilir.

** Önceden oluşturulmuş durumu kalıcı hale getirmek

Önceden girilmiş durum kalıcı olmadan, ön kayıt sırasında kullanılan durum kaybolur ve uygulama tamamen yüklendiğinde yeniden oluşturulması gerekir. Herhangi bir durum zaman uyumsuz olarak oluşturulursa, önceden renderlanmış kullanıcı arabirimi bileşen yeniden renderlandığında değiştirildiği için kullanıcı arabirimi titreyebilir.

Aşağıdaki PrerenderedCounter1 sayaç bileşenini göz önünde bulundurun. Bileşen, yaşam döngüsü yöntemindeOnInitialized ön kayıt sırasında ilk rastgele sayaç değerini ayarlar. İstemciye SignalR bağlantı kurulduktan sonra bileşen yeniden oluşturulur ve OnInitialized ikinci kez yürütüldüğünde başlangıçta verilen sayı değeri değiştirilir.

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++;
}

Uygulamayı çalıştırın ve bileşendeki günlüğü inceleyin. Aşağıda örnek çıkış verilmiştir.

Not

Uygulama etkileşimli yönlendirmeyi benimserse ve sayfaya dahili gelişmiş bir gezinti yoluyla ulaşılırsa, ön kayıt gerçekleşmez. Bu nedenle, aşağıdaki çıkışı görmek için bileşenin PrerenderedCounter1 tam sayfa yeniden yüklemesini gerçekleştirmeniz gerekir. Daha fazla bilgi için Etkileşimli Yönlendirme ve Ön İşleme bölümüne bakın.

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

İlk günlüğe kaydedilen sayı, ön işleme sırasında gerçekleşir. Bileşen tekrar render edildiğinde, ön render sonrasında sayı yeniden ayarlanır. Ayrıca, sayı 41'den 92'ye güncelleştirildiğinde kullanıcı arabiriminde bir titreşim de vardır.

Ön kayıt sırasında sayacın ilk değerini korumak için, Blazor hizmeti kullanarak önceden oluşturulmuş bir sayfada durumun kalıcı olmasını destekler (Sayfalar veya MVC uygulamalarının PersistentComponentState sayfalarına veya görünümlerine eklenmiş bileşenler için Razor).

Önceden işlenmiş durumu korumak için, durumu özelliklerde kalıcı hale getirmek üzere [SupplyParameterFromPersistentComponentState] özniteliğini kullanın. Bu özniteliğe sahip özellikler, önceden işleme sırasında PersistentComponentState servisi kullanılarak otomatik olarak kalıcı hale getirilir. Durum, bileşen etkileşimli olarak işlendiğinde veya hizmet örneği başlatıldığında alınır.

Varsayılan olarak, özellikler varsayılan ayarlarla System.Text.Json seri hale getirici kullanılarak serileştirilir. Serileştirme, düzelticilerle güvenli değildir ve kullanılan türlerin korunması gerektirir. Daha fazla bilgi için bkz ASP.NET Core için Düzeltici'yi Ayarlama Blazor.

Aşağıdaki sayaç bileşeni, ön işleme sırasında sayaç durumunu kalıcı kılar ve bileşeni başlatmak için bu durumu geri yükler.

  • [SupplyParameterFromPersistentComponentState] özniteliği türüne CounterState (State) uygulanır.
  • Sayacın durumu, null içindeki OnInitialized olduğunda atanır ve bileşen etkileşimli bir şekilde görüntülendiğinde otomatik olarak geri yüklenir.

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; }
    }
}

Bileşen çalıştığında, CurrentCount önceden işleme sırasında yalnızca bir kez belirlenir. Bileşen yeniden başlatıldığında değer geri yüklenir. Aşağıda örnek çıkış verilmiştir.

Not

Uygulama etkileşimli yönlendirmeyi benimserse ve sayfaya dahili gelişmiş bir gezinti yoluyla ulaşılırsa, ön kayıt gerçekleşmez. Bu nedenle, aşağıdaki çıkışı görmek için bileşenin tam sayfa yeniden yüklemesini gerçekleştirmeniz gerekir. Daha fazla bilgi için Etkileşimli Yönlendirme ve Ön İşleme bölümüne bakın.

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

Aşağıdaki örnekte, aynı türdeki birden çok bileşenin durumunu seri hale getiren:

  • [SupplyParameterFromPersistentComponentState] özniteliğiyle açıklama eklenmiş özellikler, ön izleme sırasında seri hale getirilir ve seri durumdan çıkarılır.
  • @key yönerge özniteliği, durumun bileşen örneğiyle doğru şekilde ilişkilendirildiğinden emin olmak için kullanılır.
  • Element özelliği, sorgu parametreleri ve form verileri için null referanslardan nasıl kaçınıldığına benzer şekilde null referans hatalarını önlemek amacıyla yaşam döngüsü yöntemiOnInitialized içinde başlatılır.

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" />
}

Bağımlılık ekleme hizmetinin durumunu seri hale getiren aşağıdaki örnekte:

  • Özniteliği [SupplyParameterFromPersistentComponentState] ile işaretlenmiş özellikler, ön işleme sırasında seri hale getirilir ve uygulama etkileşimli hale geldiğinde seri durumdan çıkarılır.
  • AddPersistentService yöntemi, hizmeti kalıcılık için kaydetmek için kullanılır. İşleme modu, hizmet türünden çıkarılamadığı için gereklidir. Aşağıdaki değerlerden herhangi birini kullanın:
    • RenderMode.Server: Hizmet, Etkileşimli Sunucu işleme modu için kullanılabilir.
    • RenderMode.Webassembly: Hizmet, Etkileşimli Webassembly işleme modu için kullanılabilir.
    • RenderMode.InteractiveAuto: Bir bileşen bu modlardan birinde işlenirse hizmet hem Etkileşimli Sunucu hem de Etkileşimli Webassembly işleme modları için kullanılabilir.
  • Hizmet, etkileşimli rendere taşıma modunun başlatılması aşamasında çözülür ve [SupplyParameterFromPersistentComponentState] özniteliği ile ek açıklama içeren özellikler deserile edilir.

Not

Yalnızca kalıcı kapsamlı hizmetler desteklenir.

CounterService.cs:

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

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

Program.cs'da:

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

Serileştirilmiş özellikler gerçek hizmet örneğinden tanımlanır:

  • Bu yaklaşım soyutlamanın kalıcı bir hizmet olarak işaretlenmesine olanak tanır.
  • Gerçek uygulamaların iç veya farklı türler olmasını sağlar.
  • Farklı derlemelerde paylaşılan kodu destekler.
  • Her örnek aynı özellikleri açığa çıkarır.

Özniteliğiyle [SupplyParameterFromPersistentComponentState] durumu kalıcı hale getirmek için bildirim temelli modeli kullanmaya alternatif olarak, hizmeti doğrudan kullanabilirsiniz PersistentComponentState ve bu da karmaşık durum kalıcılığı senaryoları için daha fazla esneklik sunar. Ön işleme sırasında bileşen durumunu sabitlemek için PersistentComponentState.RegisterOnPersisting çağırarak bir geri çağırma kaydedin. Bileşen etkileşimli olarak yeniden işlendiğinde, durum geri yüklenir. Uygulama kapatma sırasında olası bir yarış durumundan kaçınmak için başlatma kodunun sonunda aramayı yapın.

Aşağıdaki sayaç bileşeni örneği, önceden render etme sırasında sayaç durumunu saklar ve bileşeni başlatmak için durumu geri yükler.

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();
}

Bileşen çalıştığında, currentCount önceden işleme sırasında yalnızca bir kez belirlenir. Bileşen yeniden başlatıldığında değer geri yüklenir. Aşağıda örnek çıkış verilmiştir.

Not

Uygulama etkileşimli yönlendirmeyi benimserse ve sayfaya dahili gelişmiş bir gezinti yoluyla ulaşılırsa, ön kayıt gerçekleşmez. Bu nedenle, aşağıdaki çıkışı görmek için bileşenin tam sayfa yeniden yüklemesini gerçekleştirmeniz gerekir. Daha fazla bilgi için Etkileşimli Yönlendirme ve Ön İşleme bölümüne bakın.

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

Önceden oluşturulmuş durumu korumak için, hizmeti kullanarak PersistentComponentState hangi durumun kalıcı hale dönüştürüleceğine karar verin. PersistentComponentState.RegisterOnPersisting ön kayıt sırasında bileşen durumunu kalıcı hale getirmek için bir geri çağırma kaydeder. Bileşen etkileşimli olarak yeniden işlendiğinde, durum geri yüklenir. Uygulama kapatma sırasında olası bir yarış durumundan kaçınmak için başlatma kodunun sonunda aramayı yapın.

Aşağıdaki sayaç bileşeni örneği, önceden render etme sırasında sayaç durumunu saklar ve bileşeni başlatmak için durumu geri yükler.

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++;
}

Bileşen çalıştığında, currentCount önceden işleme sırasında yalnızca bir kez belirlenir. Bileşen yeniden başlatıldığında değer geri yüklenir. Aşağıda örnek çıkış verilmiştir.

Not

Uygulama etkileşimli yönlendirmeyi benimserse ve sayfaya dahili gelişmiş bir gezinti yoluyla ulaşılırsa, ön kayıt gerçekleşmez. Bu nedenle, aşağıdaki çıkışı görmek için bileşenin tam sayfa yeniden yüklemesini gerçekleştirmeniz gerekir. Daha fazla bilgi için Etkileşimli Yönlendirme ve Ön İşleme bölümüne bakın.

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

Ön kayıt sırasında kullanılan durumla aynı duruma sahip bileşenleri başlatarak, pahalı başlatma adımları yalnızca bir kez yürütülür. İşlenen kullanıcı arabirimi önceden oluşturulmuş kullanıcı arabirimiyle de eşleşir, bu nedenle tarayıcıda titreme olmaz.

Kalıcı önceden oluşturulmuş durum, bileşen durumunu geri yüklemek için kullanıldığı istemciye aktarılır. İstemci tarafı işleme (CSR, InteractiveWebAssembly) sırasında veriler tarayıcıya sunulur ve hassas, özel bilgiler içermemelidir. Etkileşimli sunucu tarafı işleme sırasında (etkileşimli SSR, InteractiveServer), ASP.NET Core Data Protection verilerin güvenli bir şekilde aktarılmasını sağlar. İşleme InteractiveAuto modu WebAssembly ve Sunucu etkileşimini birleştirir, bu nedenle CSR örneğinde olduğu gibi verilerin tarayıcıya açık olmasını göz önünde bulundurmanız gerekir.

Sayfalara ve görünümlere eklenmiş bileşenler (Razor Sayfalar/MVC)

Bir Sayfalar veya MVC uygulaması sayfasına ya da görünümüne eklenmiş bileşenler için, uygulamanın düzeni kapanış Razor etiketinin içine HTML etiketiyle birlikte <persist-component-state /> eklemelisiniz. Bu yalnızca Sayfalar ve MVC uygulamaları için Razor gereklidir. Daha fazla bilgi için bkz . ASP.NET Core'da Kalıcı Bileşen Durum Etiketi Yardımcısı.

Pages/Shared/_Layout.cshtml:

<body>
    ...

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

Etkileşimli yönlendirme ve ön kayıt

Routes bileşeni bir işleme modu tanımlamadığında, uygulama sayfa başına/bileşen etkileşimini ve gezintiyi kullanıyordur. Sayfa başına/bileşen gezintisi kullanıldığında, uygulama etkileşimli hale geldikten sonra iç† gezinti gelişmiş yönlendirme tarafından işlenir. bu bağlamda †Internal , gezinti olayının URL hedefinin uygulamanın içindeki bir Blazor uç nokta olduğu anlamına gelir.

PersistentComponentState hizmeti yalnızca ilk sayfa yüklemesinde çalışır ve iç gelişmiş sayfa gezinti olaylarında çalışmaz.

Uygulama, kalıcı bileşen durumunu kullanan bir sayfada tam (gelişmiş olmayan) bir gezinti gerçekleştirirse, kalıcı durum uygulamanın etkileşimli hale geldiğinde kullanması için kullanılabilir hale gelir.

Etkileşimli bir devre önceden oluşturulmuşsa ve kalıcı bileşen durumunu kullanan bir sayfaya gelişmiş bir gezinti gerçekleştiriliyorsa, bileşeninkullanabilmesi için durum mevcut devrede kullanılamaz. İç sayfa isteği için ön işleme yoktur ve PersistentComponentState hizmeti, gelişmiş bir gezinme oluştuğunun farkında değildir. Mevcut bir bağlantı hattında çalışmakta olan bileşenlere durum güncelleştirmeleri sunmak için bir mekanizma yoktur. Bunun nedeni, Blazor çalışma zamanı başlatıldıktan sonra değil, yalnızca çalışma zamanı başlatıldığında sunucudan istemciye durum geçirmeyi desteklemesidir.

.NET 10 (Kasım 2025) için Blazor çerçevesi üzerinde bu senaryoyu ele alan ek çalışmalar dikkate alınmalıdır. Desteklenmeyen geçici çözümler hakkında daha fazla bilgi ve topluluk tartışması için bkz. Gelişmiş sayfa gezintilerinde kalıcı bileşen durumunu destekleme (dotnet/aspnetcore #51584). ‡Desteklenmeyen geçici çözümler microsoft tarafından Blazor uygulamalarında kullanılmak üzere tasdik edilmemiştir. Riski size ait olan üçüncü taraf paketleri, yaklaşımları ve kodları kullanın.

Gelişmiş gezintiyi devre dışı bırakmak, performansı düşürür ancak aynı zamanda iç sayfa isteklerinde PersistentComponentState yükleme durumu sorununu önler ve bu konu ASP.NET Core Blazor yönlendirme ve gezinti bölümünde ele alınmıştır.

Veriyolu Ön İşleme Kılavuzu

Hazırlama kılavuzu, belgelerde konulara Blazor göre düzenlenmiştir. Aşağıdaki bağlantılar, konuya göre ayarlanan belgelerde yer alan tüm ön kayıt kılavuzlarını kapsar:

.NET 7 veya daha önceki sürümler için bkz Blazor WebAssembly . Güvenlikle ilgili ek senaryolar: Kimlik doğrulaması ile önceden giriş. Bu bölümdeki içeriği görüntüledikten sonra, sonraki ziyaretlerde belge sayfalarının en son .NET sürümüyle yüklenmesini sağlamak için, sürüm seçici açılan listesini en yeni .NET sürümüne sıfırlayın.