Merge pull request #34802 from dotnet/main

Merge to Live

Author: Rick-Anderson

aspnetcore/blazor/components/cascading-values-and-parameters.md

@@ -75,7 +75,7 @@ The following `Daleks` component displays the cascaded values.
 
 :::moniker range=">= aspnetcore-8.0"
 
-In the following example, `Dalek` is registered as a cascading value using [`CascadingValueSource<T>`](xref:Microsoft.AspNetCore.Components.CascadingValueSource%601), where `<T>` is the type. The `isFixed` flag indicates whether the value is fixed. If false, all recipients are subscribed for update notifications, which are issued by calling <xref:Microsoft.AspNetCore.Components.CascadingValueSource%601.NotifyChangedAsync%2A>. Subscriptions create overhead and reduce performance, so set `isFixed` to `true` if the value doesn't change.
+In the following example, `Dalek` is registered as a cascading value using [`CascadingValueSource<T>`](xref:Microsoft.AspNetCore.Components.CascadingValueSource%601), where `<T>` is the type. The `isFixed` flag indicates whether the value is fixed. If `false`, all recipients are subscribed for update notifications. Subscriptions create overhead and reduce performance, so set `isFixed` to `true` if the value doesn't change.
 
 ```csharp
 builder.Services.AddCascadingValue(sp =>
@@ -94,6 +94,191 @@ builder.Services.AddCascadingValue(sp =>
 >
 > Avoid using <xref:Microsoft.Extensions.DependencyInjection.CascadingValueServiceCollectionExtensions.AddCascadingValue%2A> to register a component type as a cascading value. Instead, wrap the `<Router>...</Router>` in the `Routes` component (`Components/Routes.razor`) with the component and adopt global interactive server-side rendering (interactive SSR). For an example, see the [`CascadingValue` component](#cascadingvalue-component) section.
 
+Calling <xref:Microsoft.AspNetCore.Components.CascadingValueSource%601.NotifyChangedAsync%2A> to issue update notifications can be used to signal multiple Razor component subscribers that a cascading value has changed. Notifications aren't possible for subscribers that adopt static server-side rendering (static SSR), so subscribers must adopt an interactive render mode. 
+
+In the following example:
+
+* `NotifyingDalek` implements <xref:System.ComponentModel.INotifyPropertyChanged> to notify clients that a property value has changed. When the `Units` property is set, the <xref:System.ComponentModel.PropertyChangedEventHandler> (`PropertyChanged`) is invoked.
+* The `SetUnitsToOneThousandAsync` method can be triggered by subscribers to set `Units` to 1,000 with a simulated processing delay.
+
+Keep in mind for production code that any change in state (any property value change of the class) causes all subscribed components to rerender, regardless of which part of the state they use. We recommend creating granular classes, cascading them separately with specific subscriptions to ensure that only components subscribed to a specific portion of the application state are affected by changes.
+
+`NotifyingDalek.cs`:
+
+```csharp
+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;
+    }
+}
+```
+
+The following `CascadingStateServiceCollectionExtensions` creates a <xref:Microsoft.AspNetCore.Components.CascadingValueSource%601> from a type that implements <xref:System.ComponentModel.INotifyPropertyChanged>.
+
+`CascadingStateServiceCollectionExtensions.cs`:
+
+```csharp
+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;
+        }
+    }
+}
+```
+
+The type's <xref:System.ComponentModel.PropertyChangedEventHandler> (`HandlePropertyChanged`) calls the <xref:Microsoft.AspNetCore.Components.CascadingValueSource%601>'s <xref:Microsoft.AspNetCore.Components.CascadingValueSource%601.NotifyChangedAsync%2A> method to notify subscribers that the cascading value has changed. The <xref:System.Threading.Tasks.Task> is discarded when calling <xref:Microsoft.AspNetCore.Components.CascadingValueSource%601.NotifyChangedAsync%2A> because the call only represents the duration of the dispatch to the synchronous context. Exceptions are handled internally by dispatching them to the renderer within the context of whichever component threw when receiving the update. This is the same way that exceptions are processed with a <xref:Microsoft.AspNetCore.Components.CascadingValue%601>, which isn't notified about exceptions that happen inside notification recipients. The event handler is disconnected in the `Dispose` method to prevent a memory leak.
+
+In the `Program` file&dagger;, `NotifyingDalek` is passed to create a <xref:Microsoft.AspNetCore.Components.CascadingValueSource%601> with an initial `Unit` value of 888 units:
+
+```csharp
+builder.Services.AddNotifyingCascadingValue(new NotifyingDalek() { Units = 888 });
+```
+
+> [!NOTE]
+> &dagger;For Blazor Web App solutions consisting of server and client (`.Client`) projects:
+>
+> * The preceding `NotifyingDalek.cs` and `CascadingStateServiceCollectionExtensions.cs` files are placed in the `.Client` project.
+> * The preceding code is placed into each project's `Program` file.
+
+The following component is used to demonstrate how changing the value of `NotifyingDalek.Units` notifies subscribers.
+
+`Daleks.razor`:
+
+```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();
+        }
+    }
+}
+```
+
+To demonstrate multiple subscriber notifications, the following `DaleksMain` component renders three `Daleks` components. When the unit count (`Units`) of one `Dalek` component is updated, the other two `Dalek` component subscribers are updated.
+
+`DaleksMain.razor`:
+
+```razor
+@page "/daleks-main"
+
+<PageTitle>Daleks Main</PageTitle>
+
+<h1>Daleks Main</h1>
+
+<Daleks />
+
+<Daleks />
+
+<Daleks />
+```
+
+Because the <xref:Microsoft.AspNetCore.Components.CascadingValueSource%601>'s type in this example (`NotifyingDalek`) is a class type, you can meet virtually any state management feature specification requirement. However, subscriptions create overhead and reduce performance, so benchmark the performance of this approach in your app and compare it to other [state management approaches](xref:blazor/state-management) before adopting it in a production app with constrained processing and memory resources.
+
+Any change in state (any property value change of the class) causes all subscribed components to rerender, regardless of which part of the state they use. **Avoid creating a single large class representing the entire global application state.** Instead, create granular classes and cascade them separately with specific subscriptions to cascading parameters, ensuring that only components subscribed to a specific portion of the application state are affected by changes.
+
 :::moniker-end
 
 ## `CascadingValue` component

aspnetcore/blazor/project-structure.md

@@ -20,7 +20,7 @@ This article describes the files and folders that make up a Blazor app generated
 
 Blazor Web App project template: `blazor`
 
-The Blazor Web App project template provides a single starting point for using Razor components (`.razor`) to build any style of web UI, both server-side rendered and client-side rendered. It combines the strengths of the existing Blazor Server and Blazor WebAssembly hosting models with server-side rendering, streaming rendering, enhanced navigation and form handling, and the ability to add interactivity using either Blazor Server or Blazor WebAssembly on a per-component basis.
+The Blazor Web App project template provides a single starting point for using Razor components (`.razor`) to build any style of web UI, both server-side rendered and client-side rendered. It combines the strengths of Blazor Server and Blazor WebAssembly with server-side and client-side rendering, streaming rendering, enhanced navigation and form handling, and the ability to add interactivity using either Blazor Server or Blazor WebAssembly on a per-component basis.
 
 If both client-side rendering (CSR) and interactive server-side rendering (interactive SSR) are selected on app creation, the project template uses the Interactive Auto render mode. The automatic rendering mode initially uses interactive SSR while the .NET app bundle and runtime are downloaded to the browser. After the .NET WebAssembly runtime is activated, rendering switches to CSR.
 

aspnetcore/blazor/state-management.md

@@ -61,6 +61,7 @@ Common locations exist for persisting state:
 * [URL](#url-server)
 * [Browser storage](#browser-storage-server)
 * [In-memory state container service](#in-memory-state-container-service)
+* [Cascading values and parameters](#cascading-values-and-parameters)
 
 <h2 id="server-side-storage-server">Server-side storage</h2>
 
@@ -620,7 +621,8 @@ Common locations exist for persisting state:
 * [Server-side storage](#server-side-storage-wasm)
 * [URL](#url-wasm)
 * [Browser storage](#browser-storage-wasm)
-* [In-memory state container service](#in-memory-state-container-service) 
+* [In-memory state container service](#in-memory-state-container-service)
+* [Cascading values and parameters](#cascading-values-and-parameters)
 
 <h2 id="server-side-storage-wasm">Server-side storage</h2>
 
@@ -805,6 +807,16 @@ services.AddScoped<StateContainer>();
 
 The preceding components implement <xref:System.IDisposable>, and the `OnChange` delegates are unsubscribed in the `Dispose` methods, which are called by the framework when the components are disposed. For more information, see <xref:blazor/components/lifecycle#component-disposal-with-idisposable-and-iasyncdisposable>.
 
+## Cascading values and parameters
+
+Use [cascading values and parameters](xref:blazor/components/cascading-values-and-parameters) to manage state by flowing data from an ancestor Razor component to descendent components.
+
+:::moniker range=">= aspnetcore-8.0"
+
+Root-level cascading values with a <xref:Microsoft.AspNetCore.Components.CascadingValueSource%601> permit Razor component subscriber notifications of changed cascading values. For more information and a working example, see the `NotifyingDalek` example in <xref:blazor/components/cascading-values-and-parameters#root-level-cascading-values>.
+
+:::moniker-end
+
 ## Additional approaches
 
 When implementing custom state storage, a useful approach is to adopt [cascading values and parameters](xref:blazor/components/cascading-values-and-parameters):

aspnetcore/migration/inc/wrapped.md

@@ -4,17 +4,19 @@ description: Wrapped ASP.NET Core session state
 author: rick-anderson
 ms.author: riande
 monikerRange: '>= aspnetcore-6.0'
-ms.date: 11/9/2022
+ms.date: 2/24/2025
 ms.topic: article
 uid: migration/inc/wrapped
 ---
 
 # Wrapped ASP.NET Core session state
 
-This implementation wraps the session provided on ASP.NET Core so that it can be used with the adapters. The session will be using the same backing store as `Microsoft.AspNetCore.Http.ISession` but will provide strongly-typed access to its members.
+The [AddWrappedAspNetCoreSession](https://github.com/dotnet/systemweb-adapters/blob/main/src/Microsoft.AspNetCore.SystemWebAdapters.CoreServices/SessionState/Wrapped/WrappedSessionExtensions.cs) implementation wraps the session provided on ASP.NET Core so that it can be used with the adapters. The session uses the same backing store as [`Microsoft.AspNetCore.Http.ISession`](/dotnet/api/microsoft.aspnetcore.http.isession) but provides strongly-typed access to its members.
 
-Configuration for ASP.NET Core would look similar to the following:
+Configuration for ASP.NET Core looks similar to the following:
 
 :::code language="csharp" source="~/migration/inc/samples/wrapped/Program.cs" id="snippet_WrapAspNetCoreSession" :::
 
-The framework app would not need any changes to enable this behavior.
+The framework app doesn't need any changes to enable this behavior.
+
+For more information, see the [AddWrappedAspNetCoreSession sample app](https://github.com/dotnet/systemweb-adapters/blob/main/samples/CoreApp/Program.cs)

aspnetcore/release-notes/aspnetcore-10/includes/openApi.md

@@ -74,6 +74,6 @@ app.MapOpenApi("/openapi/{documentName}.yaml");
 Support for:
 
 - YAML is currently only available for the the OpenAPI served from the OpenAPI endpoint.
-- Generating OpenAPI documents in YAML format at build time isadded in a future preview.
+- Generating OpenAPI documents in YAML format at build time is added in a future preview.
 
 See [this PR](https://github.com/dotnet/aspnetcore/pull/58616) which added support for serving the generated OpenAPI document in YAML format.