ASP.NET Core Blazor trapsgewijze waarden en parameters

Trapsgewijze waarden op rootniveau

Trapsgewijze waarden op hoofdniveau kunnen worden geregistreerd voor de hele onderdeelhiërarchie. Benoemde trapsgewijze waarden en abonnementen voor updatemeldingen worden ondersteund.

De volgende klasse wordt gebruikt in de voorbeelden van deze sectie.

Dalek.cs:

// "Dalek" ©Terry Nation https://www.imdb.com/name/nm0622334/
// "Doctor Who" ©BBC https://www.bbc.co.uk/programmes/b006q2x0

namespace BlazorSample;

public class Dalek
{
    public int Units { get; set; }
}

// "Dalek" ©Terry Nation https://www.imdb.com/name/nm0622334/
// "Doctor Who" ©BBC https://www.bbc.co.uk/programmes/b006q2x0

namespace BlazorSample;

public class Dalek
{
    public int Units { get; set; }
}

De volgende registraties worden in het Program-bestand van de app gemaakt met AddCascadingValue:

• Dalek met een eigenschapswaarde voor Units wordt geregistreerd als een vaste trapsgewijze waarde.
• Een tweede Dalek registratie met een andere eigenschapswaarde voor Units heet 'AlphaGroup'.

builder.Services.AddCascadingValue(sp => new Dalek { Units = 123 });
builder.Services.AddCascadingValue("AlphaGroup", sp => new Dalek { Units = 456 });

In het volgende Daleks-onderdeel worden de trapsgewijze waarden weergegeven.

Daleks.razor:

@page "/daleks"

<PageTitle>Daleks</PageTitle>

<h1>Root-level Cascading Value Example</h1>

<ul>
    <li>Dalek Units: @Dalek?.Units</li>
    <li>Alpha Group Dalek Units: @AlphaGroupDalek?.Units</li>
</ul>

<p>
    Dalek© <a href="https://www.imdb.com/name/nm0622334/">Terry Nation</a><br>
    Doctor Who© <a href="https://www.bbc.co.uk/programmes/b006q2x0">BBC</a>
</p>

@code {
    [CascadingParameter]
    public Dalek? Dalek { get; set; }

    [CascadingParameter(Name = "AlphaGroup")]
    public Dalek? AlphaGroupDalek { get; set; }
}

@page "/daleks"

<PageTitle>Daleks</PageTitle>

<h1>Root-level Cascading Value Example</h1>

<ul>
    <li>Dalek Units: @Dalek?.Units</li>
    <li>Alpha Group Dalek Units: @AlphaGroupDalek?.Units</li>
</ul>

<p>
    Dalek© <a href="https://www.imdb.com/name/nm0622334/">Terry Nation</a><br>
    Doctor Who© <a href="https://www.bbc.co.uk/programmes/b006q2x0">BBC</a>
</p>

@code {
    [CascadingParameter]
    public Dalek? Dalek { get; set; }

    [CascadingParameter(Name = "AlphaGroup")]
    public Dalek? AlphaGroupDalek { get; set; }
}

In het volgende voorbeeld wordt Dalek geregistreerd als een trapsgewijze waarde met behulp van CascadingValueSource<T>, waarbij <T> het type is. De vlag isFixed geeft aan of de waarde is opgelost. Als false, zijn alle geadresseerden geabonneerd op updatemeldingen. Abonnementen maken overhead en verminderen de prestaties, dus stel isFixed in op true als de waarde niet verandert.

builder.Services.AddCascadingValue(sp =>
{
    var dalek = new Dalek { Units = 789 };
    var source = new CascadingValueSource<Dalek>(dalek, isFixed: false);

    return source;
});

Cascaderende waarden op wortelniveau met meldingen

Door NotifyChangedAsync aan te roepen om updatemeldingen te versturen, kan aan meerdere Razor componentabonnees worden gesignaleerd dat een trapsgewijze waarde is gewijzigd. Meldingen zijn niet mogelijk voor abonnees die statische server-side rendering (statische SSR) gebruiken, dus abonnees moeten een interactieve rendermodus gebruiken.

In het volgende voorbeeld:

