ef-core

Entity Framework Core — Rules and Best Practices

You are working in a .NET project that uses Entity Framework Core. Follow these rules strictly.

Project Auto-Detection

When you start working in an EF Core project, orient yourself by detecting:

1. DbContext location — search for classes inheriting from DbContext. Note which project and file they live in.
2. Migrations folder — look for a Migrations/ directory containing *ModelSnapshot.cs. This is the model project.
3. Startup project — the project with Program.cs (or Startup.cs) that configures the host and registers the DbContext with dependency injection.
4. Project vs. startup project — if the DbContext and Program.cs are in different projects, all dotnet ef commands need --project and --startup-project flags.
5. Multiple DbContexts — if more than one DbContext subclass exists, all commands need --context <ContextName>.

Expose this information to the user when running EF commands so they understand the project topology.

Critical Rules

1. Never Hand-Edit Generated Files

The following files are auto-generated by EF Core tooling and must never be edited by hand:

• *.Designer.cs files in the Migrations directory — model snapshots at each migration point
• *ModelSnapshot.cs files — current model state used to compute the next migration

If these files need to change, use dotnet ef migrations add or dotnet ef migrations remove to regenerate them. Hand-editing will corrupt migration history and cause unpredictable failures.

2. Always Review Generated Migrations Before Committing

dotnet ef can pick up unrelated snapshot drift from NuGet package upgrades or other model changes. The generated Up() method should only contain the intended changes. Before committing a migration:

• Verify every operation relates to the intended feature
• Flag any operations that look unrelated (snapshot drift)
• Check for drop+add column pairs that should be RenameColumn() instead

3. Non-Nullable Columns Need Defaults

When adding a non-nullable column to an existing table, the migration must include a defaultValue or defaultValueSql. Otherwise the migration will fail on tables that already have rows.

// WRONG — will fail if the table has existing rows
migrationBuilder.AddColumn<string>(
    name: "Status",
    table: "Orders",
    nullable: false);

// CORRECT — provides a default for existing rows
migrationBuilder.AddColumn<string>(
    name: "Status",
    table: "Orders",
    nullable: false,
    defaultValue: "Pending");

If dotnet ef migrations add generates a non-nullable column without a default, flag it and suggest a fix.

4. Keep Microsoft.EntityFrameworkCore.Design Installed

Microsoft.EntityFrameworkCore.Design must be installed as a permanent dependency on both the model project and the startup project. Do not add/remove it per migration. It is required for all dotnet ef commands to work.

5. One Migration Per Feature

Do not combine unrelated schema changes in a single migration. Each migration should correspond to one logical feature or change. This makes rollbacks cleaner and migration history readable.

6. Migration Files (.cs) May Be Edited Carefully

The main migration file ([Timestamp]_MigrationName.cs) containing Up() and Down() methods can be edited when necessary. Common reasons:

• Replace a drop+add column pair with migrationBuilder.RenameColumn() to preserve data
• Add migrationBuilder.Sql() calls for data transformations
• Add defaultValue or defaultValueSql to non-nullable columns
• Adjust index or constraint names
• Add seed data with migrationBuilder.InsertData()

Always keep Up() and Down() in sync — every change in Up() must be reversed in Down().

Connection String Handling

dotnet ef requires a valid connection string at build time, even for operations like migrations add that don't touch the database. If a command fails due to a missing connection string:

• Set a temporary dummy connection string via environment variable:

  set "ConnectionStrings__DefaultConnection=Server=.;Database=EfCoreDummy;Integrated Security=false;User Id=dummy;Password=dummy;TrustServerCertificate=True"
  

  (On Linux/macOS use export instead of set)
• Migration generation only needs the model, not a real database connection
• Tell the user a dummy connection was used

Workflow

Creating Migrations

1. Modify entity models or DbContext configuration
2. Run: dotnet ef migrations add DescriptiveName
3. Review the generated migration — check for unintended drops, missing defaults, and snapshot drift
4. Apply locally: dotnet ef database update

