MappingKit 1.0.5

MappingKit

A reflection-free, source-generated object mapper for .NET 8+ with zero runtime overhead.

Features

✅ Zero Reflection at Runtime - All mapping code is generated at compile-time
✅ Nested Object Mapping - Automatically maps nested objects and complex hierarchies
✅ Collection Mapping - Built-in support for List<T>, IEnumerable<T>, and arrays
✅ Attribute-Based Mapping - Use [MapFrom("PropertyName")] for property name differences
✅ Fluent API - Configure complex mappings with MapperContext
✅ IDE Friendly - Full IntelliSense support with generated code visible in IDE

Installation

dotnet add package MappingKit

Quick Start

1. Simple Mapping (Exact Name Match)

using MappingKit.Generated;

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
}

public class PersonDto
{
    public string Name { get; set; }
    public int Age { get; set; }
}

// Usage
var person = new Person { Name = "Alice", Age = 30 };
var dto = person.MapTo<Person, PersonDto>();

2. Mapping with Different Property Names

using MappingKit.Generated;
using MappingKit.Attributes;

public class User
{
    public string UserName { get; set; }
    public int UserAge { get; set; }
}

public class UserDto
{
    [MapFrom("UserName")]
    public string Name { get; set; }
    
    [MapFrom("UserAge")]
    public int Age { get; set; }
}

// Usage
var user = new User { UserName = "Bob", UserAge = 25 };
var dto = user.MapTo<User, UserDto>();

3. Nested Object Mapping

public class Order
{
    public string OrderId { get; set; }
    public Customer Customer { get; set; }
    public List<OrderItem> Items { get; set; }
}

public class OrderDto
{
    public string OrderId { get; set; }
    public CustomerDto Customer { get; set; }
    public List<OrderItemDto> Items { get; set; }
}

// Automatically maps nested objects and collections
var order = new Order { /* ... */ };
var orderDto = order.MapTo<Order, OrderDto>();

4. Collection Mapping

var users = new List<User> 
{ 
    new User { UserName = "Alice", UserAge = 30 },
    new User { UserName = "Bob", UserAge = 25 }
};

var userDtos = users.ToUserDtoList<User, UserDto>();

5. Fluent Configuration (Advanced)

using MappingKit.Attributes;
using MappingKit.Abstractions;

[MapperContext]
public partial class AppMapperContext : IMappingConfigurator
{
    public void Configure(IMappingBuilder builder)
    {
        builder.CreateMap<User, UserDto>()
            .ForMember<User, UserDto>(dest => dest.Name, src => src.UserName);
    }
}

How It Works

MappingKit uses C# Source Generators to create mapping code at compile-time. This means:

• No reflection overhead - All type information is known at compile-time
• Debuggable code - You can step through the generated mapping code
• Type-safe - Compilation errors if mappings are invalid
• Fast - As fast as hand-written mapping code

Mapping Conventions

MappingKit maps properties using these rules (in order of priority):

1. [MapFrom] Attribute - Explicitly specified source property
2. Exact Name Match - Properties with the same name
3. Type Compatibility - Source type must be assignable to destination type

Advanced Features

Nested Mapping

Automatically maps nested objects recursively:

public class Company
{
    public string Name { get; set; }
    public Address Address { get; set; }
    public List<Employee> Employees { get; set; }
}

// All nested objects (Address, Employees) are automatically mapped
var dto = company.MapTo<Company, CompanyDto>();

Collection Types

Supports various collection types:

• List<T>
• IEnumerable<T>
• ICollection<T>
• T[] (arrays)

Null Safety

MappingKit handles null values gracefully:

• Null objects are mapped to null
• Null collections are mapped to null
• Properties with null values are preserved

Configuration

Enable Generated Files Visibility (Recommended for IDE)

Add to your .csproj:

<PropertyGroup>
    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
    <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)Generated</CompilerGeneratedFilesOutputPath>
</PropertyGroup>

Project References

For consuming projects, reference both MappingKit and the Generator:

<ItemGroup>
  <ProjectReference Include="path\to\MappingKit.csproj" />
  <ProjectReference Include="path\to\MappingKit.Generator.csproj"
                    OutputItemType="Analyzer"
                    ReferenceOutputAssembly="false" />
</ItemGroup>

Troubleshooting

"Cannot resolve symbol 'Generated'" after clean build

This is an IDE caching issue. The code compiles and runs fine. To fix:

1. Run: dotnet build-server shutdown && dotnet build
2. Restart your IDE (VS Code: Reload Window, Rider: Invalidate Caches)

Performance

MappingKit generates code at compile-time, so there's zero runtime overhead. The generated mapping code is as fast as hand-written code.

API Reference

Extension Methods

• TDest MapTo<TSrc, TDest>(this TSrc source) - Map single object
• List<TDest> ToUserDtoList<TSrc, TDest>(this IEnumerable<TSrc> sources) - Map collection

Attributes

• [MapFrom("SourcePropertyName")] - Specify source property for mapping
• [MapperContext] - Mark class as mapper configuration context

Interfaces

• IMappingBuilder - Fluent mapping configuration
• IMappingConfigurator - Mapper context configuration

Requirements

• .NET 8.0 or later
• C# 11 or later

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog

1.0.1

• Added nested object mapping support
• Added collection/list mapping support
• Improved IDE integration with generated files
• Enhanced documentation

1.0.0

• Initial release
• Basic property mapping
• Attribute-based mapping
• Fluent API support