FastCloner

Features

• Zero reflection: All cloning logic is generated at compile time.
• Circular reference detection: Automatically handled.
• High performance: Optimized for speed.
• Collections support: Supports List, Dictionary, Arrays, etc.
• Nullable reference types: Full support.
• No partial requirement: Works with any class or struct without requiring the partial keyword.

Requirements

• Framework: .NET Standard 2.0+ or .NET 5+
• Language: C# 9.0+

FastCloner is optimized for high performance in both reflection-based and AOT (Ahead-of-Time) workloads.

Source Generator Design

The source generator is built using Roslyn's incremental model to ensure minimal impact on IDE performance and build times:

• Incremental pipeline: Type analysis only re-runs when decorated types or relevant usage data changes.
• Stable models: Uses TypeModel and MemberModel records to hold precomputed data instead of Roslyn symbols, making incremental caching effective.
• Reduced invalidation: The output pipeline avoids using CompilationProvider to prevent broad invalidation and unnecessary regeneration.
• Deterministic equality: Uses EquatableArray for model collection comparisons in the incremental pipeline.
• Direct paths: One-off helpers are inlined to keep generated clone paths direct.

FastCloner is designed to prioritize correctness, particularly in complex scenarios like deep cloning dictionaries where other libraries may fail.

It operates in two modes:

1. Reflection Mode (Default): Uses reflection to perform cloning. It is highly competitive within the reflection-based category but generally slower than IL generation or source generators.
2. Source Generator Mode (Opt-in): Provides increased performance by generating cloning code at compile time.

Note that FastCloner may allocate some extra memory upfront to maintain various lookup tables, which is a one-time cost to improve subsequent cloning operations.

The FastCloner source generator automatically discovers and generates specialized cloning code for:

• Generic types: The generator scans for usages (e.g., MyClass<int>) and generates specific code for those concrete instantiations.
• Abstract classes: The generator automatically finds all concrete derived types in your codebase to ensure they can be cloned via the base type.

[FastClonerClonable]
public abstract class Animal
{
    public string Name { get; set; }
}

public class Dog : Animal
{
    public string Breed { get; set; }
}

// Cloning via the abstract type works
Animal pet = new Dog { Name = "Buddy", Breed = "Labrador" };
Animal clone = pet.FastDeepClone(); // Returns a cloned Dog

To use the source generator, follow these two steps:

1. Decorate the classes or structs you want to clone with the [FastClonerClonable] attribute from the FastCloner.SourceGenerator.Shared namespace.
2. Call the generated FastDeepClone() extension method on an instance of that type.

Note: Unlike many other source generators, you do not need to declare your classes as partial.

using FastCloner.SourceGenerator.Shared;

[FastClonerClonable]
public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public List<string> Hobbies { get; set; }
}

// Usage:
var original = new Person { Name = "John", Age = 30, Hobbies = new() { "Reading" } };
var clone = original.FastDeepClone();

For types used as keys in HashSet<T> or Dictionary<TKey, TValue>, you can use [FastClonerStableHash] to skip the runtime probe that determines if GetHashCode is value-based.

Warning: Only use this if GetHashCode is a pure function of the type's fields. Do not use it if GetHashCode depends on object identity (e.g., RuntimeHelpers.GetHashCode(this)), as the cloned collection will be unable to find its own contents.

[FastClonerStableHash]
public sealed class CompositeKey
{
    public int Major { get; }
    public int Minor { get; }
    public override int GetHashCode() => HashCode.Combine(Major, Minor);
    public override bool Equals(object? obj) 
        => obj is CompositeKey other && other.Major == Major && other.Minor == Minor;
}

If you want to include FastCloner's functionality directly within your own library without adding it as a formal dependency, you can use the FastCloner.Internalization.Builder project. This tool rewrites namespaces, handles preprocessor directives, and adjusts visibility to fit your target project.

To use it, run the builder project from your terminal using dotnet run and provide the necessary configuration flags.

dotnet run --project src/FastCloner.Internalization.Builder/FastCloner.Internalization.Builder.csproj -- \
  --root-namespace MyLibrary.FastCloner \
  --output ../MyLibrary/FastCloner \
  --preprocessor "MODERN=true;" \
  --fqn all \
  --visibility internal \
  --public-api none \
  --runtime-only true \
  --self-check

If a type is used dynamically and is not visible at compile time (e.g., in an external assembly or via reflection), use the [FastClonerInclude] attribute to ensure the source generator creates cloning code for it.

This is useful for:

1. Including types used dynamically within a generic wrapper.
2. Adding derived types from external assemblies to an abstract class hierarchy.

[FastClonerClonable]
[FastClonerInclude(typeof(Customer), typeof(Order))]
public class Wrapper<T>
{
    public T Value { get; set; }
}

[FastClonerClonable]
[FastClonerInclude(typeof(ExternalPlugin))]
public abstract class Plugin
{
    public string Name { get; set; }
}

Use [FastClonerSafeHandle] on structs that act as handles to internal state or singletons. This instructs FastCloner to shallow-copy the readonly fields instead of deep-cloning them, preserving the original internal references and preventing breakage of internal framework logic.

[FastClonerSafeHandle]
public struct MyHandle
{
    private readonly object _internalState; // Preserved (shared), not deep cloned
    public int Value; // Cloned normally
}