Dapper FluentMap Is Back: What Changed from 2.0 to 3.6
After six years without a stable release, Dapper FluentMap is maintained again and version 3.6.0 adds nested mappings, property converters, isolated runtimes, analyzers and source generators. The author stresses keeping existing applications working during upgrades. The piece also covers what to check before moving from 2.0.0 and which databases are certified.
Key points
- Existing Initialize and AddMap configuration still works in 3.x, so most applications can upgrade without rewriting entities.
- For nested property mappings, use FluentMap's dedicated query APIs such as QueryMappedSingle; a plain Dapper query will not build the nested object.
- Create an isolated runtime with FluentMapConfigurationBuilder when mappings must not share global state, for example in parallel tests.
- With Dommel, prefer DatabaseDefaultOnInsert(), ReadOnly() and Computed() metadata over Ignore() when a column must not be written.
- When upgrading from 2.0.0, verify Dapper 2.1.79 or later (below 3.0.0) and Dommel 3.5.3 or later (below 4.0.0).
- Check the compatibility matrix: SQLite, SQL Server, PostgreSQL, MySQL and MariaDB are fully certified, while Oracle and Firebird lack Dommel certification.
Dapper FluentMap maps .NET properties to database columns without placing persistence attributes on domain entities. After six years without a stable release, the project is maintained again, and version 3.6.0 shipped on October 13, 2026. The main rule behind the work is compatibility: the existing Initialize and AddMap configuration keeps working while new capabilities are added on top.
The 3.x line adds nested property mapping, mapping profiles, property converters and explicit construction with ConstructUsing. Isolated FluentMapRuntime instances and a FluentMap.DependencyInjection package are available, but plain Dapper.Query<T>() calls still use Dapper's global type maps. Roslyn analyzers and source generators move some work to compile time, with a strict mode that rejects unsupported shapes instead of falling back to reflection. Dommel gained metadata for database defaults, read-only and computed columns. The author warns that generated code is not automatically faster and that Native AOT is not fully claimed.
Real-world use
- A service layer on a legacy database whose column names differ from entity properties can keep its mapping without adding attributes to domain classes.
- A team running tests in parallel with different mapping sets can use FluentMapRuntime to avoid conflicts in global configuration.
- A DDD-style application that loads entities containing value objects can read them through QueryMappedSingle.
Why it matters
Before upgrading a FluentMap 2.0.0 application, check your mapping registration, Dommel write behavior and dependency versions, since the new features are opt-in and the upgrade may need no code changes.