ASP.NET Core Blazor valori e parametri a catena

Valori a cascata radice

I valori a cascata a livello radice possono essere registrati per l'intera gerarchia dei componenti. Sono supportati valori a cascata denominati e sottoscrizioni per le notifiche di aggiornamento.

La classe seguente viene usata negli esempi di questa sezione.

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

Le registrazioni seguenti vengono effettuate nel file dell'app Program con AddCascadingValue:

• Dalek con un valore della proprietà per Units viene registrato come valore a cascata fisso.
• Una seconda Dalek registrazione con un valore di proprietà diverso per Units è denominata "AlphaGroup".

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

Nel componente seguente Daleks vengono visualizzati i valori a cascata.

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]
    private 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]
    private Dalek? Dalek { get; set; }

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

Nell'esempio seguente, Dalek viene registrato come valore a cascata usando CascadingValueSource<T>, dove <T> è il tipo. Il isFixed flag indica se il valore è fisso. Se false, tutti i destinatari vengono sottoscritti per le notifiche di aggiornamento. Le sottoscrizioni creano overhead e riducono le prestazioni, quindi impostate isFixed su true se il valore non cambia.

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

    return source;
});

Valori a cascata a livello radice con notifiche

La chiamata NotifyChangedAsync a inviare notifiche di aggiornamento può essere usata per segnalare a più Razor sottoscrittori di componenti che un valore a catena è cambiato. Le notifiche non sono possibili per i sottoscrittori che adottano il rendering statico lato server (SSR statico), quindi i sottoscrittori devono adottare una modalità di rendering interattiva.

Nell'esempio seguente:

• NotifyingDalek implementa INotifyPropertyChanged per notificare ai client che un valore della proprietà è stato modificato. Quando la Units proprietà è impostata, il PropertyChangedEventHandler (PropertyChanged) viene richiamato.
• Il SetUnitsToOneThousandAsync metodo può essere attivato dai sottoscrittori per impostare Units su 1.000 con un ritardo di elaborazione simulato.

Tenere presente nel codice di produzione che qualsiasi modifica dello stato (qualsiasi modifica del valore della proprietà della classe) causa il ri-rendering di tutti i componenti sottoscritti, indipendentemente da quale parte dello stato venga utilizzata. È consigliabile creare classi granulari, che vengono propagate separatamente con sottoscrizioni specifiche per garantire che solo i componenti sottoscritti a una parte specifica dello stato dell'applicazione siano interessati dalle modifiche.

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

Il seguente CascadingStateServiceCollectionExtensions crea un CascadingValueSource<TValue> da un tipo che implementa 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;
        }
    }
}

Il tipo PropertyChangedEventHandler (HandlePropertyChanged) chiama il metodo di CascadingValueSource<TValue>NotifyChangedAsync per notificare ai sottoscrittori che il valore a cascata è stato modificato. L'oggetto Task viene rimosso quando si chiama NotifyChangedAsync perché la chiamata rappresenta solo la durata dell'invio al contesto sincrono. Le eccezioni vengono gestite internamente indirizzandole al renderer nel contesto del componente che ha generato l'eccezione durante la ricezione dell'aggiornamento. Si tratta dello stesso modo in cui le eccezioni vengono elaborate con un CascadingValue<TValue>oggetto , che non riceve notifiche sulle eccezioni che si verificano all'interno dei destinatari delle notifiche. Il gestore eventi viene disconnesso nel Dispose metodo per evitare una perdita di memoria.

Nel file Program, NotifyingDalek viene passato per creare un CascadingValueSource<TValue> con un valore iniziale Unit di 888 unità.

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

Il componente seguente viene usato per illustrare come modificare il valore di NotifyingDalek.Units notifica ai sottoscrittori.

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

Per illustrare più notifiche degli abbonati, il componente seguente DaleksMain renderizza tre Daleks componenti. Quando viene aggiornato il numero di unità (Units) di un Dalek componente, gli altri due Dalek sottoscrittori dei componenti vengono aggiornati.

DaleksMain.razor:

@page "/daleks-main"

<PageTitle>Daleks Main</PageTitle>

<h1>Daleks Main</h1>

<Daleks />

<Daleks />

<Daleks />

Aggiungere un collegamento di navigazione al componente DaleksMain 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>

Poiché in questo esempio il tipo di CascadingValueSource<TValue> (NotifyingDalek) è un tipo di classe, è possibile soddisfare praticamente qualsiasi requisito della specifica delle funzionalità di gestione dello stato. Tuttavia, le sottoscrizioni creano overhead e riducono le prestazioni, quindi confrontano le prestazioni di questo approccio nella tua app e confrontalo con altri approcci di gestione dello stato prima di adottarlo in un'app di produzione con risorse di elaborazione e memoria limitate.

