### Mapper Cloning Example

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Cloning-Mappers.md

Demonstrates cloning a base mapper and applying specific configurations for UK and US orders.

```APIDOC
## Mapper Cloning and Derived Mappers

### Description
This example illustrates how to clone a base mapper configuration to create specialized mappers for different regions (UK and US). The derived mappers inherit the base configuration and add their own specific mappings.

### Method
N/A (This is a code example, not an API endpoint)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Code Example (C#)

```cs
// Create a base mapper
var baseMapper = Mapper.CreateNew();

// Setup the base configuration for Order to OrderDto
baseMapper.WhenMapping
    .From<Order>()
    .To<OrderDto>()
    .Map((o, dto) => o.ProdId)
    .To(dto => dto.ProductId)
    .And
    .Map((o, dto) => o.Id)
    .To(dto => dto.OrderNumber);

// Clone a new mapper for UK orders
var ukOrderMapper = baseMapper.CloneSelf();

// Setup UK-specific configuration: add a specific DateCreated mapping
ukOrderMapper.WhenMapping
    .To<OrderDto>()
    .Map(ctx => DateTime.UtcNow.AddHours(1))
    .To(dto => dto.DateCreated);

// Clone a new mapper for US orders
var usOrderMapper = baseMapper.CloneSelf();

// Setup US-specific configuration: add a specific DateCreated mapping
usOrderMapper.WhenMapping
    .To<OrderDto>()
    .Map(ctx => DateTime.UtcNow.AddHours(-4))
    .To(dto => dto.DateCreated);
```
```

--------------------------------

### Install AgileMapper via NuGet

Source: https://context7.com/agileobjects/agilemapper/llms.txt

Command to install the AgileMapper package using the NuGet Package Manager console.

```bash
PM> Install-Package AgileObjects.AgileMapper
```

--------------------------------

### Configure Custom Object Construction

Source: https://context7.com/agileobjects/agilemapper/llms.txt

Provides examples of defining custom factories for object creation. This includes global configurations, type-pair specific factories, and conditional logic during the mapping process.

```csharp
Mapper.WhenMapping.InstancesOf<Customer>().CreateUsing(ctx => new Customer { Number = ctx.EnumerableIndex });

Mapper.WhenMapping.From<PersonViewModel>().To<Customer>().CreateInstancesUsing((pvm, c, index) => new Customer { Number = index });

Mapper.Map(customerViewModels).ToANew<Customer[]>(cfg => cfg.WhenMapping.From<CustomerViewModel>().To<Customer>().If((cvm, c) => cvm.Discount > 0).CreateInstancesUsing((cvm, c, i) => new Customer { HasDiscount = true, Number = i }));
```

--------------------------------

### Viewing Mapping Execution Plans with AgileMapper

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/index.md

Provides examples of how to retrieve and view the execution plan for various mapping operations (creation, updates, merges, query projection) using AgileMapper. This also caches the plan.

```csharp
// For object creation:
string mappingPlan = Mapper.GetPlanFor<Customer>().ToANew<CustomerViewModel>();
// For updates:
string mappingPlan = Mapper.GetPlanFor<Customer>().Over<CustomerViewModel>();
// For merges:
string mappingPlan = Mapper.GetPlanFor<Customer>().OnTo<CustomerViewModel>();

// For all three in one call:
string mappingPlans = Mapper.GetPlansFor<Customer>().To<CustomerViewModel>();

// For query projection:
string mappingPlan = Mapper
    .GetPlanForProjecting(context.Customers)
    .To<CustomerViewModel>();

// For everything in the mapping cache:
var allPlans = Mapper.GetPlansInCache();
```

--------------------------------

### Apply Multiple Inline Mapping Rules

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Inline.md

Provides examples of chaining multiple configuration rules using the .And operator or by passing multiple configuration delegates.

```csharp
var dto = mapper
    .Map(product).ToANew<ProductDto>(cfg => cfg
        .Map((p, d) => p.Spec).To(d => d.Specification)
        .And
        .Map((p, d) => p.Price).To(d => d.Cost));

// Or if you prefer:
var dto = mapper
    .Map(product).ToANew<ProductDto>(
        cfg => cfg.Map((p, d) => p.Spec).To(d => d.Specification),
        cfg => cfg.Map((p, d) => p.Price).To(d => d.Cost));
```

--------------------------------

### Configuring Mappers and Accessing Services in MapperConfiguration

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Classes.md

Shows a detailed example of a MapperConfiguration class that retrieves a DI container, accesses services like ILogger, creates and configures mappers for Product and Order objects, and registers these mappers back into the DI container.

```csharp
public class MyMappingConfiguration : MapperConfiguration
{
    protected override void Configure()
    {
        // Get a reference to the configured container:
        var diContainer = GetServiceProvider<IUnityContainer>();

        // Get a reference to a configured ILogger - this just passes 
        // the request to the container and returns the result:
        var logger = GetService<ILogger>();

        // Create a new mapper for Product mapping:
        var productMapper = CreateNewMapper();

        // Configure productMapper Product -> ProductDto mapping:
        productMapper.WhenMapping
            .From<ProductDto>()
            .To<Product>()
            .Map((dto, p) => dto.Spec)
            .To(p => p.Specification);

        // Cache all Product -> ProductDto mapping plans:
        productMapper.GetPlansFor<Product>().To<ProductDto>();

        // Create a new mapper for Order mapping:
        var orderMapper = CreateNewMapper();

        // Configure orderMapper Order -> OrderDto create new mapping:
        orderMapper.WhenMapping
            .From<Order>()
            .ToANew<OrderDto>()
            .Map((o, dto) => o.Items.Sum(i => i.Cost))
            .To(dto => dto.TotalCost);

        // Cache the Order -> OrderDto create new mapping plan:
        orderMapper.GetPlanFor<Order>().ToANew<OrderDto>();

        // Register named IMapper instances with the container:
        diContainer.RegisterInstance("ProductMapper", productMapper);
        diContainer.RegisterInstance("OrderMapper", orderMapper);

        logger.LogDebug("Product and Order mapping configured and registered");
    }
}
```

