Add TypeHandlerFactory for open-generic type handler registration

Author: PauloHMattos

Dapper/PublicAPI.Unshipped.txt

@@ -1,3 +1,8 @@
 #nullable enable
 static Dapper.SqlMapper.Settings.PreferTypeHandlersForEnums.get -> bool
-static Dapper.SqlMapper.Settings.PreferTypeHandlersForEnums.set -> void
+static Dapper.SqlMapper.Settings.PreferTypeHandlersForEnums.set -> void
+static Dapper.SqlMapper.AddTypeHandlerFactory(Dapper.SqlMapper.TypeHandlerFactory! factory) -> void
+abstract Dapper.SqlMapper.TypeHandlerFactory.CanHandle(System.Type! type) -> bool
+abstract Dapper.SqlMapper.TypeHandlerFactory.Create(System.Type! type) -> Dapper.SqlMapper.ITypeHandler!
+Dapper.SqlMapper.TypeHandlerFactory
+Dapper.SqlMapper.TypeHandlerFactory.TypeHandlerFactory() -> void

Dapper/SqlMapper.TypeHandlerFactory.cs

@@ -0,0 +1,34 @@
+using System;
+
+namespace Dapper
+{
+    public static partial class SqlMapper
+    {
+        /// <summary>
+        /// Creates <see cref="ITypeHandler"/> instances on demand for types it claims via
+        /// <see cref="CanHandle"/>.
+        /// </summary>
+        /// <remarks>
+        /// Register a factory with <see cref="AddTypeHandlerFactory"/>. When Dapper needs a handler for a
+        /// type and no direct handler has been registered, it queries each factory in registration order.
+        /// The first factory whose <see cref="CanHandle"/> returns <see langword="true"/> is asked to
+        /// <see cref="Create"/> the handler. The created handler is then cached in
+        /// <see cref="typeHandlers"/> (and in <see cref="TypeHandlerCache{T}"/> for IL-emitted paths),
+        /// so the factory is only consulted once per type.
+        /// </remarks>
+        public abstract class TypeHandlerFactory
+        {
+            /// <summary>
+            /// Returns <see langword="true"/> if this factory can provide a handler for
+            /// <paramref name="type"/>.
+            /// </summary>
+            public abstract bool CanHandle(Type type);
+
+            /// <summary>
+            /// Creates an <see cref="ITypeHandler"/> for <paramref name="type"/>.
+            /// Only called after <see cref="CanHandle"/> returned <see langword="true"/> for the same type.
+            /// </summary>
+            public abstract ITypeHandler Create(Type type);
+        }
+    }
+}

Dapper/SqlMapper.cs

@@ -269,6 +269,7 @@ private static void ResetTypeHandlers(bool clone)
             lock (typeHandlersSyncLock)
             {
                 typeHandlers = [];
+                typeHandlerFactories = [];
                 AddTypeHandlerCore(typeof(DataTable), new DataTableHandler(), clone);
                 AddTypeHandlerCore(typeof(XmlDocument), new XmlDocumentHandler(), clone);
                 AddTypeHandlerCore(typeof(XDocument), new XDocumentHandler(), clone);
@@ -337,6 +338,26 @@ public static void RemoveTypeMap(Type type)
             SetTypeMap(newCopy);
         }
 
+        /// <summary>
+        /// Register a <see cref="TypeHandlerFactory"/> that can create handlers on demand for types it claims
+        /// via <see cref="TypeHandlerFactory.CanHandle"/>. Factories are queried in registration order when
+        /// no direct handler is found for a type.
+        /// </summary>
+        /// <param name="factory">The factory to register.</param>
+        public static void AddTypeHandlerFactory(TypeHandlerFactory factory)
+        {
+            if (factory is null) throw new ArgumentNullException(nameof(factory));
+            lock (typeHandlersSyncLock)
+            {
+                // Snapshot/mutate/swap keeps reads outside the lock lock-free.
+                var prev = typeHandlerFactories;
+                var next = new TypeHandlerFactory[prev.Length + 1];
+                prev.CopyTo(next, 0);
+                next[prev.Length] = factory;
+                typeHandlerFactories = next;
+            }
+        }
+
         /// <summary>
         /// Configure the specified type to be processed by a custom handler.
         /// </summary>
