ObjectCartographer is a high-performance, convention-based C# object-to-object mapping library designed to simplify the process of copying data between objects. It eliminates the tedious task of manually writing code for data copying by providing a developer-friendly approach.
ObjectCartographer is a fast, convention based, and developer friendly object to object mapper. It's designed to simplify your life and remove the drudgery of writing code to copy data from one object to another.
Setting Up the Library
ObjectCartographer uses a library called Canister for registering itself in your ServiceCollection:
servicecollection.AddCanisterModules();
With that ObjectCartographer will automatically register any converters found in your application and work with your DI system if you are using one, allowing you to access the DataMapper object at run time if you need to. Otherwise if you are not using one, you can simply use the extension methods and it will wire itself up.
Basic Usage
Once the initial setup is done, we need to map our objects to each other. This is accomplished in a number of different ways. First by using the DataMapper class:
It's also possible, if you'd prefer, for the system to map everything for you based on the conventions that the system uses:
DataMapper.AutoMap<MyClass1, MyClass2>();
Or:
MyClass1Object.AutoMap<MyClass2>();
And lastly, you can simply skip the above steps all together and simply start using the library:
MyClass2 Result = MyClass1Object.To<MyClass2>();
If you don't set up the mapping beforehand, the library will go through the properties on MyClass1 and map them to properties with the same name on MyClass2. It compares the property names by first looking for exact matches, then it will drop underscores and compare them ignoring case.
Give Me Speed
The library is about 34% faster than AutoMapper in more complex scenarios:
The library is available via Nuget with the package name "ObjectCartographer". To install it run the following command in the Package Manager Console:
Install-Package ObjectCartographer
Note that there is a package that adds mapping for ADO.Net specific data types: "ObjectCartographer.SQL" so the system can do things like map DbType to SqlDbType along with other functionality.
FAQ
How do I add my own converter to the system?
You would need to implement the ObjectCartographer.ExpressionBuilder.Interfaces.IConverter interface. There is also the ObjectCartographer.ExpressionBuilder.BaseClasses.ConverterBaseClass abstract class to help with destination object creation/copy constructor discovery which is good in instances where you are mapping more complex objects. For simple data conversions like string to an int, the IConverter interface should be enough.
Build Process
In order to build the library you may require the following:
Visual Studio 2022
Other than that, just clone the project and you should be able to load the solution and build without too much effort.
