Key Mapping

Key Mapping and the IKeyMapper Interface

EntityAxis introduces IKeyMapper<TAppKey, TDbKey> to support scenarios where your domain entity identifier (e.g., string) differs from your database key type (e.g., Guid, int).

🔍 Why Key Mapping Exists

While many applications use matching key types between the domain and persistence layers, decoupling these keys provides important flexibility and long-term maintainability.

Some examples of why this is valuable:

• Your application layer can use flexible string-based identifiers (e.g., "ORD-1024"), which are easy to work with across APIs, logs, and UI.
• Your database layer can optimize for performance using efficient key types like Guid or int without leaking those concerns into your domain model.
• You can evolve your database schema independently of your application, or even support multiple backing stores (e.g., a read database with int keys and a write database with Guids).
• You can enforce business-specific ID formats in your application without impacting database key constraints.

In short: using key mapping gives you the best of both worlds — performance and stability in your infrastructure, and flexibility and clarity in your application code.

🛠️ Built-in Implementations

EntityAxis provides several built-in mappers:

• IdentityKeyMapper<T> – no conversion; used when both keys are the same
• StringToGuidKeyMapper – converts between string and Guid
• StringToIntKeyMapper – converts between string and int

You can register one globally, or per-entity as needed.

services.AddSingleton<IKeyMapper<Guid, Guid>, IdentityKeyMapper<Guid>>();