• NotifyingDalek implementeert om clients op de hoogte te stellen dat een eigenschapswaarde INotifyPropertyChanged is gewijzigd. Wanneer de Units eigenschap is ingesteld, wordt de PropertyChangedEventHandler (PropertyChanged) aangeroepen.
• De methode SetUnitsToOneThousandAsync kan door abonnees worden geactiveerd om Units in te stellen op 1000, met een gesimuleerde vertraging in de verwerking.

Houd er rekening mee dat bij productiecode elke verandering in de toestand (elke verandering in een eigenschapswaarde van de klasse) ervoor zorgt dat alle geabonneerde componenten opnieuw worden herladen, ongeacht welk deel van de toestand ze gebruiken. U wordt aangeraden gedetailleerde klassen te maken en deze afzonderlijk te cascaderen met specifieke abonnementen, om ervoor te zorgen dat alleen onderdelen die geabonneerd zijn op een specifiek deel van de applicatiestatus door wijzigingen worden beïnvloed.

NotifyingDalek.cs:

using System.ComponentModel;
using System.Runtime.CompilerServices;

public class NotifyingDalek : INotifyPropertyChanged
{
    public event PropertyChangedEventHandler? PropertyChanged;
    private int units;

    public int Units
    {
        get => units;
        set
        {
            if (units != value)
            {
                units = value;
                OnPropertyChanged();
            }
        }
    }

    protected virtual void OnPropertyChanged(
        [CallerMemberName] string? propertyName = default)
            => PropertyChanged?.Invoke(this, new(propertyName));

    public async Task SetUnitsToOneThousandAsync()
    {
        // Simulate a three second delay in processing
        await Task.Delay(3000);

        Units = 1000;
    }
}

CascadingStateServiceCollectionExtensions Het volgende maakt een CascadingValueSource<TValue> van een type dat INotifyPropertyChanged implementeert.

CascadingStateServiceCollectionExtensions.cs:

using System.ComponentModel;
using Microsoft.AspNetCore.Components;

namespace Microsoft.Extensions.DependencyInjection;

public static class CascadingStateServiceCollectionExtensions
{
    public static IServiceCollection AddNotifyingCascadingValue<T>(
        this IServiceCollection services, T state, bool isFixed = false)
        where T : INotifyPropertyChanged
    {
        return services.AddCascadingValue<T>(sp =>
        {
            return new CascadingStateValueSource<T>(state, isFixed);
        });
    }

    private sealed class CascadingStateValueSource<T>
        : CascadingValueSource<T>, IDisposable where T : INotifyPropertyChanged
    {
        private readonly T state;
        private readonly CascadingValueSource<T> source;

        public CascadingStateValueSource(T state, bool isFixed = false)
            : base(state, isFixed = false)
        {
            this.state = state;
            source = new CascadingValueSource<T>(state, isFixed);
            this.state.PropertyChanged += HandlePropertyChanged;
        }

        private void HandlePropertyChanged(object? sender, PropertyChangedEventArgs e)
        {
            _ = NotifyChangedAsync();
        }

        public void Dispose()
        {
            state.PropertyChanged -= HandlePropertyChanged;
        }
    }
}

Het type PropertyChangedEventHandler (HandlePropertyChanged) roept de CascadingValueSource<TValue>-methode van NotifyChangedAsync aan om abonnees op de hoogte te stellen dat de trapsgewijze waarde is gewijzigd. De Task optie wordt verwijderd bij het aanroepen NotifyChangedAsync omdat de oproep alleen de duur van de verzending naar de synchrone context vertegenwoordigt. Uitzonderingen worden intern verwerkt door ze naar de renderer te verzenden binnen de context van het onderdeel dat de uitzondering genereerde bij het ontvangen van de update. Dit is dezelfde manier waarop uitzonderingen worden verwerkt met een CascadingValue<TValue>, die niet op de hoogte wordt gesteld van uitzonderingen die plaatsvinden binnen meldingsontvangers. De gebeurtenis-handler wordt losgekoppeld in de Dispose methode om een geheugenlek te voorkomen.

In het Program bestand wordt NotifyingDalek doorgegeven, waarmee een CascadingValueSource<TValue> met een initiële Unit waarde van 888 eenheden wordt gecreëerd.

