CASMapper 1.0.2

CASMapper

CASMapper is a free, lightweight, and high-performance object mapper library for .NET. It serves as a superior alternative to AutoMapper, providing essential entity mapping functionality with maximum performance through compiled expressions and intelligent caching.

---

🌟 Features

• ✅ Zero Configuration - No DI setup required, use it directly
• ✅ High Performance - Uses compiled expressions and thread-safe caching
• ✅ Lightweight - Single static class, minimal dependencies
• ✅ Thread-Safe - Built with ConcurrentDictionary for concurrent operations
• ✅ Type-Safe - Full generic type support with compile-time safety
• ✅ Nullable Support - Handles nullable types (int? ↔ int) automatically
• ✅ Collection Mapping - Maps lists and collections recursively
• ✅ Custom Mappings - Map properties with different names using dictionaries
• ✅ 100% Free - Open source, no licensing fees

---

📦 Installation

Install CASMapper from NuGet Package Manager:

Install-Package CASMapper

Or using .NET CLI:

dotnet add package CASMapper

---

🚀 Quick Start

Basic Entity Mapping (Same Property Names)

Map entities with matching property names:

using CASMapper;

// Source entity
public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public DateTime CreatedDate { get; set; }
}

// Destination entity
public class UserDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public DateTime CreatedDate { get; set; }
}

// Usage
var user = new User 
{ 
    Id = 1, 
    Name = "John Doe", 
    Email = "john@example.com",
    CreatedDate = DateTime.Now
};

var userDto = ObjectMapper.Map<User, UserDto>(user);
// userDto now contains all mapped properties

Mapping Collections/Lists

Map collections of entities efficiently:

var users = new List<User>
{
    new User { Id = 1, Name = "John", Email = "john@example.com" },
    new User { Id = 2, Name = "Jane", Email = "jane@example.com" },
    new User { Id = 3, Name = "Bob", Email = "bob@example.com" }
};

var userDtos = ObjectMapper.MapList<User, UserDto>(users);
// Returns List<UserDto> with all users mapped

Custom Property Mapping (Different Property Names)

Map properties with different names using a dictionary:

// Source entity
public class Customer
{
    public int CustomerId { get; set; }
    public string FullName { get; set; }
    public string ContactEmail { get; set; }
}

// Destination entity
public class CustomerDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
}

// Create custom mapping dictionary
var customMappings = new Dictionary<string, string>
{
    { "CustomerId", "Id" },        // CustomerId → Id
    { "FullName", "Name" },         // FullName → Name
    { "ContactEmail", "Email" }     // ContactEmail → Email
};

var customer = new Customer 
{ 
    CustomerId = 1, 
    FullName = "John Doe", 
    ContactEmail = "john@example.com" 
};

var customerDto = ObjectMapper.Map<Customer, CustomerDto>(
    customer, 
    null, 
    customMappings
);
// customerDto.Id = 1, customerDto.Name = "John Doe", customerDto.Email = "john@example.com"

Mapping Collections with Custom Mappings

var customers = new List<Customer> { /* ... */ };

var customMappings = new Dictionary<string, string>
{
    { "CustomerId", "Id" },
    { "FullName", "Name" },
    { "ContactEmail", "Email" }
};

var customerDtos = ObjectMapper.MapList<Customer, CustomerDto>(
    customers, 
    customMappings
);

Nested Collections

CASMapper automatically handles nested collections:

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

public class OrderDto
{
    public int OrderId { get; set; }
    public List<OrderItemDto> Items { get; set; }
}

var order = new Order 
{ 
    OrderId = 1, 
    Items = new List<OrderItem> { /* ... */ } 
};

var orderDto = ObjectMapper.Map<Order, OrderDto>(order);
// Nested Items collection is automatically mapped

Nullable Type Support

CASMapper handles nullable types automatically:

public class Source
{
    public int? Age { get; set; }
    public string Name { get; set; }
}

public class Destination
{
    public int Age { get; set; }  // Non-nullable
    public string Name { get; set; }
}

var source = new Source { Age = 25, Name = "John" };
var dest = ObjectMapper.Map<Source, Destination>(source);
// dest.Age = 25 (nullable to non-nullable conversion)

Using Existing Destination Instance

You can map to an existing instance:

var existingDto = new UserDto { Id = 999 };
var user = new User { Id = 1, Name = "John", Email = "john@example.com" };

var result = ObjectMapper.Map<User, UserDto>(user, existingDto);
// existingDto is updated with mapped properties (Id remains 999 if not mapped)

---

📚 API Reference

Map<ObjectIn, ObjectOut>(ObjectIn origen, ObjectOut? destino = null)