Qualsiasi modifica dello stato (qualsiasi variazione del valore di una proprietà della classe) fa sì che tutti i componenti registrati vengano rindirizzati, indipendentemente dalla parte dello stato utilizzata. Evitare di creare una singola classe di grandi dimensioni che rappresenta l'intero stato dell'applicazione globale. Creare invece classi granulari e propagarle separatamente con sottoscrizioni specifiche ai parametri a catena, assicurandosi che solo i componenti sottoscritti a una parte specifica dello stato dell'applicazione siano interessati dalle modifiche.

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 Apps forniscono approcci alternativi per i valori a cascata che si applicano più ampiamente all'app rispetto al fornirli tramite un unico file di layout:

• Racchiudi il markup del componente Routes in un componente CascadingValue per specificare i dati come valore a cascata per tutti i componenti dell'app.

  Nell'esempio seguente vengono propagati i ThemeInfo dati dal Routes componente .

  Routes.razor:

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

  Nota

  Il wrapping dell'istanza del componente Routes nel componente App (Components/App.razor) con un componente CascadingValue non è supportato.

• Specificare un valore a catena a livello radice come servizio chiamando il AddCascadingValue metodo di estensione sul generatore della raccolta di servizi.

  Nell'esempio seguente vengono propagati i ThemeInfo dati dal Program file .

  Program.cs

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

Per altre informazioni, vedere le sezioni seguenti di questo articolo:

• Valori a cascata al livello radice
• Valori a cascata a livello radice con notifiche
• Valori/parametri a catena e limiti della modalità di rendering

@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]
    private 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]
    private 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]
    private 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]
    private 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]
    private 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]
    private ThemeInfo ThemeInfo { get; set; }

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

Analogamente a un parametro di componente normale, i componenti che accettano un parametro a cascata vengono rirenderati quando viene modificato il valore in cascata. Ad esempio, la configurazione di un'istanza del tema diversa causa un nuovo rendering del componente ThemedCounter dalla sezione del componente CascadingValue.

MainLayout.razor:

<main>
    <div class="top-row px-4">
        <a href="https://learn.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 può essere usato per indicare che un parametro a cascata non cambia dopo l'inizializzazione.

Valori/parametri a cascata e limiti della modalità di rendering

I parametri a catena non passano i dati tra i confini delle modalità di rendering:

• Le sessioni interattive vengono eseguite in un contesto diverso rispetto alle pagine che usano il rendering statico lato server (SSR statico). Non è necessario che il server che produce la pagina sia anche lo stesso computer che ospita alcune sessioni successive di Interactive Server, anche nel caso dei componenti WebAssembly in cui il server è un computer diverso dal client. Il vantaggio del rendering statico lato server (SSR statico) è quello di ottenere le prestazioni complete del rendering HTML senza stato puro.

• Lo stato che attraversa il confine tra il rendering statico e interattivo deve essere serializzabile. I componenti sono oggetti arbitrari che fanno riferimento a una vasta catena di altri oggetti, tra cui il renderer, il contenitore DI e ogni istanza di servizio DI. È necessario fare in modo esplicito che lo stato venga serializzato da SSR statico per renderlo disponibile nei componenti visualizzati in modo interattivo successivo. Vengono adottati due approcci:

  • Tramite il Blazor framework, i parametri passati attraverso il confine tra SSR statico e rendering interattivo vengono serializzati automaticamente se sono serializzabili in JSON, oppure viene generato un errore.
  • Lo stato archiviato in Persistent Component State viene serializzato e ripristinato automaticamente se è serializzabile in JSON o viene generato un errore.

I parametri a cascata non sono serializzabili in JSON perché i modelli di utilizzo tipici per i parametri a cascata sono in qualche modo simili ai servizi di dependency injection. Spesso ci sono varianti specifiche della piattaforma di parametri a cascata, quindi sarebbe inutile per gli sviluppatori se il framework impedisse agli sviluppatori di avere versioni specifiche per server interattivo o versioni specifiche di WebAssembly. Inoltre, molti valori dei parametri a cascata in generale non sono serializzabili, quindi sarebbe poco pratico aggiornare le app esistenti se si dovesse interrompere l'uso di tutti i valori dei parametri a cascata non serializzabili.

Raccomandazioni:

• Se è necessario rendere disponibile lo stato per tutti i componenti interattivi come parametro a catena, è consigliabile usare valori a catena a livello radice o valori a catena a livello radice con notifiche. È disponibile un factory pattern e l'app può generare valori aggiornati dopo l'avvio dell'app. I valori a cascata a livello radice sono disponibili per tutti i componenti, inclusi i componenti interattivi, poiché vengono elaborati come servizi di dependency injection.

• Per gli autori di librerie di componenti, è possibile creare un metodo di estensione per i consumer di libreria in modo simile al seguente:

  builder.Services.AddLibraryCascadingParameters();
  

  Istruire gli sviluppatori a chiamare il metodo di estensione. Si tratta di una valida alternativa per indicare loro di aggiungere un componente <RootComponent> nel loro componente MainLayout.