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

src/Components/Components/src/IPersistentComponentStateSerializer.cs

@@ -0,0 +1,30 @@
+// 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 interface IPersistentComponentStateSerializer<T>
+{
+    /// <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>
+    /// <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);
+
+    /// <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>
+    T Restore(ReadOnlySequence<byte> data);
+}

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

@@ -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/PersistentComponentState.cs

@@ -1,6 +1,7 @@
 // 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.Diagnostics.CodeAnalysis;
 using System.Text.Json;
 using static Microsoft.AspNetCore.Internal.LinkerFlags;
@@ -110,6 +111,34 @@ internal void PersistAsJson(string key, object instance, [DynamicallyAccessedMem
         _currentState.Add(key, JsonSerializer.SerializeToUtf8Bytes(instance, type, JsonSerializerOptionsProvider.Options));
     }
 
+    /// <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>
+    /// <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)
+    {
+        ArgumentNullException.ThrowIfNull(key);
+        ArgumentNullException.ThrowIfNull(serializer);
+
+        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}'");
+        }
+
+        using var writer = new PooledArrayBufferWriter<byte>();
+        await serializer.PersistAsync(instance, writer, cancellationToken);
+        _currentState.Add(key, writer.WrittenMemory.ToArray());
+    }
+
     /// <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 +184,34 @@ internal bool TryTakeFromJson(string key, [DynamicallyAccessedMembers(JsonSerial
         }
     }
 
+    /// <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>
+    public bool TryTake<TValue>(string key, IPersistentComponentStateSerializer<TValue> serializer, [MaybeNullWhen(false)] out TValue instance)
+    {
+        ArgumentNullException.ThrowIfNull(key);
+        ArgumentNullException.ThrowIfNull(serializer);
+
+        if (TryTake(key, out var data))
+        {
+            var sequence = new ReadOnlySequence<byte>(data!);
+            instance = serializer.Restore(sequence);
+            return true;
+        }
+        else
+        {
+            instance = default;
+            return false;
+        }
+    }
+
     private bool TryTake(string key, out byte[]? value)
     {
         ArgumentNullException.ThrowIfNull(key);

src/Components/Components/src/PersistentStateValueProvider.cs

@@ -15,7 +15,7 @@
 
 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();
@@ -42,6 +42,23 @@ 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 serializerType = typeof(IPersistentComponentStateSerializer<>).MakeGenericType(parameterInfo.PropertyType);
+        var customSerializer = serviceProvider.GetService(serializerType);
+
+        if (customSerializer != null)
+        {
+            // Use reflection to call the generic TryTake method with the custom serializer
+            var tryTakeMethod = typeof(PersistentComponentState).GetMethod(nameof(PersistentComponentState.TryTake), BindingFlags.Instance | BindingFlags.Public, [typeof(string), serializerType, parameterInfo.PropertyType.MakeByRefType()]);
+            if (tryTakeMethod != null)
+            {
+                var parameters = new object?[] { storageKey, customSerializer, null };
+                var success = (bool)tryTakeMethod.Invoke(state, parameters)!;
+                return success ? parameters[2] : null;
+            }
+        }
+
+        // Fallback to JSON serialization
         return state.TryTakeFromJson(storageKey, parameterInfo.PropertyType, out var value) ? value : null;
     }
 
@@ -52,17 +69,34 @@ public void Subscribe(ComponentState subscriber, in CascadingParameterInfo param
     {
         var propertyName = parameterInfo.PropertyName;
         var propertyType = parameterInfo.PropertyType;
-        _subscriptions[subscriber] = state.RegisterOnPersisting(() =>
+        _subscriptions[subscriber] = state.RegisterOnPersisting(async () =>
             {
                 var storageKey = ComputeKey(subscriber, propertyName);
                 var propertyGetter = ResolvePropertyGetter(subscriber.Component.GetType(), propertyName);
                 var property = propertyGetter.GetValue(subscriber.Component);
                 if (property == null)
                 {
-                    return Task.CompletedTask;
+                    return;
                 }
+
+                // Try to get a custom serializer for this type first
+                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;
+                    }
+                }
+
+                // Fallback to JSON serialization
                 state.PersistAsJson(storageKey, property, propertyType);
-                return Task.CompletedTask;
             }, subscriber.Renderer.GetComponentRenderMode(subscriber.Component));
     }
 

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

@@ -21,3 +21,8 @@ static Microsoft.AspNetCore.Components.Infrastructure.ComponentsMetricsServiceCo
 static Microsoft.AspNetCore.Components.Infrastructure.ComponentsMetricsServiceCollectionExtensions.AddComponentsTracing(Microsoft.Extensions.DependencyInjection.IServiceCollection! services) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
 static Microsoft.AspNetCore.Components.Infrastructure.PersistentStateProviderServiceCollectionExtensions.AddSupplyValueFromPersistentComponentStateProvider(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
 virtual Microsoft.AspNetCore.Components.Rendering.ComponentState.GetComponentKey() -> object?
+Microsoft.AspNetCore.Components.IPersistentComponentStateSerializer<T>
+Microsoft.AspNetCore.Components.IPersistentComponentStateSerializer<T>.PersistAsync(T value, System.Buffers.IBufferWriter<byte>! writer, System.Threading.CancellationToken cancellationToken) -> System.Threading.Tasks.Task!
+Microsoft.AspNetCore.Components.IPersistentComponentStateSerializer<T>.Restore(System.Buffers.ReadOnlySequence<byte> data) -> T
+Microsoft.AspNetCore.Components.PersistentComponentState.PersistAsync<TValue>(string! key, TValue instance, Microsoft.AspNetCore.Components.IPersistentComponentStateSerializer<TValue>! serializer, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
+Microsoft.AspNetCore.Components.PersistentComponentState.TryTake<TValue>(string! key, Microsoft.AspNetCore.Components.IPersistentComponentStateSerializer<TValue>! serializer, out TValue instance) -> bool

src/Components/Components/test/IPersistentComponentStateSerializerTests.cs

@@ -0,0 +1,73 @@
+// 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 Microsoft.Extensions.DependencyInjection;
+
+namespace Microsoft.AspNetCore.Components;
+
+public class IPersistentComponentStateSerializerTests
+{
+    [Fact]
+    public async Task PersistAsync_CanUseCustomSerializer()
+    {
+        // Arrange
+        var currentState = new Dictionary<string, byte[]>();
+        var state = new PersistentComponentState(currentState, []);
+        var customSerializer = new TestStringSerializer();
+        var testValue = "Hello, World!";
+
+        state.PersistingState = true;
+
+        // Act
+        await state.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);
+
+        Assert.True(newState.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 customSerializer = new TestStringSerializer();
+
+        // Act
+        var success = state.TryTake("test-key", customSerializer, out var retrievedValue);
+
+        // Assert
+        Assert.True(success);
+        Assert.Equal(customData, retrievedValue);
+    }
+
+    private class TestStringSerializer : IPersistentComponentStateSerializer<string>
+    {
+        public Task PersistAsync(string value, IBufferWriter<byte> writer, CancellationToken cancellationToken)
+        {
+            var bytes = Encoding.UTF8.GetBytes(value);
+            writer.Write(bytes);
+            return Task.CompletedTask;
+        }
+
+        public string Restore(ReadOnlySequence<byte> data)
+        {
+            var bytes = data.ToArray();
+            return Encoding.UTF8.GetString(bytes);
+        }
+    }
+}