ASP.NET Core Blazor sammanhängande värden och parametrar

Sammanhängande värden på rotnivå

Sammanhängande värden på rotnivå kan registreras för hela komponenthierarkin. Namngivna sammanhängande värden och prenumerationer för uppdateringsmeddelanden stöds.

Följande klass används i det här avsnittets exempel.

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

Följande registreringar görs i appens Program-fil med AddCascadingValue:

• Dalek med ett egenskapsvärde för Units registreras som ett fast sammanhängande värde.
• En andra Dalek registrering med ett annat egenskapsvärde för Units heter "AlphaGroup".

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

Följande Daleks komponent visar de överlappande värdena.

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

I följande exempel registreras Dalek som ett sammanhängande värde med hjälp av CascadingValueSource<T>, där <T> är typen. Flaggan isFixed anger om värdet är fast. Om falseprenumererar alla mottagare på uppdateringsmeddelanden. Prenumerationer skapar omkostnader och minskar prestanda, så ställ in isFixed på true om värdet inte ändras.

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

    return source;
});

Kaskaderande värden på rotnivå med meddelanden

Att anropa NotifyChangedAsync för att utfärda uppdateringsmeddelanden kan användas för att signalera flera Razor komponentprenumeranter att ett sammanhängande värde har ändrats. Meddelanden är inte möjliga för prenumeranter som använder statisk återgivning på serversidan (statisk SSR), så prenumeranter måste använda ett interaktivt återgivningsläge.

I följande exempel:

• NotifyingDalek implementerar INotifyPropertyChanged för att meddela klienter att ett egenskapsvärde har ändrats. När egenskapen Units har angetts PropertyChangedEventHandler anropas (PropertyChanged).
• Metoden SetUnitsToOneThousandAsync kan utlösas av prenumeranter för att sätta Units till 1 000 med en simulerad fördröjning i bearbetningen.

Tänk på att alla ändringar i tillståndet (eventuella ändringar av egenskapsvärden för klassen) gör att alla komponenter som prenumererar på tillståndet rendreras om, oavsett vilken del av tillståndet de använder. Vi rekommenderar att du skapar detaljerade klasser och samlar dem separat med specifika prenumerationer för att säkerställa att endast komponenter som prenumererar på en viss del av programtillståndet påverkas av ändringar.

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

Följande CascadingStateServiceCollectionExtensions skapar en CascadingValueSource<TValue> från en typ som implementerar INotifyPropertyChanged.

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

Typens PropertyChangedEventHandler (HandlePropertyChanged) anropar CascadingValueSource<TValue>s NotifyChangedAsyncmetod för att meddela prenumeranter att det sammanhängande värdet har ändrats. Task Ignoreras när du anropar NotifyChangedAsync eftersom anropet endast representerar sändningstiden till den synkrona kontexten. Undantag hanteras internt genom att de skickas till renderaren inom ramen för den komponent som kastades när uppdateringen mottogs. Det här är samma sätt som undantag hanteras med en CascadingValue<TValue>, som inte blir informerad om undantag som inträffar inuti meddelandemottagare. Händelsehanteraren kopplas från i Dispose metoden för att förhindra en minnesläcka.

I filen Program skickas NotifyingDalek för att skapa en CascadingValueSource<TValue> med ett initialt Unit-värde på 888 enheter:

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

Följande komponent används för att demonstrera hur förändringen av värdet NotifyingDalek.Units meddelar prenumeranter.

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

För att demonstrera flera prenumerantmeddelanden renderar följande DaleksMain komponent tre Daleks komponenter. När enhetsantalet (Units) för en Dalek komponent uppdateras uppdateras de andra två Dalek komponentprenumeranterna.

DaleksMain.razor:

@page "/daleks-main"

<PageTitle>Daleks Main</PageTitle>

<h1>Daleks Main</h1>

<Daleks />

<Daleks />

<Daleks />

Lägg till en navigeringslänk till komponenten DaleksMain i 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>

CascadingValueSource<TValue>Eftersom typen 's i det här exemplet (NotifyingDalek) är en klasstyp kan du uppfylla praktiskt taget alla krav för funktionsspecifikation för tillståndshantering. Prenumerationer skapar dock omkostnader och minskar prestanda, så jämför prestandan för den här metoden i din app och jämför den med andra tillståndshanteringsmetoder innan du använder den i en produktionsapp med begränsade bearbetnings- och minnesresurser.