@@ -348,7 +369,17 @@ public static void RemoveTypeMap(Type type)
         /// </summary>
         /// <param name="type">The type to handle.</param>
         /// <returns>Boolean value specifying whether the type will be processed by a custom handler.</returns>
-        public static bool HasTypeHandler(Type type) => typeHandlers.ContainsKey(type);
+        public static bool HasTypeHandler(Type type)
+        {
+            if (typeHandlers.ContainsKey(type)) return true;
+            // Also check registered factories; a type has a handler if any factory claims it.
+            var factories = typeHandlerFactories; // snapshot for thread safety
+            foreach (var factory in factories)
+            {
+                if (factory.CanHandle(type)) return true;
+            }
+            return false;
+        }
 
         /// <summary>
         /// Configure the specified type to be processed by a custom handler.
@@ -423,8 +454,37 @@ private static void AddTypeHandlerCore(Type type, ITypeHandler? handler, bool cl
         public static void AddTypeHandler<T>(TypeHandler<T> handler) => AddTypeHandlerCore(typeof(T), handler, true);
 
         private static Dictionary<Type, ITypeHandler> typeHandlers;
+        // Registered factories are queried (in order) when no direct entry is found in typeHandlers.
+        // Uses a plain array with snapshot/swap so readers outside the lock never block.
+        private static TypeHandlerFactory[] typeHandlerFactories = [];
         private static readonly object typeHandlersSyncLock = new();
 
+        /// <summary>
+        /// Looks up a registered type handler, falling back to registered <see cref="TypeHandlerFactory"/>
+        /// instances when no direct entry is found. On a factory hit the concrete handler is instantiated,
+        /// registered in <see cref="typeHandlers"/> and in <see cref="TypeHandlerCache{T}"/> (used by
+        /// IL-emitted code), so subsequent lookups for the same type are O(1) dictionary reads.
+        /// </summary>
+        private static bool TryGetTypeHandler(Type type, [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] out ITypeHandler? handler)
+        {
+            if (typeHandlers.TryGetValue(type, out handler)) return true;
+
+            var factories = typeHandlerFactories; // snapshot for thread safety
+            foreach (var factory in factories)
+            {
+                if (factory.CanHandle(type))
+                {
+                    handler = factory.Create(type);
+                    // Cache so TypeHandlerCache<T> (used by IL-emitted code paths) is populated
+                    // and future lookups bypass factory iteration entirely.
+                    AddTypeHandlerCore(type, handler, true);
+                    return true;
+                }
+            }
+
+            return false;
+        }
+
         internal const string LinqBinary = "System.Data.Linq.Binary";
 
         private const string ObsoleteInternalUsageOnly = "This method is for internal use only";
@@ -483,7 +543,7 @@ public static void SetDbType(IDataParameter parameter, object value)
             {
                 return DbType.Binary;
             }
-            if (typeHandlers.TryGetValue(type, out handler))
+            if (TryGetTypeHandler(type, out handler))
             {
                 return DbType.Object;
             }
@@ -1971,7 +2031,7 @@ private static Func<DbDataReader, object> GetDeserializer(Type type, DbDataReade
             else if (!(type.IsEnum || type.IsArray || type.FullName == LinqBinary
                 || (type.IsValueType && (underlyingType = Nullable.GetUnderlyingType(type)) is not null && underlyingType.IsEnum)))
             {
-                if (typeHandlers.TryGetValue(type, out ITypeHandler? handler))
+                if (TryGetTypeHandler(type, out ITypeHandler? handler))
                 {
                     return GetHandlerDeserializer(handler, type, startBound);
                 }
@@ -3130,7 +3190,7 @@ private static Func<DbDataReader, object> GetSimpleValueDeserializer(Type type,
                     return val is DBNull ? null! : Enum.ToObject(effectiveType, val);
                 };
             }
-            if (typeHandlers.TryGetValue(type, out var handler))
+            if (TryGetTypeHandler(type, out var handler))
             {
                 return r =>
                 {
@@ -3192,7 +3252,7 @@ private static T Parse<T>(object? value)
                 }
                 return (T)Enum.ToObject(type, value);
             }
-            if (typeHandlers.TryGetValue(type, out ITypeHandler? handler))
+            if (TryGetTypeHandler(type, out ITypeHandler? handler))
             {
                 return (T)handler.Parse(type, value)!;
             }
@@ -3805,7 +3865,7 @@ private static void LoadReaderValueOrBranchToDBNullLabel(ILGenerator il, int ind
                 {
                     TypeCode dataTypeCode = Type.GetTypeCode(colType), unboxTypeCode = Type.GetTypeCode(unboxType);
                     bool hasTypeHandler;
-                    if ((hasTypeHandler = typeHandlers.ContainsKey(unboxType)) || colType == unboxType || dataTypeCode == unboxTypeCode || dataTypeCode == Type.GetTypeCode(nullUnderlyingType))
+                    if ((hasTypeHandler = TryGetTypeHandler(unboxType, out _)) || colType == unboxType || dataTypeCode == unboxTypeCode || dataTypeCode == Type.GetTypeCode(nullUnderlyingType))
                     {
                         if (hasTypeHandler)
                         {

tests/Dapper.Tests/Providers/SqliteTests.cs

@@ -1,5 +1,6 @@
 using Microsoft.Data.Sqlite;
 using System;
+using System.Collections.Generic;
 using System.Data.Common;
 using System.Linq;
 using System.Threading;
@@ -82,6 +83,47 @@ public async Task Issue466_SqliteHatesOptimizations_Async()
             row = await connection.QueryFirstAsync<HazNameId>("select 42 as Id").ConfigureAwait(false);
             Assert.Equal(42, row.Id);
         }
+
+        [FactSqlite]
+        public void TypeHandlerFactory_CanParse_Sqlite()
+        {
+            using var connection = GetSQLiteConnection();
+            SqlMapper.ResetTypeHandlers();
+            SqlMapper.AddTypeHandlerFactory(new ListHandlerFactory());
+            try
+            {
+                Assert.True(SqlMapper.HasTypeHandler(typeof(List<int>)));
+                Assert.True(SqlMapper.HasTypeHandler(typeof(List<string>)));
+
+                var row = connection.QuerySingle<ResultWithLists>(
+                    "SELECT '1|2|3' AS Ids, 'a|b|c' AS Names");
+
+                Assert.Equal([1, 2, 3], row.Ids);
+                Assert.Equal(["a", "b", "c"], row.Names);
+            }
+            finally
+            {
+                SqlMapper.ResetTypeHandlers();
+            }
+        }
+
+        [FactSqlite]
+        public void TypeHandlerFactory_CanSetValue_Sqlite()
+        {
+            using var connection = GetSQLiteConnection();
+            SqlMapper.ResetTypeHandlers();
+            SqlMapper.AddTypeHandlerFactory(new ListHandlerFactory());
+            try
+            {
+                var ids = new List<int> { 10, 20, 30 };
+                var result = connection.ExecuteScalar<string>("SELECT @Ids", new { Ids = ids });
+                Assert.Equal("10|20|30", result);
+            }
+            finally
+            {
+                SqlMapper.ResetTypeHandlers();
+            }
+        }
     }
 
     public class SqliteTests : SqliteTypeTestBase

tests/Dapper.Tests/TypeHandlerTests.cs

@@ -875,5 +875,141 @@ public bool Equals(Issue1959_Raw other)
                 => other.Value == Value;
             public override string ToString() => Value.ToString();
         }
+
+        
+
+        [Fact]
+        public void TypeHandlerFactory_CanParse()
+        {
+            SqlMapper.ResetTypeHandlers();
+            SqlMapper.AddTypeHandlerFactory(new ListHandlerFactory());
+            try
+            {
+                // Verify the factory registration is reflected by HasTypeHandler for matching types.
+                Assert.True(SqlMapper.HasTypeHandler(typeof(List<int>)));
+                Assert.True(SqlMapper.HasTypeHandler(typeof(List<string>)));
+                // Non-matching types should not be claimed.
+                Assert.False(SqlMapper.HasTypeHandler(typeof(HashSet<int>)));
+
+                // Verify that Dapper can deserialize query results into List<int> and List<string>
+                // using the handler created by the factory.
+                var row = connection.QuerySingle<ResultWithLists>(
+                    "SELECT '1|2|3' AS Ids, 'a|b|c' AS Names");
+
+                Assert.Equal([1, 2, 3], row.Ids);
+                Assert.Equal(["a", "b", "c"], row.Names);
+            }
+            finally
+            {
+                SqlMapper.ResetTypeHandlers();
+            }
+        }
+
+        [Fact]
+        public void TypeHandlerFactory_CanSetValue()
+        {
+            SqlMapper.ResetTypeHandlers();
+            SqlMapper.AddTypeHandlerFactory(new ListHandlerFactory());
+            try
+            {
+                // Verify that Dapper serializes a List<int> parameter via the factory-created handler.
+                var ids = new List<int> { 10, 20, 30 };
+                var result = connection.ExecuteScalar<string>(
+                    "SELECT @Ids", new { Ids = ids });
+
+                Assert.Equal("10|20|30", result);
+            }
+            finally
+            {
+                SqlMapper.ResetTypeHandlers();
+            }
+        }
+
+        [Fact]
+        public void TypeHandlerFactory_ResetClearsRegistration()
+        {
+            SqlMapper.ResetTypeHandlers();
+            SqlMapper.AddTypeHandlerFactory(new ListHandlerFactory());
+            Assert.True(SqlMapper.HasTypeHandler(typeof(List<int>)));
+
+            SqlMapper.ResetTypeHandlers();
+
+            // After a reset the factory registration should be gone and the
+            // handler should no longer be resolved.
+            Assert.False(SqlMapper.HasTypeHandler(typeof(List<int>)));
+        }
+
+        [Fact]
+        public void TypeHandlerFactory_NullThrows()
+        {
+            Assert.Throws<ArgumentNullException>(() =>
+                SqlMapper.AddTypeHandlerFactory(null!));
+        }
+
+        [Fact]
+        public void TypeHandlerFactory_FirstRegisteredWins()
+        {
+            SqlMapper.ResetTypeHandlers();
+            // Register two factories that both claim List<int>; the first one registered should win.
+            var factory1 = new ListHandlerFactory();
+            var factory2 = new ListHandlerFactory();
+            SqlMapper.AddTypeHandlerFactory(factory1);
+            SqlMapper.AddTypeHandlerFactory(factory2);
+
+            try
+            {
+                Assert.True(SqlMapper.HasTypeHandler(typeof(List<int>)));
+                Assert.True(factory1.CanHandleCalls.Contains(typeof(List<int>)));
+                Assert.False(factory2.CanHandleCalls.Contains(typeof(List<int>)));
+            }
+            finally
+            {
+                SqlMapper.ResetTypeHandlers();
+            }
+        }
+    }
+
+    // A TypeHandlerFactory that creates ListHandler<T> for any List<T> type
+    public class ListHandlerFactory : SqlMapper.TypeHandlerFactory
+    {
+        public HashSet<Type> CanHandleCalls { get; } = new();
+
+        public override bool CanHandle(Type type)
+        {
+            CanHandleCalls.Add(type);
+            return type.IsGenericType && type.GetGenericTypeDefinition() == typeof(List<>);
+        }
+
+        public override SqlMapper.ITypeHandler Create(Type type)
+        {
+            var elementType = type.GetGenericArguments()[0];
+            var handlerType = typeof(ListHandler<>).MakeGenericType(elementType);
+            return (SqlMapper.ITypeHandler)Activator.CreateInstance(handlerType)!;
+        }
+        
+        public class ListHandler<T> : SqlMapper.TypeHandler<List<T>>
+        {
+            public override void SetValue(IDbDataParameter parameter, List<T>? value)
+            {
+                parameter.Value = value is null
+                    ? (object)DBNull.Value
+                    : string.Join("|", value.Select(v => Convert.ToString(v)));
+            }
+
+            public override List<T> Parse(object? value)
+            {
+                if (value is null || value is DBNull) return [];
+                return ((string)value).Split('|')
+                    .Select(s => (T)Convert.ChangeType(s, typeof(T))!)
+                    .ToList();
+            }
+        }
+    }
+
+    // Result type for TypeHandlerFactory tests, shared across SQL Server and SQLite test classes.
+    public class ResultWithLists
+    {
+        public List<int>? Ids { get; set; }
+        public List<string>? Names { get; set; }
     }
 }