[Blazor] Add IPersistentComponentStateSerializer<T> interface for custom serialization extensibility #62559

Copilot · 2025-07-03T15:55:11Z

This PR implements serialization extensibility for declarative persistent component state, allowing developers to provide custom serializers beyond the built-in JSON serialization.

Changes

New Interface

public interface IPersistentComponentStateSerializer<T>
{
    Task PersistAsync(T value, IBufferWriter<byte> writer, CancellationToken cancellationToken);
    T Restore(ReadOnlySequence<byte> data);
}

Key Features

Async Persist / Sync Restore: PersistAsync is async for serialization work, while Restore is synchronous to prevent UI tearing
Memory Efficient: Uses IBufferWriter<byte> with PooledArrayBufferWriter to minimize allocations, avoiding byte[] APIs
DI Integration: Custom serializers can be registered via dependency injection
Automatic Fallback: Falls back to existing JSON serialization when no custom serializer is registered
Full Backward Compatibility: All existing persistent state APIs continue to work unchanged

Usage Example

Register custom serializers in DI:

// Program.cs
builder.Services.AddSingleton<IPersistentComponentStateSerializer<User>, CustomUserSerializer>();

Components work exactly as before:

public class UserComponent : ComponentBase 
{
    [PersistentState] 
    public User CurrentUser { get; set; } = new();
    // User will be automatically persisted/restored with custom serializer
}

Implementation Details

PersistentComponentState: Extended with new PersistAsync<T> and TryTake<T> methods for custom serializers
PersistentStateValueProvider: Updated to attempt DI resolution of custom serializers before falling back to JSON
Type Safety: Strongly typed interface ensures compile-time safety for serializer implementations

Testing

Added comprehensive tests for custom serializer functionality
All 35 existing tests continue to pass, ensuring no breaking changes
Validates both custom serializer usage and JSON fallback scenarios

This enables scenarios like compression, encryption, or optimized binary formats for specific types while maintaining the simple declarative syntax of [PersistentState].

Fixes #60716.

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

…bility Co-authored-by: javiercn <[email protected]>

…tionality Co-authored-by: javiercn <[email protected]>

…ementation Co-authored-by: javiercn <[email protected]>

javiercn · 2025-07-03T16:16:33Z

src/Components/Components/src/PersistentComponentState.cs

+    /// <param name="instance">The instance to persist.</param>
+    /// <param name="serializer">The custom serializer to use for serialization.</param>
+    /// <param name="cancellationToken">A cancellation token that can be used to cancel the serialization operation.</param>
+    public async Task PersistAsync<TValue>(string key, TValue instance, IPersistentComponentStateSerializer<TValue> serializer, CancellationToken cancellationToken = default)


Make this internal

Made this method internal as requested, along with the corresponding TryTake method for consistency. Updated reflection calls in PersistentStateValueProvider to use NonPublic binding flags. Commit 147b5bc

javiercn · 2025-07-03T16:16:46Z

src/Components/Components/src/IPersistentComponentStateSerializer.cs

+    /// <param name="writer">The buffer writer to write the serialized data to.</param>
+    /// <param name="cancellationToken">A cancellation token that can be used to cancel the serialization operation.</param>
+    /// <returns>A task that represents the asynchronous serialization operation.</returns>
+    Task PersistAsync(T value, IBufferWriter<byte> writer, CancellationToken cancellationToken);


No cancellation token

Removed the cancellation token parameter from the PersistAsync method as requested. Updated both the interface definition and all related implementations. Commit d7ed4d9

javiercn · 2025-07-03T16:17:36Z

src/Components/Components/src/PersistentComponentState.cs

+    /// <param name="serializer">The custom serializer to use for deserialization.</param>
+    /// <param name="instance">The persisted instance.</param>
+    /// <returns><c>true</c> if the state was found; <c>false</c> otherwise.</returns>
+    public bool TryTake<TValue>(string key, IPersistentComponentStateSerializer<TValue> serializer, [MaybeNullWhen(false)] out TValue instance)


Make this API internal

Made the TryTake API internal as requested. This was already done in the previous commit but confirmed it's correct. The method is now properly scoped to internal access only. Commit d7ed4d9

javiercn · 2025-07-03T16:23:10Z

src/Components/Components/src/PersistentStateValueProvider.cs