--------------------------------

### Switching Data Source in Agile Mapper

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Member-Values.md

Shows how to redirect a mapping to use a different data source value. The example demonstrates mapping a dictionary's values to a list of DTOs, using `ToTargetInstead()` to replace the default mapping behavior.

```csharp
class VideoLibrary {
    public Dictionary<int, Video> VideosById { get; set; }
}

class VideoLibraryDto {
    public IList<VideoDto> Videos { get; set; }
}

Mapper.WhenMapping
    .FromDictionariesWithValueType<Video>()
    .To<IList<VideoDto>>()
    .Map((d, l) => d.Values)
    .ToTargetInstead();
```

--------------------------------

### Global Object Tracking Settings

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/Mapped-Object-Tracking.md

Provides examples of setting global configurations for object tracking. This includes disabling object tracking for all mappings and enabling identity integrity globally.

```csharp
// Never track objects - when your object *types* contain circular references, 
// but you're sure your *instances* of those types never do:
Mapper.WhenMapping.DisableObjectTracking();

// Always maintain identity integrity:
Mapper.WhenMapping.MaintainIdentityIntegrity();
```

--------------------------------

### Access Services During Configuration

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Dependency-Injection.md

Illustrates how to resolve services directly within a custom MapperConfiguration class. This is useful for setup logic that requires external dependencies.

```csharp
public class MyMappingConfiguration : MapperConfiguration
{
    protected override void Configure()
    {
        var provider = GetServiceProvider<IServiceProvider>();
        var logger = GetService<ILogger>();
        logger.LogDebug("Configuration complete");
    }
}
```

--------------------------------

### Test Mapper Configuration with StubServiceProvider

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Dependency-Injection.md

Provides an example of using the StubServiceProvider for unit testing mapping configurations. It allows injecting mock objects to verify that configurations are applied correctly.

```csharp
using AgileObjects.AgileMapper.Testing;
var logger = new Mock<ILogger>().Object;
var stubServiceProvider = new StubServiceProvider(logger);
Mapper.WhenMapping
    .UseServiceProvider(stubServiceProvider)
    .UseConfigurations.From<MyMapperConfiguration>();
```

--------------------------------

### Execute Code Before Mapping Begins (C#)

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Mapping-Callbacks.md

Configures custom C# code to run just before the mapping process for a specified type starts. This is useful for logging or setting up initial states. It takes a context object providing access to the target object.

```csharp
mapper.WhenMapping
    .To<Customer>() // Apply to Customer creation, updates and merges
    .Before
    .MappingBegins
    .Call(ctx => Console.WriteLine(
        "Mapping customer " + ctx.Target.CustomerId));
```

--------------------------------

### Define Customer and ViewModel Classes for Mapping

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/Member-Matching.md

This snippet defines a Customer domain model and a corresponding CustomerViewModel. It demonstrates how AgileMapper handles property matching, Guid parsing, nested object initialization, and method exclusion based on type compatibility.

```csharp
public class CustomerViewModel
{
    public string Name { get; set; }
    public string Id { get; set; }
    public string HomeAddressLine1 { get; set; }
    public string WorkAddressLine1 { get; set; }
    public byte[] Data { get; set; }
}

public class Customer
{
    public string Name;
    public Guid CustomerId { get; set; }
    public Address HomeAddress { get; set; }
    public Address WorkAddress { get; }
    public void SetData(DateTime value) {}
}

public class Address
{
    public string Line1 { get; set; }
}
```

--------------------------------

### Defining Entity Models for AgileMapper

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/Entity-Mapping.md

This example demonstrates the structure of DTO and Entity classes where the Entity contains a KeyAttribute and a related entity reference. It illustrates how AgileMapper differentiates between key members and standard numeric ID fields during mapping.

```csharp
class CategoryDto
{
    public int? Id { get; set; }
    public int? ParentId { get; set; }
    public int? TopProductId { get; set; }
}

class Category
{
    [Key]
    public int? Id { get; set; }

    public int? ParentId { get; set; }

    public Category Parent { get; set; }

    public int? TopProductId { get; set; }
}
```

--------------------------------

### Define Meta Member Source and Target Types

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/Meta-Members.md

Example classes demonstrating how AgileMapper maps meta members like HasOrders, DeliveryAddressCount, and FirstDeliveryAddressHasPostcode from a source Account object to an AccountDto.

```csharp
class Account
{
    public int Id { get; set; }
    public ICollection<Order> Orders { get; set; }
    public ICollection<Address> DeliveryAddresses { get; set; }
}

class AccountDto
{
    public int Id { get; set; }
    public bool HasOrders { get; set; }
    public int DeliveryAddressCount { get; set; }
    public bool FirstDeliveryAddressHasPostcode { get; set; }
}
```

--------------------------------

### Update Collections with AgileMapper

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/Performing-Updates.md

This example shows how to update a collection of objects using AgileMapper. Objects are matched by their identifiers (configurable), and the method handles updating existing items, adding new ones, and removing items not present in the source. The original collection instance is preserved.

```csharp
var source = new[]
{
    new CustomerViewModel { Id = 1,    Name = "Rod" },
    new CustomerViewModel { Id = 2,    Name = "Jane" },
    new CustomerViewModel { Id = null, Name = "Freddy" }
};
var target = Collection<Customer>
{
    new Customer { CustomerId = 2, Name = null },
    new Customer { CustomerId = 1, Name = "Bungle" },
    new Customer { CustomerId = 3, Name = "Zippy" }
};
var result = Mapper.Map(source).Over(target);
```

--------------------------------

### Combine Global and Inline Mapping Configurations

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Inline.md

Illustrates how to define base configurations in startup code and supplement them with specific inline configurations during mapping.

```csharp
// Configuration in app startup code:
mapper.WhenMapping
    .From<Product>().To<ProductDto>()
    .Map((p, d) => p.Spec).To(d => d.Specification);

// Configuration at the point the mapping is performed:
var dto = mapper
    .Map(product).ToANew<ProductDto>(cfg => cfg
        .Map((p, d) => p.Price).To(d => d.Cost));
```

