[Blazor] Add ability to filter persistent component state callbacks based on persistence reason

src/Components/Components/src/DefaultPersistenceReason.cs

@@ -0,0 +1,17 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.AspNetCore.Components;
+
+/// <summary>
+/// Default persistence reason used when no specific reason is provided.
+/// </summary>
+internal sealed class DefaultPersistenceReason : IPersistenceReason
+{
+    public static readonly DefaultPersistenceReason Instance = new();
+
+    private DefaultPersistenceReason() { }
+
+    /// <inheritdoc />
+    public bool PersistByDefault => true;
+}

src/Components/Components/src/IPersistenceReason.cs

@@ -0,0 +1,15 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.AspNetCore.Components;
+
+/// <summary>
+/// Represents a reason for persisting component state.
+/// </summary>
+public interface IPersistenceReason
+{
+    /// <summary>
+    /// Gets a value indicating whether state should be persisted by default for this reason.
+    /// </summary>
+    bool PersistByDefault { get; }
+}

src/Components/Components/src/IPersistenceReasonFilter.cs

@@ -0,0 +1,17 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.AspNetCore.Components;
+
+/// <summary>
+/// Filters component state persistence based on the reason for persistence.
+/// </summary>
+public interface IPersistenceReasonFilter
+{
+    /// <summary>
+    /// Determines whether state should be persisted for the given reason.
+    /// </summary>
+    /// <param name="reason">The reason for persistence.</param>
+    /// <returns><c>true</c> to persist state, <c>false</c> to skip persistence, or <c>null</c> to defer to other filters or default behavior.</returns>
+    bool? ShouldPersist(IPersistenceReason reason);
+}

src/Components/Components/src/PersistComponentStateRegistration.cs

@@ -5,9 +5,12 @@ namespace Microsoft.AspNetCore.Components;
 
 internal readonly struct PersistComponentStateRegistration(
     Func<Task> callback,
-    IComponentRenderMode? renderMode)
+    IComponentRenderMode? renderMode,
+    IReadOnlyList<IPersistenceReasonFilter>? reasonFilters = null)
 {
     public Func<Task> Callback { get; } = callback;
 
     public IComponentRenderMode? RenderMode { get; } = renderMode;
+
+    public IReadOnlyList<IPersistenceReasonFilter>? ReasonFilters { get; } = reasonFilters;
 }

src/Components/Components/src/PersistReasonFilter.cs

@@ -0,0 +1,34 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.AspNetCore.Components;
+
+/// <summary>
+/// Base class for filtering component state persistence based on specific persistence reasons.
+/// </summary>
+/// <typeparam name="TReason">The type of persistence reason this filter handles.</typeparam>
+public abstract class PersistReasonFilter<TReason> : Attribute, IPersistenceReasonFilter
+    where TReason : IPersistenceReason
+{
+    private readonly bool _persist;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PersistReasonFilter{TReason}"/> class.
+    /// </summary>
+    /// <param name="persist">Whether to persist state for the specified reason type.</param>
+    protected PersistReasonFilter(bool persist)
+    {
+        _persist = persist;
+    }
+
+    /// <inheritdoc />
+    public bool? ShouldPersist(IPersistenceReason reason)
+    {
+        if (reason is TReason)
+        {
+            return _persist;
+        }
+
+        return null;
+    }
+}

src/Components/Components/src/PersistentComponentState.cs

@@ -45,6 +45,30 @@ internal void InitializeExistingState(IDictionary<string, byte[]> existingState)
     public PersistingComponentStateSubscription RegisterOnPersisting(Func<Task> callback)
         => RegisterOnPersisting(callback, null);
 
+    /// <summary>
+    /// Register a callback to persist the component state when the application is about to be paused.
+    /// Registered callbacks can use this opportunity to persist their state so that it can be retrieved when the application resumes.
+    /// </summary>
+    /// <param name="callback">The callback to invoke when the application is being paused.</param>
+    /// <param name="renderMode"></param>
+    /// <param name="reasonFilters">Filters to control when the callback should be invoked based on the persistence reason.</param>
+    /// <returns>A subscription that can be used to unregister the callback when disposed.</returns>
+    public PersistingComponentStateSubscription RegisterOnPersisting(Func<Task> callback, IComponentRenderMode? renderMode, IReadOnlyList<IPersistenceReasonFilter>? reasonFilters)
+    {
+        ArgumentNullException.ThrowIfNull(callback);
+
+        if (PersistingState)
+        {
+            throw new InvalidOperationException("Registering a callback while persisting state is not allowed.");
+        }
+
+        var persistenceCallback = new PersistComponentStateRegistration(callback, renderMode, reasonFilters);
+
+        _registeredCallbacks.Add(persistenceCallback);
+
+        return new PersistingComponentStateSubscription(_registeredCallbacks, persistenceCallback);
+    }
+
     /// <summary>
     /// Register a callback to persist the component state when the application is about to be paused.
     /// Registered callbacks can use this opportunity to persist their state so that it can be retrieved when the application resumes.