Alla ändringar i tillståndet (vilken egenskapsvärdeändring som helst i klassen) orsakar att alla prenumererade komponenter renderas om, oavsett vilken del av tillståndet de använder. Undvik att skapa en enda stor klass som representerar hela det globala programtillståndet. Skapa i stället detaljerade klasser och koppla dem separat med specifika prenumerationer till sammanhängande parametrar, vilket säkerställer att endast komponenter som prenumererar på en viss del av programtillståndet påverkas av ändringar.

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://free.blessedness.top/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://free.blessedness.top/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 Appger alternativa metoder för värden i en kaskad som gäller mer allmänt för appen än att tillhandahålla dem via en enda layoutfil.

• Omslut Routes komponenten i en CascadingValue komponent för att ange data som ett sammanhängande värde för alla appens komponenter.

  Följande exempel överlappar ThemeInfo data från komponenten Routes.

  Routes.razor:

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

  Obs

  Det är inte möjligt att omsluta komponentinstansen Routes i komponenten App (Components/App.razor) med en CascadingValue-komponent.

• Ange ett sammanhängande värde på rotnivå som en tjänst genom att anropa AddCascadingValue-tilläggsmetoden i servicesamlingsverktyget.

  I följande exempel kaskaderar data från ThemeInfo-filen till Program-filen.

  Program.cs

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

Mer information finns i följande avsnitt i den här artikeln:

• Kaskadvärden på rotnivå
• Sammanhängande värden på rotnivå med meddelanden
• Kaskaderande värden/parametrar och gränser för rendreringsläge

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

På samma sätt som en vanlig komponentparameter återskapas komponenter som accepterar en sammanhängande parameter när det sammanhängande värdet ändras. Om du till exempel konfigurerar en annan temainstans orsakar det att ThemedCounter-komponenten från komponent CascadingValue sektionen återskapas.

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 användas för att indikera att en sammanhängande parameter inte ändras efter initieringen.

Sammanhängande värden/parametrar och återgivningslägesgränser

Sammanhängande parametrar skickar inte data över gränserna för återgivningsläge:

• Interaktiva sessioner körs i en annan kontext än de sidor som använder statisk återgivning på serversidan (statisk SSR). Det finns inget krav på att servern som producerar sidan ens är samma dator som är värd för en senare interaktiv serversession, inklusive för WebAssembly-komponenter där servern är en annan dator än klienten. Fördelen med statisk återgivning på serversidan (statisk SSR) är att få full prestanda för ren tillståndslös HTML-rendering.

• Tillstånd som korsar gränsen mellan statisk och interaktiv återgivning måste vara serialiserbart. Komponenter är godtyckliga objekt som refererar till en omfattande kedja av andra objekt, inklusive renderaren, DI-containern och varje DI-tjänstinstans. Du måste uttryckligen orsaka att tillståndet serialiseras från statisk SSR för att göra det tillgängligt i efterföljande interaktivt renderade komponenter. Två metoder används:

  • Via det Blazor ramverket serialiseras parametrar som skickas över en statisk SSR till en interaktiv återgivningsgräns automatiskt om de är JSON-serialiserbara eller om ett fel utlöses.
  • Tillståndet som lagras i beständigt komponenttillstånd serialiseras och återställs automatiskt om det är JSON-serialiserbart, eller om ett fel utlöses.

Sammanhängande parametrar är inte JSON-serialiserbara eftersom de typiska användningsmönstren för sammanhängande parametrar liknar DI-tjänster. Det finns ofta plattformsspecifika varianter av sammanhängande parametrar, så det skulle inte vara till någon hjälp för utvecklare om ramverket hindrade utvecklare från att ha server-interaktiva specifika versioner eller WebAssembly-specifika versioner. Dessutom är många sammanhängande parametervärden i allmänhet inte serialiserbara, så det skulle vara opraktiskt att uppdatera befintliga appar om du var tvungen att sluta använda alla icke-numeriska sammanhängande parametervärden.

Rekommendationer:

• Om du behöver göra tillståndet tillgängligt för alla interaktiva komponenter som en sammanhängande parameter rekommenderar vi att du använder sammanhängande värden på rotnivå eller sammanhängande värden på rotnivå med meddelanden. Ett fabriksmönster är tillgängligt och appen kan generera uppdaterade värden efter appstart. Sammanhängande värden på rotnivå är tillgängliga för alla komponenter, inklusive interaktiva komponenter, eftersom de bearbetas som DI-tjänster.

• För komponentbiblioteksförfattare kan du skapa en tilläggsmetod för bibliotekskonsumenter som liknar följande:

  builder.Services.AddLibraryCascadingParameters();
  

  Instruera utvecklare att anropa tilläggsmetoden. Det här är ett bra alternativ till att instruera dem att lägga till en <RootComponent> komponent i sin MainLayout komponent.