--------------------------------

### Configure and Map using AgileMapper Instance API (C#)

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/Static-vs-Instance-Mappers.md

Shows how to create a new mapper instance using `Mapper.CreateNew()`, configure it with `WhenMapping`, and perform mapping operations. This approach is suitable for dependency injection.

```csharp
var mapper = Mapper.CreateNew();
mapper.WhenMapping
    .From<Order>()
    .To<OrderDto>()
    .Map(ctx => ctx.Source.OrderNumber)
    .To(dto => dto.OrderNo);

var orderDto = mapper.Map(order).ToANew<OrderDto>();
```

--------------------------------

### Configure and Map using AgileMapper Static API (C#)

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/Static-vs-Instance-Mappers.md

Demonstrates how to configure mapping rules using the static `Mapper.WhenMapping` and perform mapping operations with `Mapper.Map`. Includes resetting the default instance.

```csharp
Mapper.WhenMapping
    .From<Order>()
    .To<OrderDto>()
    .Map(ctx => ctx.Source.OrderNumber)
    .To(dto => dto.OrderNo);

var orderDto = Mapper.Map(order).ToANew<OrderDto>();

Mapper.ResetDefaultInstance();
```

--------------------------------

### Configure Instance Mapper for Product Projection (C#)

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/query-projection/Configuration.md

Illustrates configuring an instance mapper for query projections. It shows how to define a mapping from Product.Spec to ProductDto.Specification and conditionally map Product.Cost to ProductDto.Price using .ProjectUsing() with an EF Core DbContext.

```csharp
mapper.WhenMapping
    .From<Product>()           // Apply to Product mappings
    .ProjectedTo<ProductDto>() // Apply to all ProductDto projections
    .Map(p => p.Spec)          // Map Product.Spec
    .To(p => p.Specification);

// Using an EF Core DbContext;
// Product.Spec will be projected to ProductDto.Specification, and 
// Product.Cost will be projected to ProductDto.Price conditionally:
var productDtos = await context
    .Products
    .ProjectUsing(mapper).To<ProductDto>(cfg => cfg
        .If(p => p.Cost > 0)
        .Map(p => p.Cost)
        .To(dto => dto.Price)
        .But
        .If(p => p.Cost == 0)
        .Map(p => p.Price)
        .To(dto => dto.Price))
    .ToArrayAsync();
```

--------------------------------

### Ignoring Null or Empty Strings for Specific Type

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Ignoring-Source-Values.md

This example shows how to configure the mapper to ignore null or empty string values when updating an `Order` object from an `OrderDto`.

```APIDOC
## POST /agileobjects/agilemapper/ignore-empty-strings

### Description
Configures the mapper to ignore null or empty source strings when updating a specific target type.

### Method
POST

### Endpoint
/agileobjects/agilemapper/ignore-empty-strings

### Parameters
#### Request Body
- **SourceType** (string) - Required - The type of the source object (e.g., "OrderDto").
- **TargetType** (string) - Required - The type of the target object (e.g., "Order").
- **Condition** (string) - Required - The condition to ignore source values (e.g., "string.IsNullOrEmpty").

### Request Example
```json
{
  "SourceType": "OrderDto",
  "TargetType": "Order",
  "Condition": "string.IsNullOrEmpty"
}
```

### Response
#### Success Response (200)
- **Message** (string) - Confirmation message.

#### Response Example
```json
{
  "Message": "Mapping condition configured successfully."
}
```
```

--------------------------------

### Manage Static and Instance Mapper APIs

Source: https://context7.com/agileobjects/agilemapper/llms.txt

Demonstrates the use of the static Mapper API for simple scenarios versus the instance API for dependency injection and isolated configurations.

```csharp
// Static API usage
Mapper.WhenMapping
    .From<Order>()
    .To<OrderDto>()
    .Map(ctx => ctx.Source.OrderNumber)
    .To(dto => dto.OrderNo);

var orderDto = Mapper.Map(order).ToANew<OrderDto>();

// Reset static mapper (useful for testing)
Mapper.ResetDefaultInstance();

// Instance API usage
var mapper = Mapper.CreateNew();
mapper.WhenMapping
    .From<Order>()
    .To<OrderDto>()
    .Map(ctx => ctx.Source.OrderNumber)
    .To(dto => dto.OrderNo);

var orderDto = mapper.Map(order).ToANew<OrderDto>();

// Dependency injection with StructureMap
public class OrderMapperRegistry : Registry
{
    public OrderMapperRegistry()
    {
        var mapperOne = Mapper.CreateNew();
        For<OrderOneController>().Use<OrderOneController>()
            .Ctor<IMapper>().Is(mapperOne);

        var mapperTwo = Mapper.CreateNew();
        For<OrderTwoController>().Use<OrderTwoController>()
            .Ctor<IMapper>().Is(mapperTwo);
    }
}
```

--------------------------------

### Ignore Target Members by Attribute in Agile Mapper

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Ignoring-Target-Members.md

This example demonstrates how to ignore target members that are decorated with a specific attribute, such as 'IgnoreDataMember'. This allows for attribute-based control over which members are mapped.

```csharp
Mapper.WhenMapping
    .IgnoreTargetMembersWhere(m => 
        m.HasAttribute<IgnoreDataMember>("IgnoreDataMember"))); // Global ignore

Mapper.WhenMapping
    .OnTo<MyTarget>() // Apply the ignore to MyTarget merges
    .IgnoreTargetMembersWhere(m => 
        m.HasAttribute<IgnoreDataMember>("IgnoreDataMember"))); // Ignore
```

--------------------------------

### Cache Mapping Execution Plans

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/Using-Execution-Plans.md

Demonstrates how to pre-cache mapping plans for specific type transformations. This helps avoid the overhead of generating plans during the first mapping execution.

```csharp
Mapper.GetPlanFor<PersonViewModel>().ToANew<Person>();

Mapper
    .GetPlanFor<Person>()
    .ToANew<PersonViewModel>(cfg => cfg
        .Map((p, pvm) => p.Title + " " + p.Name)
        .To(pvm => p.Name));

Mapper.GetPlansFor<PersonViewModel>().To<Person>();

Mapper.GetPlanForProjecting(context.People).To<PersonViewModel>();
```