+                var serializerType = typeof(IPersistentComponentStateSerializer<>).MakeGenericType(propertyType);
+                var customSerializer = serviceProvider.GetService(serializerType);
+
+                if (customSerializer != null)
+                {
+                    // Use reflection to call the generic PersistAsync method with the custom serializer
+                    var persistMethod = typeof(PersistentComponentState).GetMethod(nameof(PersistentComponentState.PersistAsync), BindingFlags.Instance | BindingFlags.Public, [typeof(string), propertyType, serializerType, typeof(CancellationToken)]);
+                    if (persistMethod != null)
+                    {
+                        var task = (Task)persistMethod.Invoke(state, [storageKey, property, customSerializer, CancellationToken.None])!;
+                        await task;
+                        return;
+                    }
+                }


Cache the serializers by type on a ConcurrentDictionary<Type, IPersistentComponentStateSerializer> (see how it's done in this file.

IPersistentComponentStateSerializer should be an internal interface, have the same methods as IPersistentComponentStateSerializer but take the Type type argument as a first argument.

IPersistentComponentStateSerializer<T> should implement IPersistentComponentStateSerializer with a default interface implementation that calls into Persist no matter the Type t passed as first argument

Move this code outside of the lambda.

Implemented the requested architecture changes:

Added ConcurrentDictionary<Type, IPersistentComponentStateSerializer> for serializer caching (made instance-based to avoid cross-test contamination)

Created internal IPersistentComponentStateSerializer base interface with Type parameter

Made IPersistentComponentStateSerializer implement the base interface with default implementations

Moved serializer resolution code outside of lambda for better performance

Used non-generic interface methods to avoid reflection

Commit d7ed4d9

Co-authored-by: javiercn <[email protected]>

…eedback - Remove CancellationToken from IPersistentComponentStateSerializer interface - Create internal IPersistentComponentStateSerializer base interface with Type parameter - Add default interface implementations for type safety - Add serializer caching with ConcurrentDictionary - Move serializer resolution outside of lambda for better performance - Add PersistAsBytes and TryTakeBytes methods for raw byte operations - Update PublicAPI to reflect interface changes Co-authored-by: javiercn <[email protected]>

…mination - Changed _serializerCache from static to instance field to prevent different service providers from sharing cached serializers - This ensures each PersistentStateValueProvider instance has its own serializer cache Co-authored-by: javiercn <[email protected]>

javiercn · 2025-07-03T17:09:52Z

src/Components/Components/src/IPersistentComponentStateSerializer.cs

+/// <summary>
+/// Provides custom serialization logic for persistent component state values.
+/// </summary>
+public interface IPersistentComponentStateSerializer


Make this interface internal

Made the IPersistentComponentStateSerializer interface internal as requested. Also updated the generic interface IPersistentComponentStateSerializer to internal to maintain consistent accessibility and removed the interfaces from PublicAPI.Unshipped.txt since they are no longer part of the public API. Commit 358f9e4

@copilot

No. IPersistentComponentStateSerializer should be internal, and IPersistentComponentStateSerializer<T> should be public. Also move it to a separate file.

Made IPersistentComponentStateSerializer internal and moved IPersistentComponentStateSerializer to a separate file (IPersistentComponentStateSerializerOfT.cs) while keeping it public. Added adapter pattern in PersistentStateValueProvider to bridge between the interfaces. Updated PublicAPI.Unshipped.txt accordingly. Commit c1fefc5

…review feedback Co-authored-by: javiercn <[email protected]>

javiercn · 2025-07-03T17:38:37Z

src/Components/Components/src/IPersistentComponentStateSerializer.cs

+/// Provides custom serialization logic for persistent component state values of type <typeparamref name="T"/>.
+/// </summary>
+/// <typeparam name="T">The type of the value to serialize.</typeparam>
+internal interface IPersistentComponentStateSerializer<T> : IPersistentComponentStateSerializer


IPersistentComponentStateSerializer should be public, but IPersistentComponentStateSerializer should remain internal

Made IPersistentComponentStateSerializer<T> public while keeping the base interface IPersistentComponentStateSerializer internal as requested. Also added the public interface to PublicAPI.Unshipped.txt. Commit 4c3dcac

javiercn · 2025-07-04T03:18:51Z

@copilot

We might need to make the registration in another project. The error seems to persist. It’s likely in Wasm.Minimal

2025-07-03T21:41:37Z] [Warning] http://127.0.0.1:35589/subdir/_framework/blazor.web.nt15gxxvjs.js 0:42409 "[2025-07-03T21:41:37.200Z] Warning: Initializer 'http://127.0.0.1:35589/subdir/JSInitializers/Classic/BasicTestApp.j2kfp6tx1s.lib.module.js' will be ignored because multiple runtimes are available. Use 'before(Web|WebAssembly|Server)Start' and 'after(Web|WebAssembly|Server)Started' instead."
[2025-07-03T21:41:37Z] [Info] http://127.0.0.1:35589/subdir/_framework/blazor.web.nt15gxxvjs.js 0:167352 "Debugging hotkey: Shift+Alt+D (when application has focus)"
[2025-07-03T21:41:40Z] [Severe] http://127.0.0.1:35589/subdir/_framework/blazor.web.nt15gxxvjs.js 0:170184 "crit: Microsoft.AspNetCore.Components.WebAssembly.Rendering.WebAssemblyRenderer[100]\n Unhandled exception rendering component: ExpectedStartOfValueNotFound, C Path: $ | LineNumber: 0 | BytePositionInLine: 0.\nSystem.Text.Json.JsonException: ExpectedStartOfValueNotFound, C Path: $ | LineNumber: 0 | BytePositionInLine: 0.\n ---> System.Text.Json.JsonReaderException: ExpectedStartOfValueNotFound, C LineNumber: 0 | BytePositionInLine: 0.\n at System.Text.Json.ThrowHelper.ThrowJsonReaderException(Utf8JsonReader& json, ExceptionResource resource, Byte nextByte, ReadOnlySpan`1 bytes)\n at System.Text.Json.Utf8JsonReader.ConsumeValue(Byte marker)\n at System.Text.Json.Utf8JsonReader.ReadFirstToken(Byte first)\n at System.Text.Json.Utf8JsonReader.ReadSingleSegment()\n at System.Text.Json.Utf8JsonReader.Read()\n at System.Text.Json.JsonSerializer.GetReaderScopedToNextValue(Utf8JsonReader& reader, ReadStack& state)\n Exception_EndOfInnerExceptionStack\n at System.Text.Json.ThrowHelper.ReThrowWithPath(ReadStack& state, JsonReaderException ex)\n at System.Text.Json.JsonSerializer.GetReaderScopedToNextValue(Utf8JsonReader& reader, ReadStack& state)\n at System.Text.Json.JsonSerializer.ReadAsObject(Utf8JsonReader& reader, JsonTypeInfo jsonTypeInfo)\n at System.Text.Json.JsonSerializer.Deserialize(Utf8JsonReader& reader, Type retu

