OnMapper 2.0.0

OnMapper

A high-performance, lightweight object mapper for .NET that simplifies mapping between Data Transfer Objects (DTOs) and domain models. OnMapper supports nested objects, collections, and async operations with minimal configuration.

✨ Features

• 🚀 High Performance - Optimized reflection with caching for fast mappings
• 🎯 Simple API - Easy to use with minimal configuration
• 🔄 Nested Objects - Automatically maps nested objects and complex hierarchies
• 📦 Collections - Built-in support for lists, arrays, and enumerables
• ⚡ Async/Await - Fully asynchronous API
• 🎨 Multi-Framework - Supports .NET 6, 7, 8, and 9
• 💪 Type-Safe - Strongly typed with full nullable reference type support
• 📝 Result Pattern - Built-in result type for error handling

📦 Installation

Install via NuGet Package Manager:

dotnet add package OnMapper

Or via Package Manager Console:

Install-Package OnMapper

🚀 Quick Start

Basic Mapping

using OnMapper;
using OnMapper.Services.Interfaces;

// Create mapper instance
IMappingService mapper = new OnMapping();

// Define your models
public class UserDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
}

public class UserEntity
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
}

// Map single object
var userDto = new UserDto { Id = 1, Name = "John Doe", Email = "john@example.com" };
var result = await mapper.Map<UserDto, UserEntity>(userDto);

if (result.IsSuccess)
{
    var userEntity = result.Data;
    Console.WriteLine($"Mapped: {userEntity.Name}");
}
else
{
    Console.WriteLine($"Error: {result.Message}");
}

Collection Mapping

// Map collections
var userDtos = new List<UserDto>
{
    new UserDto { Id = 1, Name = "John Doe", Email = "john@example.com" },
    new UserDto { Id = 2, Name = "Jane Smith", Email = "jane@example.com" }
};

var result = await mapper.MapCollection<UserDto, UserEntity>(userDtos);

if (result.IsSuccess)
{
    foreach (var user in result.Data)
    {
        Console.WriteLine($"Mapped: {user.Name}");
    }
}

Nested Objects

public class OrderDto
{
    public int Id { get; set; }
    public CustomerDto Customer { get; set; }
    public List<OrderItemDto> Items { get; set; }
}

public class OrderEntity
{
    public int Id { get; set; }
    public CustomerEntity Customer { get; set; }
    public List<OrderItemEntity> Items { get; set; }
}

// OnMapper automatically maps nested objects and collections
var orderDto = new OrderDto { /* ... */ };
var result = await mapper.Map<OrderDto, OrderEntity>(orderDto);

🎯 Usage Patterns

Dependency Injection

// In Program.cs or Startup.cs
services.AddScoped<IMappingService, OnMapping>();

// In your service or controller
public class UserService
{
    private readonly IMappingService _mapper;
    
    public UserService(IMappingService mapper)
    {
        _mapper = mapper;
    }
    
    public async Task<UserDto> GetUserAsync(int id)
    {
        var userEntity = await _repository.GetByIdAsync(id);
        var result = await _mapper.Map<UserEntity, UserDto>(userEntity);
        return result.Data;
    }
}

Error Handling

var result = await mapper.Map<SourceType, DestinationType>(source);

if (result.IsSuccess)
{
    // Success - use result.Data
    var mapped = result.Data;
}
else
{
    // Failure - handle error
    Console.WriteLine($"Mapping failed: {result.Message}");
}

🔧 Advanced Features

Result Pattern

OnMapper uses a Result pattern for robust error handling:

public class Result<T>
{
    public bool IsSuccess { get; set; }
    public string Message { get; set; }
    public T Data { get; set; }
}

Property Matching

OnMapper matches properties by name. Properties must:

• Have the same name in source and destination
• Be readable in source
• Be writable in destination

📊 Performance Tips

1. Reuse Mapper Instance - Create one instance and reuse it (singleton or scoped)
2. Avoid Unnecessary Mappings - Only map when crossing boundaries (e.g., API layer)
3. Use Collections Wisely - For large collections, consider pagination

🆚 Comparison with AutoMapper

🤝 Contributing

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors

• Moath Al-Makhlafi
• Osama Dammag

🙏 Acknowledgments

Created to simplify object mapping in .NET applications with minimal overhead and maximum developer productivity.

📞 Support

If you encounter any issues or have questions:

• Open an issue on GitHub
• Check existing documentation
• Review the examples above

Made with ❤️ for the .NET community