--------------------------------

### Dependency Injection Configuration with AgileMapper Instance API (C#)

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/Static-vs-Instance-Mappers.md

Illustrates configuring multiple mapper instances with different settings and registering them for dependency injection using StructureMap. This allows for distinct mapping behaviors in different parts of an application.

```csharp
public class OrderMapperRegistry : Registry
{
    public OrderMapperRegistry()
    {
        var mapperOne = Mapper.CreateNew();
        // Do mapperOne.WhenMapping configuration...

        For<OrderOneController>().Use<OrderOneController>()
            .Ctor<IMapper>().Is(mapperOne);

        var mapperTwo = Mapper.CreateNew();
        // Do mapperTwo.WhenMapping configuration...

        For<OrderTwoController>().Use<OrderTwoController>()
            .Ctor<IMapper>().Is(mapperTwo);
    }
}
```

--------------------------------

### Ignore Target Members by Member Type in Agile Mapper

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Ignoring-Target-Members.md

This example demonstrates ignoring target members based on their kind, such as fields or properties. It shows global ignores and specific configurations for target creations, updates, and merges.

```csharp
Mapper.WhenMapping
    .IgnoreTargetMembersWhere(m => m.IsSetMethod); // Global ignore

Mapper.WhenMapping
    .ToANew<MyTarget>() // Apply the ignore to MyTarget creations
    .IgnoreTargetMembersWhere(m => m.IsField); // Ignore all fields

Mapper.WhenMapping
    .From<MySource>() // Apply when mapping from MySource (optional)
    .Over<MyTarget>() // Apply the ignore to MyTarget updates
    .IgnoreTargetMembersWhere(m => m.IsProperty); // Ignore all properties
```

--------------------------------

### Project IQueryable to DTO using Instance Mapper

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/query-projection/index.md

Shows how to project query results using an instance-scoped mapper. This is useful when you need to manage mapper lifecycles or configurations explicitly.

```csharp
var orderDtos = await context
    .Orders
    .ProjectUsing(mapper).To<OrderDto>()
    .ToListAsync();
```

--------------------------------

### Registering DI Container with Agile Mapper

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Classes.md

Demonstrates how to obtain a Dependency Injection container and register it with Agile Mapper. This allows MapperConfiguration classes to access registered services.

```csharp
var diContainer = GetDiContainer();
Mapper.WhenMapping.UseServiceProvider(diContainer);
```

--------------------------------

### Auto-Reversing Mapped Data Sources - C#

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Member-Values.md

Configures mappings to apply in both directions (source to target and target to source). This simplifies bidirectional mapping setup. It can be applied globally, per type pair, or per specific member mapping.

```csharp
Mapper.WhenMapping.AutoReverseConfiguredDataSources();
```

```csharp
Mapper.WhenMapping
    .From<Product>().To<ProductDto>()
    .AutoReverseConfiguredDataSources();
```

```csharp
Mapper.WhenMapping
    .From<Product>().To<ProductDto>()
    .Map(p => p.Specification, dto => dtp.Spec)
    .AndViceVersa();
```

--------------------------------

### Performing Basic Mappings with Extension Methods

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/Mapping-Extension-Methods.md

Demonstrates how to use AgileMapper extension methods to map to new objects, deep clone, update, or merge existing objects. Requires the AgileObjects.AgileMapper.Extensions namespace.

```csharp
using AgileObjects.AgileMapper.Extensions;

var customerViewModel = customer.Map().ToANew<CustomerViewModel>();
var clonedCustomer = customerToBeCloned.DeepClone();
customerSaveRequest.Map().Over(customer);
customerDto.Map().OnTo(customer);
```

--------------------------------

### Ignore Source Members by Member Type (C#)

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Ignoring-Source-Members.md

Provides examples of ignoring source members based on their type (e.g., GetMethod, Field, Property) globally or for specific mapping configurations. This allows fine-grained control over which kinds of members are mapped.

```csharp
Mapper.WhenMapping
    .IgnoreSourceMembersWhere(m => m.IsGetMethod); // Global ignore

Mapper.WhenMapping
    .ToANew<MyTarget>() // Apply the ignore to MyTarget creations
    .IgnoreSourceMembersWhere(m => m.IsField); // Ignore all fields

Mapper.WhenMapping
    .From<MySource>() // Apply when mapping from MySource (optional)
    .Over<MyTarget>() // Apply the ignore to MyTarget updates
    .IgnoreSourceMembersWhere(m => m.IsProperty); // Ignore all properties
```

--------------------------------

### Object Creation Mapping with AgileMapper

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/index.md

Demonstrates how to create a new object from an existing one using AgileMapper. This can be done via the static Mapper class or extension methods.

```csharp
var customer = Mapper.Map(customerViewModel).ToANew<Customer>();
// Or:
var customer = customerViewModel.Map().ToANew<Customer>();
```

--------------------------------

### Ignore Target Members by MemberInfo Matcher in Agile Mapper

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Ignoring-Target-Members.md

This example demonstrates ignoring target members using MemberInfo matchers, allowing for fine-grained control based on properties of the member itself, such as whether it's a field or property and its specific characteristics.

```csharp
Mapper.WhenMapping
    .IgnoreTargetMembersWhere(m => 
        m.IsFieldMatching(f => f.IsAssembly)); // Global ignore

Mapper.WhenMapping
    .Over<MyTarget>() // Apply the ignore to MyTarget updates
    .IgnoreTargetMembersWhere(m => 
        m.IsPropertyMatching(p => p.IsAssembly)); // Ignore
```

--------------------------------

### C# Derived Type Mapping Example

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/Derived-Types.md

Demonstrates automatic mapping of derived types in C# using AgileMapper. It shows how a 'Customer' object, mapped as a 'Person', is correctly transformed into a 'CustomerViewModel'. This relies on the [Type] -> [TypeViewModel] naming convention for auto-discovery.