Naming Conventions

Use descriptive migration names that indicate purpose:

• AddProductTable — adding a new table
• AddCreatedAtToOrders — adding a column
• RenameUserNameToFullName — renaming
• AddIndexOnEmail — adding an index
• RemoveDeprecatedFields — cleanup

Avoid generic names like Update, Changes, Fix.

Removing Migrations

• Only remove the last unapplied migration: dotnet ef migrations remove
• Never remove migrations that have been applied to shared or production databases
• To undo an applied migration, create a new migration that reverses the changes

Production Deployments

Prefer generating SQL scripts or migration bundles over running dotnet ef database update directly:

• SQL scripts (reviewable by DBAs): dotnet ef migrations script --idempotent -o deploy.sql
• Migration bundles (standalone executable): dotnet ef migrations bundle --self-contained
• Avoid context.Database.MigrateAsync() at startup in production — it causes race conditions and can't be easily rolled back

Common Options

All dotnet ef commands support these options:

• --project <PATH> (-p) — project containing the DbContext
• --startup-project <PATH> (-s) — project that configures the host and connection string
• --context <NAME> (-c) — DbContext class to use (required when multiple exist)
• --configuration <CONFIG> — build configuration (Debug/Release)
• --framework <TFM> — target framework (for multi-targeted projects)
• --verbose (-v) — show detailed output
• --no-build — skip building the project (use if already built)

For the full command reference, see commands-reference.md.

Entity Configuration Best Practices

• Prefer Fluent API over data annotations for complex configurations — it keeps entity classes clean and provides more options
• Use IEntityTypeConfiguration<T> classes to organize configurations per entity
• Apply configurations in OnModelCreating via modelBuilder.ApplyConfigurationsFromAssembly()
• Follow EF Core conventions for primary keys (Id or <EntityName>Id) and foreign keys (<NavigationProperty>Id)
• Use nullable reference types to express optionality — EF Core respects C# nullability

Query Best Practices

• Use .AsNoTracking() for read-only queries
• Use projections (.Select()) to load only needed columns
• Avoid loading full entity graphs when only a subset is needed
• Use IQueryable to compose queries before execution
• Be aware of N+1 query problems — use .Include() or projections
• Client-side evaluation — EF Core throws on C# methods in LINQ expressions that can't be translated to SQL. Don't put C# methods (e.g., string formatting, custom logic) inside Where() or Select() that runs on IQueryable. Materialize with ToListAsync() first, then apply client-side logic in memory.
• Use compiled models (dotnet ef dbcontext optimize) for improved startup performance in production

SQL Server-Specific Warnings

• Filtered indexes on computed columns are not supported in SQL Server. Use a regular (non-unique, non-filtered) index instead.
• String column length — nvarchar(max) is the default if no MaxLength is specified. Always set explicit lengths for indexed string columns.

Project Structure Conventions

Typical Layout

ProjectName/
├── Data/
│   ├── ApplicationDbContext.cs
│   ├── Migrations/
│   │   ├── 20250101120000_InitialCreate.cs
│   │   ├── 20250101120000_InitialCreate.Designer.cs
│   │   └── ApplicationDbContextModelSnapshot.cs
│   └── Configuration/         (IEntityTypeConfiguration classes)
│       ├── BlogConfiguration.cs
│       └── PostConfiguration.cs
├── Models/ (or Entities/)
│   ├── Blog.cs
│   └── Post.cs
└── Program.cs

When the project uses a separate data layer:

• Entities live in the domain/core project
• DbContext, migrations, and configurations live in the data/infrastructure project
• Use --project and --startup-project flags with dotnet ef commands

Multi-Context Projects

When multiple DbContext classes exist, always specify which one:

dotnet ef migrations add MigrationName --context MyDbContext
dotnet ef database update --context MyDbContext