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

Copilot · 2025-06-18T13:44:04Z

This PR implements the ability to filter persistent component state callbacks based on the reason for persistence, addressing scenarios where components need different persistence behavior for prerendering, enhanced navigation, and circuit pause events.

Changes

Core Interfaces and Classes

Added IPersistenceReason interface with PersistByDefault property
Added concrete persistence reason implementations:
- PersistOnPrerendering (default: true)
- PersistOnEnhancedNavigation (default: false)
- PersistOnCircuitPause (default: true)
Added IPersistenceReasonFilter interface for filtering logic
Added generic PersistReasonFilter<TReason> base class

Filter Classes in Components.Web

PersistOnPrerenderingFilter - Controls persistence during prerendering
PersistOnEnhancedNavigationFilter - Controls persistence during enhanced navigation
PersistOnCircuitPauseFilter - Controls persistence during circuit pause

Infrastructure Updates

Enhanced PersistComponentStateRegistration to include reason filters
Added new RegisterOnPersisting overload accepting IReadOnlyList<IPersistenceReasonFilter>
Added new PersistStateAsync overload accepting IPersistenceReason
Updated calling code to pass appropriate persistence reasons:
- RazorComponentEndpointInvoker uses PersistOnPrerendering
- CircuitPersistenceManager uses PersistOnCircuitPause

Filtering Logic

The persistence manager now evaluates filters in order:

If any filter returns a definitive result (true/false), that decision is used
If no filters match the persistence reason, the reason's PersistByDefault value is used
Maintains full backward compatibility - existing code works unchanged

Usage Example

// Register callback with filtering
var filters = new List<IPersistenceReasonFilter>
{
    new PersistOnPrerenderingFilter(persist: true),
    new PersistOnEnhancedNavigationFilter(persist: false),
    new PersistOnCircuitPauseFilter(persist: true)
};

PersistentState.RegisterOnPersisting(PersistData, renderMode, filters);

This allows fine-grained control over when component state should be persisted based on the specific persistence scenario.

Fixes #62393.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

dotnet-policy-service · 2025-06-18T13:46:07Z

Greetings human! You've submitted a PR that modifies code that is shared with https://github.com/dotnet/runtime . Please make sure you synchronize this code with the changes in that repo!

javiercn · 2025-06-18T13:59:20Z

Create concrete persistence reason implementations: PersistOnPrerendering, PersistOnEnhancedNavigation, PersistOnCircuitPause must live on the Components.Web assembly.

javiercn · 2025-06-18T14:00:36Z

RazorComponentEndpointInvoker needs to pass in Prerendering as the reason during the initial rendering and EnhancedNavigation when the request comes from an enhanced navigation

Co-authored-by: javiercn <6995051+javiercn@users.noreply.github.com>

…RazorComponentEndpointInvoker to detect enhanced navigation Co-authored-by: javiercn <6995051+javiercn@users.noreply.github.com>

Copilot · 2025-06-18T14:42:46Z

Create concrete persistence reason implementations: PersistOnPrerendering, PersistOnEnhancedNavigation, PersistOnCircuitPause must live on the Components.Web assembly.

Moved the concrete persistence reason implementations (PersistOnPrerendering, PersistOnEnhancedNavigation, PersistOnCircuitPause) to the Components.Web assembly as requested. Updated all references and PublicAPI files accordingly. Created a DefaultPersistenceReason for internal fallback use in the Components assembly to avoid dependency issues. (f938ea4)

RazorComponentEndpointInvoker needs to pass in Prerendering as the reason during the initial rendering and EnhancedNavigation when the request comes from an enhanced navigation

Updated RazorComponentEndpointInvoker to detect enhanced navigation requests using the IsProgressivelyEnhancedNavigation method. Now passes PersistOnPrerendering for initial rendering and PersistOnEnhancedNavigation when the request comes from enhanced navigation, as determined by the "text/html; blazor-enhanced-nav=on" Accept header. (f938ea4)

