PanoramicData.DeepCloner 1.0.1

PanoramicData.DeepCloner

Library with extension to clone objects for .NET. It can deep or shallow copy objects. In deep cloning, the full object graph is maintained. Library actively uses code-generation in runtime and other tricks for blazingly-fast object cloning. Objects are copied by their internal structure, no methods or constructors are called for cloning objects. You can copy any object, but we don't recommend to copy objects which are bound to native resources or pointers, as this can cause unpredictable results. There is no requirement to specify object type for cloning.

You don't need to mark objects with the Serializable attribute, or restrict objects to a specific interface.

Object can be cast to interface or as an abstract object, you can clone array of ints as abstract Array or IEnumerable, even null can be cloned without any errors.

Installation through Nuget:

	Install-Package PanoramicData.DeepCloner

Origins

This library is a fork of FastDeepCloner.

Supported Frameworks

DeepCloner is a .NET Standard 2.0 library.

Limitation

Library requires Full Trust permission set or Reflection permission (MemberAccess). It prefers Full Trust, but if code lacks of this variant, library seamlessly switches to slightly slower but safer variant.

If your code is on very limited permission set, you can try to use another library e.g. CloneExtensions. It clones only public properties of objects, so, result can differ, but should work better (it requires only RestrictedMemberAccess permission).

Usage

Deep cloning any object:

  var clone = new { Id = 1, Name = "222" }.DeepClone();

With a reference to same object:

  // public class Tree { public Tree ParentTree;  }
  var t = new Tree();
  t.ParentTree = t;
  var cloned = t.DeepClone();
  Console.WriteLine(cloned.ParentTree == cloned); // True

Or as object:

  var date = DateTime.Now;
  var obj = (object)date;
  obj.DeepClone().GetType(); // DateTime

Shallow cloning (clone only same object, not objects that object relate to)

  var clone = new { Id = 1, Name = "222" }.ShallowClone();

Cloning to existing object (can be useful for copying constructors, creating wrappers or for keeping references to same object)

public class Derived : BaseClass
{
	public Derived(BaseClass parent)
	{
		parent.DeepCloneTo(this); // now this has every field from parent
	}
}

Please, note, that DeepCloneTo and ShallowCloneTo require that object should be class (it is useless for structures) and derived class must be real descendant of parent class (or same type). In another words, this code will not work:

public class Base {}
public class Derived1 : Base {}
public class Derived2 : Base {}

var b = (Base)new Derived1(); // casting derived to parent
var derived2 = new Derived2();
// will compile, but will throw an exception in runtime, Derived1 is not parent for Derived2
b.DeepCloneTo(derived2); 

Installation

Through nuget:

  Install-Package PanoramicData.DeepCloner

Details

You can use deep clone of objects for a lot of situations, e.g.:

• Emulation of external service or deserialization elimination (e.g. in Unit Testing). When code has received object from external source, code can change it (because object for code is own).
• ReadOnly object replace. Instead of wrapping your object to readonly object, you can clone object and target code can do anything with it without any restriction.
• Caching. You can cache data locally and want to ensure that cached object hadn't been changed by other code.

You can use shallow clone as fast, light version of deep clone (if your situation allows that). Main difference between deep and shallow clone in code below:

	// public class A { public B B; }
	// public class B { public int X; }
	var b = new B { X = 1 };
	var a = new A { B = b };
	var deepClone = a.DeepClone();
	deepClone.B.X = 2;
	Console.WriteLine(a.B.X); // 1
	var shallowClone = a.ShallowClone();
	shallowClone.B.X = 2;
	Console.WriteLine(a.B.X); // 2

So, deep cloning is guarantee that all changes of cloned object does not affect original. Shallow clone does not guarantee this. But it faster, because deep clone of object can copy big graph of related objects and related objects of related objects and related related related objects, and... so on...

This library does not call any method of cloning object: constructors, Equals, GetHashCode, propertes - nothing is called. So, it is impossible for cloning object to receive information about cloning, throw an exception or return invalid data. If you need to call some methods after cloning, you can wrap cloning call to another method which will perform required actions.

Extension methods in library are generic, but it is not require to specifify type for cloning. You can cast your objects to System.Object, or to an interface, add fields will be carefully copied to new object.

Performance

Cloning Speed can vary on many factors. This library contains some optimizations, e.g. structs are just copied, arrays also can be copied through Array.Copy if possible. So, real performance will depend on structure of your object.

Tables below, just for information. Simple object with some fields is cloned multiple times. Preparation time (only affect first execution) excluded from tests.

Example of object

	var c = new C1 { V1 = 1, O = new object(), V2 = "xxx" };
	var c1 = new C1Complex { C1 = c, Guid = Guid.NewGuid(), O = new object(), V1 = 42, V2 = "some test string", Array = new[] { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 } };

Deep cloning

Shallow cloning Shallow cloning is usually faster, because we no need to calculate references and clone additional objects.

Performance tricks

We perform a lot of performance tricks to ensure cloning is really fast. Here is some of them:

• Using a shallow cloning instead of deep cloning if object is safe for this operation
• Copying an whole object and updating only required fields
• Special handling for structs (can be copied without any cloning code, if possible)
• Cloners caching
• Optimizations for copying simple objects (reduced number of checks to ensure good performance)
• Special handling of reference count for simple objects, that is faster than default dictionary
• Constructors analyzing to select best variant of object construction
• Direct copying of arrays if possible
• Custom handling of one-dimensional and two-dimensional zero-based arrays (most of arrays in usual code)

License

MIT license