```csharp
public class Person {}
public class Customer : Person
{
    public float Discount { get; set; }
}

public class PersonViewModel {}
public class CustomerViewModel : PersonViewModel
{
    public double Discount { get; set; }
}

var person = new Customer { Discount = 0.1f } as Person;
var viewModel = Mapper.Map(person).ToANew<PersonViewModel>();
// viewModel is of type CustomerViewModel
// viewModel.Discount is 0.1
```

--------------------------------

### Instance API Query Projection

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/query-projection/Configuration.md

Demonstrates how to use an instance-based mapper to project data with specific configurations merged at runtime.

```APIDOC
## POST /query-projection/instance

### Description
Uses an instance mapper to project data, allowing for inline configuration merging and conditional mapping logic.

### Method
POST

### Endpoint
/query-projection/instance

### Parameters
#### Request Body
- **MapperInstance** (Object) - Required - The configured mapper instance.
- **Configuration** (Object) - Optional - Inline configuration rules.

### Request Example
{
  "Mapper": "instance",
  "Rules": {
    "If": "p => p.Cost > 0",
    "Map": "p => p.Cost",
    "To": "dto => dto.Price"
  }
}

### Response
#### Success Response (200)
- **Result** (Array) - The projected collection of DTOs.
```

--------------------------------

### Mapping Entities with AgileMapper

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Entity-Mapping.md

Demonstrates standard mapping of a DTO to an existing entity and creating a new entity from a DTO. Shows how to handle entity updates and deletions using Entity Framework.

```csharp
// Retrieve the existing Customer entity:
var customer = await dbContext
    .Customers
    .FirstOrDefaultAsync(c => c.Id == customerDto.Id);

// Update the Customer from the DTO - this does not map Customer.Id:
Mapper.Map(customerDto).Over(customer);

// Save the changes:
await dbContext.SaveChangesAsync();

// Create a dummy Customer entity from the DTO:
var customerToDelete = Mapper.Map(customerDto).ToANew<Customer>();

// Attach then remove the Customer from the context:
dbContext.Customers.Attach(customer);
dbContext.Customers.Remove(customer);
await dbContext.SaveChangesAsync();
```

--------------------------------

### Apply Inline Mapping Configuration in C#

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Inline.md

Demonstrates how to provide inline mapping rules using a configuration lambda expression during the mapping process.

```csharp
var dto = mapper
    .Map(product).ToANew<ProductDto>(cfg => cfg
        .Map((p, d) => p.Spec).To(d => d.Specification));
```

--------------------------------

### Inline Configuration to Ignore Target Members Conditionally

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Ignoring-Target-Members.md

This example shows how to use an inline configuration to ignore multiple target members based on a condition. The 'Id' and 'DateCreated' members of the target object are ignored only if the source object's 'Id' is 0.

```csharp
// Source, target and mapping types are implicit from the mapping:
Mapper.Map(orderDto).Over(order, cfg => cfg
    .If((dto, o) => dto.Id == 0) // Apply the ignores if OrderDto.Id is 0
    .Ignore(
        o => o.Id,               // Ignore Order.Id...
        o => o.DateCreated));     // ...and Order.DateCreated
```

--------------------------------

### Configure Static Mapper for Product Projection (C#)

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/query-projection/Configuration.md

Demonstrates configuring the default static mapper to apply a custom mapping from Product.Spec to ProductDto.Specification for query projections. This configuration is automatically applied when using the .Project() extension method with an EF Core DbContext.

```csharp
Mapper.WhenMapping
    .From<Product>()           // Apply to Product mappings
    .To<ProductDto>()          // Apply to all ProductDto mappings
    .Map((p, dto) => p.Spec)   // Map Product.Spec
    .To(p => p.Specification);

// Using an EF Core DbContext;
// Product.Spec will be projected to ProductDto.Specification:
var productDtos = await context
    .Products
    .Project().To<ProductDto>()
    .ToArrayAsync();
```

--------------------------------

### Configure Service Provider in AgileMapper

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Dependency-Injection.md

Demonstrates how to register a service provider using a Func delegate or a duck-typed object. This configuration makes services available throughout the mapping lifecycle.

```csharp
Mapper.WhenMapping.UseServiceProvider(serviceType => CreateService(serviceType));
Mapper.WhenMapping.UseServiceProvider((serviceType, name) => CreateService(serviceType, name));
Mapper.WhenMapping.UseServiceProvider(myDuckTypedProvider);
```

--------------------------------

### Conditional Derived Type Mapping for Collections in C#

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Pairing-Derived-Types.md

Demonstrates inline conditional derived type mapping for collections in Agile Mapper. This example maps `AnimalViewModel` instances to `Dog` only if they meet a specific condition (e.g., `avm.Sound == "Woof"`).

```csharp
Mapper
    .Map(animalViewModels).ToANew<Animal[]>(cfg => cfg
        .WhenMapping
        .From<AnimalViewModel>()
        .ToANew<Animal>()
        .If((avm, a) => avm.Sound == "Woof") // If the animal woofs
        .MapTo<Dog>());                      // Create an instance of Dog
```

--------------------------------

### Cache Projection Execution Plan

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/query-projection/index.md

Illustrates how to generate and cache an execution plan for a projection. This requires an instance of the queryable to identify the IQueryProvider type.

```csharp
Mapper.GetPlanForProjecting(context.People).To<PersonDto>();
```

--------------------------------

### Manage Execution Plans in AgileMapper

Source: https://context7.com/agileobjects/agilemapper/llms.txt

Demonstrates how to retrieve, cache, and inspect execution plans for object mapping and projections. These plans can be viewed as strings or expressions to aid in debugging and performance tuning.

