ForgeSharp.Mapper 1.2.1

ForgeSharp.Mapper

ForgeSharp.Mapper is a high-performance, type-safe, and extensible object mapping library for .NET. It enables you to define, configure, and execute mappings between different object types using a fluent, strongly-typed API. The library is designed for speed, maintainability, and ease of integration with modern .NET applications.

Features

• Fluent, Type-Safe API:
  Define mappings using expressive, chainable syntax with full compile-time safety.
• Reflection-Free Runtime Mapping:
  Mappings are compiled to delegates for maximum performance.
• Extensible Builder Pattern:
  Easily register and configure mappings for any type combination.
• Validation Tools:
  Built-in utilities to detect unmapped properties and validate mapping completeness.
• Dependency Injection Ready:
  Seamless integration with Microsoft.Extensions.DependencyInjection with the ForgeSharp.Mapper.DependencyInjection NuGet.
• Advanced Scenarios:
  Supports custom mapping logic, property transformations, and cloning.

Performance Comparison

At the time of writing, ForgeSharp.Mapper is significantly faster than other popular mapping libraries. Below is a benchmark* comparison against AutoMapper, Mapster, and manual mapping:

Forgesharp.Mapper is:

• ~46% faster than Mapster
• ~83% faster than AutoMapper

Despite its simplicity and lightweight footprint, ForgeSharp.Mapper delivers the same core functionality as other major mappers:

• Complex mapping support
• Custom value transformations
• Validation features

*The full benchmark project is included in the repository for reproducibility.

Installation

Add the NuGet package to your project:

dotnet add package ForgeSharp.Mapper

For Dependency Injection support, also install:

dotnet add package ForgeSharp.Mapper.DependencyInjection

Quick Start

1. Define a Mapper Builder

public class MyMapperBuilder : MapperBuilder
{
    public MyMapperBuilder()
    {
        Register<Source, Destination>()
            .To(d => d.Name).From(s => s.SourceName)
            .To(d => d.Age).From((s, d) => s.Years + 1);
    }
}

2. Register the Mapper in DI

services.AddMapper<MyMapperBuilder>();

3. Use the Mapper

var mapper = serviceProvider.GetRequiredService<IMapperService>();
var destination = mapper.Map<Source, Destination>(sourceObject);

Advanced Usage

Configure Extension (Recommended)

The Configure extension method allows you to define complex mappings in a single, expressive member-initializer expression. This makes your mapping configuration more readable and maintainable, especially for larger objects.

Register<Source, Destination>()
    .Configure((src, dest) => new Destination
    {
        Name = src.SourceName,
        Age = src.Years + 1,
        IsActive = true
    });

You can also use Configure for context-aware mappings:

RegisterWithContext<Source, MyContext, Destination>()
    .Configure((src, ctx, dest) => new Destination
    {
        Name = src.SourceName,
        UserId = ctx.CurrentUser,
        IsActive = true
    });

This just uses reflection to handle the fluent API, but the actual mapping is still compiled to delegates for performance.

Cloning

Register<MyType, MyType>().UseReflectionToClone();

Validation

var tester = serviceProvider.GetRequiredService<IMapperTester>();
foreach (var result in tester.ValidateMissingProperties())
{
    Console.WriteLine(result);
}

Custom Reflection-Based Mapping

register.AddAssignment(
    typeof(Destination).GetProperty(nameof(Destination.SomeProperty)),
    (Expression<Func<Source, string>>)(s => s.SomeSourceProperty)
);

Context-aware Mapping

ForgeSharpMapper supports context-aware mappers, allowing you to inject a custom context object into the mapping logic.

public class MyContext(Guid currentUser)
{
    public Guid CurrentUser { get; set; } = currentUser;
}

This context can then be injected into the mapping logic:

RegisterWithContext<Source, MyContext, Destination>()
    .To(d => d.UserId).From((s, ctx) => ctx.CurrentUser)
    .To(d => d.Name).From(s => s.SourceName);

API Overview

• IMapperService: Main entry point for mapping operations.
• MapperBuilder: Base class for registering and configuring mappings.
• IMapperRegister: Fluent interface for mapping configuration.
• IMapperTester: Utility for validating mapping completeness.
• ReflectionExtension / ConfigureExtension / CloneExtension: Helpers for advanced and reflection-based mapping scenarios.

Project Structure

• MapperRegistry.cs – Core fluent mapping API and registry.
• MapperService.cs – Service and DI integration.
• MapperTester.cs – Validation and diagnostics.
• Reflection/ – Extensions for reflection-based and advanced mapping.

Requirements

• .NET 8.0 or later

Contributing

Contributions are welcome! Please open issues or submit pull requests for bug fixes, improvements, or new features.

License

MIT License

Acknowledgements

• Inspired by AutoMapper and other mapping libraries, but designed for maximum performance, type safety and zero reflection.
• Built with modern C# features and best practices.

Contact

For questions, suggestions, or support, please open an issue on GitHub.

ForgeSharp.Mapper – Fast, type-safe, and extensible mapping for .NET.