Maps a single entity from source to destination type.

Parameters:

• origen: Source entity instance (required)
• destino: Destination entity instance (optional, creates new if null)

Returns: Mapped destination entity

Constraints:

• ObjectIn must be a class
• ObjectOut must be a class with parameterless constructor

---

Map<ObjectIn, ObjectOut>(ObjectIn origen, ObjectOut? destino, Dictionary<string, string>? mapeosPersonalizados)

Maps a single entity with custom property name mappings.

Parameters:

• origen: Source entity instance (required)
• destino: Destination entity instance (optional)
• mapeosPersonalizados: Dictionary mapping source property names to destination property names

Returns: Mapped destination entity

---

MapList<ObjectIn, ObjectOut>(IEnumerable<ObjectIn> origenes)

Maps a collection of entities to a list of destination entities.

Parameters:

• origenes: Collection of source entities

Returns: List<ObjectOut> with all mapped entities

---

MapList<ObjectIn, ObjectOut>(IEnumerable<ObjectIn> origenes, Dictionary<string, string>? mapeosPersonalizados)

Maps a collection with custom property name mappings.

Parameters:

• origenes: Collection of source entities
• mapeosPersonalizados: Dictionary mapping source property names to destination property names

Returns: List<ObjectOut> with all mapped entities

---

ClearCache()

Clears the internal mapping cache. Useful for testing or memory management.

ObjectMapper.ClearCache();

---

⚡ Performance

CASMapper is optimized for performance:

• Compiled Expressions: Mappings are compiled to IL code once and cached
• Property Caching: Property reflection results are cached to avoid repeated lookups
• Thread-Safe Caching: Uses ConcurrentDictionary for safe concurrent access
• Pre-allocated Lists: Collections are pre-sized when possible for better memory usage

---

🔧 Requirements

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

---

📝 License

MIT License - Free to use in commercial and personal projects.

---

👨‍💻 About

CASMapper is developed by Central American System (CAS), a Guatemalan software development company focused on high-performance enterprise solutions.

Developer: José Alonso
Title: Systems Engineer, CEO of CEAMSYS (Central American System)
Location: Guatemala

---

🤝 Contributing

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

---

📧 Support

For issues, questions, or contributions, please visit our GitHub repository.

---

CASMapper (Español)

CASMapper es una biblioteca gratuita, ligera y de alto rendimiento para mapeo de objetos en .NET. Sirve como una alternativa superior a AutoMapper, proporcionando funcionalidad esencial de mapeo de entidades con máximo rendimiento mediante expresiones compiladas y caché inteligente.

---

🌟 Características

• ✅ Sin Configuración - No requiere configuración de DI, úsalo directamente
• ✅ Alto Rendimiento - Usa expresiones compiladas y caché thread-safe
• ✅ Ligero - Una sola clase estática, dependencias mínimas
• ✅ Thread-Safe - Construido con ConcurrentDictionary para operaciones concurrentes
• ✅ Type-Safe - Soporte completo de tipos genéricos con seguridad en tiempo de compilación
• ✅ Soporte Nullable - Maneja tipos anulables (int? ↔ int) automáticamente
• ✅ Mapeo de Colecciones - Mapea listas y colecciones recursivamente
• ✅ Mapeos Personalizados - Mapea propiedades con nombres diferentes usando diccionarios
• ✅ 100% Gratis - Código abierto, sin costos de licencia

---

📦 Instalación

Instala CASMapper desde el Administrador de Paquetes NuGet:

Install-Package CASMapper

O usando .NET CLI:

dotnet add package CASMapper

---

🚀 Inicio Rápido

Mapeo Básico de Entidades (Nombres de Propiedades Iguales)

Mapea entidades con nombres de propiedades coincidentes:

using CASMapper;

// Entidad origen
public class Usuario
{
    public int Id { get; set; }
    public string Nombre { get; set; }
    public string Email { get; set; }
    public DateTime FechaCreacion { get; set; }
}

// Entidad destino
public class UsuarioDto
{
    public int Id { get; set; }
    public string Nombre { get; set; }
    public string Email { get; set; }
    public DateTime FechaCreacion { get; set; }
}

// Uso
var usuario = new Usuario 
{ 
    Id = 1, 
    Nombre = "Juan Pérez", 
    Email = "juan@ejemplo.com",
    FechaCreacion = DateTime.Now
};

var usuarioDto = ObjectMapper.Map<Usuario, UsuarioDto>(usuario);
// usuarioDto ahora contiene todas las propiedades mapeadas

Mapeo de Colecciones/Listas

Mapea colecciones de entidades eficientemente:

var usuarios = new List<Usuario>
{
    new Usuario { Id = 1, Nombre = "Juan", Email = "juan@ejemplo.com" },
    new Usuario { Id = 2, Nombre = "María", Email = "maria@ejemplo.com" },
    new Usuario { Id = 3, Nombre = "Pedro", Email = "pedro@ejemplo.com" }
};

var usuarioDtos = ObjectMapper.MapList<Usuario, UsuarioDto>(usuarios);
// Retorna List<UsuarioDto> con todos los usuarios mapeados

Mapeo Personalizado de Propiedades (Nombres de Propiedades Diferentes)

Mapea propiedades con nombres diferentes usando un diccionario:

// Entidad origen
public class Cliente
{
    public int ClienteId { get; set; }
    public string NombreCompleto { get; set; }
    public string EmailContacto { get; set; }
}

// Entidad destino
public class ClienteDto
{
    public int Id { get; set; }
    public string Nombre { get; set; }
    public string Email { get; set; }
}

// Crear diccionario de mapeo personalizado
var mapeosPersonalizados = new Dictionary<string, string>
{
    { "ClienteId", "Id" },           // ClienteId → Id
    { "NombreCompleto", "Nombre" },   // NombreCompleto → Nombre
    { "EmailContacto", "Email" }      // EmailContacto → Email
};

var cliente = new Cliente 
{ 
    ClienteId = 1, 
    NombreCompleto = "Juan Pérez", 
    EmailContacto = "juan@ejemplo.com" 
};

var clienteDto = ObjectMapper.Map<Cliente, ClienteDto>(
    cliente, 
    null, 
    mapeosPersonalizados
);
// clienteDto.Id = 1, clienteDto.Nombre = "Juan Pérez", clienteDto.Email = "juan@ejemplo.com"

Mapeo de Colecciones con Mapeos Personalizados

var clientes = new List<Cliente> { /* ... */ };

var mapeosPersonalizados = new Dictionary<string, string>
{
    { "ClienteId", "Id" },
    { "NombreCompleto", "Nombre" },
    { "EmailContacto", "Email" }
};

var clienteDtos = ObjectMapper.MapList<Cliente, ClienteDto>(
    clientes, 
    mapeosPersonalizados
);

Colecciones Anidadas

CASMapper maneja automáticamente las colecciones anidadas:

public class Orden
{
    public int OrdenId { get; set; }
    public List<ItemOrden> Items { get; set; }
}

public class OrdenDto
{
    public int OrdenId { get; set; }
    public List<ItemOrdenDto> Items { get; set; }
}

var orden = new Orden 
{ 
    OrdenId = 1, 
    Items = new List<ItemOrden> { /* ... */ } 
};

var ordenDto = ObjectMapper.Map<Orden, OrdenDto>(orden);
// La colección anidada Items se mapea automáticamente

Soporte de Tipos Anulables

CASMapper maneja tipos anulables automáticamente:

public class Origen
{
    public int? Edad { get; set; }
    public string Nombre { get; set; }
}

public class Destino
{
    public int Edad { get; set; }  // No anulable
    public string Nombre { get; set; }
}

var origen = new Origen { Edad = 25, Nombre = "Juan" };
var destino = ObjectMapper.Map<Origen, Destino>(origen);
// destino.Edad = 25 (conversión de anulable a no anulable)

Usar Instancia de Destino Existente

Puedes mapear a una instancia existente:

var dtoExistente = new UsuarioDto { Id = 999 };
var usuario = new Usuario { Id = 1, Nombre = "Juan", Email = "juan@ejemplo.com" };

var resultado = ObjectMapper.Map<Usuario, UsuarioDto>(usuario, dtoExistente);
// dtoExistente se actualiza con las propiedades mapeadas (Id permanece 999 si no se mapea)

---

📚 Referencia de API

Map<ObjectIn, ObjectOut>(ObjectIn origen, ObjectOut? destino = null)

Mapea una entidad única del tipo origen al tipo destino.

Parámetros:

• origen: Instancia de la entidad origen (requerido)
• destino: Instancia de la entidad destino (opcional, crea nueva si es null)

Retorna: Entidad destino mapeada

Restricciones:

• ObjectIn debe ser una clase
• ObjectOut debe ser una clase con constructor sin parámetros

---

Map<ObjectIn, ObjectOut>(ObjectIn origen, ObjectOut? destino, Dictionary<string, string>? mapeosPersonalizados)

Mapea una entidad única con mapeos personalizados de nombres de propiedades.

Parámetros:

• origen: Instancia de la entidad origen (requerido)
• destino: Instancia de la entidad destino (opcional)
• mapeosPersonalizados: Diccionario que mapea nombres de propiedades origen a nombres de propiedades destino