src/Components/Components/src/PersistentState/ComponentStatePersistenceManager.cs

@@ -68,6 +68,16 @@ public async Task RestoreStateAsync(IPersistentComponentStateStore store)
     /// <param name="renderer">The <see cref="Renderer"/> that components are being rendered.</param>
     /// <returns>A <see cref="Task"/> that will complete when the state has been restored.</returns>
     public Task PersistStateAsync(IPersistentComponentStateStore store, Renderer renderer)
+        => PersistStateAsync(store, renderer, DefaultPersistenceReason.Instance);
+
+    /// <summary>
+    /// Persists the component application state into the given <see cref="IPersistentComponentStateStore"/>.
+    /// </summary>
+    /// <param name="store">The <see cref="IPersistentComponentStateStore"/> to restore the application state from.</param>
+    /// <param name="renderer">The <see cref="Renderer"/> that components are being rendered.</param>
+    /// <param name="persistenceReason">The reason for persisting the state.</param>
+    /// <returns>A <see cref="Task"/> that will complete when the state has been restored.</returns>
+    public Task PersistStateAsync(IPersistentComponentStateStore store, Renderer renderer, IPersistenceReason persistenceReason)
     {
         if (_stateIsPersisted)
         {
@@ -113,7 +123,7 @@ async Task PauseAndPersistState()
 
         async Task<bool> TryPersistState(IPersistentComponentStateStore store)
         {
-            if (!await TryPauseAsync(store))
+            if (!await TryPauseAsync(store, persistenceReason))
             {
                 _currentState.Clear();
                 return false;
@@ -159,7 +169,7 @@ private void InferRenderModes(Renderer renderer)
                 var componentRenderMode = renderer.GetComponentRenderMode(component);
                 if (componentRenderMode != null)
                 {
-                    _registeredCallbacks[i] = new PersistComponentStateRegistration(registration.Callback, componentRenderMode);
+                    _registeredCallbacks[i] = new PersistComponentStateRegistration(registration.Callback, componentRenderMode, registration.ReasonFilters);
                 }
                 else
                 {
@@ -177,6 +187,9 @@ private void InferRenderModes(Renderer renderer)
     }
 
     internal Task<bool> TryPauseAsync(IPersistentComponentStateStore store)
+        => TryPauseAsync(store, DefaultPersistenceReason.Instance);
+
+    internal Task<bool> TryPauseAsync(IPersistentComponentStateStore store, IPersistenceReason persistenceReason)
     {
         List<Task<bool>>? pendingCallbackTasks = null;
 
@@ -199,6 +212,27 @@ internal Task<bool> TryPauseAsync(IPersistentComponentStateStore store)
                 continue;
             }
 
+            // Evaluate reason filters to determine if the callback should be executed for this persistence reason
+            if (registration.ReasonFilters != null)
+            {
+                var shouldPersist = EvaluateReasonFilters(registration.ReasonFilters, persistenceReason);
+                if (shouldPersist.HasValue && !shouldPersist.Value)
+                {
+                    // Filters explicitly indicate not to persist for this reason
+                    continue;
+                }
+                else if (!shouldPersist.HasValue && !persistenceReason.PersistByDefault)
+                {
+                    // No filter matched and default is not to persist
+                    continue;
+                }
+            }
+            else if (!persistenceReason.PersistByDefault)
+            {
+                // No filters defined and default is not to persist
+                continue;
+            }
+
             var result = TryExecuteCallback(registration.Callback, _logger);
             if (!result.IsCompletedSuccessfully)
             {
@@ -271,4 +305,19 @@ static async Task<bool> AnyTaskFailed(List<Task<bool>> pendingCallbackTasks)
             return true;
         }
     }
+
+    private static bool? EvaluateReasonFilters(IReadOnlyList<IPersistenceReasonFilter> reasonFilters, IPersistenceReason persistenceReason)
+    {
+        foreach (var reasonFilter in reasonFilters)
+        {
+            var shouldPersist = reasonFilter.ShouldPersist(persistenceReason);
+            if (shouldPersist.HasValue)
+            {
+                return shouldPersist.Value;
+            }
+        }
+
+        // No filter matched
+        return null;
+    }
 }

src/Components/Components/src/PublicAPI.Unshipped.txt

@@ -10,9 +10,18 @@ Microsoft.AspNetCore.Components.Routing.NotFoundEventArgs.NotFoundEventArgs(stri
 Microsoft.AspNetCore.Components.Routing.NotFoundEventArgs.Path.get -> string!
 Microsoft.AspNetCore.Components.Infrastructure.ComponentStatePersistenceManager.ComponentStatePersistenceManager(Microsoft.Extensions.Logging.ILogger<Microsoft.AspNetCore.Components.Infrastructure.ComponentStatePersistenceManager!>! logger, System.IServiceProvider! serviceProvider) -> void
 Microsoft.AspNetCore.Components.Infrastructure.ComponentStatePersistenceManager.SetPlatformRenderMode(Microsoft.AspNetCore.Components.IComponentRenderMode! renderMode) -> void
+Microsoft.AspNetCore.Components.Infrastructure.ComponentStatePersistenceManager.PersistStateAsync(Microsoft.AspNetCore.Components.IPersistentComponentStateStore! store, Microsoft.AspNetCore.Components.RenderTree.Renderer! renderer, Microsoft.AspNetCore.Components.IPersistenceReason! persistenceReason) -> System.Threading.Tasks.Task!
 Microsoft.AspNetCore.Components.Infrastructure.RegisterPersistentComponentStateServiceCollectionExtensions
 Microsoft.AspNetCore.Components.SupplyParameterFromPersistentComponentStateAttribute
 Microsoft.AspNetCore.Components.SupplyParameterFromPersistentComponentStateAttribute.SupplyParameterFromPersistentComponentStateAttribute() -> void
+Microsoft.AspNetCore.Components.IPersistenceReason
+Microsoft.AspNetCore.Components.IPersistenceReason.PersistByDefault.get -> bool
+Microsoft.AspNetCore.Components.IPersistenceReasonFilter
+Microsoft.AspNetCore.Components.IPersistenceReasonFilter.ShouldPersist(Microsoft.AspNetCore.Components.IPersistenceReason! reason) -> bool?
+Microsoft.AspNetCore.Components.PersistReasonFilter<TReason>
+Microsoft.AspNetCore.Components.PersistReasonFilter<TReason>.PersistReasonFilter(bool persist) -> void
+Microsoft.AspNetCore.Components.PersistReasonFilter<TReason>.ShouldPersist(Microsoft.AspNetCore.Components.IPersistenceReason! reason) -> bool?
+Microsoft.AspNetCore.Components.PersistentComponentState.RegisterOnPersisting(System.Func<System.Threading.Tasks.Task!>! callback, Microsoft.AspNetCore.Components.IComponentRenderMode? renderMode, System.Collections.Generic.IReadOnlyList<Microsoft.AspNetCore.Components.IPersistenceReasonFilter!>? reasonFilters) -> Microsoft.AspNetCore.Components.PersistingComponentStateSubscription
 Microsoft.Extensions.DependencyInjection.SupplyParameterFromPersistentComponentStateProviderServiceCollectionExtensions
 static Microsoft.AspNetCore.Components.Infrastructure.RegisterPersistentComponentStateServiceCollectionExtensions.AddPersistentServiceRegistration<TService>(Microsoft.Extensions.DependencyInjection.IServiceCollection! services, Microsoft.AspNetCore.Components.IComponentRenderMode! componentRenderMode) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
 static Microsoft.AspNetCore.Components.Infrastructure.ComponentsMetricsServiceCollectionExtensions.AddComponentsMetrics(Microsoft.Extensions.DependencyInjection.IServiceCollection! services) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!

src/Components/Components/test/Microsoft.AspNetCore.Components.Tests.csproj

@@ -7,6 +7,7 @@
 
   <ItemGroup>
     <Reference Include="Microsoft.AspNetCore.Components" />
+    <Reference Include="Microsoft.AspNetCore.Components.Web" />
     <Reference Include="Microsoft.Extensions.DependencyInjection" />
     <Reference Include="Microsoft.Extensions.Diagnostics.Testing" />
   </ItemGroup>

src/Components/Components/test/PersistentState/ComponentStatePersistenceManagerTest.cs

@@ -6,6 +6,7 @@
 using System.Text.Json;
 using Microsoft.AspNetCore.Components.Infrastructure;
 using Microsoft.AspNetCore.Components.RenderTree;
+using Microsoft.AspNetCore.Components.Web;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Logging.Abstractions;
@@ -418,6 +419,98 @@ IEnumerator IEnumerable.GetEnumerator()
         }
     }
 
+    [Fact]
+    public void PersistenceReasons_HaveCorrectDefaults()
+    {
+        // Arrange & Act
+        var prerenderingReason = new PersistOnPrerendering();
+        var enhancedNavReason = new PersistOnEnhancedNavigation();
+        var circuitPauseReason = new PersistOnCircuitPause();
+
+        // Assert
+        Assert.True(prerenderingReason.PersistByDefault);
+        Assert.False(enhancedNavReason.PersistByDefault);
+        Assert.True(circuitPauseReason.PersistByDefault);
+    }
+
+    [Fact]
+    public async Task PersistStateAsync_RespectsReasonFilters()
+    {
+        // Arrange
+        var logger = NullLogger<ComponentStatePersistenceManager>.Instance;
+        var manager = new ComponentStatePersistenceManager(logger);
+        var renderer = new TestRenderer();
+        var store = new TestStore([]);
+        var callbackExecuted = false;
+
+        // Register callback with filter that blocks enhanced navigation
+        var filters = new List<IPersistenceReasonFilter>
+        {
+            new TestPersistenceReasonFilter<PersistOnEnhancedNavigation>(false)
+        };
+
+        manager.State.RegisterOnPersisting(() =>
+        {
+            callbackExecuted = true;
+            return Task.CompletedTask;
+        }, new TestRenderMode(), filters);
+
+        // Act - persist with enhanced navigation reason
+        await manager.PersistStateAsync(store, renderer, new PersistOnEnhancedNavigation());
+
+        // Assert - callback should not be executed
+        Assert.False(callbackExecuted);
+    }
+
+    [Fact]
+    public async Task PersistStateAsync_AllowsWhenFilterMatches()
+    {
+        // Arrange
+        var logger = NullLogger<ComponentStatePersistenceManager>.Instance;
+        var manager = new ComponentStatePersistenceManager(logger);
+        var renderer = new TestRenderer();
+        var store = new TestStore([]);
+        var callbackExecuted = false;
+
+        // Register callback with filter that allows prerendering
+        var filters = new List<IPersistenceReasonFilter>
+        {
+            new TestPersistenceReasonFilter<PersistOnPrerendering>(true)
+        };
+
+        manager.State.RegisterOnPersisting(() =>
+        {
+            callbackExecuted = true;
+            return Task.CompletedTask;
+        }, new TestRenderMode(), filters);
+
+        // Act - persist with prerendering reason
+        await manager.PersistStateAsync(store, renderer, new PersistOnPrerendering());
+
+        // Assert - callback should be executed
+        Assert.True(callbackExecuted);
+    }
+
+    private class TestPersistenceReasonFilter<TReason> : IPersistenceReasonFilter
+        where TReason : IPersistenceReason
+    {
+        private readonly bool _allow;
+
+        public TestPersistenceReasonFilter(bool allow)
+        {
+            _allow = allow;
+        }
+
+        public bool? ShouldPersist(IPersistenceReason reason)
+        {
+            if (reason is TReason)
+            {
+                return _allow;
+            }
+            return null;
+        }
+    }
+
     private class TestRenderMode : IComponentRenderMode
     {
     }

src/Components/Endpoints/src/Rendering/EndpointHtmlRenderer.PrerenderingState.cs

@@ -50,7 +50,10 @@ public async ValueTask<IHtmlContent> PrerenderPersistedStateAsync(HttpContext ht
 
         if (store != null)
         {
-            await manager.PersistStateAsync(store, this);
+            IPersistenceReason persistenceReason = IsProgressivelyEnhancedNavigation(httpContext.Request)
+                ? new PersistOnEnhancedNavigation()
+                : new PersistOnPrerendering();
+            await manager.PersistStateAsync(store, this, persistenceReason);
             return store switch
             {
                 ProtectedPrerenderComponentApplicationStore protectedStore => new ComponentStateHtmlContent(protectedStore, null),
@@ -80,7 +83,10 @@ public async ValueTask<IHtmlContent> PrerenderPersistedStateAsync(HttpContext ht
             var webAssembly = new CopyOnlyStore<InteractiveWebAssemblyRenderMode>();
             store = new CompositeStore(server, auto, webAssembly);
 
-            await manager.PersistStateAsync(store, this);
+            IPersistenceReason persistenceReason = IsProgressivelyEnhancedNavigation(httpContext.Request)
+                ? new PersistOnEnhancedNavigation()
+                : new PersistOnPrerendering();
+            await manager.PersistStateAsync(store, this, persistenceReason);
 
             foreach (var kvp in auto.Saved)
             {

src/Components/Server/src/Circuits/CircuitPersistenceManager.cs

@@ -28,7 +28,7 @@ public async Task PauseCircuitAsync(CircuitHost circuit, bool saveStateToClient
             collector.PersistRootComponents,
             RenderMode.InteractiveServer);
 
-        await persistenceManager.PersistStateAsync(collector, renderer);
+        await persistenceManager.PersistStateAsync(collector, renderer, new PersistOnCircuitPause());
 
         if (saveStateToClient)
         {