ObjectCartographer 3.0.65
See the version list below for details.
dotnet add package ObjectCartographer --version 3.0.65
NuGet\Install-Package ObjectCartographer -Version 3.0.65
<PackageReference Include="ObjectCartographer" Version="3.0.65" />
paket add ObjectCartographer --version 3.0.65
#r "nuget: ObjectCartographer, 3.0.65"
// Install ObjectCartographer as a Cake Addin #addin nuget:?package=ObjectCartographer&version=3.0.65 // Install ObjectCartographer as a Cake Tool #tool nuget:?package=ObjectCartographer&version=3.0.65
ObjectCartographer
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:
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
- 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.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. 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. |
-
net6.0
- Canister.IoC (>= 5.3.18)
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.2)
-
net8.0
- Canister.IoC (>= 5.3.18)
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.2)
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 | 1,431 | 11/24/2024 |
4.0.1 | 559 | 11/18/2024 |
4.0.0 | 87 | 11/18/2024 |
3.0.65 | 1,366 | 11/11/2024 |
3.0.64 | 2,111 | 11/4/2024 |
3.0.63 | 1,712 | 10/29/2024 |
3.0.62 | 737 | 10/29/2024 |
3.0.61 | 1,373 | 10/14/2024 |
3.0.60 | 2,159 | 10/9/2024 |
3.0.59 | 8,615 | 8/28/2024 |
3.0.58 | 1,179 | 8/23/2024 |
3.0.57 | 1,827 | 8/21/2024 |
3.0.56 | 3,948 | 8/1/2024 |
3.0.55 | 1,837 | 7/24/2024 |
3.0.54 | 4,018 | 6/25/2024 |
3.0.53 | 33,344 | 6/17/2024 |
3.0.52 | 1,792 | 6/13/2024 |
3.0.51 | 834 | 6/12/2024 |
3.0.50 | 563 | 6/12/2024 |
3.0.49 | 121 | 6/12/2024 |
3.0.48 | 6,830 | 5/6/2024 |
3.0.47 | 1,927 | 5/1/2024 |
3.0.46 | 1,545 | 4/30/2024 |
3.0.45 | 763 | 4/29/2024 |
3.0.44 | 5,548 | 3/28/2024 |
3.0.43 | 3,095 | 3/14/2024 |
3.0.42 | 885 | 3/13/2024 |
3.0.41 | 1,885 | 3/5/2024 |
3.0.40 | 315 | 3/4/2024 |
3.0.39 | 4,121 | 2/26/2024 |
3.0.38 | 2,740 | 2/21/2024 |
3.0.37 | 1,185 | 2/19/2024 |
3.0.36 | 2,852 | 2/8/2024 |
3.0.35 | 1,061 | 2/6/2024 |
3.0.34 | 778 | 2/2/2024 |
3.0.33 | 6,240 | 1/29/2024 |
3.0.32 | 3,193 | 1/19/2024 |
3.0.31 | 3,364 | 1/10/2024 |
3.0.30 | 5,630 | 12/11/2023 |
3.0.29 | 4,811 | 11/17/2023 |
3.0.28 | 1,669 | 11/16/2023 |
3.0.27 | 3,251 | 11/6/2023 |
3.0.26 | 2,600 | 10/30/2023 |
3.0.25 | 4,547 | 9/22/2023 |
3.0.24 | 1,716 | 9/18/2023 |
3.0.23 | 2,768 | 9/11/2023 |
3.0.22 | 1,266 | 9/11/2023 |
3.0.21 | 1,357 | 9/8/2023 |
3.0.20 | 2,080 | 9/5/2023 |
3.0.19 | 1,498 | 9/4/2023 |
3.0.18 | 1,506 | 9/1/2023 |
3.0.17 | 1,646 | 8/31/2023 |
3.0.16 | 1,666 | 8/30/2023 |
3.0.15 | 1,354 | 8/29/2023 |
3.0.14 | 1,749 | 8/28/2023 |
3.0.13 | 5,879 | 8/8/2023 |
3.0.12 | 1,531 | 8/7/2023 |
3.0.11 | 3,634 | 7/24/2023 |
3.0.10 | 2,707 | 7/13/2023 |
3.0.9 | 982 | 7/12/2023 |
3.0.8 | 1,298 | 7/10/2023 |
3.0.7 | 889 | 7/8/2023 |
3.0.6 | 914 | 7/8/2023 |
3.0.5 | 904 | 7/8/2023 |
3.0.4 | 964 | 7/8/2023 |
3.0.3 | 3,008 | 12/13/2022 |
3.0.2 | 1,112 | 12/13/2022 |
3.0.0 | 4,150 | 12/12/2022 |
2.0.14 | 10,628 | 6/6/2022 |
2.0.12 | 11,456 | 1/11/2022 |
2.0.10 | 1,253 | 10/15/2021 |
2.0.9 | 1,226 | 9/22/2021 |
2.0.8 | 4,282 | 6/21/2021 |
2.0.7 | 7,344 | 6/16/2021 |
2.0.6 | 2,244 | 6/16/2021 |
2.0.4 | 2,090 | 6/16/2021 |
2.0.2 | 2,464 | 6/15/2021 |
2.0.1 | 1,297 | 6/15/2021 |
1.1.0 | 3,730 | 3/28/2011 |