https://github.com/mapstermapper/mapster
A fast, fun and stimulating object to object Mapper
https://github.com/mapstermapper/mapster
c-sharp codegenerator fast mapper mapping
Last synced: about 1 month ago
JSON representation
A fast, fun and stimulating object to object Mapper
- Host: GitHub
- URL: https://github.com/mapstermapper/mapster
- Owner: MapsterMapper
- License: mit
- Created: 2014-05-30T21:19:14.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2024-06-17T20:46:35.000Z (almost 2 years ago)
- Last Synced: 2024-12-22T09:47:49.440Z (over 1 year ago)
- Topics: c-sharp, codegenerator, fast, mapper, mapping
- Language: C#
- Size: 1.46 MB
- Stars: 4,403
- Watchers: 77
- Forks: 333
- Open Issues: 207
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Mapster - The Mapper of Your Domain
Writing mapping methods is a machine job. Do not waste your time, let Mapster do it.
## NuGet Sources
### NuGet Packages
| Package | Stable | Pre-release |
|---------|--------|-------------|
| **Mapster** | [](https://www.nuget.org/packages/Mapster/latest) | [](https://www.nuget.org/packages/Mapster) |
| **Mapster.Core** | [](https://www.nuget.org/packages/Mapster.Core/latest) | [](https://www.nuget.org/packages/Mapster.Core) |
| **Mapster.DependencyInjection** | [](https://www.nuget.org/packages/Mapster.DependencyInjection/latest) | [](https://www.nuget.org/packages/Mapster.DependencyInjection) |
| **Mapster.EFCore** | [](https://www.nuget.org/packages/Mapster.EFCore/latest) | [](https://www.nuget.org/packages/Mapster.EFCore) |
| **Mapster.EF6** | [](https://www.nuget.org/packages/Mapster.EF6/latest) | [](https://www.nuget.org/packages/Mapster.EF6) |
| **Mapster.JsonNet** | [](https://www.nuget.org/packages/Mapster.JsonNet/latest) | [](https://www.nuget.org/packages/Mapster.JsonNet) |
| **Mapster.Immutable** | [](https://www.nuget.org/packages/Mapster.Immutable/latest) | [](https://www.nuget.org/packages/Mapster.Immutable) |
| **Mapster.Diagnostics** | [](https://www.nuget.org/packages/Mapster.Diagnostics/latest) | |
| **ExpressionDebugger** | [](https://www.nuget.org/packages/ExpressionDebugger/latest) | |
### DotNet Tools
| Tool | Stable | Pre-release |
|------|--------|-------------|
| **Mapster.Tool** | [](https://www.nuget.org/packages/Mapster.Tool/latest) | [](https://www.nuget.org/packages/Mapster.Tool) |
## Installation
Install Mapster with the NuGet CLI:
```Powershell
Install-Package Mapster
```
Or use the .NET core CLI to install Mapster:
```bash
dotnet add package Mapster --project
```
## Basic usage
### Mapping to a new object
Mapster creates the destination object and maps values to it.
```csharp
var destObject = sourceObject.Adapt();
```
### Mapping to an existing object
You create the object, Mapster maps to the object.
```csharp
sourceObject.Adapt(destObject);
```
### Use Mapster with Dependency Injection
You can get your `IMapper` instance via dependency injection, so you do not have to change code, when migrating to mapster from automapper!
**Just add Mapster to service collection:**
```csharp
services.AddMapster();
```
**And use it with DI in your Project:**
```csharp
public class Test
{
public Test(IMapper mapper)
{
var sourceObject = mapper.Adapt();
}
}
```
### Queryable Extensions
Mapster also provides extensions to map queryables.
```csharp
using (MyDbContext context = new MyDbContext())
{
// Build a Select Expression from DTO
var destinations = context.Sources.ProjectToType().ToList();
// Versus creating by hand:
var destinations = context.Sources.Select(c => new Destination {
Id = c.Id,
Name = c.Name,
Surname = c.Surname,
....
})
.ToList();
}
```
### Generating models & mappers
No need to write your own DTO classes. Mapster provides [Mapster.Tool](https://mapstermapper.github.io/Mapster/articles/tools/mapster-tool/Mapster-Tool-Overview.html) to help you generating models. And if you would like to have explicit mapping, Mapster also generates mapper class for you.
```csharp
[AdaptTo("[name]Dto"), GenerateMapper]
public class Student {
...
}
```
Then Mapster will generate for you:
```csharp
public class StudentDto {
...
}
public static class StudentMapper {
public static StudentDto AdaptToDto(this Student poco) { ... }
public static StudentDto AdaptTo(this Student poco, StudentDto dto) { ... }
public static Expression> ProjectToDto => ...
}
```
## What's new
- [Fluent API for code generation](https://mapstermapper.github.io/Mapster/articles/tools/mapster-tool/Fluent-API-Code-generation.html)
- [Automatically generate mapping code on build](https://mapstermapper.github.io/Mapster/articles/tools/mapster-tool/Mapster-Tool-Overview.html)
- [Define setting to nested mapping](https://mapstermapper.github.io/Mapster/articles/configuration/Config-for-nested-mapping.html)
- [`ISet`, `IDictionary`, `IReadOnlyDictionary` support](https://mapstermapper.github.io/Mapster/articles/mapping/Data-types.html#collections)
- [`EmptyCollectionIfNull`, `CreateNewIfNull` DestinationTransform](https://mapstermapper.github.io/Mapster/articles/settings/Setting-values.html#transform-value)
- [Several fixes](https://github.com/MapsterMapper/Mapster/releases/)
- New plugins
- [Immutable collection support](https://mapstermapper.github.io/Mapster/articles/packages/Immutable.html)
## Why Mapster?
### Performance & Memory efficient
Mapster was designed to be efficient on both speed and memory. You could gain a 4x performance improvement whilst using only 1/3 of memory.
And you could gain up to 12x faster performance with:
- [Roslyn Compiler](https://mapstermapper.github.io/Mapster/articles/packages/ExpressionDebugging.html)
- [FEC](https://mapstermapper.github.io/Mapster/articles/packages/FastExpressionCompiler.html)
- Code generation
| Method | Mean | StdDev | Error | Gen 0 | Gen 1 | Gen 2 | Allocated |
|-------------------------- |----------:|----------:|----------:|-----------:|------:|------:|----------:|
| 'Mapster 6.0.0' | 108.59 ms | 1.198 ms | 1.811 ms | 31000.0000 | - | - | 124.36 MB |
| 'Mapster 6.0.0 (Roslyn)' | 38.45 ms | 0.494 ms | 0.830 ms | 31142.8571 | - | - | 124.36 MB |
| 'Mapster 6.0.0 (FEC)' | 37.03 ms | 0.281 ms | 0.472 ms | 29642.8571 | - | - | 118.26 MB |
| 'Mapster 6.0.0 (Codegen)' | 34.16 ms | 0.209 ms | 0.316 ms | 31133.3333 | - | - | 124.36 MB |
| 'ExpressMapper 1.9.1' | 205.78 ms | 5.357 ms | 8.098 ms | 59000.0000 | - | - | 236.51 MB |
| 'AutoMapper 10.0.0' | 420.97 ms | 23.266 ms | 35.174 ms | 87000.0000 | - | - | 350.95 MB |
### Step into debugging
[Step-into debugging](https://mapstermapper.github.io/docs/packages/Diagnostics.html) lets you debug your mapping and inspect values just like your code.
### Code Generation
Code generation allows you to
- Validate mapping at compile time
- Getting raw performance
- Seeing your mapping code & debugging
- Finding usage of your models' properties
There are currently two tools which you can choose based on your preferences.
- [Mapster.Tool](https://mapstermapper.github.io/Mapster/articles/tools/mapster-tool/Mapster-Tool-Overview.html) _**NEW!**_
- [TextTemplate](https://mapstermapper.github.io/Mapster/articles/tools/TextTemplate.html)
## Change logs
https://github.com/MapsterMapper/Mapster/releases
## Usage Guides with Translations
- [English](https://github.com/MapsterMapper/Mapster/wiki)
- [中文文档](https://github.com/rivenfx/Mapster-docs) (sp thx to [@staneee](https://github.com/staneee))
## Acknowledgements
[JetBrains](https://www.jetbrains.com/?from=Mapster) kindly provides Mapster with a free open-source licence for their Resharper and Rider.
- **Resharper** makes Visual Studio a much better IDE
- **Rider** is fast & powerful cross platform .NET IDE