Feature | Trimming-compatible UDT deserialization

[edwardneal]

Is your feature request related to a problem? Please describe.

SqlClient supports CLR-defined user-defined types via runtime type resolution using assembly-qualified names supplied by SQL Server. These assembly-qualified names are defined in MS-TDS, section 2.2.5.5.2.

This assembly-qualified name is resolved to a concrete Type via Type.GetType, and it can be deserialized using one of two methods. The method is selected based upon an attribute attached to the type definition.

Method 1: custom serialization

This requires the type to implement IBinarySerialize. When reading an object from SQL Server, the type's default constructor is invoked, and SqlClient calls IBinarySerialize.Read. When passing it as a parameter, SqlClient calls IBinarySerialize.Write on the object.

SqlClient implements this using the BinarySerializeSerializer class.

Method 2: native serialization

When this is used, SqlClient follows the MS-SSCLRT protocol specification, adhering to the constraints in section 2.3.1.

The serializer for this is NormalizedSerializer. This uses a BinaryOrderedUdtNormalizer instance to get each instance field, sort them by Marshal.OffsetOf and write the field values.

Problem

The problem is that neither of these methods is compatible with IL trimming. Although the types have been annotated, the underlying tension is protocol-level: there's no way for the IL trimmer to know what types it should preserve because this type information comes from the database at runtime.

This tension materialises at a few key locations:

• If the CLR UDT is never statically referenced then the type may be removed during trimming, preventing SqlClient from resolving it from SQL Server's type metadata via Type.GetType.
• If a field on the object is not statically observed as used, it could be trimmed away completely. Native serialization will silently serialize an instance of an incomplete type.
• Similarly to the above - if the parameterless constructor on an otherwise-used CLR UDT isn't ever statically visible, it could be trimmed away. The type metadata may exist, but when SqlClient calls Activator.CreateInstance, the constructor won't be found and the type can't be instantiated.

Of these, the issue with certain fields being trimmed is the most serious. A trimmed type or constructor will throw an exception, but silently serialising an incomplete type would result in corrupt data - a situation which SQL Server doesn't verify.

The fact that the UDT's assembly-qualified name originates from SQL Server metadata also means that there's no call site which we can annotate to preserve these types - and even if one did exist, the annotations would only apply to the single type specified. This means they wouldn't cover more complex scenarios where a UDT can consist of multiple nested structs.

Describe the solution you'd like

I'm proposing a set of APIs which clients can call to use CLR-defined UDTs safely:

using System.Diagnostics.CodeAnalysis;

namespace Microsoft.Data.SqlClient;

public sealed class SqlUserDefinedTypeRegistration
{
    private const DynamicallyAccessedMemberTypes PreservedMembers =
		DynamicallyAccessedMemberTypes.PublicParameterlessConstructor | DynamicallyAccessedMemberTypes.Interfaces
		| DynamicallyAccessedMemberTypes.PublicFields | DynamicallyAccessedMemberTypes.NonPublicFields
		| DynamicallyAccessedMemberTypes.PublicMethods | DynamicallyAccessedMemberTypes.NonPublicMethods;
		
	private SqlUserDefinedTypeRegistration() { }

	// Declares preservation requirements for a type which is used as a SQL Server CLR UDT.
    public static SqlUserDefinedTypeRegistration Register<[DynamicallyAccessedMembers(PreservedMembers)] T>();

	// Declares an additional CLR type dependency of the registered CLR UDT.
    public SqlUserDefinedTypeRegistration WithDependency<[DynamicallyAccessedMembers(PreservedMembers)] T>();
}

This API surface wouldn't replace the existing CLR UDT resolution surface. Its only purpose is to declare CLR UDT preservation requirements in a form which can be observed and respected by the IL linker at build/publish time. It doesn't do anything at runtime, and would be safe to run from a .NET Framework (or a non-trimmed .NET Core) application.

Client applications would be expected to invoke these methods on a code path which the IL linker sees as reachable (such as Main() or a module initializer) in order to preserve the UDTs they want to read:

