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

* Implements support for custom serialization on the declarative persistent component model.
* Developers can register an instance of `builder.Services.AddSingleton<PersistentComponentStateSerializer<TData>, CustomSerializer>();` to handle serialization of persistent component state properties of that type.

Author: Copilot

activate.sh

@@ -0,0 +1,12 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Buffers;
+
+namespace Microsoft.AspNetCore.Components;
+
+internal interface IPersistentComponentStateSerializer
+{
+    void Persist(Type type, object value, IBufferWriter<byte> writer);
+    object Restore(Type type, ReadOnlySequence<byte> data);
+}

src/Components/Components/src/IPersistentComponentStateSerializer.cs

@@ -19,6 +19,7 @@
     <Compile Include="$(ComponentsSharedSourceRoot)src\HotReloadManager.cs" LinkBase="HotReload" />
     <Compile Include="$(ComponentsSharedSourceRoot)src\RootTypeCache.cs" LinkBase="Shared" />
     <Compile Include="$(SharedSourceRoot)LinkerFlags.cs" LinkBase="Shared" />
+    <Compile Include="$(SharedSourceRoot)PooledArrayBufferWriter.cs" LinkBase="Shared" />
     <Compile Include="$(SharedSourceRoot)QueryStringEnumerable.cs" LinkBase="Shared" />
     <Compile Include="$(SharedSourceRoot)Debugger\DictionaryItemDebugView.cs" LinkBase="Shared" />
     <Compile Include="$(SharedSourceRoot)Debugger\DictionaryDebugView.cs" LinkBase="Shared" />

src/Components/Components/src/Microsoft.AspNetCore.Components.csproj

