Identity Management & Patch Mode

AutoMappic v0.5.0 enhances Identity Management -- an opt-in feature that transforms the mapper from a simple property copier into an entity-aware graph engine compatible with EF Core change trackers.

Enabling Identity Management

Add the MSBuild property to your .csproj:

<PropertyGroup>
  <AutoMappic_EnableIdentityManagement>true</AutoMappic_EnableIdentityManagement>
</PropertyGroup>

When active, the source generator will:

1. Track object instances via a MappingContext to prevent cyclic recursion.
2. Infer primary keys (Id, ClassNameId, [Key]) on destination types automatically.
3. Generate conditional assignments for nullable source properties (Patch Mode).
4. Emit key-based collection Smart-Sync instead of "Clear-and-Add" (v0.5.0).
5. Support explicit keys via the [AutoMappicKey] attribute (v0.5.0).

MappingContext

All generated mapping methods accept an optional MappingContext? context parameter:

// The context tracks visited objects to prevent infinite loops
var dto = entity.MapToEntityDto(context: new MappingContext());

// Or let it default to null for simple mappings
var dto = entity.MapToEntityDto();

Patch Mode (Null-Ignore)

When identity management is active, nullable source properties generate conditional assignments:

// Generated code (simplified)
if (source.Name != null)
{
    result.Name = source.Name;
}

This makes HTTP PATCH endpoints trivial -- only non-null values trigger property setters:

public class PatchUserRequest
{
    public string? Name { get; set; }
    public string? Email { get; set; }
}

public class User
{
    public string Name { get; set; } = "";
    public string Email { get; set; } = "";
}

// Only provided fields are updated
mapper.Map(patchRequest, existingUser);

Collection Syncing (Diffing)

With identity management active, collections use key-based matching:

public class Order
{
    public List<OrderItem> Items { get; set; } = new();
}

public class OrderItem
{
    public int Id { get; set; }  // Auto-detected as key
    public string Name { get; set; } = "";
}

The generated in-place mapping will:

• Match source and destination items by Id.
• Update existing items in-place (preserving EF Core change tracking).
• Add new items that exist in source but not in destination.

🆕 Smart-Sync (v0.5.0)

In v0.5.0, you can opt-in to advanced Smart-Sync by adding <AutoMappic_EnableEntitySync>true</AutoMappic_EnableEntitySync> to your project file. This enables:

• Key Overrides: Use [AutoMappicKey] when your DTO properties don't match the entity's key name.
• Ambiguity Detection: AM0017 warns you if a type has multiple potential keys (e.g., Id and UserId) and you haven't specified which one to use.
• Unmapped Key Alerts: AM0014 warns you if a destination type has a key but the source mapping doesn't provide a way to resolve it.

AM0013 Diagnostic

When using Patch Mode, AutoMappic warns you about dangerous patterns:

// WARNING AM0013: Patching into required 'Name' from nullable source
public class Dest { public required string Name { get; set; } }
public class Source { public string? Name { get; set; } }

See the Diagnostic Suite for remediation options.

Performance

All identity management features are:

• Opt-in: Standard mapping remains zero-overhead for existing users.
• AOT-compatible: Generated as static, type-safe C# code.
• Zero-reflection: No runtime reflection or heavy DI required.