…ompatibility Co-authored-by: javiercn <[email protected]>

Copilot · 2025-07-04T03:27:04Z

@copilot

We might need to make the registration in another project. The error seems to persist. It’s likely in Wasm.Minimal
...

Fixed by registering CustomIntSerializer in Components.WasmMinimal project. The issue was that when E2E tests transition from server to WebAssembly rendering, the WebAssembly side needs the same custom serializer to deserialize the "CUSTOM:" format that was persisted server-side. Commit 67ca5ec

…terface to separate file Co-authored-by: javiercn <[email protected]>

javiercn · 2025-07-04T10:26:05Z

src/Components/Components/src/IPersistentComponentStateSerializerOfT.cs

+/// Provides custom serialization logic for persistent component state values of type <typeparamref name="T"/>.
+/// </summary>
+/// <typeparam name="T">The type of the value to serialize.</typeparam>
+public interface IPersistentComponentStateSerializer<T>


This needs to have an explicit interface implementation of IPersistentComponentStateSerializer.

Implemented explicit interface implementation in the SerializerAdapter class since C# doesn't allow public interfaces to inherit from internal interfaces. The adapter now uses explicit interface implementation for IPersistentComponentStateSerializer methods. Commit cbf9fa9

@copilot

Wrong again. This is what we want (with comments, formatting, etc where appropriate).

public interface IPersistentComponentStateSerializer<T> : IPersistentComponentSerializer { Task PersistAsync(T value, IBufferWriter<byte> writer); Task IPersistentComponentStateSerializer.PersistAsync(Type type, object value, IBufferWriter<byte> writer) => Persist<T>(value, writter); T Restore(ReadOnlySequence<byte> data) object IPersistentComponentStateSerializer.Restore(Type type, ReadOnlySequence<byte> data) => Restore<T>(data); }

Implemented the requested architecture:

Made IPersistentComponentStateSerializer<T> inherit from IPersistentComponentStateSerializer

Added explicit interface implementations directly in the generic interface

