Data Annotation vs. Fluent API

Modeling Entities in EF Core

When mapping your C# classes to a database schema, Entity Framework Core provides two primary mechanisms: Data Annotations (Attributes) and the Fluent API. Choosing the right one depends on your architectural goals and the complexity of your schema.

1. Data Annotations

Attributes applied directly to the properties and classes of your domain model.

Pros	Cons
Quick and easy to apply.	Clutters domain entities with persistence details.
Highly readable for simple valdiation.	Limited features (cannot handle composite keys).
Shared with ASP.NET Core validation.	Violates “Pure Domain” if using Clean Architecture.

Common Attributes: [Key], [Required], [MaxLength(200)], [Table("Orders")].

2. Fluent API

Logic contained within the OnModelCreating method of your DbContext.

Pros	Cons
Full power of EF Core configuration.	More verbose.
Supports composite keys and shadow properties.	Logic is physically separated from the model.
Keeps Domain POCOs “Pure”.	Steeper learning curve.

Common Methods: .HasKey(), .Property(x => x.Email).IsRequired(), .HasIndex().

Precedence: Who Wins?

If you configure the same property using both methods, the result follows a strict hierarchy:

Fluent API (Highest Precedence)
Data Annotations
Convention (Lowest Precedence)

Practice Exercise

Demonstrate the precedence of the Fluent API over Data Annotations by configuring a Name property with conflicting MaxLength values.

Answer

1. The Entity with Annotations

public class Product
{
    public int Id { get; set; }

    [MaxLength(50)] // Annotation suggests 50
    public string Name { get; set; }
}

2. The Context with Fluent API

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Product>()
        .Property(p => p.Name)
        .HasMaxLength(255); // Fluent API overrides to 255
}

Why This Architecture Works

Clean Architecture Compliance: By using the Fluent API, your Domain project doesn’t need to reference the System.ComponentModel.DataAnnotations namespace or EF Core packages, keeping it entirely platform-agnostic.
Single Source of Truth: For complex relationships (like many-to-many with payload), the Fluent API is the only place where the mapping is clearly defined, making it the authoritative source for schema design.
Validation Sharing: Data Annotations like [Required] are great because they are automatically picked up by both EF Core and ASP.NET Core’s model validation, giving you “write once, validate twice” efficiency for simple rules.

Summary

Use Data Annotations for simple bread-and-butter validation and documentation.
Use Fluent API for complex database mapping, unique indexes, and maintaining a clean domain model.
Always remember that the Fluent API wins in a conflict—use this to your advantage to override legacy attributes without changing the entity classes.