```csharp
// Cache execution plan for object creation
Mapper.GetPlanFor<PersonViewModel>().ToANew<Person>();

// Cache with inline configuration
Mapper
    .GetPlanFor<Person>()
    .ToANew<PersonViewModel>(cfg => cfg
        .Map((p, pvm) => p.Title + " " + p.Name)
        .To(pvm => pvm.Name));

// Cache all mapping plans (create, update, merge)
Mapper.GetPlansFor<PersonViewModel>().To<Person>();

// Cache projection plan (requires queryable instance)
Mapper.GetPlanForProjecting(context.People).To<PersonViewModel>();

// View plan as string for debugging
string plan = Mapper.GetPlanFor<PersonViewModel>().ToANew<Person>();

// View plan as Expression (use with ReadableExpressions visualizer)
Expression plan = Mapper.GetPlanFor<PersonViewModel>().ToANew<Person>();

// View all cached plans
var allPlans = Mapper.GetPlansInCache();
var allPlansExpression = Mapper.GetPlanExpressionsInCache();
```

--------------------------------

### Configure Decimal to Currency String Formatting in C#

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/To-String-Formatting.md

This example shows how to map decimal values to strings formatted as currency ('c'). The formatting is applied inline during the mapping configuration using `Mapper.Map().ToANew<T>(cfg => ...)` and `cfg.WhenMapping.StringsFrom<decimal>()`. This approach allows for specific formatting rules within a particular mapping operation.

```csharp
// Map decimals to strings as currency (inline example):
Mapper
    .Map(productDto).ToANew<Product>(cfg => cfg
        .WhenMapping
        .StringsFrom<decimal>(_ => _.UseFormat("c")));
```

--------------------------------

### Configure Dictionary Key Mapping

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Dictionary-Mapping.md

Demonstrates how to map specific dictionary keys or member name parts to target object properties when keys do not match member names directly.

```csharp
var source = new Dictionary<string, string>
{
    ["ContactName"] = "Steve",
    ["PhoneNums[0]"] = "01234 567890",
    ["PhoneNums[1]"] = "07890 654321"
};

Mapper.WhenMapping
    .FromDictionaries
    .To<ContactDetails>()
    .MapKey("ContactName")
    .To(cd => cd.Name)
    .And
    .MapMemberName("PhoneNums")
    .To(cd => cd.PhoneNumbers);
```

--------------------------------

### C# Derived Collection Mapping Example

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/Derived-Types.md

Illustrates AgileMapper's ability to map collections of derived types. It shows how an array of 'Animal' objects, containing 'Dog' and 'Cat', are mapped to an array of 'AnimalDto', with each derived type correctly mapped to its corresponding DTO (e.g., 'Dog' to 'DogDto'). This mapping is based on the convention derived from the base type mapping ('Animal' -> 'AnimalDto').

```csharp
public class Animal {}
public class Dog : Animal {}
public class Cat : Animal {}

public class AnimalDto {}
public class DogDto : AnimalDto {}
public class CatDto : AnimalDto {}

var sourceAnimal = new Dog() as Animal;
var resultAnimal = Mapper.Map(sourceAnimal).ToANew<Animal>();
// resultAnimal is of type Dog

var sourceAnimals = new Animal[] { new Cat(), new Dog() };
var resultAnimals = Mapper.Map(sourceAnimals).ToANew<AnimalDto[]>();
// resultAnimals[0] is of type CatDto
// resultAnimals[1] is of type DogDto
```

--------------------------------

### Configure Custom Member Mappings

Source: https://context7.com/agileobjects/agilemapper/llms.txt

Shows how to define custom data sources for target members, including expressions, constants, injected services, and conditional logic.

```csharp
// Map source member to different target member
Mapper.WhenMapping
    .From<ProductDto>()
    .To<Product>()
    .Map(dto => dto.Spec, p => p.Specification);

// Map expression inline
Mapper.Map(productDto).ToANew<Product>(cfg => cfg
    .Map(ctx => "$" + ctx.Source.Price)
    .To(p => p.Price));

// Map constant value
Mapper.WhenMapping
    .From<ProductDto>()
    .OnTo<Product>()
    .Map("Company ABC", p => p.CompanyName);

// Map with injected service
Mapper.WhenMapping
    .From<OrderDto>()
    .ToANew<Order>()
    .Map(ctx => ctx.GetService<IDateTimeProvider>().UtcNow)
    .To(o => o.DateCreated);

// Conditional data source
Mapper.WhenMapping
    .From<ProductDto>()
    .ToANew<Product>()
    .If((dto, p) => dto.CompanyId == 0)
    .Map("No-one")
    .To(p => p.CompanyName);

// Sequence of data sources
Mapper.WhenMapping
    .From<Customer>()
    .ToANew<CustomerViewModel>()
    .Map((c, vm) => new[] { c.HomeAddress })
        .Then.Map((c, vm) => new[] { c.WorkAddress })
        .Then.Map((c, vm) => c.AddressHistory)
    .To(vm => vm.AllAddresses);

// Auto-reverse configured mappings
Mapper.WhenMapping
    .From<Product>().To<ProductDto>()
    .Map(p => p.Specification, dto => dto.Spec)
    .AndViceVersa();
```

--------------------------------

### Order Configuration Execution

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Classes.md

Use the ApplyAfter attribute to define the execution order of multiple configuration classes to ensure dependencies are met.

```csharp
[ApplyAfter(typeof(ChildMapperConfiguration))]
public class ParentMapperConfiguration : MapperConfiguration
{
}

public class ChildMapperConfiguration : MapperConfiguration
{
}
```

--------------------------------

### View Mapping Execution Plans

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/Using-Execution-Plans.md

Shows how to retrieve mapping plans as strings or Expression objects for debugging and visualization in the debugger.

```csharp
string plan = Mapper.GetPlanFor<PersonViewModel>().ToANew<Person>();

Expression plan = Mapper.GetPlanFor<PersonViewModel>().ToANew<Person>();
```

--------------------------------

### Configuring Mappings Inline

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/Mapping-Extension-Methods.md

Explains how to apply custom configuration rules inline during the mapping process. This can be combined with both static and instance-scoped mappers.

```csharp
var customerSaveRequest = customerDto.Map().ToANew<CustomerSaveRequest>(cfg => cfg
    .Map((dto, csr) => dto.Id)
    .To(csr => csr.CustomerId));

customerSaveRequest
    .MapUsing(instanceMapper)
    .Over(customer, cfg => cfg
        .Map((csr, c) => csr.AddressSaveRequest)
        .To(c => c.Address));
```

