Prototype Pattern

Think about how a bakery works. To make 50 identical gingerbread cookies, you don't sculpt each one from scratch. You make one perfect cookie cutter (the prototype), then stamp out copies. Each copy starts identical to the original shape, and you can decorate them differently afterward. That's Prototype in a nutshell — create one well-configured object, then copy it whenever you need a similar one.

Prototype is a creational design pattern that creates new objects by copying (cloning) an existing instance. Instead of calling new ConcreteClass() and configuring from scratch every time, the client calls prototype.Clone() to get a pre-configured copy. The client doesn't even need to know what concrete class it's dealing with — it just says "give me another one like this."

This matters in two situations: (1) when setting up the object is expensive (loading config from a database, parsing files), so you only want to do it once, and (2) when the exact type isn't known at compile time (runtime plugins, dynamic type loading), so you can't write new SpecificType() in your code.

Imagine you have a folder with a document and a sticky note inside. Shallow copy is like photocopying just the folder — you get a new folder, but the document and sticky note inside are the same physical items. Move the sticky note in one folder, and it's gone from the other. Deep copy is like photocopying the folder AND everything inside it — you get a completely independent set. Nothing you do to one folder affects the other.

In code terms: shallow copy duplicates the top-level object but copies reference-type fields by reference. The original and clone share the same nested objects (lists, dictionaries, custom classes). Changing a nested object in the clone also changes it in the original. Deep copy duplicates everything — the top-level object AND all nested objects recursively. Original and clone are completely independent.

In C#: MemberwiseClone() is always shallow. For deep copies, you need manual field copying (new List<string>(this.Tags)), serialization round-trips, or copy constructors. The important nuance: strings and value types (int, DateTime) are safe to shallow-copy because they're either immutable or copied by value automatically. The danger zone is mutable reference types — List<T>, Dictionary<K,V>, arrays, and custom classes.

Imagine ordering food from a menu that just says "food" with no description. You don't know if you're getting a salad or a steak. That's ICloneable — it promises a Clone() method but tells you nothing useful about what you'll get back.

Two specific problems. First, Clone() returns object — callers must cast the result (e.g., (MyClass)thing.Clone()), and if they cast to the wrong type, the error only shows up at runtime, not at compile time. Second, the interface says nothing about whether the clone is deep or shallow. Different .NET classes implement it differently: Array.Clone() is shallow, but some classes do deep copies. A caller has no way to know without reading the source code.

This is why Microsoft's own Framework Design Guidelines explicitly state: "Do not implement ICloneable." The interface was created in .NET 1.0 before generics existed. If it were designed today, it would be ICloneable<T> with a T Clone() method. The modern alternative is a custom IPrototype<T> with a typed return and an explicit name like DeepClone() that leaves no ambiguity.

Think of MemberwiseClone() as a high-speed photocopier for objects. It doesn't read each page one by one — it grabs the entire stack and copies it all in one shot. That's why it's so fast (2-5 nanoseconds for small objects).