builder.Services.AddNotifyingCascadingValue(new NotifyingDalek() { Units = 888 });

Het volgende onderdeel wordt gebruikt om te demonstreren hoe het wijzigen van de waarde van NotifyingDalek.Units abonnees meldt.

Daleks.razor:

<h2>Daleks component</h2>

<div>
    <b>Dalek Units:</b> @Dalek?.Units
</div>

<div>
    <label>
        <span style="font-weight:bold">New Unit Count:</span>
        <input @bind="dalekCount" />
    </label>
    <button @onclick="Update">Update</button>
</div>

<div>
    <button @onclick="SetOneThousandUnits">Set Units to 1,000</button>
</div>

<p>
    Dalek© <a href="https://www.imdb.com/name/nm0622334/">Terry Nation</a><br>
    Doctor Who© <a href="https://www.bbc.co.uk/programmes/b006q2x0">BBC</a>
</p>

@code {
    private int dalekCount;

    [CascadingParameter]
    public NotifyingDalek? Dalek { get; set; }

    private void Update()
    {
        if (Dalek is not null)
        {
            Dalek.Units = dalekCount;
            dalekCount = 0;
        }
    }

    private async Task SetOneThousandUnits()
    {
        if (Dalek is not null)
        {
            await Dalek.SetUnitsToOneThousandAsync();
        }
    }
}

Als u meerdere abonneemeldingen wilt demonstreren, worden in het volgende DaleksMain onderdeel drie Daleks onderdelen weergegeven. Wanneer het aantal eenheden (Units) van het ene Dalek onderdeel wordt bijgewerkt, worden de andere twee Dalek onderdeelabonnees bijgewerkt.

DaleksMain.razor:

@page "/daleks-main"

<PageTitle>Daleks Main</PageTitle>

<h1>Daleks Main</h1>

<Daleks />

<Daleks />

<Daleks />

Voeg een navigatiekoppeling toe aan het DaleksMain onderdeel in NavMenu.razor:

<div class="nav-item px-3">
    <NavLink class="nav-link" href="daleks-main">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> Daleks
    </NavLink>
</div>

Omdat het CascadingValueSource<TValue>type in dit voorbeeld (NotifyingDalek) een klassetype is, kunt u vrijwel elke vereiste voor functiespecificatie voor statusbeheer voldoen. Abonnementen maken echter overhead en verminderen de prestaties, dus benchmark de prestaties van deze benadering in uw app en vergelijk deze met andere statusbeheermethoden voordat ze in een productie-app worden gebruikt met beperkte verwerking en geheugenbronnen.

Elke verandering in de toestand (elke wijziging van de eigenschapswaarde van de klasse) zorgt ervoor dat alle geabonneerde componenten opnieuw worden gerenderd, ongeacht welk deel van de toestand ze gebruiken. Vermijd het maken van één grote klasse die de hele globale toepassingsstatus vertegenwoordigt. Maak in plaats daarvan gedetailleerde klassen en cascadeer deze afzonderlijk met specifieke abonnementen op cascaderende parameters, zodat alleen componenten die zich hebben geabonneerd op een specifiek deel van de applicatiestatus worden beïnvloed door wijzigingen.

namespace BlazorSample;

public class ThemeInfo
{
    public string? ButtonClass { get; set; }
}

namespace BlazorSample;

public class ThemeInfo
{
    public string? ButtonClass { get; set; }
}

namespace BlazorSample.UIThemeClasses;

public class ThemeInfo
{
    public string? ButtonClass { get; set; }
}

namespace BlazorSample.UIThemeClasses;

public class ThemeInfo
{
    public string? ButtonClass { get; set; }
}

namespace BlazorSample.UIThemeClasses
{
    public class ThemeInfo
    {
        public string ButtonClass { get; set; }
    }
}

namespace BlazorSample.UIThemeClasses
{
    public class ThemeInfo
    {
        public string ButtonClass { get; set; }
    }
}

@inherits LayoutComponentBase