--------------------------------

### Configure Constructor Mapping via Fluent API

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Constructor-Arguments.md

Demonstrates how to map source DTO properties to specific constructor parameters of a target class using the global Mapper configuration and inline mapping expressions.

```csharp
Mapper.WhenMapping
    .From<CustomerDto>()
    .ToANew<Customer>()
    .Map((dto, c) => dto.CustomerNum)
    .ToCtor<Guid>()
    .And
    .Map((dto, c) => dto.Name)
    .ToCtor("customerName");
```

```csharp
Mapper
    .Map(customerDto).ToANew<Customer>(cfg => cfg
        .Map((dto, c) => dto.CustomerNum)
        .ToCtor<Guid>()
        .And
        .Map((dto, c) => dto.Name)
        .ToCtor("customerName"));
```

--------------------------------

### Configuring Individual Mapping Key Behavior

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Entity-Mapping.md

Demonstrates how to enable or disable key mapping for a single, specific mapping operation using configuration callbacks.

```csharp
// Map keys for an individual mapping:
var customerToDelete = Mapper
    .Map(customerDto)
    .ToANew<Customer>(cfg => cfg.MapEntityKeys());

// Ignore keys for an individual mapping:
Mapper
    .Map(customerDto)
    .Over(customer, cfg => cfg.IgnoreEntityKeys());
```

--------------------------------

### Configure Regex Naming Patterns

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Member-Name-Patterns.md

Shows how to use regular expressions to define complex matching logic. The pattern must include a capturing group '(.+)' to identify the core property name.

```csharp
Mapper.WhenMapping
    .UseNamePattern("^_(.+)Value$");
```

--------------------------------

### Applying Mappings with Target Member Matcher in Agile Mapper

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Member-Values.md

Explains how to apply mappings to target members that meet specific criteria using a matcher. This includes matching by type, member type, member name, member path, or a custom `MemberInfo` matcher.

```csharp
// Match bool to string for members with YesNoAttribute
Mapper.WhenMapping
    .From<bool>()
    .To<string>()
    .IfTargetMemberMatches(m => m.HasAttribute<YesNoAttribute>())
    .Map((b, str) => b ? "Y" : "N")
    .ToTarget();

// Match all string members
Mapper.WhenMapping
    .To<ProductDto>()
    .IfTargetMemberMatches(m => m.HasType<string>())
    .Map("MatchedByType")
    .ToTarget();

// Match fields and properties
Mapper.WhenMapping
    .ToANew<ProductDto>()
    .IfTargetMemberMatches(m => m.IsField || m.IsProperty)
    .Map("MatchedByMatcher")
    .ToTarget();

// Match any Product members with names starting with 'Id'
Mapper.WhenMapping
    .To<Product>()
    .IfTargetMemberMatches(m => m.Name.StartsWith("Id"))
    .Map("MatchedByName")
    .ToTarget();

// Match by member path
Mapper.WhenMapping
    .To<Customer>()
    .IfTargetMemberMatches(m =>
        m.Path.StartsWith("ContactDetails.") &&
        m.Path.Contains("Address"))
    .Map("MatchedByPath")
    .ToTarget();

// Match by MemberInfo matcher
Mapper.WhenMapping
    .To<Customer>()
    .IfTargetMemberMatches(m =>
        m.IsFieldMatching(f => f.IsSpecialName))
    .Map("MatchedByFieldMatcher")
    .ToTarget();
```

--------------------------------

### Define MapperConfiguration Class

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Classes.md

Create a dedicated configuration class by inheriting from MapperConfiguration. Use the Configure method to define mapping rules and pre-cache mapping plans.

```csharp
public class ProductMappingConfiguration : MapperConfiguration
{
    protected override void Configure()
    {
        WhenMapping
            .From<ProductDto>()
            .To<Product>()
            .Map((dto, p) => dto.Spec)
            .To(p => p.Specification)
            .And
            .Ignore(p => p.Price, p => p.CatNum);

        GetPlansFor<Product>().To<ProductDto>();
    }
}
```

--------------------------------

### Configuring Global and Type-Specific Key Mapping

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Entity-Mapping.md

Shows how to enable entity key mapping globally or for specific type pairs using the Mapper configuration API.

```csharp
// Map keys by default in all mappings:
Mapper.WhenMapping.MapEntityKeys();

// Map keys by default when mapping between two particular types:
Mapper.WhenMapping
    .From<CustomerDto>()
    .ToANew<Customer>()
    .MapEntityKeys();
```

--------------------------------

### Configure Naming Prefixes and Suffixes

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Member-Name-Patterns.md

Demonstrates how to globally ignore specific prefixes or suffixes during member mapping. This is useful when source and target properties have inconsistent naming conventions.

```csharp
Mapper.WhenMapping
    .UseNamePrefixes("str", "dec");

Mapper.WhenMapping
    .UseNameSuffix("Value");
```

--------------------------------

### Apply Inline and Type-Specific Naming Patterns

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Member-Name-Patterns.md

Illustrates how to apply naming patterns locally during an inline mapping operation or scoped to specific source and target types.

```csharp
Mapper
    .Map(anonSource).ToANew<Product>(cfg => cfg
        .UseNamePattern("^_(.+)Value$"));

Mapper.WhenMapping
    .From(anonSource)
    .To<Product>()
    .UseNamePattern("^_(.+)Value$");
```

--------------------------------

### Execute Code Before Target Instance Creation (C#)

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Mapping-Callbacks.md

Allows execution of custom C# code before a new target instance is created during a mapping. This is useful for pre-populating or modifying source data before the target object is instantiated. It accepts the source and target objects as parameters.

```csharp
mapper.WhenMapping
    .From<AddressDto>() // Apply to AddressDto mappings
    .ToANew<Address>()  // Apply to Address creation
    .Before
    .CreatingTargetInstances
    .Call((dto, a) => dto.Line1 = dto.HouseNum + " " + dto.Line1);
```

--------------------------------

### Using Instance-Scoped Mappers with Extensions

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/Mapping-Extension-Methods.md