Made the base interface public to enable inheritance (C# doesn't allow public interfaces to inherit from internal ones)

Removed the SerializerAdapter class since it's no longer needed

Updated PublicAPI.Unshipped.txt to include the now-public base interface

The generic interface now properly implements the base interface with explicit implementations as requested. Commit 365064d

javiercn · 2025-07-04T10:26:49Z

src/Components/Components/src/PersistentStateValueProvider.cs

+    /// <summary>
+    /// Adapter class to bridge between the public generic interface and the internal interface.
+    /// </summary>
+    /// <typeparam name="T">The type of the value to serialize.</typeparam>
+    private sealed class SerializerAdapter<T>(IPersistentComponentStateSerializer<T> serializer) : IPersistentComponentStateSerializer
+    {
+        public Task PersistAsync(Type type, object value, IBufferWriter<byte> writer)
+            => serializer.PersistAsync((T)value, writer);
+
+        public object Restore(Type type, ReadOnlySequence<byte> data)
+            => serializer.Restore(data)!;
+    }


This is not needed. IPersistentComponentStateSerializer<T> needs to have an explicit interface implementation of IPersistentComponentStateSerializer.

Updated the SerializerAdapter to use explicit interface implementation for IPersistentComponentStateSerializer methods, removing the public method declarations while maintaining the bridge functionality. Commit cbf9fa9

javiercn · 2025-07-04T10:27:27Z

src/Components/Components/src/IPersistentComponentStateSerializer.cs

+/// <summary>
+/// Provides custom serialization logic for persistent component state values.
+/// </summary>


Remove the comments from all the non public types and members

Removed XML documentation comments from the internal IPersistentComponentStateSerializer interface as requested. Commit cbf9fa9

…d remove XML comments from internal interface Co-authored-by: javiercn <[email protected]>

javiercn · 2025-07-04T10:41:05Z

src/Components/test/testassets/BasicTestApp/Program.cs

+        // Register custom serializer for E2E testing of persistent component state serialization extensibility
+        builder.Services.AddSingleton<IPersistentComponentStateSerializer<int>, CustomIntSerializer>();


Do we need this? Since it's already on WasmMinimal

You're correct - the registration is not needed since E2E tests use Components.WasmMinimal for WebAssembly rendering, not BasicTestApp. Removed the redundant registration and unused using directive. Commit 3b3af1d

…ateSerializer<T> and make base interface public Co-authored-by: javiercn <[email protected]>

Co-authored-by: javiercn <[email protected]>

javiercn · 2025-07-04T11:08:31Z

src/Components/Components/src/IPersistentComponentStateSerializerOfT.cs

+/// Provides custom serialization logic for persistent component state values of type <typeparamref name="T"/>.
+/// </summary>
+/// <typeparam name="T">The type of the value to serialize.</typeparam>
+public interface IPersistentComponentStateSerializer<T> : IPersistentComponentStateSerializer


Make this a class PersistentComponentStateSerializer<T> and make the interface internal

Converted IPersistentComponentStateSerializer<T> interface to abstract class PersistentComponentStateSerializer<T> and made the base interface internal as requested. Updated all implementations, tests, and service registrations accordingly. Commit 970977b

…tract class PersistentComponentStateSerializer<T> Co-authored-by: javiercn <[email protected]>

Initial plan

e2d0602

Copilot AI assigned Copilot and javiercn Jul 3, 2025

Copilot started work on behalf of javiercn July 3, 2025 15:55 View session

dotnet-policy-service bot added the Attention: Shared Code Modified label Jul 3, 2025

Copilot AI and others added 3 commits July 3, 2025 16:01

Initial planning for persistent component state serialization extensi…

726d6f5

…bility Co-authored-by: javiercn <[email protected]>

Implement IPersistentComponentStateSerializer interface and core func…

efb1c3b

…tionality Co-authored-by: javiercn <[email protected]>

Add comprehensive tests and finalize serialization extensibility impl…

6f2f33c

…ementation Co-authored-by: javiercn <[email protected]>

Copilot AI changed the title ~~[WIP] [Blazor] Support serialization extensibility for declarative persistent component state~~ [Blazor] Add IPersistentComponentStateSerializer<T> interface for custom serialization extensibility Jul 3, 2025

Copilot AI requested a review from javiercn July 3, 2025 16:15

Copilot finished work on behalf of javiercn July 3, 2025 16:15

javiercn reviewed Jul 3, 2025

View reviewed changes

Copilot started work on behalf of javiercn July 3, 2025 16:16 View session

javiercn reviewed Jul 3, 2025

View reviewed changes

Make PersistAsync and TryTake methods internal for custom serializers

147b5bc

Co-authored-by: javiercn <[email protected]>

Copilot AI requested a review from javiercn July 3, 2025 16:27

Copilot finished work on behalf of javiercn July 3, 2025 16:27

Copilot started work on behalf of javiercn July 3, 2025 16:27 View session

Copilot AI and others added 2 commits July 3, 2025 16:43

Copilot finished work on behalf of javiercn July 3, 2025 16:52

javiercn reviewed Jul 3, 2025

View reviewed changes

Copilot started work on behalf of javiercn July 3, 2025 17:09 View session

Make IPersistentComponentStateSerializer interface internal per code …

358f9e4

…review feedback Co-authored-by: javiercn <[email protected]>

Copilot AI requested a review from javiercn July 3, 2025 17:19

Copilot finished work on behalf of javiercn July 3, 2025 17:19

javiercn reviewed Jul 3, 2025

View reviewed changes

Copilot started work on behalf of javiercn July 3, 2025 17:38 View session

build-analysis bot mentioned this pull request Jul 4, 2025

The Operation will be canceled. The next steps may not contain expected logs. dotnet/dnceng#3008

Open

3 tasks

Copilot started work on behalf of javiercn July 4, 2025 03:18 View session

Register CustomIntSerializer in Components.WasmMinimal for E2E test c…

67ca5ec

…ompatibility Co-authored-by: javiercn <[email protected]>

Copilot finished work on behalf of javiercn July 4, 2025 03:27

build-analysis bot mentioned this pull request Jul 4, 2025

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

Open

javiercn marked this pull request as ready for review July 4, 2025 09:40

javiercn requested a review from a team as a code owner July 4, 2025 09:40

Copilot started work on behalf of javiercn July 4, 2025 09:43 View session

Make IPersistentComponentStateSerializer internal and move generic in…

c1fefc5

…terface to separate file Co-authored-by: javiercn <[email protected]>

Copilot finished work on behalf of javiercn July 4, 2025 09:56

javiercn reviewed Jul 4, 2025

View reviewed changes

Copilot started work on behalf of javiercn July 4, 2025 10:27 View session

Implement explicit interface implementation for custom serializers an…

cbf9fa9

…d remove XML comments from internal interface Co-authored-by: javiercn <[email protected]>

Copilot AI requested a review from javiercn July 4, 2025 10:36

Copilot finished work on behalf of javiercn July 4, 2025 10:36

Copilot started work on behalf of javiercn July 4, 2025 10:40 View session

javiercn reviewed Jul 4, 2025

View reviewed changes

Implement explicit interface implementation in IPersistentComponentSt…

365064d

…ateSerializer<T> and make base interface public Co-authored-by: javiercn <[email protected]>

Copilot AI requested a review from javiercn July 4, 2025 10:53

Copilot finished work on behalf of javiercn July 4, 2025 10:53

Copilot started work on behalf of javiercn July 4, 2025 10:53 View session

Remove redundant CustomIntSerializer registration from BasicTestApp

3b3af1d

Co-authored-by: javiercn <[email protected]>

Copilot finished work on behalf of javiercn July 4, 2025 11:05

javiercn reviewed Jul 4, 2025

View reviewed changes

Copilot started work on behalf of javiercn July 4, 2025 11:08 View session

Convert IPersistentComponentStateSerializer<T> interface to abs…

970977b

…tract class PersistentComponentStateSerializer<T> Co-authored-by: javiercn <[email protected]>

Copilot finished work on behalf of javiercn July 4, 2025 11:20

Copilot AI requested a review from javiercn July 4, 2025 11:20

		// Register custom serializer for E2E testing of persistent component state serialization extensibility
		builder.Services.AddSingleton<IPersistentComponentStateSerializer<int>, CustomIntSerializer>();

[Blazor] Add IPersistentComponentStateSerializer<T> interface for custom serialization extensibility #62559

Are you sure you want to change the base?

[Blazor] Add IPersistentComponentStateSerializer<T> interface for custom serialization extensibility #62559

Conversation

Copilot AI commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

New Interface

Key Features

Usage Example

Implementation Details

Testing

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 3, 2025

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!

Copilot AI Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 4, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

javiercn commented Jul 4, 2025

Uh oh!

Copilot AI commented Jul 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 4, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 4, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 4, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 4, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 4, 2025

Choose a reason for hiding this comment

Uh oh!

javiercn Jul 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Copilot AI commented Jul 3, 2025 •

edited

Loading

javiercn Jul 4, 2025 •

edited

Loading