// Return value discarded - Address doesn't need any additional field types.
SqlUserDefinedTypeRegistration.Register<Address>();

// Use the returned SqlUserDefinedTypeRegistration to record the types of nested fields.
SqlUserDefinedTypeRegistration.Register<LineIntersection>()
	.WithDependency<Line>()
	.WithDependency<Point>();
	
[SqlUserDefinedType(Format.UserDefined, IsByteOrdered = false, MaxByteSize = 500)]
public class Address : IBinarySerialize
{
	public string Line1;
	
	public string Line2;

	void IBinarySerialize.Read(BinaryReader r) { }
	
	void IBinarySerialize.Write(BinaryWriter r) { }
}

public struct Point
{
	public int X;
	public int Y;
}

public struct Line
{
	public Point Start;
	public Point End;
}

[SqlUserDefinedType(Format.Native)]
public struct LineIntersection
{
	public Line FirstLine;
	public Line SecondLine;
}

Clients call Register to register the "top-level" UDT - the one directly registered within SQL Server via CREATE TYPE. If that top-level UDT has fields which are also struct types, those types are registered as dependencies via calls to WithDependency. The second step is necessary because DynamicallyAccessedMembers only applies preservation requirements to the type we attach it to. Preserving the fields of Line doesn't automatically preserve the constructor, fields and methods of Point - and the linker only sees compile-time annotations so any runtime discovery method (such as recursively discovering fields) is too late.

It's worth noting that this lack of recursion means that unusually complex UDTs may need multiple WithDependency calls - one for the type of a field on the UDT, another for a field within that type. The example demonstrates this principle with LineIntersection, Line and Point.

We would preserve the following member types:

• Parameterless constructor, since this is necessary to support Activator.CreateInstance;
• Interfaces, since this determines which (de)serialization method to use;
• Public and non-public fields, because these are the fields which native serialization operates on;
• Public and non-public methods, to preserve IBinarySerialize.Read and IBinarySerialize.Write (whether they're implemented implicitly or explicitly.)
  This is slightly coarser than we'd strictly need - but DynamicallyAccessedMembers doesn't provide a way to only preserve specific interface implementations. We don't force the trimmer to preserve properties here: IBinarySerialize-based implementations should reference them anyway, and native serialization only operates over fields.

Finally, although we preserve IBinarySerialize.Read / .Write, client applications will be responsible for making sure that those two methods are only performing operations which are compatible with trimming.

At the point of implementation, I would expect that Register and WithDependency would flow typeof(T) into a private method with an identically-annotated Type parameter. This would enable the linker to observe the preservation requirements.

Describe alternatives you've considered

Provide an assembly-scoped attribute

We're using SqlUserDefinedTypeRegistration to perform type declaration tasks which are nothing more than signals to the IL trimmer. This sort of declarative task would typically be better as an attribute on the assembly.

I've ruled this out because the IL trimmer won't perform data flow analysis into this attribute's constructor parameters at link time.

Drop WithDependency method

There's an argument to be made that we could simply call Register multiple times. This would preserve the types, but it leaves two semantic gaps open.

1. When using native serialization, it's possible to nest structs. SqlClient only respects the serialization method specified on the top-level type - so a struct which implements IBinarySerialize could be serialized in two different ways depending on whether we serialize the struct directly, or as a member of a struct which uses native serialization. It's helpful to have a way to expose this semantic relationship in code.
2. If a client registers each struct in the UDT independently then they're treating it as a set of types which should be preserved during UDT (de)serialization. They're essentially configuring an internal implementation detail of SqlClient. Having a Register / WithDependency pair means that clients are registering a specific UDT for preservation by describing its serialization graph, and allowing SqlClient to encapsulate its own implementation.

For these reasons, the API proposal provides a way to describe this relationship between types in code.

// Describe a type TopLevelStruct with a field of type MemberStructType.
SqlUserDefinedTypeRegistration.Register<TopLevelStruct>()
	.WithDependency<MemberStructType>();

// Describe TopLevelStruct and MemberStructType as independent UDTs.
SqlUserDefinedTypeRegistration.Register<TopLevelStruct>();
SqlUserDefinedTypeRegistration.Register<MemberStructType>();

Move API to SqlConnection

I don't want to prematurely dismiss this particular alternative, so this might need some discussion. The two methods I'm describing are linker-level preservation requirements; I felt that this was unrelated to SqlConnection's functionality, so chose to place the methods on a new type.

It's worth noting that SqlConnection already contains a RegisterColumnEncryptionKeyStoreProviders method and Register would have a somewhat similar purpose. The key difference is that RegisterColumnEncryptionKeyStoreProviders operates at runtime, while Register is a signal to the linker, and I found this a compelling enough reason to treat them differently.

Registry pattern

I considered exposing a SqlUserDefinedTypesRegistry object with Register<T> and WithDependency<T> methods, then providing a UserDefinedTypes property on SqlCommand. This would mean that we could also front-load the process of getting a list of fields and building serializers.

This is attractive because it aligns closely to SqlClient's existing process-wide mapping from Type to serializer, but the semantics of this would need to specifically be that this registry would contain all of the UDTs which were expected from executing a specific command. If UserDefinedTypes is null, we'd expect a (potentially incomplete) fallback to the current process-wide Type/serializer mapping; if UserDefinedTypes is non-null and the assembly-qualified name doesn't exist, an exception would be thrown.

I decided against it because I think the design would be overkill. Our core requirement is to make sure that UDTs we care about (and their relevant metadata and associated types) are preserved by the IL trimmer by indicating that they may be referenced dynamically by SQL Server. I don't personally see the need to expand the API surface with a full registry pattern for that.

There were also additional considerations around whether we'd want to be able to unregister types, and what should happen if someone adds an entry to a registry while a command was executing (for example, between a successful call to SqlCommand.ExecuteReader and a call to SqlDataReader.GetFieldValue<T>. While both of these are solvable, they introduce complexity and made the idea of SqlUserDefinedTypesRegistry harder to justify.

Client-specified DynamicDependency attributes

Clients could technically achieve a similar outcome by using a [DynamicDependency] attribute. However, this tightly couples each client to the implementation details of SqlClient's UDT serialization and deserialization logic and requires them to modify theirs if our implementation changes. In an environment which uses IL trimming with DynamicDependency, the type of reflection which SqlClient performs is part of its public contract with client applications.

The proposed API encapsulates this reflection contract within SqlClient, pulling ownership of it back within the library.

Additional context

Although I've described this as primarily enabling SqlClient to operate in IL-trimmed environments, it's also worth noting that Native AOT environments have very similar constraints - we can't assume that we'll be able to dynamically discover CLR UDTs at runtime. In both cases, the result of this API proposal will cause the linker to preserve the type metadata, its members and its default constructor, enabling Type.GetType, Activator.CreateInstance and reflection-based field access to function.

This API would address one of the major blockers for UDT support in trimmed/Native AOT environments; it's thus part of #1947.

[github-actions]

🔍 Triage Summary

Check	Result
Issue type	Feature
Environment	N/A — feature request
Area	Area\Netcore
Duplicates	Potentially related: #1947 (NativeAOT zero-warnings epic, explicitly referenced as parent)
Regression	Not indicated

Analysis

This is a detailed, well-researched API proposal to address a fundamental incompatibility between CLR UDT deserialization and IL trimming / Native AOT. The root cause is that UDT assembly-qualified names arrive at runtime from SQL Server metadata (via MS-TDS §2.2.5.5.2), making it impossible for the IL trimmer to statically determine which types, constructors, and fields must be preserved. The proposed SqlUserDefinedTypeRegistration class with Register<T>() / WithDependency<T>() methods acts purely as a linker signal (no runtime behavior) and is a targeted, well-scoped solution. The most dangerous failure mode — silently serializing an incomplete (partially-trimmed) struct under native serialization — correctly motivates urgency. Severity is P2: meaningful capability gap for NativeAOT/trimmed deployments that use CLR UDTs, but not a regression in existing trimming-unaware scenarios.

Next Steps

• This is a sub-issue of the NativeAOT support: get to zero warnings #1947 NativeAOT tracking epic; link them formally.
• Assign to Copilot coding agent to investigate and implement. Suggested investigation guidance:
  1. Define SqlUserDefinedTypeRegistration in src/Microsoft.Data.SqlClient/src/ (not legacy directories) with the proposed Register<T>() / WithDependency<T>() generic methods, annotating the T type parameter with [DynamicallyAccessedMembers(PreservedMembers)].
  2. Add the new public type to the reference assemblies in netcore/ref/ (and netfx/ref/ if applicable for net462 compatibility).
  3. Ensure the private implementation method that typeof(T) flows into is also annotated so the linker can trace the preservation requirement.
  4. Add unit tests in tests/UnitTests/ verifying the API is callable and functional (the runtime behavior is a no-op, so tests can confirm the type and methods exist and are callable).
  5. Add a code sample under doc/samples/ demonstrating Register<T>() and WithDependency<T>() usage patterns.
  6. Review SqlNormalizer.cs and SqlSer.cs for any existing linker annotation gaps that this API is meant to complement.

Note: This triage summary is auto-generated by an AI agent. The analysis and suggestions above have not been verified by a human maintainer. Please treat as preliminary guidance only.

Generated by SqlClient Issue Auto-Triage for issue #4413 · 34.7 AIC · ⌖ 9.96 AIC · ⊞ 8.4K · ◷

[tetolv]

Hello.
Probably it would be better to use source generators to produce required sequence of normalizers, needed to (de)serialize a particular type. Each UDT type already is decorated with convenient attribute SqlUserDefinedTypeAttribute, which could be used as trigger for source generation.
Generating a correct sequence of normalizers for a type shouldn't be hard, and it will be a perfect solution not only from NativeAOT code trimming perspective, but for performance as well.
I just don't know if it's possible to make it completely backward compatible with existing codebases. For instance, if we take a slightly modified class Address from ManualTests project:

[Serializable]
[SqlUserDefinedType(Format.Native, IsByteOrdered = false, MaxByteSize = 500)]
public partial class Address : INullable
{
   ...
}

,source generator would enhance it with a partial :

public partial class Address : IBinarySerialize
{
    public void Read(BinaryReader r)
    {
        // Generated code
    }

    public void Write(BinaryWriter w)
    {
        // Generated code
    }
}

The problem is that generated class should already be treated like binary serializable class, but it still retains attribute [SqlUserDefinedType(Format.Native, ...]. Perhaps actual serialization type should be determined by presence of IBinarySerialize interface on a type, not from attribute. Also all serializable classes should be made partial.

What do you think?

[edwardneal]

Hi. Thanks for looking into it, and I agree - source generators would definitely improve the performance of UDT serialization and deserialization. One of my frustrations with the current implementation is that it calls FieldInfo.GetValue/.SetValue, and this results in every field value in the UDT structure being boxed. Source generators for natively serialized UDTs could avoid that overhead.

With that said, the core challenge is that the source generator could generate the (de)serialization code we need to operate on a UDT quickly, only for the linker to remove both the UDT and the generated serializer because neither appears reachable from the application's static call graph. Consider a case such as this:

CREATE PROCEDURE [dbo].[GetPrimaryAddressByCustomerId]
	@Customer_Id INT NOT NULL,
	@Address dbo.Address OUTPUT
AS
BEGIN
	SELECT TOP 1 @Address = [Address]
	FROM dbo.Customer
	WHERE [Id] = @Customer_Id
END

using SqlConnection conn = new("...");

conn.Open();

using SqlCommand getAddressCommand = new("dbo.GetPrimaryAddressByCustomerId", conn);
getAddressCommand.CommandType = CommandType.StoredProcedure;

SqlParameter idParameter = getAddressCommand.Parameters.Add("@Customer_Id", SqlDbType.Int);
SqlParameter addressParameter = getAddressCommand.Parameters.Add("@Address", SqlDbType.Udt);

addressParameter.Direction = ParameterDirection.Output;
addressParameter.UdtTypeName = "dbo.Address";

idParameter.Value = 1;
getAddressCommand.ExecuteNonQuery();

Console.WriteLine(addressParameter.Value.GetType().Name);

In this scenario, nothing references the CLR type corresponding to dbo.Address. The only reference comes from SQL Server metadata at runtime, so the linker has no reason to preserve the type or any generated serializer associated with it. This is the best case scenario - the failure is deterministic, it's clearly associated with IL trimming and the client is failing to load or instantiate the entire type.

The idea of a source generator would definitely remove the worst case scenario (where the linker doesn't believe that a field in a UDT is ever referenced, so trims them from the type and silently corrupts data) - but the linker still needs a reason to consider the UDT and its generated serializer reachable in the first place.

I see SqlUserDefinedTypeRegistration (or its alternative) as providing that reachability information to the linker. Once that exists, if there's demand for improved performance of UDTs then a source generator could build on that foundation to provide those improvements while relying on the same mechanism for communicating preservation requirements to the linker.

[tetolv]

I would say, that it's a very niche case, when reading an UDT, it wouldn't be explicitly deserialized into it's typed object. Why would then someone read that UDT column in the first place?
But anyway such cases could be mitigated by using your proposed SqlUserDefinedTypeRegistration. Another solution would be adding a generic override for UDT parameter registration method, like SqlParameter addressParameter = getAddressCommand.Parameters.Add<Address>("@Address");, advantage of that being, that developer would not need to remember to add/remove separate type registration somewhere in the main() method.

I could try myself to implement that source generator, and see what would come out of it. That could be either a separate feature, or done as a part of this one.

[edwardneal]

That particular example is niche, but its goal is to highlight a more general point: it's entirely possible for an application to reference an instance of a UDT without ever providing a statically visible reference which allows the linker to root the type. Other examples could have been:

• Reading a UDT via SqlParameter.Value or the return value of SqlDataReader.GetValue and only interacting with it via an interface implemented by that type
• Populating a DataTable which referenced the type, but not all of its members or its constructor

Adding a new SqlParameterCollection.Add<T> would be interesting too, although I'm not sure the API would be positioned on the right type to handle the case of SqlDataReader.GetValue (if the SQL command doesn't involve parameters.)

Another option which might integrate neatly with source generators could be something similar to the below:

interface IBinarySerializer<T>
{
	T Read(BinaryReader reader);
	void Write(BinaryWriter writer, T value)
}

public sealed class SqlUserDefinedTypeRegistration
{
	// <existing members>

	// Specifies a serializer for type T which is used as a SQL Server CLR UDT
	public static void Register<[DynamicallyAccessedMembers(PreservedMembers)] T, TSerializer>(TSerializer serializer)
		where TSerializer : IBinarySerializer<T>;
}

Your source generators could create a serializer type which implements IBinarySerializer<T> and which registers them in a module initializer. That registration provides a static reference to the generated serializer, ensuring that the linker will preserve it and that SqlClient can call it. The serializer's implementation of Read and Write would naturally reference the fields we need to preserve within type T.

Three points which probably need to be considered are:

1. This would shift SqlUserDefinedTypeRegistration from a declarative API used solely to communicate preservation requirements into part of the runtime serializer infrastructure. I don't think that's a show-stopper, but it just means that any implementation would need to consider thread safety, whether it'd be possible to unregister serializers, what happens if Register<T, TSerializer> is called twice, etc.
2. CLR UDT assemblies must target a framework that SQL Server can host (typically .NET Framework or .NET Standard). Applications using IL trimming will be built on modern .NET, so the UDTs will live in a separate assembly to the trimmed application. This means that the source generator couldn't augment them with partial implementations - it'd need to generate companion serializer types and register them.
3. As a consequence of the source generator needing to generate companion serializer types, the serializer wouldn't be able to direct access private fields in order to serialize them. We'd need to use UnsafeAccessor or reflection for that.

I don't think any of those points are necessarily roadblocks, but they'd probably be best considered in their own feature request - and whatever API emerges from this should be designed to provide a coherent foundation for your proposed source generators to build on in the future.