@@ -110,6 +110,28 @@ internal void PersistAsJson(string key, object instance, [DynamicallyAccessedMem
         _currentState.Add(key, JsonSerializer.SerializeToUtf8Bytes(instance, type, JsonSerializerOptionsProvider.Options));
     }
 
+    /// <summary>
+    /// Persists the provided byte array under the given key.
+    /// </summary>
+    /// <param name="key">The key to use to persist the state.</param>
+    /// <param name="data">The byte array to persist.</param>
+    internal void PersistAsBytes(string key, byte[] data)
+    {
+        ArgumentNullException.ThrowIfNull(key);
+
+        if (!PersistingState)
+        {
+            throw new InvalidOperationException("Persisting state is only allowed during an OnPersisting callback.");
+        }
+
+        if (_currentState.ContainsKey(key))
+        {
+            throw new ArgumentException($"There is already a persisted object under the same key '{key}'");
+        }
+
+        _currentState.Add(key, data);
+    }
+
     /// <summary>
     /// Tries to retrieve the persisted state as JSON with the given <paramref name="key"/> and deserializes it into an
     /// instance of type <typeparamref name="TValue"/>.
@@ -155,6 +177,19 @@ internal bool TryTakeFromJson(string key, [DynamicallyAccessedMembers(JsonSerial
         }
     }
 
+    /// <summary>
+    /// Tries to retrieve the persisted state as raw bytes with the given <paramref name="key"/>.
+    /// When the key is present, the raw bytes are successfully returned via <paramref name="data"/>
+    /// and removed from the <see cref="PersistentComponentState"/>.
+    /// </summary>
+    /// <param name="key">The key used to persist the data.</param>
+    /// <param name="data">The persisted raw bytes.</param>
+    /// <returns><c>true</c> if the state was found; <c>false</c> otherwise.</returns>
+    internal bool TryTakeBytes(string key, [MaybeNullWhen(false)] out byte[]? data)
+    {
+        return TryTake(key, out data);
+    }
+
     private bool TryTake(string key, out byte[]? value)
     {
         ArgumentNullException.ThrowIfNull(key);

src/Components/Components/src/PersistentComponentState.cs

@@ -0,0 +1,40 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Buffers;
+
+namespace Microsoft.AspNetCore.Components;
+
+/// <summary>
+/// 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 abstract class PersistentComponentStateSerializer<T> : IPersistentComponentStateSerializer
+{
+    /// <summary>
+    /// Serializes the provided <paramref name="value"/> and writes it to the <paramref name="writer"/>.
+    /// </summary>
+    /// <param name="value">The value to serialize.</param>
+    /// <param name="writer">The buffer writer to write the serialized data to.</param>
+    public abstract void Persist(T value, IBufferWriter<byte> writer);
+
+    /// <summary>
+    /// Deserializes a value of type <typeparamref name="T"/> from the provided <paramref name="data"/>.
+    /// This method must be synchronous to avoid UI tearing during component state restoration.
+    /// </summary>
+    /// <param name="data">The serialized data to deserialize.</param>
+    /// <returns>The deserialized value.</returns>
+    public abstract T Restore(ReadOnlySequence<byte> data);
+
+    /// <summary>
+    /// Explicit interface implementation for non-generic serialization.
+    /// </summary>
+    void IPersistentComponentStateSerializer.Persist(Type type, object value, IBufferWriter<byte> writer)
+        => Persist((T)value, writer);
+
+    /// <summary>
+    /// Explicit interface implementation for non-generic deserialization.
+    /// </summary>
+    object IPersistentComponentStateSerializer.Restore(Type type, ReadOnlySequence<byte> data)
+        => Restore(data)!;
+}

src/Components/Components/src/PersistentComponentStateSerializer.cs

@@ -15,10 +15,11 @@
 
 namespace Microsoft.AspNetCore.Components.Infrastructure;
 
-internal sealed class PersistentStateValueProvider(PersistentComponentState state) : ICascadingValueSupplier
+internal sealed class PersistentStateValueProvider(PersistentComponentState state, IServiceProvider serviceProvider) : ICascadingValueSupplier
 {
     private static readonly ConcurrentDictionary<(string, string, string), byte[]> _keyCache = new();
     private static readonly ConcurrentDictionary<(Type, string), PropertyGetter> _propertyGetterCache = new();
+    private readonly ConcurrentDictionary<Type, IPersistentComponentStateSerializer?> _serializerCache = new();
 
     private readonly Dictionary<ComponentState, PersistingComponentStateSubscription> _subscriptions = [];
 
@@ -42,6 +43,20 @@ public bool CanSupplyValue(in CascadingParameterInfo parameterInfo)
         var componentState = (ComponentState)key!;
         var storageKey = ComputeKey(componentState, parameterInfo.PropertyName);
 
+        // Try to get a custom serializer for this type first
+        var customSerializer = _serializerCache.GetOrAdd(parameterInfo.PropertyType, SerializerFactory);
+        
+        if (customSerializer != null)
+        {
+            if (state.TryTakeBytes(storageKey, out var data))
+            {
+                var sequence = new ReadOnlySequence<byte>(data!);
+                return customSerializer.Restore(parameterInfo.PropertyType, sequence);
+            }
+            return null;
+        }
+
+        // Fallback to JSON serialization
         return state.TryTakeFromJson(storageKey, parameterInfo.PropertyType, out var value) ? value : null;
     }
 
@@ -52,6 +67,10 @@ public void Subscribe(ComponentState subscriber, in CascadingParameterInfo param
     {
         var propertyName = parameterInfo.PropertyName;
         var propertyType = parameterInfo.PropertyType;
+        
+        // Resolve serializer outside the lambda
+        var customSerializer = _serializerCache.GetOrAdd(propertyType, SerializerFactory);
+        
         _subscriptions[subscriber] = state.RegisterOnPersisting(() =>
             {
                 var storageKey = ComputeKey(subscriber, propertyName);
@@ -61,6 +80,16 @@ public void Subscribe(ComponentState subscriber, in CascadingParameterInfo param
                 {
                     return Task.CompletedTask;
                 }
+
+                if (customSerializer != null)
+                {
+                    using var writer = new PooledArrayBufferWriter<byte>();
+                    customSerializer.Persist(propertyType, property, writer);
+                    state.PersistAsBytes(storageKey, writer.WrittenMemory.ToArray());
+                    return Task.CompletedTask;
+                }
+
+                // Fallback to JSON serialization
                 state.PersistAsJson(storageKey, property, propertyType);
                 return Task.CompletedTask;
             }, subscriber.Renderer.GetComponentRenderMode(subscriber.Component));
@@ -71,6 +100,15 @@ private static PropertyGetter ResolvePropertyGetter(Type type, string propertyNa
         return _propertyGetterCache.GetOrAdd((type, propertyName), PropertyGetterFactory);
     }
 
+    private IPersistentComponentStateSerializer? SerializerFactory(Type type)
+    {
+        var serializerType = typeof(PersistentComponentStateSerializer<>).MakeGenericType(type);
+        var serializer = serviceProvider.GetService(serializerType);
+        
+        // The generic class now inherits from the internal interface, so we can cast directly
+        return serializer as IPersistentComponentStateSerializer;
+    }
+
     [UnconditionalSuppressMessage(
     "Trimming",
     "IL2077:Target parameter argument does not satisfy 'DynamicallyAccessedMembersAttribute' in call to target method. The source field does not have matching annotations.",
@@ -281,4 +319,49 @@ private static bool IsSerializableKey(object key)
 
         return result;
     }
+
+    /// <summary>
+    /// Serializes <paramref name="instance"/> using the provided <paramref name="serializer"/> and persists it under the given <paramref name="key"/>.
+    /// </summary>
+    /// <typeparam name="TValue">The <paramref name="instance"/> type.</typeparam>
+    /// <param name="key">The key to use to persist the state.</param>
+    /// <param name="instance">The instance to persist.</param>
+    /// <param name="serializer">The custom serializer to use for serialization.</param>
+    internal void PersistAsync<TValue>(string key, TValue instance, PersistentComponentStateSerializer<TValue> serializer)
+    {
+        ArgumentNullException.ThrowIfNull(key);
+        ArgumentNullException.ThrowIfNull(serializer);
+
+        using var writer = new PooledArrayBufferWriter<byte>();
+        serializer.Persist(instance, writer);
+        state.PersistAsBytes(key, writer.WrittenMemory.ToArray());
+    }
+
+    /// <summary>
+    /// Tries to retrieve the persisted state with the given <paramref name="key"/> and deserializes it using the provided <paramref name="serializer"/> into an
+    /// instance of type <typeparamref name="TValue"/>.
+    /// When the key is present, the state is successfully returned via <paramref name="instance"/>
+    /// and removed from the <see cref="PersistentComponentState"/>.
+    /// </summary>
+    /// <param name="key">The key used to persist the instance.</param>
+    /// <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>
+    internal bool TryTake<TValue>(string key, PersistentComponentStateSerializer<TValue> serializer, [MaybeNullWhen(false)] out TValue instance)
+    {
+        ArgumentNullException.ThrowIfNull(key);
+        ArgumentNullException.ThrowIfNull(serializer);
+
+        if (state.TryTakeBytes(key, out var data))
+        {
+            var sequence = new ReadOnlySequence<byte>(data!);
+            instance = serializer.Restore(sequence);
+            return true;
+        }
+        else
+        {
+            instance = default;
+            return false;
+        }
+    }
 }

src/Components/Components/src/PersistentStateValueProvider.cs

@@ -16,6 +16,10 @@ Microsoft.AspNetCore.Components.Infrastructure.RegisterPersistentComponentStateS
 Microsoft.AspNetCore.Components.PersistentStateAttribute
 Microsoft.AspNetCore.Components.PersistentStateAttribute.PersistentStateAttribute() -> void
 Microsoft.AspNetCore.Components.Infrastructure.PersistentStateProviderServiceCollectionExtensions
+Microsoft.AspNetCore.Components.PersistentComponentStateSerializer<T>
+Microsoft.AspNetCore.Components.PersistentComponentStateSerializer<T>.PersistentComponentStateSerializer() -> void
+abstract Microsoft.AspNetCore.Components.PersistentComponentStateSerializer<T>.Persist(T value, System.Buffers.IBufferWriter<byte>! writer) -> void
+abstract Microsoft.AspNetCore.Components.PersistentComponentStateSerializer<T>.Restore(System.Buffers.ReadOnlySequence<byte> data) -> T
 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!
 static Microsoft.AspNetCore.Components.Infrastructure.ComponentsMetricsServiceCollectionExtensions.AddComponentsTracing(Microsoft.Extensions.DependencyInjection.IServiceCollection! services) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!

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

@@ -0,0 +1,79 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Buffers;
+using System.Text;
+using System.Text.Json;
+using Microsoft.AspNetCore.Components.Infrastructure;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Microsoft.AspNetCore.Components;
+
+public class IPersistentComponentStateSerializerTests
+{
+    [Fact]
+    public void PersistAsync_CanUseCustomSerializer()
+    {
+        // Arrange
+        var currentState = new Dictionary<string, byte[]>();
+        var state = new PersistentComponentState(currentState, []);
+        var serviceProvider = new ServiceCollection().BuildServiceProvider();
+        var stateValueProvider = new PersistentStateValueProvider(state, serviceProvider);
+        var customSerializer = new TestStringSerializer();
+        var testValue = "Hello, World!";
+
+        state.PersistingState = true;
+
+        // Act
+        stateValueProvider.PersistAsync("test-key", testValue, customSerializer);
+
+        // Assert
+        state.PersistingState = false;
+        
+        // Simulate the state transfer that happens between persist and restore phases
+        var newState = new PersistentComponentState(new Dictionary<string, byte[]>(), []);
+        newState.InitializeExistingState(currentState);
+        var newStateValueProvider = new PersistentStateValueProvider(newState, serviceProvider);
+        
+        Assert.True(newStateValueProvider.TryTake("test-key", customSerializer, out var retrievedValue));
+        Assert.Equal(testValue, retrievedValue);
+    }
+
+    [Fact]
+    public void TryTake_CanUseCustomSerializer()
+    {
+        // Arrange
+        var customData = "Custom Data";
+        var customBytes = Encoding.UTF8.GetBytes(customData);
+        var existingState = new Dictionary<string, byte[]> { { "test-key", customBytes } };
+        
+        var state = new PersistentComponentState(new Dictionary<string, byte[]>(), []);
+        state.InitializeExistingState(existingState);
+        
+        var serviceProvider = new ServiceCollection().BuildServiceProvider();
+        var stateValueProvider = new PersistentStateValueProvider(state, serviceProvider);
+        var customSerializer = new TestStringSerializer();
+
+        // Act
+        var success = stateValueProvider.TryTake("test-key", customSerializer, out var retrievedValue);
+
+        // Assert
+        Assert.True(success);
+        Assert.Equal(customData, retrievedValue);
+    }
+
+    private class TestStringSerializer : PersistentComponentStateSerializer<string>
+    {
+        public override void Persist(string value, IBufferWriter<byte> writer)
+        {
+            var bytes = Encoding.UTF8.GetBytes(value);
+            writer.Write(bytes);
+        }
+
+        public override string Restore(ReadOnlySequence<byte> data)
+        {
+            var bytes = data.ToArray();
+            return Encoding.UTF8.GetString(bytes);
+        }
+    }
+}