<div class="page">
    <div class="sidebar">
        <NavMenu />
    </div>

    <main>
        <div class="top-row px-4">
            <a href="https://learn.microsoft.com/aspnet/core/" target="_blank">About</a>
        </div>

        <CascadingValue Value="theme">
            <article class="content px-4">
                @Body
            </article>
        </CascadingValue>
    </main>
</div>

<div id="blazor-error-ui" data-nosnippet>
    An unhandled error has occurred.
    <a href="." class="reload">Reload</a>
    <span class="dismiss">🗙</span>
</div>

@code {
    private ThemeInfo theme = new() { ButtonClass = "btn-success" };
}

@inherits LayoutComponentBase

<div class="page">
    <div class="sidebar">
        <NavMenu />
    </div>

    <main>
        <div class="top-row px-4">
            <a href="https://learn.microsoft.com/aspnet/core/" target="_blank">About</a>
        </div>

        <CascadingValue Value="theme">
            <article class="content px-4">
                @Body
            </article>
        </CascadingValue>
    </main>
</div>

<div id="blazor-error-ui" data-nosnippet>
    An unhandled error has occurred.
    <a href="" class="reload">Reload</a>
    <a class="dismiss">🗙</a>
</div>

@code {
    private ThemeInfo theme = new() { ButtonClass = "btn-success" };
}

@inherits LayoutComponentBase
@using BlazorSample.UIThemeClasses

<div class="page">
    <div class="sidebar">
        <NavMenu />
    </div>

    <main>
        <div class="top-row px-4">
            <a href="https://docs.microsoft.com/aspnet/" target="_blank">About</a>
        </div>

        <CascadingValue Value="@theme">
            <article class="content px-4">
                @Body
            </article>
        </CascadingValue>
    </main>
</div>

@code {
    private ThemeInfo theme = new() { ButtonClass = "btn-success" };
}

@inherits LayoutComponentBase
@using BlazorSample.UIThemeClasses

<div class="page">
    <div class="sidebar">
        <NavMenu />
    </div>

    <main>
        <CascadingValue Value="@theme">
            <div class="content px-4">
                @Body
            </div>
        </CascadingValue>
    </main>
</div>

@code {
    private ThemeInfo theme = new() { ButtonClass = "btn-success" };
}

@inherits LayoutComponentBase
@using BlazorSample.UIThemeClasses

<div class="page">
    <div class="sidebar">
        <NavMenu />
    </div>

    <div class="main">
        <CascadingValue Value="@theme">
            <div class="content px-4">
                @Body
            </div>
        </CascadingValue>
    </div>
</div>

@code {
    private ThemeInfo theme = new() { ButtonClass = "btn-success" };
}

@inherits LayoutComponentBase
@using BlazorSample.UIThemeClasses

<div class="sidebar">
    <NavMenu />
</div>

<div class="main">
    <CascadingValue Value="theme">
        <div class="content px-4">
            @Body
        </div>
    </CascadingValue>
</div>

@code {
    private ThemeInfo theme = new ThemeInfo { ButtonClass = "btn-success" };
}

Blazor Web Appbieden alternatieve benaderingen voor trapsgewijze waarden die breder van toepassing zijn op de app dan het inrichten ervan via één indelingsbestand:

• Verpakt de opmaak van het Routes onderdeel in een CascadingValue-onderdeel om de gegevens op te geven als trapsgewijze waarde voor alle onderdelen van de app.

  In het volgende voorbeeld worden ThemeInfo-gegevens trapsgewijs van het Routes-onderdeel afgeleid.

  Routes.razor:

  <CascadingValue Value="theme">
      <Router ...>
          ...
      </Router>
  </CascadingValue>
  
  @code {
      private ThemeInfo theme = new() { ButtonClass = "btn-success" };
  }
  

  Notitie

  Het verpakken van het Routes-componentexemplaar in het App-component (Components/App.razor) met een CascadingValue-component wordt niet ondersteund.

• Geef een cascaderende waarde op op hoofdniveau als een service door de extensiemethode AddCascadingValue aan te roepen op de servicecollectiebouwer.

  In het volgende voorbeeld worden ThemeInfo-gegevens trapsgewijs afkomstig uit het Program-bestand.

  Program.cs

  builder.Services.AddCascadingValue(sp => 
      new ThemeInfo() { ButtonClass = "btn-primary" });
  

