MapOnly 1.0.0

Welcome to MapOnly Documentation

Introduction

MapOnly is a simple and lightweight .NET library for object-to-object mapping. If you need a straightforward library focused solely on mapping without extra complexity, MapOnly is the perfect choice for you.

Requirements

• .NET Standard 2.0+
• .NET Standard 2.1+
• .NET 6.0+
• .NET 8.0+
• .NET Framework 4.6.1+

Installation

# Using .NET CLI
dotnet add package MapOnly

# Using Package Manager Console
Install-Package MapOnly

# Or search "MapOnly" in NuGet Package Manager

Features

• ✨ Simple and intuitive API
• 🚀 Lightweight with minimal dependencies
• 🎯 Automatic property mapping by name
• 🔧 Custom property mappings
• 🚫 Property ignore functionality
• 💎 Support for constant values
• 🏷️ Attribute-based configuration
• ✅ Fully tested and documented

Quick Start

Basic Usage (No Configuration Required)

For simple object mapping where properties have the same names:

using MapOnly;

// Map using the new instance creation overload (recommended)
var userDto = user.Map<User, UserDto>();

// Or if you need to map to an existing instance
var existingDto = new UserDto();
user.Map(existingDto);

With Configuration

For custom mappings, configure once at application startup:

// At application startup
MapExtension.Create<User, UserDto>()
    .Add(u => u.FullName, dto => dto.DisplayName)
    .Ignore(dto => dto.InternalField);

// Then use throughout your application
var userDto = user.Map<User, UserDto>();

Methods

1. Create

This method creates a mapping configuration between two classes. If the classes have the same property names, automatic mapping will work without configuration.

Syntax

using MapOnly;

MapExtension.Create<SourceClass, DestinationClass>()

Example

MapExtension.Create<UserViewModel, User>()

2. Add

For properties with different names or when you need to set constant values, use the Add method.

Syntax

using MapOnly;

// Map properties with different names
MapExtension.Create<SourceClass, DestinationClass>()
    .Add(source => source.Property1, dest => dest.Property2);

// Set a constant value
MapExtension.Create<SourceClass, DestinationClass>()
    .Add(dest => dest.Property1, "ConstantValue");

Example

MapExtension.Create<UserViewModel, User>()
    .Add(v => v.DisplayName, u => u.FullName)
    .Add(u => u.CreatedBy, "Admin");

3. Ignore

Use this method to exclude properties from mapping.

Syntax

using MapOnly;

MapExtension.Create<SourceClass, DestinationClass>()
    .Ignore(dest => dest.Property1);

Example

MapExtension.Create<UserViewModel, User>()
    .Add(x => x.Birthday, a => a.UpdatedDate)
    .Ignore(u => u.CreatedDate)
    .Ignore(u => u.CreatedUser)
    .Ignore(u => u.IsActive)
    .Ignore(u => u.UpdatedDate)
    .Ignore(u => u.UpdatedUser);

4. Map

Converts one object to another following configured or automatic mappings.

Syntax

// Recommended: Automatically create destination instance
var destination = source.Map<SourceClass, DestinationClass>();

// Alternative: Map to existing instance (useful when updating objects)
var destination = new DestinationClass();
source.Map(destination);

Example

// Simple mapping - automatically creates UserViewModel instance
var viewModel = user.Map<User, UserViewModel>();

// Map collections
var userViewModels = users
    .Select(u => u.Map<User, UserViewModel>())
    .ToList();

// Map to existing instance (e.g., updating an entity)
var existingUser = GetUserFromDatabase(id);
userViewModel.Map(existingUser);
SaveChanges();

Advanced: Attribute-Based Mapping

You can also use attributes to control mapping behavior:

public class MyClass
{
    public int Id { get; set; }
    
    [MapAttribute(Ignored = true)]
    public string InternalProperty { get; set; }
}

Configuration

Configure your mappings once at application startup. MapOnly uses a static configuration that persists throughout your application's lifetime.

ASP.NET Core / Modern .NET

Program.cs or Startup.cs:

// Program.cs (.NET 6+)
var builder = WebApplication.CreateBuilder(args);

// Configure MapOnly mappings
ConfigureMappings();

var app = builder.Build();
app.Run();

static void ConfigureMappings()
{
    MapExtension.Create<User, UserDto>()
        .Add(u => u.FullName, dto => dto.DisplayName)
        .Ignore(dto => dto.CreatedDate);

    MapExtension.Create<Product, ProductDto>()
        .Ignore(dto => dto.InternalId);
}

Or create a dedicated configuration class:

// MappingConfiguration.cs
public static class MappingConfiguration
{
    public static void Configure()
    {
        ConfigureUserMappings();
        ConfigureProductMappings();
    }

    private static void ConfigureUserMappings()
    {
        MapExtension.Create<User, UserDto>()
            .Add(u => u.FullName, dto => dto.DisplayName)
            .Ignore(dto => dto.CreatedDate);
    }

    private static void ConfigureProductMappings()
    {
        MapExtension.Create<Product, ProductDto>()
            .Ignore(dto => dto.InternalId);
    }
}

// Program.cs
MappingConfiguration.Configure();

ASP.NET MVC / Web API (.NET Framework)

Global.asax.cs:

protected void Application_Start()
{
    // Other configurations...
    AreaRegistration.RegisterAllAreas();
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    
    // Configure MapOnly
    MappingConfiguration.Configure();
}

Console / Desktop Applications

Program.cs:

static class Program
{
    [STAThread]
    static void Main()
    {
        // Configure mappings at startup
        MappingConfiguration.Configure();

        // Rest of your application
        Application.EnableVisualStyles();
        Application.SetCompatibleTextRenderingDefault(false);
        Application.Run(new MainForm());
    }
}

Best Practices

1. Configure Once, Use Everywhere: Set up all mappings at application startup
2. Organize by Domain: Group related mappings together in separate methods
3. Keep It Simple: Only configure mappings for properties that differ between source and destination
4. Use the Automatic Creation Overload: Prefer source.Map<TSource, TDest>() over source.Map(new TDest())

// ✅ Recommended
var dto = user.Map<User, UserDto>();

// ❌ Less efficient (creates instance before calling Map)
var dto = user.Map(new UserDto());

// ✅ Good - when you need to update an existing instance
var existingEntity = repository.Get(id);
dto.Map(existingEntity);
repository.Update(existingEntity);

Change Log

Version 0.3.0 (Latest)

• 🎯 Multi-target support: .NET Standard 2.0/2.1, .NET 6.0/8.0
• ✨ Nullable reference types enabled
• 🐛 Bug fixes: Better null handling, skip missing properties
• 📚 Improved documentation and error messages
• ✅ Comprehensive unit test coverage
• 🔒 Security improvements

Version 0.2.1

• Initial stable release

License

MIT License - See LICENSE.txt for details

Contributing

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