javiercn · 2025-06-18T14:46:15Z

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" />


Do not add this reference here

Removed the Microsoft.AspNetCore.Components.Web reference from the Components.Tests project. Created test-specific implementations of persistence reasons within the test file to maintain test functionality without the dependency. (4439a8c)

javiercn · 2025-06-18T14:47:34Z

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

    internal Task<bool> TryPauseAsync(IPersistentComponentStateStore store)
+        => TryPauseAsync(store, DefaultPersistenceReason.Instance);
+
+    internal Task<bool> TryPauseAsync(IPersistentComponentStateStore store, IPersistenceReason persistenceReason)


Do not create and overload. Simply change this method and adjust all the places it's used

Removed the overload from ComponentStatePersistenceManager.PersistStateAsync and modified the existing method to accept an optional nullable IPersistenceReason parameter. Updated all calling sites to work with the new signature. (a2c9f1c)

javiercn · 2025-06-18T14:48:40Z

src/Components/Components/src/DefaultPersistenceReason.cs

+internal sealed class DefaultPersistenceReason : IPersistenceReason
+{
+    public static readonly DefaultPersistenceReason Instance = new();
+
+    private DefaultPersistenceReason() { }
+
+    /// <inheritdoc />
+    public bool PersistByDefault => true;


Use null as a value in legacy overloads (and handle that within PauseAsync) instead of a "default" reason

Replaced DefaultPersistenceReason with null handling in legacy overloads. The ComponentStatePersistenceManager now handles null persistence reasons with default behavior (persist by default). Removed the DefaultPersistenceReason.cs file entirely. (a2c9f1c)

javiercn · 2025-06-18T14:49:35Z

src/Components/Components/src/PersistentComponentState.cs

+    /// <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)


IReadOnlyList? reasonFilters <= Make this mandatory

Made the reasonFilters parameter mandatory in the RegisterOnPersisting overload that accepts filters. Updated the legacy overloads to pass Array.Empty<IPersistenceReasonFilter>() when no filters are provided. (a2c9f1c)

javiercn · 2025-06-18T14:50:12Z

src/Components/Components/src/PersistComponentStateRegistration.cs

 {
    public Func<Task> Callback { get; } = callback;

    public IComponentRenderMode? RenderMode { get; } = renderMode;
+
+    public IReadOnlyList<IPersistenceReasonFilter>? ReasonFilters { get; } = reasonFilters;


public IReadOnlyList<IPersistenceReasonFilter> ReasonFilters { get; } = reasonFilters ?? Array.Empty<IPersistenceReasonFilter>();

Updated PersistComponentStateRegistration.ReasonFilters property initialization to use the suggested pattern: reasonFilters ?? Array.Empty<IPersistenceReasonFilter>(). The property is now non-nullable and always returns a valid collection. (a2c9f1c)

javiercn · 2025-06-18T14:51:42Z

src/Components/Web/src/PersistenceReasons.cs

+public class PersistOnPrerendering : IPersistenceReason
+{
+    /// <inheritdoc />
+    public bool PersistByDefault { get; } = true;
+}


Use the singleton pattern here and provide a static Instance value that gets reused everywhere

Implemented the singleton pattern for all persistence reason classes. Each class (PersistOnPrerendering, PersistOnEnhancedNavigation, PersistOnCircuitPause) now has a static Instance property and private constructor. Updated all usage sites to use the singleton instances. (a2c9f1c)

javiercn · 2025-06-18T14:52:12Z

src/Components/Web/src/PersistenceReasons.cs

+public class PersistOnPrerendering : IPersistenceReason
+{
+    /// <inheritdoc />
+    public bool PersistByDefault { get; } = true;
+}
+
+/// <summary>
+/// Represents persistence during enhanced navigation.
+/// </summary>
+public class PersistOnEnhancedNavigation : IPersistenceReason
+{
+    /// <inheritdoc />
+    public bool PersistByDefault { get; }
+}
+
+/// <summary>
+/// Represents persistence when a circuit is paused.
+/// </summary>
+public class PersistOnCircuitPause : IPersistenceReason
+{
+    /// <inheritdoc />
+    public bool PersistByDefault { get; } = true;
+}


Put each class in its own file

Separated the persistence reason classes into individual files: PersistOnPrerendering.cs, PersistOnEnhancedNavigation.cs, and PersistOnCircuitPause.cs. Removed the original PersistenceReasons.cs file. (a2c9f1c)

Co-authored-by: javiercn <6995051+javiercn@users.noreply.github.com>

javiercn · 2025-06-18T15:16:36Z

Here are instructions on how to add an E2E test to validate the changes, separated by --------------------------

Instructions for Adding E2E Tests for a Feature

1. Create Test Class Files

Create test classes that inherit from appropriate base classes and follow naming conventions:

using Microsoft.AspNetCore.Components.E2ETest.Infrastructure;
using Microsoft.AspNetCore.Components.E2ETest.Infrastructure.ServerFixtures;
using Microsoft.AspNetCore.E2ETesting;
using OpenQA.Selenium;
using Xunit.Abstractions;

namespace Microsoft.AspNetCore.Components.E2ETests.Tests;

public class YourFeatureTest : ServerTestBase<BasicTestAppServerSiteFixture<RazorComponentEndpointsStartup<App>>>
{
    static int _nextTestIdContext;

    public YourFeatureTest(
        BrowserFixture browserFixture,
        BasicTestAppServerSiteFixture<RazorComponentEndpointsStartup<App>> serverFixture,
        ITestOutputHelper output)
        : base(browserFixture, serverFixture, output)
    {
    }

    // Separate contexts to ensure that caches and other state don't interfere across tests
    public override Task InitializeAsync()
        => InitializeAsync(BrowserFixture.StreamingContext + _nextTestIdContext++);
}

2. Add Test Methods with Theory/Fact Attributes

Use [Theory] for parameterized tests and [Fact] for single-scenario tests:

[Theory]
[InlineData(true, typeof(InteractiveServerRenderMode), (string)null)]
[InlineData(true, typeof(InteractiveWebAssemblyRenderMode), (string)null)]
[InlineData(true, typeof(InteractiveAutoRenderMode), (string)null)]
[InlineData(false, typeof(InteractiveServerRenderMode), (string)null)]
public void CanUseYourFeature(bool parameter1, Type renderMode, string parameter2)
{
    var mode = renderMode switch
    {
        var t when t == typeof(InteractiveServerRenderMode) => "server",
        var t when t == typeof(InteractiveWebAssemblyRenderMode) => "wasm",
        var t when t == typeof(InteractiveAutoRenderMode) => "auto",
        _ => throw new ArgumentException($"Unknown render mode: {renderMode.Name}")
    };

    // Test implementation
    Navigate($"your-feature-page?mode={mode}");
    
    // Assertions using Browser.Equal
    Browser.Equal("Expected Value", () => Browser.FindElement(By.Id("test-element")).Text);
}

[Fact]
public void YourFeature_SpecificScenario()
{
    Navigate($"{ServerPathBase}/your-feature-specific-page");
    
    Browser.Equal("Expected Result", () => Browser.FindElement(By.Id("result")).Text);
    Browser.Click(By.Id("action-button"));
    Browser.Equal("Updated Result", () => Browser.FindElement(By.Id("result")).Text);
}

3. Create Test Pages and Components

Add Razor pages for testing in the test assets:

@page "/your-feature-page"
@using Microsoft.AspNetCore.Components.Web

<h1>Your Feature Test Page</h1>

@if (Mode == "server") {
    <YourFeatureComponent @rendermode="@RenderMode.InteractiveServer" />
}

@if (Mode == "wasm") {
    <YourFeatureComponent @rendermode="@RenderMode.InteractiveWebAssembly" />
}

@if (Mode == "auto") {
    <YourFeatureComponent @rendermode="@RenderMode.InteractiveAuto" />
}

@code {
    [Parameter, SupplyParameterFromQuery(Name = "mode")]
    public string Mode { get; set; }
}

4. Create Test Components

Add test components in the TestContentPackage:

@implements IDisposable

<p id="test-element">@_value</p>
<p id="render-mode">Render mode: <span>@_renderMode</span></p>
<button id="action-button" @onclick="PerformAction">Test Action</button>

@code {
    private string _value = "Initial Value";
    private string _renderMode = "SSR";

    protected override void OnInitialized()
    {
        _renderMode = OperatingSystem.IsBrowser() ? "WebAssembly" : "Server";
        // Initialize your feature
    }

    private void PerformAction()
    {
        _value = "Updated Value";
    }

    public void Dispose()
    {
        // Cleanup if needed
    }
}

5. Add Helper Methods for Complex Scenarios

Create helper methods for reusable test logic:

private void ValidateFeatureState(
    string expectedValue,
    string renderMode,
    bool isInteractive = true)
{
    Browser.Equal($"Render mode: {renderMode}", () => Browser.FindElement(By.Id("render-mode")).Text);
    Browser.Equal($"Interactive: {isInteractive}", () => Browser.FindElement(By.Id("interactive")).Text);
    Browser.Equal(expectedValue, () => Browser.FindElement(By.Id("test-element")).Text);
}

private void BlockWebAssemblyResourceLoad()
{
    ((IJavaScriptExecutor)Browser).ExecuteScript("sessionStorage.setItem('block-load-boot-resource', 'true')");
    ((IJavaScriptExecutor)Browser).ExecuteScript("caches.keys().then(keys => keys.forEach(key => caches.delete(key)))");
}

6. Add Services for Test Support (if needed)

Create services that support your testing scenarios:

namespace TestContentPackage.Services;

public class YourFeatureTestService
{
    private readonly Dictionary<string, object> _state = new();

    public void SetState(string key, object value)
    {
        _state[key] = value;
    }

    public T GetState<T>(string key)
    {
        return _state.TryGetValue(key, out var value) ? (T)value : default(T);
    }
}

7. Register Services in Test Applications

Update Program.cs files to register test services:

// ...existing code...
var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.Services.AddSingleton<YourFeatureTestService>();
// ...existing code...

8. Use Proper Assertions

Use Browser.Equal for element text comparisons and other Browser methods for interactions:

// Wait for element to have expected value
Browser.Equal("Expected Text", () => Browser.FindElement(By.Id("element-id")).Text);

// Click elements
Browser.Click(By.Id("button-id"));

// Check element existence
Browser.Exists(By.Id("element-id"));

// Navigate to pages
Navigate($"{ServerPathBase}/test-page?param=value");

9. Add Comments for Test Organization

Include clear comments explaining test scenarios:

// These tests validate that your feature works correctly across different render modes
// and scenarios including enhanced navigation, streaming rendering, and state persistence
[Theory]
[InlineData("server")]
[InlineData("wasm")]
[InlineData("auto")]
public void YourFeature_WorksAcrossRenderModes(string renderMode)
{
    // Arrange: Navigate to test page
    Navigate($"your-feature-page?mode={renderMode}");
    
    // Act: Perform feature action
    Browser.Click(By.Id("trigger-feature"));
    
    // Assert: Verify expected behavior
    Browser.Equal("Feature Activated", () => Browser.FindElement(By.Id("status")).Text);
}

Use these instructions to add an E2E test for filtering

…fault reason, implement singleton pattern Co-authored-by: javiercn <6995051+javiercn@users.noreply.github.com>

Co-authored-by: javiercn <6995051+javiercn@users.noreply.github.com>

Copilot · 2025-06-18T15:52:13Z

Here are instructions on how to add an E2E test to validate the changes, separated by --------------------------

...

Added comprehensive E2E tests for the persistent component state filtering functionality. The tests validate:

Basic filtering behavior - Components can selectively persist state based on persistence reasons (prerendering, enhanced navigation, circuit pause)
Enhanced navigation filtering - State persistence can be controlled differently for enhanced navigation scenarios
Prerendering filter disabling - Ability to disable persistence during prerendering when needed

Test Components Created:

FilteredPersistentStateComponent.razor - Demonstrates different filter combinations and validates selective persistence
FilteringTestPage.razor - Test page for E2E scenarios with parameterized filter configurations

Test Methods Added:

CanFilterPersistentStateCallbacks - Tests filtering across server/wasm/auto modes with enhanced navigation
CanFilterPersistentStateForEnhancedNavigation - Validates enhanced navigation-specific filtering behavior
CanDisablePersistenceForPrerendering - Tests disabling persistence during prerendering

The tests cover all render modes (server, WebAssembly, auto) and validate that the filtering logic works correctly for different persistence scenarios. (52e8488)

Initial plan for issue

bae3489

Copilot AI assigned Copilot and javiercn Jun 18, 2025

Copilot started work on behalf of javiercn June 18, 2025 13:44 View session

dotnet-policy-service bot added the Attention: Shared Code Modified label Jun 18, 2025

Copilot AI and others added 2 commits June 18, 2025 14:07

Implement core persistence reason interfaces and filtering logic

2519ee8

Co-authored-by: javiercn <6995051+javiercn@users.noreply.github.com>

Add tests and update calling code with persistence reasons

0fddad7

Co-authored-by: javiercn <6995051+javiercn@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] [Blazor] Provide the ability to filter persistent component state callbacks based on the reason for persistence~~ [Blazor] Add ability to filter persistent component state callbacks based on persistence reason Jun 18, 2025

Copilot AI requested a review from javiercn June 18, 2025 14:16

Copilot finished work on behalf of javiercn June 18, 2025 14:16

Copilot started work on behalf of javiercn June 18, 2025 14:16 View session

Move persistence reason implementations to Components.Web and update …

f938ea4

…RazorComponentEndpointInvoker to detect enhanced navigation Co-authored-by: javiercn <6995051+javiercn@users.noreply.github.com>

Copilot finished work on behalf of javiercn June 18, 2025 14:45

javiercn reviewed Jun 18, 2025

View reviewed changes

Copilot started work on behalf of javiercn June 18, 2025 14:46 View session

javiercn reviewed Jun 18, 2025

View reviewed changes

Remove Components.Web reference from Components.Tests project

4439a8c

Co-authored-by: javiercn <6995051+javiercn@users.noreply.github.com>

Copilot AI requested a review from javiercn June 18, 2025 15:01

Copilot finished work on behalf of javiercn June 18, 2025 15:01

Copilot started work on behalf of javiercn June 18, 2025 15:01 View session

Address PR review comments - remove overloads, use null instead of de…

a2c9f1c

…fault reason, implement singleton pattern Co-authored-by: javiercn <6995051+javiercn@users.noreply.github.com>

Copilot finished work on behalf of javiercn June 18, 2025 15:31

Copilot started work on behalf of javiercn June 18, 2025 15:31 View session

Add E2E tests for persistent component state filtering functionality

52e8488

Co-authored-by: javiercn <6995051+javiercn@users.noreply.github.com>

Copilot finished work on behalf of javiercn June 18, 2025 15:52

This was referenced Jun 18, 2025

Known Build Error: error : Cannot create a file when that file already exists. #61178

Open

"We stopped hearing from agent Azure Pipelines 32. Verify the agent machine is running and has a healthy network connection" dotnet/dnceng#1886

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

Uh oh!

Changes

Core Interfaces and Classes

Filter Classes in Components.Web

Infrastructure Updates

Filtering Logic

Usage Example

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!