Technically, MemberwiseClone() is a protected method on System.Object (so every object in C# has it). It's implemented as a native CLR intrinsic — it allocates a new chunk of memory the same size as the original object and does a raw byte-for-byte memory copy. No constructor runs, no field-by-field assignment, just one block copy operation (essentially memcpy at the CLR level).

The result: value-type fields (int, decimal, bool) get independent copies. Reference-type fields (List<T>, custom classes) get their pointers copied — they point to the same object in memory. That's what makes it "shallow." It also means no constructor side effects fire — if your constructor logs "object created" or increments a counter, the clone bypasses all of that. It exists without the constructor ever knowing.

Imagine a print shop with a filing cabinet full of document templates. You walk in and say "I need an invoice template." The clerk doesn't hand you the original template — they photocopy it and give you the copy. You fill in your details on the copy while the original stays pristine for the next customer. That filing cabinet is a Prototype Registry.

In code, a Prototype Registry is a centralized lookup (typically a Dictionary<string, IPrototype<T>>) that maps string keys to pre-configured prototype instances. The client asks the registry for a clone by name: registry.Create("goblin"). The registry finds the matching prototype, calls DeepClone(), and returns the independent copy.

The big advantage: the client is completely decoupled from concrete types. It never writes new Goblin() or new Orc(). It only knows about the registry and the prototype interface. New types can be added to the registry at runtime (loaded from config files, database, or plugins) without touching any client code. In a game server, you could add a new "dragon" enemy type by simply loading a new config entry — zero code changes, zero recompilation.

C# records are the language saying: "Prototype is so useful, we'll bake it into the syntax." When you declare a record, the compiler secretly generates: (1) a protected copy constructor that does a memberwise copy, and (2) a hidden method called <Clone>$ that calls this copy constructor. You never see these — they're auto-generated.

The with expression is the user-friendly way to clone with modifications: var clone = original with { Name = "New" };. Under the hood, this compiles to roughly: "clone the original, then set Name on the clone." It's Prototype in one line of code, with zero boilerplate.

The caveat: records do shallow cloning. This is safe when all properties are immutable (other records, strings, value types) because immutable things can't be changed — sharing is harmless. But if a record has a mutable List<string> property, the with expression shares that list. The same shallow-copy trap as MemberwiseClone(), just with prettier syntax.

Serialize the object to a byte stream or string, then deserialize it back into a new instance. This creates a completely independent deep copy because deserialization constructs entirely new objects.

Three common approaches in modern .NET:

• System.Text.Json — Built-in, handles circular refs with ReferenceHandler.Preserve. Medium speed. No attributes required on simple types.
• MessagePack — Binary format, typically 3-10x faster than JSON. Requires [MessagePackObject] attributes. Best for hot paths.
• protobuf-net — Google's Protocol Buffers for .NET. Very fast, compact. Requires [ProtoContract] attributes.

The trade-off: serialization-based cloning is 100-1000x slower than MemberwiseClone and requires all properties to be serializable. But it handles arbitrary object graphs with zero manual code.

Choose Prototype when: (1) object construction is expensive and you want to avoid repeating it, (2) the number of product variants is large or dynamic (loading types at runtime), (3) you want to avoid a parallel hierarchy of factory classes — one for each product type.

Choose Factory Method when: (1) each variant has different construction logic (not just different data), (2) the creation process itself varies across types, (3) you want compile-time type safety via the class hierarchy.

In practice, Prototype avoids the "class explosion" problem — instead of 20 factory subclasses for 20 product types, you have 20 prototype instances in a registry.

Use a Dictionary<object, object> (with ReferenceEqualityComparer.InstanceA comparer that uses Object.ReferenceEquals for equality (is this the exact same memory address?) instead of the potentially-overridden Equals method. Critical for visited dictionaries because you need to detect if you've seen this EXACT OBJECT before, not if you've seen an "equal" object. Available since .NET 5.) as a "visited" map. Before cloning any object, check if it's already in the map — if yes, return the existing clone. If no, create the clone, add it to the map BEFORE recursing into children, then clone the children.

The critical detail: register the clone in the visited map BEFORE populating its fields. This ensures that when a child references back to the parent, it finds the already-created (but not yet fully populated) clone — breaking the cycle.

Alternatively, use serializers that handle cycles natively: System.Text.Json with ReferenceHandler.Preserve adds $id/$ref markers to track references.

These fields must be reset or regenerated in the clone:

• Primary Key (Id) — Set to 0/default so the database generates a new one
• CreatedAt / UpdatedAt timestamps — Should reflect clone creation time
• Audit fields (CreatedBy, ModifiedBy) — Should reflect the current user
• Navigation property IDs — Child entity IDs must also be reset (0) so EF Core treats them as new
• Concurrency tokensA mechanism for optimistic concurrency control. EF Core uses a RowVersion column (SQL Server) or xmin (PostgreSQL) to detect conflicts. When saving, EF checks if the token matches the database. If someone else modified the row, the tokens won't match and EF throws DbUpdateConcurrencyException. A clone must have a fresh token to avoid false conflicts. (RowVersion) — Must be reset to avoid stale-data conflicts
• Unique constraints (slug, email, SKU) — Append "(Copy)" or generate new values

Immutability is Prototype's biggest competitor. If an object is truly immutable (all fields readonly, no mutable collections), you don't need to clone it — multiple consumers can safely share the same instance. Changing a property means creating a new instance with the changed value (which is what records with with do).

The relationship: Prototype solves the problem of "I need a similar but modified version of this object." Immutability solves the same problem differently — instead of "clone and mutate," you do "create new with changes." Records with with are the bridge: they use Prototype's mechanism (clone via copy constructor) to support immutability's semantics (new instance for every change).

Three approaches depending on access patterns:

• ConcurrentDictionary — Thread-safe reads and writes. Best when prototypes are added/updated at runtime. The TryGetValue + DeepClone() pattern is naturally safe because each clone is an independent object.
• ImmutableDictionary — Replace the entire dictionary atomically on update. Best when updates are rare and reads dominate (hot path spawning, cold path configuration).
• Read-only dictionary at startup — Load all prototypes during initialization, store in a IReadOnlyDictionary. No concurrency concerns because it never changes. Best for static registries (game enemy types, document templates).

Critical: the DeepClone() method itself must be thread-safe — it should only READ from the prototype, never mutate it. If your clone method has any temporary state modifications, protect them with a lock or make the method pure.

Prototype's intent: Create a new object by copying an existing one. The clone is used going forward — it becomes its own entity with its own lifecycle.

Memento's intent: Capture an object's internal state so it can be restored later. The memento is a snapshot saved for undo/rollback — it's not a new active entity.

They often use the same mechanism (cloning/serialization), but the purpose is different. Prototype says "I need a new object like this one." Memento says "I need to remember what this object looked like at this point in time." In practice, they complement each other: use Prototype to create the snapshot (clone), use Memento to store and manage it.

Write a reflection-based guard test that automatically discovers all reference-type properties and verifies they were deep-copied. This catches forgotten properties the moment they're added — no manual test updates needed:

• Use reflection to get all public properties of the cloneable class
• Filter to reference types (excluding string, which is immutable)
• Clone the object, then assert Assert.NotSame() on each reference-type property between original and clone
• If a developer adds a new List<T> property but forgets to deep-copy it, this test fails immediately because NotSame detects the shared reference

The key insight: this is a structural guard, not a behavioral test. It doesn't test what the clone does — it tests that the clone's shape is correct. Pair it with a count assertion (Assert.Equal(expectedCount, referenceProps.Length)) so the test also fails if someone adds a property but marks it to be skipped.

Events in C# are backed by delegate fields (reference types). MemberwiseClone() copies the delegate reference — meaning the clone's event points to the same subscriber list as the original.

The result: raising an event on the clone fires handlers that were subscribed to the original. In a UI application, changing a property on a cloned ViewModel updates the wrong UI panel. The fix: never copy event fields during cloning. Create a new instance and let the new context subscribe fresh handlers.

Copy-on-write (CoW) delays the deep copy until a mutation actually occurs. The clone initially shares data with the original (cheap), and only creates a private copy of a field when that field is about to be modified.

.NET's ImmutableList<T> and ImmutableDictionary<K,V> use a variant of this via structural sharingInstead of copying the entire data structure, new versions share unchanged internal tree nodes with the previous version. Adding one item to a 1M-element ImmutableList creates ~20 new nodes (O(log n)) while sharing 999,980 existing nodes. This gives you the semantics of immutability with the memory efficiency of mutation.. For custom objects, you can wrap mutable fields in a Lazy<T> or use a flag to track whether the field has been "detached" from the original.

This is most useful when clones are read-heavy — many clones are created but few are actually modified. The unmodified clones share data with the original, saving memory and allocation time.

Pros:

• Zero reflection at runtime — all mapping code is generated at compile time
• AOT-compatible (works with Native AOT / trimming)
• Type-safe — compile errors if you add a property without updating the mapper
• Fast — comparable to hand-written copy code
• Can selectively ignore fields (e.g., [MapperIgnoreTarget(nameof(Id))])

Cons:

• Requires a third-party package (Mapperly, MapStruct equivalent)
• Shallow by default — you need to configure nested type mappings
• Generated code can be hard to debug
• Doesn't handle circular references automatically

EF Core's change tracker complicates cloning. A tracked entity is "attached" to a DbContext. If you clone it and call Add(), EF might see duplicate key conflicts or try to update the original instead of inserting a new row.

The correct approach:

• Load the source entity with AsNoTracking() — this gives you a detached entity
• Include all navigation properties you want to clone (eager loading)
• Reset the primary key (Id = 0) on the root AND all child entities
• Reset audit fields (CreatedAt, RowVersion)
• Call db.Entity.Add(clone) — EF treats it as a brand new entity
• Call SaveChangesAsync() — the database generates new IDs

A prototype pool pre-clones N instances and serves them from a buffer. When the buffer is empty, it refills by cloning more from the prototype. This amortizes clone cost across requests.

public sealed class PrototypePool<T> where T : class, IPrototype<T>
{
    private readonly T _prototype;
    private readonly Channel<T> _pool;
    private readonly int _refillSize;

    public PrototypePool(T prototype, int capacity = 100, int refillSize = 25)
    {
        _prototype = prototype;
        _refillSize = refillSize;
        _pool = Channel.CreateBounded<T>(capacity);
        Refill(capacity); // pre-clone initial batch
    }

    public async ValueTask<T> RentAsync(CancellationToken ct = default)
    {
        if (_pool.Reader.TryRead(out var item))
            return item;

        // Pool empty — refill in background, return one clone immediately
        _ = Task.Run(() => Refill(_refillSize), ct);
        return _prototype.DeepClone();
    }

    private void Refill(int count)
    {
        for (int i = 0; i < count; i++)
        {
            if (!_pool.Writer.TryWrite(_prototype.DeepClone()))
                break; // pool is full
        }
    }
}

Key: Channel<T> is thread-safe and lock-free for single-reader/writer scenarios. The pool is bounded to prevent memory blowup. Background refill keeps the pool warm without blocking callers.

Use an immutable snapshot approach: each registry update creates a new version (immutable dictionary) rather than mutating the existing one. Previous versions are retained for rollback.

public sealed class VersionedPrototypeRegistry<T> where T : class, IPrototype<T>
{
    private readonly Stack<ImmutableDictionary<string, T>> _versions = new();
    private volatile ImmutableDictionary<string, T> _current;
    private readonly object _lock = new(); // Lock required: Stack<T> is not thread-safe

    public VersionedPrototypeRegistry(IDictionary<string, T> initial)
    {
        _current = initial.ToImmutableDictionary();
        _versions.Push(_current);
    }

    public T Create(string key) =>
        _current.TryGetValue(key, out var proto)
            ? proto.DeepClone()
            : throw new KeyNotFoundException(key);

    public void Update(string key, T newPrototype)
    {
        lock (_lock)
        {
            var next = _current.SetItem(key, newPrototype);
            _versions.Push(next);
            _current = next;
        }
    }

    public void Rollback()
    {
        lock (_lock)
        {
            if (_versions.Count <= 1) throw new InvalidOperationException("No version to rollback to");
            _versions.Pop();
            _current = _versions.Peek();
        }
    }
}

Separate clonable data from non-clonable services. The clone operation should only copy data fields; service dependencies should be re-injected or shared.

• Data fields (Name, Stats, Config) — deep clone these
• Immutable services (ILogger, IConfiguration) — share the same reference (safe because they're thread-safe and stateless)
• Stateful resources (Stream, DbContext) — do NOT clone. Either pass via method injection or resolve from DI in the clone's consumer.

Pattern: extract data into a separate EntityData class that implements IPrototype<EntityData>. The service wrapper holds a reference to data + services. Clone only the data, inject the services.

Register the prototype as Singleton (the template), then register a Transient factory that clones it on each resolution:

// Register the prototype template as Singleton
builder.Services.AddSingleton(new ReportTemplate
{
    Sections = { "Header", "Compliance", "Footer" },
    Compliance = new ComplianceData { GdprChecked = true }
});

// Register a Transient factory that clones the template per request
builder.Services.AddTransient<Report>(sp =>
{
    var template = sp.GetRequiredService<ReportTemplate>();
    return template.DeepClone();  // fresh clone per resolution
});

// Each controller gets its own independent Report instance
public class ReportController(Report report) { ... }

With .NET 8 Keyed ServicesA .NET 8 DI feature that lets you register multiple implementations of the same service type, distinguished by a key. builder.Services.AddKeyedSingleton<ICache>("redis", new RedisCache()); Resolve with [FromKeyedServices("redis")] ICache cache or sp.GetRequiredKeyedService<ICache>("redis"). Perfect for prototype registries in DI., you can register multiple named prototypes:

builder.Services.AddKeyedSingleton("engineering", new ReportTemplate { Department = "Engineering" });
builder.Services.AddKeyedSingleton("marketing", new ReportTemplate { Department = "Marketing" });

builder.Services.AddTransient<Report>(sp =>
{
    var dept = sp.GetRequiredService<ICurrentUser>().Department;
    var template = sp.GetRequiredKeyedService<ReportTemplate>(dept);
    return template.DeepClone();
});

Expression-tree cloning (used by libraries like DeepCloner) analyzes a type's fields via reflection once, generates an expression tree that performs field-by-field copying, compiles it into a delegate, and caches the delegate. Subsequent clones call the compiled delegate directly — near-native speed.

Structural sharing is an optimization of the Prototype concept. Instead of copying the entire data structure (O(n) memory), a new "version" shares unchanged nodes with the previous version and only allocates new nodes for changed elements (O(log n) memory for balanced trees).

ImmutableList<T>.Add(item) returns a new list that shares most of its internal tree nodes with the original — only the path from the new item to the root is newly allocated. For a list of 1,000,000 items, adding one item creates ~20 new tree nodes (log2(1M) ≈ 20), not 1,000,001 copies.

This is Prototype's "spirit" (create a new version from an existing one) with a dramatically better implementation for large collections. The trade-off: access patterns change (O(log n) random access instead of O(1) for arrays), and the implementation complexity is hidden inside the immutable collection library.

This is one of Prototype's strongest use cases. The plugin system loads assemblies at runtime, discovers types implementing IPrototype<T>, creates one instance of each (the prototype), and registers it in the registry. Users create new instances by cloning.

public interface IPlugin : IPrototype<IPlugin>
{
    string Name { get; }
    void Execute();
}

public class PluginRegistry
{
    private readonly Dictionary<string, IPlugin> _prototypes = new();

    public void LoadPlugins(string pluginDir)
    {
        foreach (var dll in Directory.GetFiles(pluginDir, "*.dll"))
        {
            var assembly = Assembly.LoadFrom(dll);
            var pluginTypes = assembly.GetTypes()
                .Where(t => typeof(IPlugin).IsAssignableFrom(t) && !t.IsAbstract);

            foreach (var type in pluginTypes)
            {
                var prototype = (IPlugin)Activator.CreateInstance(type)!;
                _prototypes[prototype.Name] = prototype;
            }
        }
    }

    public IPlugin Create(string name) => _prototypes[name].DeepClone();
}

In Event Sourcing, aggregates are rebuilt by replaying events. This replay is expensive for aggregates with many events. Prototype appears in two places:

• Snapshotting: Periodically deep-clone the aggregate state and persist the snapshot. Future rebuilds start from the snapshot instead of replaying all events from the beginning.
• Command validation: Before applying a command, clone the current state, apply the command to the clone, validate the result, and only then apply to the real aggregate. If validation fails, discard the clone — the real state is untouched.

This "speculative execution" pattern uses Prototype as an isolation mechanism: test mutations on a copy, commit only if valid.

MemberwiseClone() on a base class DOES copy subclass fields — it copies the entire object regardless of which class declares the method. So Shape.MemberwiseClone() called on a Circle produces a Circle with all fields copied.

The problem arises with manual deep clone: if Shape.DeepClone() creates new Shape { ... }, it slices the Circle fields. The fix: make DeepClone() virtual, override in each subclass, and use the covariant return typeA C# 9 feature that allows an overriding method to return a more derived type than the base method declares. Shape.DeepClone() returns Shape, but Circle.DeepClone() can return Circle. The compiler allows this because Circle IS a Shape — the override is type-safe and avoids casting. feature (C# 9+):

public abstract class Shape
{
    public double X { get; set; }
    public double Y { get; set; }
    public abstract Shape DeepClone();  // each subclass overrides
}

public class Circle : Shape
{
    public double Radius { get; set; }
    public override Circle DeepClone() => new()  // covariant return (C# 9+)
        { X = X, Y = Y, Radius = Radius };
}

public class Rectangle : Shape
{
    public double Width { get; set; }
    public double Height { get; set; }
    public override Rectangle DeepClone() => new()
        { X = X, Y = Y, Width = Width, Height = Height };
}

Before each mutation, deep-clone the canvas state and push it onto an undo stack. Undo = pop the stack and replace current state. Redo = push current onto a redo stack before restoring.

public class Canvas : IPrototype<Canvas>
{
    public List<Shape> Shapes { get; set; } = new();

    public Canvas DeepClone() => new()
    {
        Shapes = Shapes.Select(s => s.DeepClone()).ToList()
    };
}

public class UndoManager
{
    private readonly Stack<Canvas> _undoStack = new();
    private readonly Stack<Canvas> _redoStack = new();
    private Canvas _current;

    public UndoManager(Canvas initial) => _current = initial;

    public void Execute(Action<Canvas> mutation)
    {
        _undoStack.Push(_current.DeepClone());  // snapshot BEFORE mutation
        _redoStack.Clear();                      // new action clears redo
        mutation(_current);
    }

    public void Undo()
    {
        if (_undoStack.Count == 0) return;
        _redoStack.Push(_current.DeepClone());
        _current = _undoStack.Pop();
    }

    public void Redo()
    {
        if (_redoStack.Count == 0) return;
        _undoStack.Push(_current.DeepClone());
        _current = _redoStack.Pop();
    }
}

Native AOTAhead-of-Time compilation that produces a self-contained native executable with no runtime JIT compilation needed. Available since .NET 7 (preview) and .NET 8 (stable). The executable starts instantly and has a smaller memory footprint, but cannot use runtime code generation (Reflection.Emit, dynamic assemblies, etc.). eliminates the JIT compiler — all code must be known at compile time. This affects Prototype in several ways:

• Manual deep clone — fully AOT-compatible. No reflection, no runtime code generation.
• MemberwiseClone() — AOT-compatible (CLR intrinsic, not reflection).
• Records with with — AOT-compatible (compiler-generated code).
• Expression-tree cloning (DeepCloner) — NOT AOT-compatible (uses Reflection.Emit).
• BinaryFormatter — Removed entirely in .NET 9.
• System.Text.Json — AOT-compatible WITH source generators ([JsonSerializable]).
• Mapperly — Fully AOT-compatible (source-generated at compile time).

Trimming also removes unused types. If a prototype registry dynamically loads types, the trimmer might remove those types. Mark them with [DynamicallyAccessedMembers]A .NET trimming annotation that tells the linker "this Type reference needs specific members preserved." Without it, the trimmer may remove types it thinks are unused — but your plugin loader needs them at runtime. Apply to Type parameters in prototype registries and plugin systems. or use source generators to preserve them.