Retorna: Entidad destino mapeada

---

MapList<ObjectIn, ObjectOut>(IEnumerable<ObjectIn> origenes)

Mapea una colección de entidades a una lista de entidades destino.

Parámetros:

• origenes: Colección de entidades origen

Retorna: List<ObjectOut> con todas las entidades mapeadas

---

MapList<ObjectIn, ObjectOut>(IEnumerable<ObjectIn> origenes, Dictionary<string, string>? mapeosPersonalizados)

Mapea una colección con mapeos personalizados de nombres de propiedades.

Parámetros:

• origenes: Colección de entidades origen
• mapeosPersonalizados: Diccionario que mapea nombres de propiedades origen a nombres de propiedades destino

Retorna: List<ObjectOut> con todas las entidades mapeadas

---

ClearCache()

Limpia el caché interno de mapeos. Útil para testing o gestión de memoria.

ObjectMapper.ClearCache();

---

⚡ Rendimiento

CASMapper está optimizado para rendimiento:

• Expresiones Compiladas: Los mapeos se compilan a código IL una vez y se almacenan en caché
• Caché de Propiedades: Los resultados de reflexión de propiedades se almacenan en caché para evitar búsquedas repetidas
• Caché Thread-Safe: Usa ConcurrentDictionary para acceso concurrente seguro
• Listas Pre-asignadas: Las colecciones se pre-dimensionan cuando es posible para mejor uso de memoria

---

🔧 Requisitos

• .NET 8.0 o superior
• C# 12.0 o superior

---

📝 Licencia

Licencia MIT - Libre de usar en proyectos comerciales y personales.

---

👨‍💻 Acerca de

CASMapper es desarrollado por Central American System (CAS), una empresa guatemalteca de desarrollo de software enfocada en soluciones empresariales de alto rendimiento.

Desarrollador: José Alonso
Título: Ingeniero en Sistemas, CEO de CEAMSYS (Central American System)
Ubicación: Guatemala

---

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor, siéntete libre de enviar un Pull Request.

---

📧 Soporte

Para problemas, preguntas o contribuciones, por favor visita nuestro repositorio de GitHub.

---

🎯 Funcionalidades Principales

CASMapper ofrece tres funciones principales:

1. Mapeo de Entidades con Nombres Iguales (Uno a Uno)

   • Mapea automáticamente propiedades con el mismo nombre y tipo
   • Soporte completo para tipos anulables y conversiones implícitas

2. Mapeo de Listas o Colecciones de Datos

   • Mapea eficientemente colecciones de entidades
   • Soporte para colecciones anidadas recursivas
   • Pre-asignación de memoria para mejor rendimiento

3. Mapeo de Objetos y Listas con Nombres Diferentes

   • Usa un diccionario de referencia para mapear propiedades con nombres diferentes
   • Los mapeos personalizados se propagan recursivamente a colecciones anidadas
   • Flexible y fácil de usar

---

💡 Ejemplos Adicionales

Ejemplo Completo: Sistema de Usuarios

using CASMapper;

// Modelo de dominio
public class Usuario
{
    public int UsuarioId { get; set; }
    public string NombreCompleto { get; set; }
    public string CorreoElectronico { get; set; }
    public DateTime FechaRegistro { get; set; }
    public List<Direccion> Direcciones { get; set; }
}

public class Direccion
{
    public string Calle { get; set; }
    public string Ciudad { get; set; }
}

// DTOs
public class UsuarioDto
{
    public int Id { get; set; }
    public string Nombre { get; set; }
    public string Email { get; set; }
    public DateTime Registro { get; set; }
    public List<DireccionDto> Direcciones { get; set; }
}

public class DireccionDto
{
    public string Calle { get; set; }
    public string Ciudad { get; set; }
}

// Mapeo personalizado
var mapeos = new Dictionary<string, string>
{
    { "UsuarioId", "Id" },
    { "NombreCompleto", "Nombre" },
    { "CorreoElectronico", "Email" },
    { "FechaRegistro", "Registro" }
};

var usuario = new Usuario
{
    UsuarioId = 1,
    NombreCompleto = "Juan Pérez",
    CorreoElectronico = "juan@ejemplo.com",
    FechaRegistro = DateTime.Now,
    Direcciones = new List<Direccion>
    {
        new Direccion { Calle = "Calle 1", Ciudad = "Ciudad de Guatemala" }
    }
};

// Mapeo con mapeos personalizados
var usuarioDto = ObjectMapper.Map<Usuario, UsuarioDto>(usuario, null, mapeos);
// Las direcciones anidadas se mapean automáticamente

---

Desarrollado con ❤️ en Guatemala por Central American System