What is convention over configuration, and where does .NET use it in ASP.NET Core and EF Core?

1. Origin

David Heinemeier Hansson popularised "convention over configuration" with Ruby on Rails (2004): decide the common case once in the framework, so applications only declare deviations. ASP.NET MVC (2009) and Entity Framework Code First brought the same philosophy to .NET.

2. How EF Core applies conventions

EF Core builds its model through a pipeline of model-building conventions that run as you add entities and properties: key discovery, relationship discovery, foreign-key discovery (including shadow properties), table naming, cascade behaviour and more. Data annotations and the Fluent API then override what conventions inferred. Precedence (lowest → highest): convention → data annotations → Fluent API.

3. Customising conventions

protected override void ConfigureConventions(ModelConfigurationBuilder builder)   // EF Core 6+
{
    builder.Properties<string>().HaveMaxLength(256);
    builder.Properties<decimal>().HavePrecision(18, 2);
    builder.Properties<DateTimeOffset>().HaveConversion<DateTimeOffsetToBinaryConverter>(); // e.g. for SQLite
}

EF Core 7+ lets you add or remove model-building conventions (builder.Conventions.Remove(typeof(CascadeDeleteConvention)) or add a custom IModelFinalizingConvention), useful for team-wide rules such as snake_case naming or restricting cascades.

4. ASP.NET Core configuration conventions

Precedence (later wins):
appsettings.json
appsettings.{Environment}.json
user secrets (Development only)
environment variables         Payments__BaseUrl  →  Payments:BaseUrl
command-line arguments        --Payments:BaseUrl=...

Knowing this order explains most "why is production using the wrong value?" incidents.

5. Making conventions visible

6. Team conventions

Convention over configuration also applies to your own codebase: feature folders, naming (*Handler, *Endpoint), one way to register modules, one error format. Written down and enforced (analysers, architecture tests, templates), they cut decisions and review noise the same way framework conventions do.

7. Try it yourself

1. Create Customer and Order with a navigation and no configuration; run dotnet ef migrations add Initial and read the keys/FKs.
2. Rename the FK property (keep the navigation), add another migration, and look for the shadow FK.
3. Fix it with HasForeignKey and confirm the migration becomes a rename.
4. Add ConfigureConventions for string length and decimal precision; regenerate and compare column types.
5. Set Payments__BaseUrl as an environment variable and confirm it overrides appsettings.json.

using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata.Builders;

using var db = new ShopDb();
db.Database.EnsureDeleted();
db.Database.EnsureCreated();

db.Customers.Add(new Customer { Name = "Ava", Orders = { new Order { Total = 49.95m } } });
db.SaveChanges();
Console.WriteLine(db.Orders.Single().CustomerId);   // FK set by convention via the navigation

public sealed class Customer
{
    public int Id { get; set; }                          // primary key by convention
    public required string Name { get; set; }            // C# 11+ 'required'
    public List<Order> Orders { get; } = [];             // one-to-many by convention
}

public sealed class Order
{
    public int Id { get; set; }
    public decimal Total { get; set; }
    public int CustomerId { get; set; }                  // FK by convention: <Navigation>Id
    public Customer Customer { get; set; } = null!;
}

// Explicit configuration for a core relationship, so a rename can't silently create a shadow FK.
public sealed class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder) =>
        builder.HasOne(o => o.Customer)
               .WithMany(c => c.Orders)
               .HasForeignKey(o => o.CustomerId)
               .OnDelete(DeleteBehavior.Restrict);
}

public sealed class ShopDb : DbContext
{
    // Set<T>() returns the DbSet; the table name comes from the property name by convention.
    public DbSet<Customer> Customers => Set<Customer>();
    public DbSet<Order> Orders => Set<Order>();

    protected override void OnConfiguring(DbContextOptionsBuilder options) =>
        options.UseSqlite("Data Source=shop.db");

    protected override void OnModelCreating(ModelBuilder modelBuilder) =>
        modelBuilder.ApplyConfigurationsFromAssembly(typeof(ShopDb).Assembly);

    // Project-wide conventions instead of repeating attributes on every property.
    protected override void ConfigureConventions(ModelConfigurationBuilder builder)
    {
        builder.Properties<string>().HaveMaxLength(256);
        builder.Properties<decimal>().HavePrecision(18, 2);
    }
}

Requires Microsoft.EntityFrameworkCore.Sqlite (EF Core 6+ for ConfigureConventions).