Shows how to perform mapping operations using a specific instance-scoped mapper instead of the default static mapper. This is useful for managing mapper lifecycle and configuration isolation.

```csharp
var clonedCustomer = customer.DeepCloneUsing(myInstanceScopedMapper);

customerSaveRequest
    .MapUsing(myInstanceScopedMapper)
    .Over(customer);
```

--------------------------------

### Apply Mapper Configurations

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Classes.md

Apply configuration classes explicitly, via assembly scanning, or by scanning the current AppDomain to register mapping rules.

```csharp
Mapper.WhenMapping.UseConfigurations.From<ProductMappingConfiguration>();
Mapper.WhenMapping.UseConfigurations.FromAssemblyOf<Product>();
Mapper.WhenMapping.UseConfigurations.From(assembly1, assembly2, assembly3);
Mapper.WhenMapping.UseConfigurations.FromCurrentAppDomain(assembly => assembly.FullName.Contains("MyCompanyName"));
```

--------------------------------

### Access Services During Mapping

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Dependency-Injection.md

Shows how to retrieve services from the configured provider within mapping callbacks using the mapping context. This allows for logging or other service-dependent logic during the mapping process.

```csharp
Mapper.WhenMapping.UseServiceProvider(serviceProvider);
Mapper.Before.MappingBegins
    .Call(ctx => ctx.GetService<ILogger>().Log("Mapping started"))
    .And
    .After.MappingEnds
    .Call(ctx => ctx.GetService<ILogger>("PostLogger").Log("Mapping complete"));
```

--------------------------------

### Cloning AgileMapper for Derived Configurations (C#)

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Cloning-Mappers.md

This C# code snippet illustrates the process of cloning an AgileMapper instance. It first sets up a base mapper with general mapping rules between Order and OrderDto. Then, it clones this base mapper twice to create specialized mappers for UK and US orders, each with its own specific configuration for the DateCreated field. This technique is useful for managing complex mapping scenarios where a base configuration needs to be extended or modified for different contexts.

```cs
var baseMapper = Mapper.CreateNew();

// Setup the base configuration:
baseMapper.WhenMapping
    .From<Order>()
    .To<OrderDto>()
    .Map((o, dto) => o.ProdId)
    .To(dto => dto.ProductId)
    .And
    .Map((o, dto) => o.Id)
    .To(dto => dto.OrderNumber);

// Clone a new mapper for mapping UK orders:
var ukOrderMapper = baseMapper.CloneSelf();

// Setup UK-specific configuration:
ukOrderMapper.WhenMapping
    .To<OrderDto>()
    .Map(ctx => DateTime.UtcNow.AddHours(1))
    .To(dto => dto.DateCreated);

// Clone a new mapper for mapping US orders:
var usOrderMapper = baseMapper.CloneSelf();

// Setup US-specific configuration:
usOrderMapper.WhenMapping
    .To<OrderDto>()
    .Map(ctx => DateTime.UtcNow.AddHours(-4))
    .To(dto => dto.DateCreated);
```

--------------------------------

### Static API Query Projection

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/query-projection/Configuration.md

Demonstrates how to configure global mapping rules using the static Mapper API that will be applied to EF Core projections.

```APIDOC
## POST /query-projection/static

### Description
Configures global mapping rules via the static Mapper API to be applied during IQueryable projection.

### Method
POST

### Endpoint
/query-projection/static

### Parameters
#### Request Body
- **SourceType** (Type) - Required - The source entity type.
- **TargetType** (Type) - Required - The target DTO type.
- **MappingLogic** (Expression) - Required - The custom member mapping logic.

### Request Example
{
  "Source": "Product",
  "Target": "ProductDto",
  "Map": "p => p.Spec",
  "To": "p => p.Specification"
}

### Response
#### Success Response (200)
- **Status** (string) - Configuration applied successfully.
```

--------------------------------

### Deep Cloning Objects with AgileMapper

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/index.md

Illustrates how to create a deep clone of an object using AgileMapper. This ensures that all nested objects are also copied, not just referenced.

```csharp
var clonedCustomer = Mapper.DeepClone(customerToBeCloned);
// Or:
var clonedCustomer = customerToBeCloned.DeepClone();
```

--------------------------------

### Project IQueryable to DTO using Static Mapper

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/query-projection/index.md

Demonstrates how to project an EF Core query result directly into a DTO using the default static mapper. This approach minimizes data retrieval by selecting only the required fields.

```csharp
var orderDtos = await context
    .Orders
    .Project().To<OrderDto>()
    .ToListAsync();
```

--------------------------------

### Create New Objects with ToANew

Source: https://context7.com/agileobjects/agilemapper/llms.txt

Maps a source object to a new instance of the target type. This supports basic mapping, extension methods, inline configuration, and collection mapping.

```csharp
using AgileObjects.AgileMapper;

// Basic object creation mapping
var customer = Mapper.Map(customerViewModel).ToANew<Customer>();

// Using extension methods
using AgileObjects.AgileMapper.Extensions;
var customerDto = customer.Map().ToANew<CustomerDto>();

// With inline configuration
var product = Mapper.Map(productDto).ToANew<Product>(cfg => cfg
    .Map((dto, p) => dto.Spec).To(p => p.Specification)
    .And
    .Map((dto, p) => dto.Price).To(p => p.Cost));

// Mapping collections
var customers = Mapper.Map(customerViewModels).ToANew<List<Customer>>();
```

--------------------------------

### Configure Custom Object Identification

Source: https://github.com/agileobjects/agilemapper/blob/master/docs/src/configuration/Object-Identifiers.md

Demonstrates how to define a custom property for object identification. This is useful when the default naming conventions do not apply to your domain models.

```csharp
Mapper.WhenMapping
    .InstancesOf<NamedCustomer>()
    .IdentifyUsing(c => c.Name);
```

```csharp
Mapper.Map(customerDtos).ToANew<NamedCustomer[]>(cfg => cfg
    .WhenMapping
    .InstancesOf<NamedCustomer>()
    .IdentifyUsing(c => c.Name));
```