DeepCopy.Expression 1.6.0

DeepCopy.Expression

DeepCopy.Expression is a high-performance deep copy library for .NET. It generates clone logic with expression trees and cashes compiled delegates for repreated use.

A deep copy duplicates not only the object itself, but also the objects it references. An Expression Tree is a data structure that represents code as a tree of expressions.

Features

• Deep copy for classes, structs, nullable structs, and anonymous types
• Array clone APIs for T[], T[,], T[,,], T[,,,], T[,,,,] and non-generic Array
• Supports deep cloning of polymorphic object hierarchies, including abstract classes and interfaces
• Handles circular references and self-referencing object graphs
• Supports cloning deeply nested object graphs such as LinkedList<T>.
• Optional reference-preserving mode (preserveObjectReferences parameter) for shared object graphs
• Member-level copy control with [Cloneable], [CopyMember] attributes and CopyPolicy parameter.
• Custom clone logic registration for each type
• Warm-up and cache lifecycle APIs: Compile<T> and Cleanup<T> methods

Installation

To install the library, you can use the following command in the Package Manager Console

PM > Install-Package DeepCopy.Expression

Supported Target Frameworks

• net10.0
• netstandard2.0

Quick Start

To create a deep copy of an object, call the ObjectCloner.Clone method:

var source = new User
{
    Id = 1,
    Name = "John Doe",
    Tags = new List<string> { "admin", "reviewer" }
};

var cloned = ObjectCloner.Clone(source);

Anonymous types are also supported:

var source = new
{
    Id = 1,
    Name = "John Doe",
    Tags = ["admin", "reviewer"]
};

var cloned = ObjectCloner.Clone(source);

Preserving Shared References

By default, objects are deep-cloned without preserving shared references to maximize performance. If the object graph contains shared nodes and reference identity must be preserved, pass true:

var cloned = ObjectCloner.Clone(source, preserveObjectReferences: true);

Attribute-Based Member Control

Default behavior (without [Cloneable]:

• All instance fields are copied, including private fields.
• Event backing fields are excluded

Opt-in behavior (with [Cloneable]):

• Only members marked with [CopyMember] are copied
• A CopyPolicy can be specified for each member

[Cloneable]
public sealed class Settings
{
    [CopyMember]
    private readonly string _id = Guid.NewGuid().ToString();

    [CopyMember(CopyPolicy.DeepCopy)]
    public List<string> Values { get; set; } = new ();

    [CopyMember(CopyPolicy.Assign)]
    public IServiceProvider ServiceProvider { get; set; } = default!;
}

Copy Policy

The following copy policies are available:

• Default: Uses the default behavior for the member type. Value types are assigned, reference types are deep-copied, arrays are cloned, and delegates are assigned.
• DeepCopy: Performs a deep copy of the member regardless of its type.
• ShallowCopy: Performs a shallow copy of the member regardless of its type. A shallow copy duplicates only the object itself and not the objects it references.
• Assign: Copies the member as-is regardless of its type. For reference types, no new instance is created and the original reference is shared.

Custom Clone Registration

Starting with version 1.5.0, custom clone logic can be registered for specific types using the ObjectCloner.RegisterCustomClone method.

The following example ensures that cloned object recieves a new unique ID:

ObjectCloner.RegisterCustomClone(
    typeof(MyCustomizableObject),
    (source, destination, context) =>
    {
        var fields = CustomCloneHelper.BuildCloneFieldsExpression(
            source.Type, source, destination, context, "_id");

        return Expression.Block(
            fields,
            CustomCloneHelper.BuildFieldAssignment(
                destination, "_id", Guid.NewGuid())
        );
    });

Performance

This is a benchmark of TestObject's deep clone. The performance of the library is comparable to the code that is specially implemented for deep copying. The library uses caching to avoid generating expression trees every time. The first time you clone an object, it may take longer than subsequent times.

Limitations

The library has some limitations:

• Delegates are not copied and are shared between the source and cloned objects.
• CopyTo is disabled for immutable collections such as ImmutableList<T>, ImmutableStack<T>, ImmutableQueue<T>, and ImmutableHashSet<T>.
• ImmutableHashSet<T> and ImmutableSortedSet<T> cannot be cloned correctly when they contain self-references.
• To prevent stack overflows, members deeper than DeepCopyOptions.MaxRecursionDepth are processed interatively, except for types specified in DeepCopyOptions.NonCopyableGenericTypes, which are always processed recursively.

License

This library is under the MIT License.