Zie de volgende secties van dit artikel voor meer informatie:

• trapsgewijze waarden op Root-niveau
• Trapsgewijze waarden op hoofdniveau met meldingen
• trapsgewijze waarden/parameters en weergavemodusgrenzen

@page "/themed-counter"

<PageTitle>Themed Counter</PageTitle>

<h1>Themed Counter Example</h1>

<p>Current count: @currentCount</p>

<p>
    <button @onclick="IncrementCount">
        Increment Counter (Unthemed)
    </button>
</p>

<p>
    <button 
        class="btn @(ThemeInfo is not null ? ThemeInfo.ButtonClass : string.Empty)" 
        @onclick="IncrementCount">
        Increment Counter (Themed)
    </button>
</p>

@code {
    private int currentCount = 0;

    [CascadingParameter]
    protected ThemeInfo? ThemeInfo { get; set; }

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

@page "/themed-counter"

<PageTitle>Themed Counter</PageTitle>

<h1>Themed Counter Example</h1>

<p>Current count: @currentCount</p>

<p>
    <button @onclick="IncrementCount">
        Increment Counter (Unthemed)
    </button>
</p>

<p>
    <button 
        class="btn @(ThemeInfo is not null ? ThemeInfo.ButtonClass : string.Empty)" 
        @onclick="IncrementCount">
        Increment Counter (Themed)
    </button>
</p>

@code {
    private int currentCount = 0;

    [CascadingParameter]
    protected ThemeInfo? ThemeInfo { get; set; }

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

@page "/themed-counter"
@using BlazorSample.UIThemeClasses

<h1>Themed Counter</h1>

<p>Current count: @currentCount</p>

<p>
    <button @onclick="IncrementCount">
        Increment Counter (Unthemed)
    </button>
</p>

<p>
    <button 
        class="btn @(ThemeInfo is not null ? ThemeInfo.ButtonClass : string.Empty)" 
        @onclick="IncrementCount">
        Increment Counter (Themed)
    </button>
</p>

@code {
    private int currentCount = 0;

    [CascadingParameter]
    protected ThemeInfo? ThemeInfo { get; set; }

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

@page "/themed-counter"
@using BlazorSample.UIThemeClasses

<h1>Themed Counter</h1>

<p>Current count: @currentCount</p>

<p>
    <button @onclick="IncrementCount">
        Increment Counter (Unthemed)
    </button>
</p>

<p>
    <button 
        class="btn @(ThemeInfo is not null ? ThemeInfo.ButtonClass : string.Empty)" 
        @onclick="IncrementCount">
        Increment Counter (Themed)
    </button>
</p>

@code {
    private int currentCount = 0;

    [CascadingParameter]
    protected ThemeInfo? ThemeInfo { get; set; }

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

@page "/themed-counter"
@using BlazorSample.UIThemeClasses

<h1>Themed Counter</h1>

<p>Current count: @currentCount</p>

<p>
    <button @onclick="IncrementCount">
        Increment Counter (Unthemed)
    </button>
</p>

<p>
    <button class="btn @ThemeInfo.ButtonClass" @onclick="IncrementCount">
        Increment Counter (Themed)
    </button>
</p>

@code {
    private int currentCount = 0;

    [CascadingParameter]
    protected ThemeInfo ThemeInfo { get; set; }

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

@page "/themed-counter"
@using BlazorSample.UIThemeClasses

<h1>Themed Counter</h1>

<p>Current count: @currentCount</p>

<p>
    <button @onclick="IncrementCount">
        Increment Counter (Unthemed)
    </button>
</p>

<p>
    <button class="btn @ThemeInfo.ButtonClass" @onclick="IncrementCount">
        Increment Counter (Themed)
    </button>
</p>

@code {
    private int currentCount = 0;

    [CascadingParameter]
    protected ThemeInfo ThemeInfo { get; set; }

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

Net als bij een normale onderdeelparameter worden onderdelen die een trapsgewijze parameter accepteren, aangepast wanneer de trapsgewijze waarde wordt gewijzigd. Als u bijvoorbeeld een ander thema-exemplaar configureert, wordt het ThemedCounter-onderdeel uit het CascadingValue-onderdeel-sectie opnieuw gerenderd.

MainLayout.razor:

<main>
    <div class="top-row px-4">
        <a href="https://docs.microsoft.com/aspnet/" target="_blank">About</a>
    </div>

    <CascadingValue Value="theme">
        <article class="content px-4">
            @Body
        </article>
    </CascadingValue>
    <button @onclick="ChangeToDarkTheme">Dark mode</button>
</main>

@code {
    private ThemeInfo theme = new() { ButtonClass = "btn-success" };

    private void ChangeToDarkTheme()
    {
        theme = new() { ButtonClass = "btn-secondary" };
    }
}

CascadingValue<TValue>.IsFixed kan worden gebruikt om aan te geven dat een trapsgewijze parameter niet wordt gewijzigd na initialisatie.

Trapsgewijze waarden/parameters en grenzen van de rendermodus

Trapsgewijze parameters geven geen gegevens door over de grenzen van de rendermodus:

• Interactieve sessies worden uitgevoerd in een andere context dan de pagina's die gebruikmaken van statische server-side rendering (statische SSR). Er is geen vereiste dat de server die de pagina produceert, zelfs dezelfde computer is die als host fungeert voor een latere Interactieve Server-sessie, waaronder voor WebAssembly-onderdelen waarbij de server een andere computer is dan de client. Het voordeel van statische server-side rendering (statische SSR) is het bereiken van de volledige prestaties van pure stateless HTML-rendering.

• De status die de grens tussen statische en interactieve rendering overschrijdt, moet serialiseerbaar zijn. Onderdelen zijn willekeurige objecten die verwijzen naar een enorme keten van andere objecten, waaronder de renderer, de DI-container en elk DI-service-exemplaar. U moet ervoor zorgen dat de status expliciet vanuit statische SSR wordt geserialiseerd om deze beschikbaar te maken in volgende interactief gegenereerde onderdelen. Er worden twee benaderingen aangenomen:

  • Via het Blazor-framework worden parameters die via een statische SSR naar een interactieve renderinggrens worden doorgegeven, automatisch geserialiseerd als ze JSON-serializeerbaar zijn of als er een fout optreedt.
  • Toestand die is opgeslagen in permanente onderdeelstatus wordt automatisch geserialiseerd en hersteld als deze JSON-serialiseerbaar is, of een fout wordt opgeworpen.

Trapsgewijze parameters zijn niet JSON-serializeerbaar omdat de typische gebruikspatronen voor trapsgewijze parameters enigszins lijken op DI-services. Er zijn vaak platformspecifieke varianten van trapsgewijze parameters, dus het zou niet nuttig zijn voor ontwikkelaars als het framework hen zou verhinderen om server-interactieve versies of WebAssembly-specifieke versies te hebben. Bovendien zijn veel trapsgewijze parameterwaarden in het algemeen niet serialiseerbaar, dus het zou onpraktisch zijn om bestaande apps bij te werken als u zou moeten stoppen met het gebruik van alle niet-serialiseerbare trapsgewijze parameterwaarden.

Aanbevelingen:

• Als u status beschikbaar wilt maken voor alle interactieve onderdelen als trapsgewijze parameter, raden we u aan trapsgewijze waarden of trapsgewijze waarden op hoofdniveau te gebruiken met meldingen. Er is een factory-patroon beschikbaar en de app kan bijgewerkte waarden verzenden na het opstarten van de app. Trapsgewijze waarden op hoofdniveau zijn beschikbaar voor alle onderdelen, inclusief interactieve onderdelen, omdat ze worden verwerkt als DI-services.

• Voor auteurs van onderdeelbibliotheken kunt u een uitbreidingsmethode maken voor een bibliotheekgebruiker die vergelijkbaar is met de volgende:

  builder.Services.AddLibraryCascadingParameters();
  

  Instrueer ontwikkelaars om uw extensiemethode aan te roepen. Dit is een goed alternatief voor hen instrueren om een <RootComponent>-onderdeel aan hun MainLayout-onderdeel toe te voegen.