FluentMap

Map your data. Keep your models clean.

English · Português (Brasil)

Getting Started · Documentation · NuGet · Examples · GitHub Releases · Contributing

FluentMap provides fluent, strongly typed mappings for applications that use Dapper. It connects .NET properties to database columns without adding persistence attributes to domain entities.

FluentMap complements Dapper; it does not replace it and is not a full ORM. SQL, connections, transactions, migrations, and entity tracking remain outside its scope.

Version status: 3.6.0 is the latest published stable release. The repository is configured for 3.6.1, which is the next release being prepared and is not published yet. Until publication, unversioned installation commands resolve to the latest version available on the selected package source.

Why FluentMap?

Imagine a .NET application with a Customer entity whose properties are Id and Name, while its database returns customer_id and customer_name. FluentMap keeps those physical column names in a dedicated, strongly typed map instead of coupling the entity to persistence details.

That gives you:

• cleaner domain models;
• strongly typed configuration;
• explicit, reusable mappings;
• direct integration with Dapper;
• support for reusable conventions;
• better organization of persistence code.

Quick Start

Install the core package and, for this self-contained SQLite example, the database provider:

dotnet add package Dapper.FluentMap
dotnet add package Microsoft.Data.Sqlite

Define the entity and its map, register it once during startup, then query normally with Dapper:

using Dapper;
using Dapper.FluentMap;
using Dapper.FluentMap.Mapping;
using Microsoft.Data.Sqlite;

FluentMapper.Initialize(config => config.AddMap<CustomerMap>());
FluentMapper.Validate();

using var connection = new SqliteConnection("Data Source=:memory:");
var customer = connection.QuerySingle<Customer>(
    "SELECT 7 AS customer_id, 'Ada' AS customer_name;");

public sealed class Customer
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
}

public sealed class CustomerMap : EntityMap<Customer>
{
    public CustomerMap()
    {
        Map(customer => customer.Id).ToColumn("customer_id");
        Map(customer => customer.Name).ToColumn("customer_name");
    }
}

Initialize the global configuration before concurrent queries and treat it as read-only afterward. See the Quick Start source if the planned portal is not yet deployed.

Key Features

Feature	Scope	Learn more
Explicit property mapping	Core	EntityMap<T> and property mapping
Naming conventions	Core	Conventions
Immutable objects	Core	Immutable objects
Mapping profiles	Core	Mapping profiles
Runtime isolation	Core	FluentMapRuntime
Dependency Injection	Optional package	DI integration
Dommel integration	Optional package	Dommel integration
Source generators	Optional package	Source generators
Roslyn analyzers	Optional package	Roslyn analyzers

The repository-local usage guide remains available as a fallback for detailed API examples.

Packages

Package	Purpose
Dapper.FluentMap	Core mapping, conventions, profiles, materialization, and runtime APIs.
Dapper.FluentMap.Dommel	Optional Dommel metadata and persistence integration.
FluentMap.DependencyInjection	Registration of immutable configuration and isolated runtimes with Microsoft DI.
FluentMap.Analyzers	Roslyn diagnostics for statically detectable mapping problems.
FluentMap.Generators	Generated map registration and supported materializers.

Package IDs are distribution identities. Assemblies, namespaces, and public APIs remain under Dapper.FluentMap.* where documented.

The current compatibility contract requires Dapper [2.1.89,3.0.0). This is a minimum-version range, not an exact pin: consumers may resolve a compatible Dapper 2.x release at or above 2.1.89. See Compatibility and Migration before upgrading an application that still uses Dapper 2.1.79.

Documentation

The bilingual documentation portal is planned for https://rodri-oliveira-dev.github.io/Dapper-FluentMap/. Until its deployment is confirmed, use the linked repository-local sources as fallbacks.

Topic	Portal source	Repository guide
Getting Started	Start here	Quick Start
Basic Mapping	Property mapping	Usage guide
Advanced Mapping	Advanced mapping	Usage guide
Integrations	Integrations	Package overview
Examples	Examples	SQLite example
Migration Guide	Migration	MIGRATION.md
Compatibility	Compatibility matrix	COMPATIBILITY.md
API Reference	API overview	Configuration reference

Project Status

FluentMap is actively maintained. The 3.x line preserves the main historical contracts—including EntityMap<T>, FluentMapper.Initialize(...), and the Dapper type-map bridge—while newer capabilities remain opt-in. Review the compatibility documentation before upgrading.

For published versions and release history, see GitHub Releases and the changelog.

Contributing

Contributions are welcome. You can report a bug or suggest an improvement, help improve the documentation, or submit a focused pull request.

If FluentMap helps your project, consider giving the repository a GitHub star.

License

FluentMap is licensed under the MIT License.