ObjectCartographer 4.0.2

dotnet add package ObjectCartographer --version 4.0.2                
NuGet\Install-Package ObjectCartographer -Version 4.0.2                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ObjectCartographer" Version="4.0.2" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add ObjectCartographer --version 4.0.2                
#r "nuget: ObjectCartographer, 4.0.2"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install ObjectCartographer as a Cake Addin
#addin nuget:?package=ObjectCartographer&version=4.0.2

// Install ObjectCartographer as a Cake Tool
#tool nuget:?package=ObjectCartographer&version=4.0.2                

ObjectCartographer

.NET Publish Coverage Status

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

Register ObjectCartographer with your IoC container during startup. Example code:

ServiceProvider? ServiceProvider = new ServiceCollection().RegisterObjectCartographer()?.BuildServiceProvider();

or

ServiceProvider? ServiceProvider = new ServiceCollection().AddCanisterModules()?.BuildServiceProvider();

As the library supports Canister Modules. 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:

DataMapper.Map<MyClass1, MyClass2>()
            .AddMapping(MyClass1 => MyClass1.PropertyToReadFrom, (MyClass2, value) => MyClass2.PropertyToWriteTo = value)
            .AddMapping(MyClass1 => MyClass1.Property1 + MyClass1.Property2, (MyClass1, value) => MyClass2.ComputedProperty = value)
            .AddMapping(MyClass1 => MyClass1.A.B.C.D, (MyClass1, value) => MyClass2.ProjectionProperty = value)
            .Build();

The above code could also be written using the extension method Map:

MyClass1Object.Map<MyClass1, MyClass2>()
                .AddMapping(MyClass1 => MyClass1.PropertyToReadFrom, (MyClass2, value) => MyClass2.PropertyToWriteTo = value)
                .AddMapping(MyClass1 => MyClass1.Property1 + MyClass1.Property2, (MyClass1, value) => MyClass2.ComputedProperty = value)
                .AddMapping(MyClass1 => MyClass1.A.B.C.D, (MyClass1, value) => MyClass2.ProjectionProperty = value)
                .Build();
				

You can also supply your own method for copying the data:

MyClass1Object.Map<MyClass1, MyClass2>()
                .UseMethod(MyCopier)
                .Build();

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:


BenchmarkDotNet=v0.13.0, OS=Windows 10.0.18363.1440 (1909/November2019Update/19H2)
Intel Core i7-9850H CPU 2.60GHz, 1 CPU, 12 logical and 6 physical cores
.NET SDK=5.0.203
  [Host]     : .NET 5.0.6 (5.0.621.22011), X64 RyuJIT
  DefaultJob : .NET 5.0.6 (5.0.621.22011), X64 RyuJIT


Method Mean Error StdDev Ratio RatioSD Rank
AutoMapper 91.575 ns 0.9259 ns 0.8661 ns 1.34 0.02 2
ObjectCartographer 68.374 ns 0.6952 ns 0.6163 ns 1.00 0.00 1

And about 350% faster when an object is supplied to it and only data copying is required.


BenchmarkDotNet=v0.13.0, OS=Windows 10.0.18363.1440 (1909/November2019Update/19H2)
Intel Core i7-9850H CPU 2.60GHz, 1 CPU, 12 logical and 6 physical cores
.NET SDK=5.0.203
  [Host]     : .NET 5.0.6 (5.0.621.22011), X64 RyuJIT
  DefaultJob : .NET 5.0.6 (5.0.621.22011), X64 RyuJIT


Method Mean Error StdDev Median Ratio RatioSD Rank
AutoMapper 88.796 ns 1.4598 ns 3.2951 ns 87.404 ns 3.48 0.16 2
ObjectCartographer 26.804 ns 0.2989 ns 0.2650 ns 26.712 ns 1.00 0.00 1

Installation

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

  1. 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:

  1. 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.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on ObjectCartographer:

Package Downloads
ObjectCartographer.SQL

ObjectCartographer converters for helping with SQL/ADO.Net.

Archivist

Archivist is a C# open-source library designed to simplify file loading tasks by providing a unified interface for accessing files of various formats.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
4.0.2 3,166 11/24/2024
4.0.1 742 11/18/2024
4.0.0 102 11/18/2024
3.0.65 1,460 11/11/2024
3.0.64 2,185 11/4/2024
3.0.63 1,747 10/29/2024
3.0.62 745 10/29/2024
3.0.61 1,389 10/14/2024
3.0.60 2,166 10/9/2024
3.0.59 8,672 8/28/2024
3.0.58 1,187 8/23/2024
3.0.57 1,833 8/21/2024
3.0.56 3,961 8/1/2024
3.0.55 1,841 7/24/2024
3.0.54 4,026 6/25/2024
3.0.53 33,360 6/17/2024
3.0.52 1,802 6/13/2024
3.0.51 840 6/12/2024
3.0.50 587 6/12/2024
3.0.49 126 6/12/2024
3.0.48 6,854 5/6/2024
3.0.47 1,931 5/1/2024
3.0.46 1,549 4/30/2024
3.0.45 767 4/29/2024
3.0.44 5,552 3/28/2024
3.0.43 3,099 3/14/2024
3.0.42 889 3/13/2024
3.0.41 1,889 3/5/2024
3.0.40 321 3/4/2024
3.0.39 4,125 2/26/2024
3.0.38 2,744 2/21/2024
3.0.37 1,189 2/19/2024
3.0.36 2,877 2/8/2024
3.0.35 1,065 2/6/2024
3.0.34 782 2/2/2024
3.0.33 6,244 1/29/2024
3.0.32 3,197 1/19/2024
3.0.31 3,366 1/10/2024
3.0.30 5,632 12/11/2023
3.0.29 4,813 11/17/2023
3.0.28 1,693 11/16/2023
3.0.27 3,278 11/6/2023
3.0.26 2,602 10/30/2023
3.0.25 4,549 9/22/2023
3.0.24 1,718 9/18/2023
3.0.23 2,770 9/11/2023
3.0.22 1,270 9/11/2023
3.0.21 1,359 9/8/2023
3.0.20 2,084 9/5/2023
3.0.19 1,500 9/4/2023
3.0.18 1,508 9/1/2023
3.0.17 1,650 8/31/2023
3.0.16 1,668 8/30/2023
3.0.15 1,358 8/29/2023
3.0.14 1,753 8/28/2023
3.0.13 5,888 8/8/2023
3.0.12 1,533 8/7/2023
3.0.11 3,638 7/24/2023
3.0.10 2,709 7/13/2023
3.0.9 984 7/12/2023
3.0.8 1,300 7/10/2023
3.0.7 893 7/8/2023
3.0.6 916 7/8/2023
3.0.5 906 7/8/2023
3.0.4 966 7/8/2023
3.0.3 3,010 12/13/2022
3.0.2 1,114 12/13/2022
3.0.0 4,154 12/12/2022
2.0.14 10,631 6/6/2022
2.0.12 11,458 1/11/2022
2.0.10 1,255 10/15/2021
2.0.9 1,228 9/22/2021
2.0.8 4,286 6/21/2021
2.0.7 7,349 6/16/2021
2.0.6 2,246 6/16/2021
2.0.4 2,092 6/16/2021
2.0.2 2,466 6/15/2021
2.0.1 1,299 6/15/2021
1.1.0 3,736 3/28/2011