# EF Core From Zero > Learn Entity Framework Core, .NET's flagship ORM: the DbContext and connecting, entity models and migrations, create and read, LINQ querying, change tracking and SaveChanges, relationships, loading strategies and the N+1 trap, and transactions. The data layer most ASP.NET Core apps use - including where to drop to SQL. --- # EF Core From Zero Entity Framework Core is the ORM most ASP.NET Core apps reach for. You define your tables as C# classes, and EF Core writes the SQL for create, read, update, delete, relationships, and schema migrations. If you've used an ORM elsewhere it'll feel familiar; if you haven't, it's a comfortable way into "describe your data as types, let the library talk to the database." And because good engineers like to know what's really happening, the most valuable habit you'll build here is watching the SQL EF Core generates - so you can drop to raw SQL the moment the ORM gets in your way. The mental model is two pieces plus a query language. A **`DbContext`** is your session with the database: it holds **`DbSet`** properties (one per table), **tracks the changes** you make to the objects it hands you, and pushes them all to the database when you call **`SaveChanges`**. And you query with **LINQ** - C#'s built-in query syntax - which EF Core translates into SQL. Hold "the DbContext is a change-tracking session, DbSets are your tables, LINQ becomes SQL," and EF Core stops being magic and becomes a tool you direct. > 📝 This teaches the **library** - it assumes you know **C#** (classes, generics, LINQ basics, > `async`/`await` - [C# From Zero](/guides/csharp-from-zero)) and basic **databases** (tables, keys, > joins - [What a Database Is](/guides/what-a-database-is)). The ORM concepts transfer directly from > [Hibernate & JPA](/guides/hibernate-and-jpa-from-zero), [SQLAlchemy](/guides/sqlalchemy-from-zero), and > [GORM](/guides/gorm-from-zero). It pairs with [ASP.NET Core](/guides/aspnet-core-from-zero) as its data > layer. Examples use SQLite for zero setup and are shown with their output. ## How to read this Read in order - it builds one schema (a **blog**: blogs, posts, tags) from a bare `DbContext` up to relationships, the N+1 trap, and migrations. Phases carry difficulty badges. ## The phases **Part 1 - Foundations (🟢 → 🟡)** 1. **[What EF Core Is & the DbContext](01-what-efcore-is.md)** 🟢 - the ORM idea, the `DbContext`/`DbSet` model, and seeing the SQL. 2. **[Entity Models & Migrations](02-models-and-migrations.md)** 🟡 - classes as tables, conventions, and `dotnet ef` migrations. 3. **[Create & Read](03-create-and-read.md)** 🟡 - `Add` + `SaveChanges`, `Find`/`First`/`Single`, and how records round-trip. **Part 2 - Real queries (🟡 → 🔴)** 4. **[Querying with LINQ](04-querying-with-linq.md)** 🟡 - `Where`/`OrderBy`/`Select`, deferred execution, and `AsNoTracking`. 5. **[Change Tracking & SaveChanges](05-change-tracking.md)** 🔴 - the unit of work: how EF detects edits and batches the writes. 6. **[Relationships](06-relationships.md)** 🔴 - navigation properties, one-to-many, many-to-many, and the fluent API. 7. **[Loading Strategies & the N+1 Trap](07-loading-and-n-plus-1.md)** 🔴 - `Include` vs lazy loading, and the query explosion that bites everyone. **Part 3 - Real projects (🔴 → 🟢)** 8. **[Transactions & Migrations in Production](08-transactions-and-migrations.md)** 🔴 - transactions, concurrency, and applying migrations safely. 9. **[EF Core in the Real World & Where to Go Next](09-where-to-go-next.md)** 🟢 - when to drop to SQL, EF Core vs Dapper, and what to build. > The throughline: a **`DbContext` is a change-tracking session**, **`DbSet`s are your tables**, and > **LINQ becomes SQL**. Watch that SQL and you stay in command of the database. --- # What EF Core Is & the DbContext A .NET app that reads and writes SQL rows *could* hand-write every `INSERT`, `SELECT`, and `UPDATE` - opening a connection, building a command, reading columns back one at a time. It works, but it's repetitive plumbing, and the day a column name changes, you're chasing it through every query that touched it. EF Core - Entity Framework Core - is what most ASP.NET Core apps reach for instead. It's .NET's flagship **ORM** (object-relational mapper): you describe your tables as plain C# classes, and EF Core writes the SQL for create, read, update, delete, relationships, and schema migrations. Fewer typos in column names, less boilerplate, and the shape of your data lives in one place. > 📝 This phase teaches the **library**. It assumes you know **C#** (classes, generics, LINQ basics, > `async`/`await` - [C# From Zero](/guides/csharp-from-zero)) and the basics of **databases** (tables, > rows, keys - [What a Database Is](/guides/what-a-database-is)). If you've used an ORM in another > language, the core ideas transfer straight across - see [GORM From Zero](/guides/gorm-from-zero) for the > same concepts in Go. ## The real cost Every convenience comes with a bill. When a library writes your SQL for you, you stop *seeing* your SQL - exactly where ORMs earn their bad reputation. One innocent-looking method call can fire off a query you'd never have written by hand, and if you're not watching, you find out in production when a page is mysteriously slow. ⚠️ The cure isn't avoiding EF Core - it's **watching the SQL it generates**. EF Core can log every statement it runs. Turn that on while you learn (we'll do it in a minute), and the ORM stops being a black box. You'll see the `INSERT` behind an `Add`, the `SELECT` behind a query, and the moment a call does something expensive. ## The mental model Before any setup, hold this picture - it's the whole guide in one line: > **A `DbContext` is a change-tracking session, a `DbSet` is a table, and LINQ becomes SQL.** Three pieces: - **The `DbContext` = your session with the database.** You create one, do some work through it, and dispose it. While it's alive it **tracks the changes** you make to the objects it hands you, and pushes them all to the database when you call `SaveChanges`. - **A `DbSet` = a table.** Your context exposes one `DbSet` property per table - `DbSet` is the `Blogs` table. You add to it, and you query through it. - **LINQ becomes SQL.** You write queries in C#'s built-in query language (LINQ), and EF Core translates them into real `SELECT ... WHERE ...` statements. (Querying is Phase 4 - for now, just know that's the flow.) 💡 EF Core is a **SQL generator**, not a cage. When the high-level API gets awkward - a gnarly report, a bulk update - you drop straight to raw SQL with `FromSql(...)` or `ExecuteSql(...)`, against the same connection. You never lose access to the database underneath. ## Installing EF Core EF Core is the core library plus a **provider** for your specific database. We'll use SQLite - zero setup (the database is just a file), so you can run everything here without standing up a server. From inside a console project (`dotnet new console -o blog` if you're starting fresh), pull in the SQLite provider: ```bash dotnet add package Microsoft.EntityFrameworkCore.Sqlite ``` *What just happened:* `dotnet add package` downloaded the SQLite provider and added it to your `.csproj`. That one package brings EF Core's core along as a dependency, plus the adapter that teaches it to speak SQLite specifically. Moving to PostgreSQL or SQL Server later just means swapping the provider (`Npgsql.EntityFrameworkCore.PostgreSQL` or `Microsoft.EntityFrameworkCore.SqlServer`) - little else changes. ## Defining a DbContext and an entity You write two kinds of class: a **`DbContext`** subclass that names your tables and points at the database, and an **entity** class for each table - a plain class whose properties become columns: ```csharp using Microsoft.EntityFrameworkCore; public class BlogContext : DbContext { public DbSet Blogs => Set(); public DbSet Posts => Set(); protected override void OnConfiguring(DbContextOptionsBuilder options) => options.UseSqlite("Data Source=blog.db"); } public class Blog { public int Id { get; set; } public string Url { get; set; } = ""; } ``` *What just happened:* `BlogContext` derives from `DbContext`, which is what makes it a database session. Its two `DbSet` properties declare the tables - `Blogs` and `Posts` - and `=> Set()` is the standard way to wire each one up. `OnConfiguring` is where the context learns *which* database to talk to: `UseSqlite("Data Source=blog.db")` says "use the SQLite provider, pointed at a file called `blog.db`" (created automatically if it doesn't exist). `Blog` is an **entity** - an ordinary C# class. Its `Id` and `Url` properties will become columns; EF Core treats a property named `Id` as the primary key by convention. (We'll define `Post` and turn these into real tables in [Phase 2](02-models-and-migrations.md).) 📝 In an ASP.NET Core app you usually *don't* write `OnConfiguring`. Instead you register the context with dependency injection via `AddDbContext(...)`, and the framework hands a fresh, correctly-scoped context to each request - see [ASP.NET Core From Zero](/guides/aspnet-core-from-zero). Same mental model, different wiring. ## Opening, saving, and disposing Using the context is three moves - create it, change something, save: ```csharp using var ctx = new BlogContext(); ctx.Blogs.Add(new Blog { Url = "https://example.com" }); ctx.SaveChanges(); ``` Run it with `dotnet run`. *What just happened:* `new BlogContext()` opened a session. `ctx.Blogs.Add(...)` didn't touch the database yet - it told the context "start tracking this new `Blog`, I intend to insert it." Nothing is written until `ctx.SaveChanges()`, which looks at everything the context is tracking, generates the SQL, and runs it in a single batch (here, one `INSERT`). `using var` makes this safe: `DbContext` is meant to be **short-lived**, and `using` disposes it - releasing the connection - the moment the block ends. Create one, do a unit of work, let it go. (`SaveChanges` has an `async` twin, `SaveChangesAsync`, for web apps.) ## Turn on the SQL log This is the fix for the real cost, and the single best habit to build while learning. Chain `LogTo` onto your provider setup and EF Core prints every statement it runs: ```csharp protected override void OnConfiguring(DbContextOptionsBuilder options) => options.UseSqlite("Data Source=blog.db") .LogTo(Console.WriteLine); ``` *What just happened:* the only change is `.LogTo(Console.WriteLine)`, which hands EF Core a place to send its log lines - here, straight to the console. From now on, every query leaves a trail you can read. (In development you can also add `.EnableSensitiveDataLogging()` to see actual parameter *values*, not just `@p0` placeholders - handy while learning, but keep it out of production since it can print real data.) Re-run the save with logging on, and the `INSERT` from a moment ago shows up looking roughly like this: ```sql INSERT INTO "Blogs" ("Url") VALUES (@p0); SELECT "Id" FROM "Blogs" WHERE changes() = 1 AND "rowid" = last_insert_rowid(); ``` *What just happened:* that's the literal SQL behind `Add` + `SaveChanges`. The first statement inserts the row; the second reads back the database-generated `Id` so EF Core can fill it into your `Blog` object in memory. Two C# lines, and here's exactly what they became. 💡 Keep this on the entire time you're learning - the instant a single call fires five queries, or runs a `SELECT` with no `WHERE`, you'll see it. ## The running example: a blog Rather than disconnected snippets, this guide builds one small, recognizable schema - a **blog** - and grows it phase by phase. You've already met two of its tables; here's the cast and how they relate: ```mermaid flowchart LR Blog -- "has many" --> Post Post -- "tagged with many" --> Tag Tag -- "applied to many" --> Post ``` *What just happened:* the diagram lays out where we're headed. A **`Blog`** has many **`Post`s** - a one-to-many relationship. A **`Post`** can carry many **`Tag`s** while each `Tag` labels many posts - a many-to-many. Right now they're just boxes and arrows; in [Phase 2](02-models-and-migrations.md) we turn these into real entity classes, use migrations to create the tables, then create rows, query with LINQ, watch change tracking batch our edits, and wire up these relationships. The win for this phase: you can connect, you've saved a row, the SQL log is on, and you hold the mental model. That's the foundation everything else stands on. ## Recap 1. **EF Core is .NET's flagship ORM** - you describe tables as C# classes and it writes the SQL for CRUD, relationships, and migrations, so you skip the hand-written query boilerplate. 2. **The real cost is invisible SQL.** The cure is `LogTo`: turn it on while learning so you see the exact statement behind every call. 3. **The mental model:** a `DbContext` is a change-tracking session, a `DbSet` is a table, and LINQ becomes SQL - and you can always drop to raw SQL with `FromSql`/`ExecuteSql`. 4. **Install a provider** (`Microsoft.EntityFrameworkCore.Sqlite` here), define a `DbContext` subclass with `DbSet` properties, and point it at the database in `OnConfiguring` with `UseSqlite("Data Source=...")`. 5. **`Add` then `SaveChanges`:** `Add` only starts tracking; nothing hits the database until `SaveChanges` batches and runs the SQL. Keep the context **short-lived** - `using var ctx = new BlogContext();`. 6. In **ASP.NET Core** you register the context with `AddDbContext` and let DI hand one per request, instead of writing `OnConfiguring`. ## Quick check Three questions on the framing that has to stick before Phase 2: ```quiz [ { "q": "In EF Core's mental model, what is a `DbContext`?", "choices": [ "A change-tracking session with the database that exposes DbSets and pushes changes on SaveChanges", "A single row fetched from a table", "The SQLite file on disk", "A class that maps directly to exactly one table" ], "answer": 0, "explain": "A `DbContext` is your session with the database: it holds `DbSet` properties (the tables), tracks the changes you make, and writes them all when you call `SaveChanges`. A class that maps to one table is an entity; a `DbSet` represents the table." }, { "q": "After `ctx.Blogs.Add(blog);`, when is the row actually written to the database?", "choices": [ "When you call `ctx.SaveChanges()` - `Add` only starts tracking it", "Immediately, inside the `Add` call", "When the `DbContext` is garbage collected", "Only after you manually open a transaction" ], "answer": 0, "explain": "`Add` just tells the context to start tracking the new entity as something to insert. Nothing reaches the database until `SaveChanges`, which generates and runs the SQL (here an `INSERT`) in one batch." }, { "q": "Why is `.LogTo(Console.WriteLine)` such a good habit while learning EF Core?", "choices": [ "It prints the exact SQL behind every call, so the ORM stops being a black box", "It makes queries run faster by caching them", "It is required or EF Core refuses to connect", "It automatically rewrites slow queries for you" ], "answer": 0, "explain": "The real cost of an ORM is that you stop seeing your SQL. `LogTo` prints every generated statement, so you immediately catch surprises - like one call firing several queries or a `SELECT` with no `WHERE`." } ] ``` --- # Entity Models & Migrations The mental model for this phase: **a class is a table.** You write an ordinary C# class, EF Core looks at it, and figures out the table's columns, types, and primary key - mostly without you saying a word. When you later change that class, you don't reach for a SQL editor. You generate a **migration**: a small, versioned record of "the schema went from *this* to *that*," committed alongside your code and applied when you deploy. > 📝 In [Phase 1](01-what-efcore-is.md) you built a `DbContext` with `DbSet` properties. Each `DbSet Blogs` is one table - but EF Core needs the actual `Blog` *class* to know what goes in it. That class is what we're writing now. ## A class is a table EF Core works from **conventions** - sensible defaults it applies automatically so you write less configuration. The big ones: - A property named `Id` (or `Id`, like `BlogId`) becomes the **primary key**. - Every public property with a getter and setter becomes a **column**. - The column's SQL type is inferred from the C# type (`int` → integer, `string` → text, `DateTime` → timestamp, and so on). - The **table name** comes from the `DbSet` property name on your context - so `DbSet Blogs` produces a table called `Blogs`. Let's give our blog a `Post` entity: ```csharp public class Post { public int Id { get; set; } [Required, MaxLength(200)] public string Title { get; set; } = ""; public string Content { get; set; } = ""; } ``` *What just happened:* EF Core reads this class and concludes: a table with `Id` as the primary key (auto-incrementing, since it's an `int` named `Id`), a `Title` text column, and a `Content` text column. `[Required, MaxLength(200)]` on `Title` is the one place we overrode a convention. The `= ""` initializers aren't an EF thing; they just keep C#'s nullable-reference warnings quiet. And the matching `Blog`: ```csharp public class Blog { public int Id { get; set; } public string Url { get; set; } = ""; } ``` *What just happened:* same story - `Id` is the key, `Url` is a column. No annotations here, so EF Core uses pure conventions: `Url` becomes a text column with no length cap. We'll tighten that next, since "no length cap" is rarely what you want. > 💡 Conventions do real work for you. You didn't declare a single column type, key, or constraint by hand - you described your data as C# types and EF Core inferred a reasonable schema. You only step in when a guess is wrong. ## Two ways to override: annotations vs the Fluent API When the conventions aren't enough - you need a max length, a different column name, a column that *isn't* mapped at all - you have two tools. **Data annotations** are attributes you put right on the property. They live with the model, which makes them easy to read: | Annotation | What it does | |---|---| | `[Required]` | Column is `NOT NULL` | | `[MaxLength(200)]` | Caps string/array length (e.g. `varchar(200)`) | | `[Column("url")]` | Maps the property to a differently named column | | `[Key]` | Marks the primary key explicitly (when convention can't guess) | | `[NotMapped]` | Exclude this property - no column for it | The **Fluent API** is the other option: you configure everything in code inside your `DbContext`, in an `OnModelCreating` override. ```csharp public class BloggingContext : DbContext { public DbSet Blogs => Set(); public DbSet Posts => Set(); protected override void OnModelCreating(ModelBuilder b) { b.Entity() .Property(x => x.Url) .IsRequired() .HasMaxLength(200); } } ``` *What just happened:* we told EF Core that `Blog.Url` is required and capped at 200 characters - the same rule `[Required, MaxLength(200)]` expresses, but written centrally instead of on the property. `ModelBuilder` is the configuration surface; `b.Entity().Property(...)` drills down to one column and chains the rules onto it. Why two systems? Annotations are concise and live next to the data - great for simple rules. The Fluent API is more powerful: it can express things annotations can't (composite keys, relationships, indexes, default values), and keeps entity classes free of EF-specific attributes. **If you ever configure the same thing both ways, the Fluent API wins.** A confusing "but I set `[MaxLength]`!" bug is almost always a Fluent API line quietly overriding it. > ⚠️ Don't sprinkle both for the *same* property and hope for the best. Pick a default approach (many teams lean Fluent API for anything non-trivial) and reserve mixing for deliberate overrides you actually understand. ## Migrations: versioning your schema You've got classes. Now you need an actual database with actual tables - and a way to *change* that schema later without losing data or hand-writing `ALTER TABLE` statements. First, install the design-time pieces: the `Design` package powers the tooling, and the `dotnet-ef` global tool gives you the commands. ```bash dotnet add package Microsoft.EntityFrameworkCore.Design dotnet tool install --global dotnet-ef ``` Now create your first migration: ```bash dotnet ef migrations add InitialCreate ``` *What just happened:* EF Core compared your current model (the `Blog` and `Post` classes plus any Fluent config) against the *last* migration - since there isn't one yet, the "diff" is "create everything." It wrote a new C# migration class into a `Migrations/` folder, with two methods: `Up()` (apply the change) and `Down()` (undo it). Nothing has touched your database yet - a migration is just a plan. Here's a peek at what that generated class looks like: ```csharp public partial class InitialCreate : Migration { protected override void Up(MigrationBuilder migrationBuilder) { migrationBuilder.CreateTable( name: "Blogs", columns: table => new { Id = table.Column(nullable: false) .Annotation("Sqlite:Autoincrement", true), Url = table.Column(maxLength: 200, nullable: false) }, constraints: table => table.PrimaryKey("PK_Blogs", x => x.Id)); // ... CreateTable for "Posts" follows ... } protected override void Down(MigrationBuilder migrationBuilder) { migrationBuilder.DropTable(name: "Blogs"); // ... DropTable for "Posts" ... } } ``` *What just happened:* the migration describes your schema as code, not raw SQL - `Up()` creates the tables (notice `Url` came out as `maxLength: 200, nullable: false`, exactly the Fluent rule we set), and `Down()` drops them so the change is reversible. EF Core translates this to dialect-specific SQL at apply time, so the same migration can target SQLite, SQL Server, or Postgres. Now apply it: ```bash dotnet ef database update ``` *What just happened:* EF Core ran the `Up()` of every pending migration against your database - creating the `Blogs` and `Posts` tables for real. It also created a bookkeeping table (`__EFMigrationsHistory`) that records which migrations have applied, so next time it only runs the new ones. Run `database update` again right now and nothing happens. If you want to *see* the SQL without touching the database, `dotnet ef migrations script` prints it - same instinct as watching the SQL EF Core generates from Phase 1. ## Migrations vs `EnsureCreated()` - don't mix them A tempting shortcut you'll see in tutorials: `ctx.Database.EnsureCreated()`. It looks at your model and creates the schema in one shot, no migration files, no tooling. ```csharp // Dev/prototyping only - NOT a migration. ctx.Database.EnsureCreated(); ``` *What just happened:* EF Core created the tables directly from your current model - fast and convenient for a throwaway prototype or test database. But notice what it *didn't* do: no migration created, nothing recorded in the history table, no `Down()`. > ⚠️ `EnsureCreated()` and migrations are two different worlds that don't cooperate. `EnsureCreated()` creates the schema **once** with no concept of evolving it - there's no "add a column later." Worse, a database made by `EnsureCreated()` has no migrations history, so `database update` won't know where to start. **Pick one per database.** For anything real, that's migrations. ## A migration per change, committed and deployed The workflow once you're rolling, worth internalizing: 1. Change a model (add a property, a new entity, a constraint). 2. `dotnet ef migrations add DescribeTheChange` - generates the diff. 3. Review the generated `Up()`/`Down()`. Did it do what you expected? 4. Commit the migration files **with the code change** - they're part of your source history. 5. On deploy, run `dotnet ef database update` (or apply the migration as part of your release). Each model change earns its own migration - a readable, reviewable timeline of how your schema evolved, with the ability to roll forward or back deliberately. > 💡 Treat migration files like code, because they are: reviewed in pull requests, tracked in version control, order matters. We'll cover the *production* side - applying migrations safely on a live database, handling concurrency - in [Phase 8](08-transactions-and-migrations.md). For now, the habit to build is: model change → migration → commit. ## Recap - **A class is a table.** EF Core reads your plain C# entity classes and maps them by **convention**: `Id`/`Id` becomes the primary key, public properties become columns, types are inferred, and the table name comes from the `DbSet` name. - Override conventions with **data annotations** (`[Required]`, `[MaxLength]`, `[Column]`, `[Key]`, `[NotMapped]`) on the property, or with the **Fluent API** in `OnModelCreating`. The Fluent API is more powerful and **wins** when both configure the same thing. - **Migrations** version your schema. Install `Microsoft.EntityFrameworkCore.Design` and the `dotnet-ef` tool, then `dotnet ef migrations add ` generates a reversible `Up()`/`Down()` class from the diff, and `dotnet ef database update` applies pending migrations. - A migration is a **plan**, not an action - nothing hits the database until `database update`. EF Core tracks applied migrations in `__EFMigrationsHistory`. - `EnsureCreated()` is a **dev-only** shortcut that creates schema once with no migration history - never mix it with migrations on the same database. - Make **one migration per model change**, review it, commit it with the code, and apply it on deploy. ## Quick check ```quiz [ { "q": "You have a Blog class with an int property named Id and a public string Url. With pure EF Core conventions, what schema does EF infer?", "choices": ["No table at all until you add [Table] and [Key] attributes", "A Blogs table with Id as the primary key and Url as a column", "A Blog table with no primary key", "A table where only Url is mapped, because Id is reserved"], "answer": 1, "explain": "Conventions: Id becomes the primary key, public properties become columns, and the table name comes from the DbSet name (Blogs)." }, { "q": "A property has [MaxLength(50)] in an annotation, but OnModelCreating also calls HasMaxLength(200) for it. What max length does the column get?", "choices": ["50, annotations take priority", "200, the Fluent API wins", "It throws an error for conflicting config", "The smaller of the two, 50"], "answer": 1, "explain": "When both configure the same thing, the Fluent API wins. That precedence is a common source of 'but I set the annotation!' confusion." }, { "q": "What does `dotnet ef migrations add InitialCreate` do?", "choices": ["Immediately creates the tables in the database", "Generates a versioned migration class with Up/Down from the model diff, without touching the database", "Deletes and recreates the database from scratch", "Runs EnsureCreated() for you"], "answer": 1, "explain": "migrations add only generates the migration (a plan). Nothing reaches the database until you run dotnet ef database update." } ] ``` --- # Create & Read You've got a `DbContext`, a `Blog` class, and a real database with tables behind it (Phase 2). Now comes the part you actually came for: putting rows in and getting them back out. This is the C and the R of CRUD, and the half of EF Core you'll use every single day. ## The mental model: a session you stage into, then flush Here's the one picture to carry through this whole phase: **`Add` doesn't touch the database. It stages an insert in your `DbContext`'s memory. `SaveChanges` is the moment EF turns everything you've staged into SQL and sends it - in one transaction. The finders (`Find`, `First`, `Single`, `ToList`) go the other direction: they run a `SELECT` and pour the rows back into C# objects.** > 💡 Think of the `DbContext` as a notepad, not a phone line. You scribble intentions on it ("insert > this blog"), and nothing reaches the database until you call `SaveChanges`. That's why a single > `SaveChanges` can flush ten inserts at once - they were all just sitting on the notepad. We'll lean on the SQL logger from Phase 1 throughout, because the fastest way to trust an ORM is to read the SQL it writes. ## Creating rows: `Add` + `SaveChanges` The pattern is two lines: make an object, hand it to the `DbSet`, then flush. ```csharp var blog = new Blog { Url = "https://battle-hardened.dev" }; ctx.Blogs.Add(blog); // staged, not saved - no SQL yet ctx.SaveChanges(); // NOW the INSERT runs Console.WriteLine(blog.Id); // 1 ← EF filled this in for you ``` With the logger on, `SaveChanges` prints something like: ```sql INSERT INTO "Blogs" ("Url") VALUES (@p0); SELECT "Id" FROM "Blogs" WHERE changes() = 1 AND "rowid" = last_insert_rowid(); ``` *What just happened:* `Add` only marked the object as "to be inserted" - the first line did nothing to the database. `SaveChanges` generated the `INSERT`, ran it inside a transaction, then read back the auto-generated primary key with that second `SELECT`. EF Core writes that key **into your object** - `blog.Id` was `0` before the save and `1` after, so the object you're holding matches the row that now exists. > ⚠️ A brand-new object's `Id` is `0` (the default for `int`) until you call `SaveChanges`. If you try > to use `blog.Id` before saving, you'll get `0`, not the real key. The Id exists only after the row > exists. ### Inserting many at once: `AddRange` When you have a batch, stage them all and save once: ```csharp var posts = new[] { new Post { Title = "Why I read the SQL", BlogId = blog.Id }, new Post { Title = "The N+1 trap", BlogId = blog.Id }, }; ctx.Blogs.Add(blog); ctx.Posts.AddRange(posts); ctx.SaveChanges(); // one trip, one transaction, all rows ``` *What just happened:* `AddRange` staged both posts alongside the blog. The single `SaveChanges` flushed everything together in **one transaction** - if any insert failed, they'd all roll back, nothing left half-written. That's the unit-of-work behavior we'll dig into in [Phase 5](05-change-tracking.md); for now, hold "stage as much as you want, save once." ### Async, for web apps In a web request you don't want to block the thread while the database works. Use the async variant: ```csharp ctx.Blogs.Add(blog); await ctx.SaveChangesAsync(); ``` *What just happened:* same `INSERT`, same write-back of `blog.Id`, but the thread is freed to handle other requests while the database works. In an ASP.NET Core app, this is the default to reach for. `Add` itself stays synchronous (it's just touching the in-memory notepad) - only the flush has an async form. ## Reading rows: the four finders Reading is where EF gives you a few tools that look similar but behave differently. Pick the one whose **failure mode** matches what you mean. ### `Find(id)` - by primary key, tracker-first ```csharp var blog = ctx.Blogs.Find(1); ``` *What just happened:* `Find` looks up a row by its **primary key**, checking the change tracker (the notepad) *first*. If you already loaded blog #1 earlier in this `DbContext`, `Find` hands you the same object with **no database trip at all**. Only if it's not already in memory does EF run: ```sql SELECT "Id", "Url" FROM "Blogs" WHERE "Id" = @p ``` If no row has that key, `Find` returns `null`. Use it when you have an Id in hand (a route parameter like `/blogs/1`) and want the cheapest possible lookup. ### `First` / `FirstOrDefault` - first match of a condition ```csharp var blog = ctx.Blogs.First(b => b.Url == "https://battle-hardened.dev"); var maybe = ctx.Blogs.FirstOrDefault(b => b.Url == "https://nope.dev"); ``` *What just happened:* these take a predicate (any condition, not just the key) and return the **first** match. EF translates it to: ```sql SELECT "Id", "Url" FROM "Blogs" WHERE "Url" = @p LIMIT 1 ``` The difference is what happens when nothing matches: `First` **throws** an `InvalidOperationException`; `FirstOrDefault` returns `null`. The first line above succeeds; the second returns `null` because no blog has that URL. ### `Single` / `SingleOrDefault` - exactly one match ```csharp var blog = ctx.Blogs.Single(b => b.Url == "https://battle-hardened.dev"); ``` *What just happened:* `Single` says "I expect exactly one row to match." It throws if **none** match *and* throws if **more than one** matches - doubling as a sanity check on uniqueness. Behind the scenes EF fetches up to two rows (`LIMIT 2`) to tell whether there was more than one. `SingleOrDefault` is the same but returns `null` when none match (still throws on two or more). Reach for `Single` when a duplicate would mean your data is broken and you want to find out loudly. ### `ToList` / `ToListAsync` - all the rows ```csharp var all = ctx.Blogs.ToList(); var dotnet = ctx.Posts.Where(p => p.Title.Contains(".NET")).ToList(); var allAsync = await ctx.Blogs.ToListAsync(); ``` *What just happened:* `ToList` runs the query and materializes **every** matching row into a `List`. On its own it's `SELECT * FROM Blogs`; with a `Where`, EF folds the condition into the SQL so only matching rows come back - the database filters, not your C#. We'll go deep on `Where`, `OrderBy`, `Select` in [Phase 4](04-querying-with-linq.md). The async `ToListAsync` is what you want in web apps, for the same thread-freeing reason as `SaveChangesAsync`. ## `First` vs `FirstOrDefault`: the choice that bites people The single most common stumble in EF Core reads. > ⚠️ `First` and `Single` **throw** when nothing matches. `FirstOrDefault` and `SingleOrDefault` > return **`null`**. They are not interchangeable - pick based on whether "not found" is an *error* or > an *expected outcome*. The clear way to choose: ask "if this returns nothing, is my program broken, or is that just a normal 'not found'?" ```csharp // A user requested /blogs/999 - "not found" is normal, return a 404. var blog = ctx.Blogs.FirstOrDefault(b => b.Id == id); if (blog is null) return NotFound(); // We just inserted this and MUST be able to read it back - missing = bug, throw loud. var settings = ctx.Blogs.First(b => b.Url == knownSeedUrl); ``` *What just happened:* the first case maps a missing row to an HTTP 404 - a user typing a bad Id isn't a crash, so we check for `null` and respond gracefully. The second uses `First` because absence would mean something is genuinely wrong; throwing surfaces the bug instead of letting a `null` slip downstream and blow up later with a confusing `NullReferenceException`. Choosing the throwing or `*OrDefault` variant *is* deciding how "missing" should be handled. ## Two things that come for free > 📝 **Your queries are injection-safe by default.** Notice the `@p0` / `@p` in every generated > statement above - EF Core turns the values in your LINQ predicates into **SQL parameters**, never > string-concatenated into the query text. So `b.Url == userInput` is safe even when `userInput` is > `"'; DROP TABLE Blogs; --"`; it goes in as a parameter value, not as SQL - one of the real reasons to > let the ORM write the SQL. > 📝 **Prefer the async finders in web apps.** `ToListAsync`, `FirstOrDefaultAsync`, > `SingleOrDefaultAsync`, `FindAsync`, and `SaveChangesAsync` all exist. In a server handling many > concurrent requests, blocking a thread on a synchronous database call wastes a thread that could serve > someone else. It matters far less in a one-off script - but in ASP.NET Core, async is the house style. ## Recap - **`Add` stages, `SaveChanges` flushes.** Nothing reaches the database until `SaveChanges` (or `SaveChangesAsync`) runs, and it runs everything staged in one transaction. - **EF writes the generated `Id` back into your object** after the insert - it's `0` before saving and the real key after. - **`Find(id)`** looks up by primary key and checks the in-memory tracker first (no DB hit if already loaded); **`ToList`/`ToListAsync`** pull every matching row. - **`First`/`Single` throw on no match; `FirstOrDefault`/`SingleOrDefault` return `null`.** Pick by whether "missing" is an error or a normal outcome (e.g. a 404). - **`Single` also throws on more than one match**, making it a built-in uniqueness check. - **Values become SQL parameters automatically**, so reads are injection-safe; prefer the async finders in web apps. ## Quick check ```quiz [ { "q": "You call ctx.Blogs.Add(blog) but never call SaveChanges. What's in the database?", "choices": ["The new blog row", "Nothing - Add only stages the insert in memory", "A row with a null Url", "An empty row reserving the Id"], "answer": 1, "explain": "Add only marks the object for insertion on the DbContext. No SQL runs until SaveChanges (or SaveChangesAsync) flushes it." }, { "q": "A user requests /blogs/999 and no blog has that Id. You want to return a 404, not crash. Which finder fits?", "choices": ["First, then catch the exception", "Single", "FirstOrDefault and check for null", "Find, then call SaveChanges"], "answer": 2, "explain": "FirstOrDefault returns null when nothing matches, so you can check for null and respond with a 404. First would throw, treating a normal 'not found' as a crash." }, { "q": "After ctx.Blogs.Add(blog); ctx.SaveChanges();, what is blog.Id?", "choices": ["Still 0 - you must reload the object", "The auto-generated key EF wrote back into the object", "null until you call Find", "A random GUID"], "answer": 1, "explain": "SaveChanges runs the INSERT and reads the database-generated primary key back into your object, so blog.Id holds the real key right after the save." } ] ``` --- # Querying with LINQ The mental model to lock in: **a LINQ query is not code that runs - it's a description that EF Core turns into SQL.** When you write `ctx.Posts.Where(...)`, nothing touches the database. You're building an *expression tree*, a blueprint that says "I want posts, filtered like this, sorted like that." EF holds that blueprint and translates it into a single SQL statement only when you actually ask for the results. Once you internalize "LINQ describes, SQL executes, and execution happens *later* than you'd think," EF Core querying stops surprising you. Every weird behavior in this phase - why your query didn't run, why it ran twice, why it suddenly broke - traces back to that one idea. We'll keep using the running **blog** schema: a `Blog` has many `Post`s, each `Post` has a `BlogId`, `Title`, and `Id`. ## A query is a blueprint, not a result Look at this chain and the SQL it becomes: ```csharp var recent = ctx.Posts .Where(p => p.BlogId == blogId) .OrderByDescending(p => p.Id) .Take(10) .ToList(); ``` EF translates that into one statement: ```sql SELECT "p"."Id", "p"."BlogId", "p"."Title" FROM "Posts" AS "p" WHERE "p"."BlogId" = @blogId ORDER BY "p"."Id" DESC LIMIT 10 ``` *What just happened:* you wrote four C# method calls, and EF folded all of them into a single round-trip to the database. `Where` became `WHERE`, `OrderByDescending` became `ORDER BY ... DESC`, `Take(10)` became `LIMIT 10`. The database filters, sorts, and limits - your app gets back only the 10 rows it asked for, not the whole table. > 📝 There are two ways to write LINQ. The **method syntax** above (`.Where(...).OrderBy(...)`) is what you'll see most. There's also **query syntax**, reading more like SQL: `from p in ctx.Posts where p.BlogId == blogId select p`. They compile to the same thing - pick whichever you find clearer. This guide uses method syntax throughout. ## The operators that map to SQL Most LINQ operators you'd reach for have a direct SQL translation. The common ones: ```csharp // Filtering and sorting var titles = ctx.Posts.Where(p => p.Title.Contains("EF")).ToList(); // Paging: skip the first 20, take the next 10 (page 3, 10 per page) var page = ctx.Posts.OrderBy(p => p.Id).Skip(20).Take(10).ToList(); // Aggregates - these run in SQL and return a single value int total = ctx.Posts.Count(p => p.BlogId == blogId); bool anyDrafts = ctx.Posts.Any(p => p.Title == ""); // Grouping: count posts per blog var perBlog = ctx.Posts .GroupBy(p => p.BlogId) .Select(g => new { BlogId = g.Key, Count = g.Count() }) .ToList(); ``` *What just happened:* each operator pushed work down into the database. `Contains` became a SQL `LIKE`; an `In`-style filter (`Where(p => ids.Contains(p.Id))`) becomes a SQL `IN (...)`. `Skip`/`Take` became `OFFSET`/`LIMIT` - that's your paging. `Count` and `Any` came back as `COUNT(*)` and an `EXISTS` check, returning one number or one boolean instead of shipping rows across the wire. `GroupBy` became `GROUP BY`. None of these loaded the table into memory. ## ⚠️ Deferred execution: nothing runs until you enumerate This is the part that bites everyone at least once. A LINQ query over `IQueryable` is *lazy*. Building it does nothing. The SQL fires only when you **enumerate** the results - a specific list of things count as enumerating. ```csharp // No database call yet. This is just a blueprint. var query = ctx.Posts.Where(p => p.BlogId == blogId); // Still nothing - you can keep composing. query = query.OrderByDescending(p => p.Id); // NOW the SQL runs - ToList() enumerates. var results = query.ToList(); ``` *What just happened:* the first two lines built and refined an expression tree without touching the database. You could pass `query` around, add more `.Where(...)` calls conditionally, and EF would fold them all into one statement. Only `ToList()` triggered the actual SQL. The triggers that force execution: `ToList()`/`ToListAsync()`, `First()`/`FirstOrDefault()`, `Single()`, `Count()`, `Any()`, `Sum()`, and a plain `foreach`. Until one of those, you're composing - not querying. ⚠️ The flip side of laziness: if you enumerate the *same* query twice (two `foreach` loops, or `.Count()` then `.ToList()`), you hit the database **twice**. When you need the results more than once, call `ToList()` once and reuse the list. > 💡 In real apps, prefer the async versions - `ToListAsync()`, `FirstOrDefaultAsync()` - so the thread isn't blocked waiting on the database. You'll need `using Microsoft.EntityFrameworkCore;` for those extension methods. ## Select: project to exactly the columns you need By default, querying `ctx.Posts` selects every column and materializes full `Post` entities. Often you don't need the whole row - just an id and a title for a list view. That's what **projection** with `Select` is for. ```csharp public record PostDto(int Id, string Title); var list = await ctx.Posts .Where(p => p.BlogId == blogId) .Select(p => new PostDto(p.Id, p.Title)) .ToListAsync(); ``` The generated SQL is narrower: ```sql SELECT "p"."Id", "p"."Title" FROM "Posts" AS "p" WHERE "p"."BlogId" = @blogId ``` *What just happened:* instead of `SELECT Id, BlogId, Title`, EF generated `SELECT Id, Title` - only the columns your `PostDto` actually uses. Less data crosses the wire, and EF skips building full entity objects. For a posts table with a big `Content` or `Body` column you don't need in a list, this is a real, measurable win. > 💡 For read-only API endpoints (your typical `GET /posts`), project straight to a DTO. You get a leaner query *and* avoid leaking your internal entity shape into your API response - two birds, one `Select`. ## AsNoTracking and keeping queries translatable When EF hands you full entities, it **tracks** them - keeping a snapshot of each one so it can detect edits later when you call `SaveChanges` (Phase 5's topic). For a read-only query, that bookkeeping is pure overhead: you're never going to save these objects back. ```csharp var posts = await ctx.Posts .AsNoTracking() .Where(p => p.BlogId == blogId) .ToListAsync(); ``` *What just happened:* `AsNoTracking()` told EF "don't bother watching these for changes." The query runs faster and uses less memory because EF skips creating change-tracking snapshots. Trade-off: if you edit one of these objects and call `SaveChanges`, nothing happens - EF isn't watching them. That's exactly what you want for GET endpoints and any read you won't modify. (Projections with `Select` to a DTO are effectively untracked already.) ⚠️ **Client vs server evaluation** is the sharp edge here. Almost everything in your LINQ runs as SQL on the database (the *server*). But if your predicate calls a C# method EF can't translate, it can't push that into SQL. ```csharp // EF can translate this - it knows StartsWith → LIKE 'EF%' var ok = ctx.Posts.Where(p => p.Title.StartsWith("EF")).ToList(); // EF CANNOT translate a custom C# method - this throws at runtime var bad = ctx.Posts.Where(p => MyCustomCheck(p.Title)).ToList(); ``` *What just happened:* the first query translated cleanly - `StartsWith` maps to a SQL `LIKE`. The second referenced `MyCustomCheck`, a method that exists only in C#, with no SQL equivalent. Modern EF Core won't silently pull the whole table into memory to run it (older ORMs did, causing brutal performance surprises) - instead it **throws**, telling you the expression couldn't be translated. The fix: keep `Where` predicates built from things EF understands (entity properties, comparisons, `StartsWith`/`Contains`/`==`), or pull the data first and do the C# logic afterward on the in-memory list, knowing you've now loaded more rows. The habit that saves you: **watch the SQL EF generates.** If a query is slow or behaving oddly, the logged SQL tells you whether the work is happening in the database or accidentally in your app. For a deep dive on diagnosing slow queries, see [Why Is My Query Slow?](/guides/why-is-my-query-slow). ## Recap - A LINQ query is a **description**, not a result. EF builds an expression tree and translates it to one SQL statement. - Execution is **deferred** - the SQL fires only when you enumerate: `ToList()`/`ToListAsync()`, `First()`, `Count()`, `Any()`, or `foreach`. Enumerate twice, hit the database twice. - `Where`, `OrderBy`, `Skip`/`Take`, `Count`, `Any`, `Sum`, `GroupBy`, and `Contains` all map to SQL - the database does the work and returns just the answer. - `Select` **projects** to a DTO, generating a narrower SELECT - fewer columns, less data, leaner read endpoints. - `AsNoTracking()` skips change-tracking for read-only queries: faster and lighter. - ⚠️ Keep predicates **translatable** - a C# method EF can't turn into SQL throws. Watch the generated SQL to stay in command. ## Quick check ```quiz [ { "q": "You write `var q = ctx.Posts.Where(p => p.BlogId == 1);` and stop there. What has hit the database?", "choices": ["The full filtered result set", "A COUNT of matching rows", "Nothing - execution is deferred until you enumerate", "An empty query that errors"], "answer": 2, "explain": "Building a LINQ query only creates an expression tree. No SQL runs until you enumerate with ToList(), First(), Count(), foreach, etc." }, { "q": "For a read-only GET endpoint that returns posts you won't modify, which is the best fit?", "choices": ["ctx.Posts.AsNoTracking().Where(...)", "ctx.Posts.Where(...) with full tracking", "Load every column and filter in C#", "ctx.Posts.Find(id) in a loop"], "answer": 0, "explain": "AsNoTracking() skips the change-tracker bookkeeping you don't need for read-only data - faster and less memory." }, { "q": "What does adding `.Select(p => new PostDto(p.Id, p.Title))` change about the generated SQL?", "choices": ["It adds a JOIN to every related table", "It narrows the SELECT to only the Id and Title columns", "It forces the query to run in memory", "It disables deferred execution"], "answer": 1, "explain": "Projection tells EF to select only the columns the DTO uses, producing a narrower SELECT that ships less data." } ] ``` --- # Change Tracking & SaveChanges The thing that trips up almost everyone the first time: there is no `Update` method you call to save an edit. You load a `Post`, change its `Title`, call `SaveChanges`, and the `UPDATE` statement just... appears. That can feel like magic, and magic you don't understand is magic that will bite you. So before any code, the mental model. > 💡 **The mental model.** A `DbContext` is a **unit of work** with a built-in **change tracker**. The moment a query hands you an entity, the context starts watching it: it stashes a private **snapshot** of every property value as they were when loaded. When you call `SaveChanges`, EF compares the current values of each tracked entity against its snapshot, works out the minimal set of inserts, updates, and deletes needed, and pushes them all to the database in **one transaction**. You don't tell EF *what* changed - it figures that out by diffing. Hold that picture - **load, mutate, diff, save** - and everything in this phase follows from it. ## Update by mutation Because the context already tracks the entity, updating a row is three steps: load it, change a property, save. No "update" call. ```csharp using var ctx = new BlogContext(); var post = ctx.Posts.First(p => p.Id == 42); post.Title = "Rewritten and better"; ctx.SaveChanges(); ``` *What just happened:* the `First` query loaded the post **and** registered it with the change tracker, snapshot included. Setting `post.Title` only changed the in-memory object - nothing hit the database yet. `SaveChanges` diffed the entity against its snapshot, saw exactly one column differed, and emitted SQL touching only that column: ```sql UPDATE Posts SET Title = 'Rewritten and better' WHERE Id = 42; ``` > 📝 Notice it does **not** rewrite every column - only `Title`. EF tracks changes per-property, so an `UPDATE` carries just the columns that actually moved. That keeps writes small and avoids stomping on columns another process may have touched. Deleting is the same shape, except you tell the context to mark the entity for removal: ```csharp var post = ctx.Posts.First(p => p.Id == 42); ctx.Posts.Remove(post); ctx.SaveChanges(); ``` *What just happened:* `Remove` doesn't delete anything immediately - it flips the tracked entity's state to `Deleted`. `SaveChanges` runs `DELETE FROM Posts WHERE Id = 42;`. Until you save, the row's still there. ## Entity states: what the tracker is really storing Every entity the context knows about sits in exactly one of five states. This is the vocabulary the change tracker thinks in: | State | Meaning | What `SaveChanges` does | |-------|---------|--------------------------| | `Added` | New, not yet in the DB (you called `Add`) | `INSERT` | | `Unchanged` | Loaded and untouched since | nothing | | `Modified` | A tracked property changed | `UPDATE` (changed columns) | | `Deleted` | Marked for removal (you called `Remove`) | `DELETE` | | `Detached` | The context isn't tracking it at all | nothing - it's invisible | You can read or set the state yourself through `ctx.Entry(...)`: ```csharp var post = ctx.Posts.First(p => p.Id == 42); Console.WriteLine(ctx.Entry(post).State); // Unchanged post.Title = "Edited"; Console.WriteLine(ctx.Entry(post).State); // Modified ``` *What just happened:* fresh from the query, the post is `Unchanged`. The instant you mutate a tracked property, the change tracker notices (detected when you inspect state or call `SaveChanges`) and moves the entity to `Modified`. You never set this by hand in the normal flow - the diff drives it. `ctx.Entry(post).State` is your window into what the tracker believes about any entity. > 💡 Want to see the whole picture? `ctx.ChangeTracker.Entries()` returns every tracked entity with its state - a great thing to dump when an update mysteriously does nothing (foreshadowing). ## SaveChanges: one batch, one transaction `SaveChanges` isn't a per-entity operation. It collects **all** pending changes across every tracked entity, then sends them together, wrapped in a single database transaction. ```csharp ctx.Posts.Add(new Post { Title = "Brand new" }); // Added ctx.Posts.First(p => p.Id == 7).Title = "Touched up"; // Modified ctx.Posts.Remove(ctx.Posts.First(p => p.Id == 9)); // Deleted int rows = ctx.SaveChanges(); Console.WriteLine($"{rows} rows affected"); // 3 rows affected ``` *What just happened:* three different operations - an insert, an update, and a delete - accumulated in the tracker. The single `SaveChanges` call issued all three inside one transaction: if any statement fails, the whole batch rolls back and your database is left untouched. The return value is the **number of rows affected**, here `3`. ## ⚠️ The detached-entity trap - the #1 web-app surprise Everything above assumes the entity was **loaded by this context**, so it's tracked. In a web app, that assumption quietly breaks - the single most common EF Core gotcha you'll hit. When a controller receives an object deserialized from a JSON request body, that object was created by the model binder - **not** loaded by your `DbContext`. It is `Detached`. The context has never seen it, has no snapshot for it, isn't watching it. So this does **nothing**: ```csharp // post came from the HTTP request body - it is DETACHED public IActionResult UpdatePost(Post post) { post.Title = "Changed in the controller"; ctx.SaveChanges(); // ⚠️ no UPDATE runs - the context isn't tracking `post` return Ok(); } ``` *What just happened:* nothing, and that's the trap. `post` is detached, so there's no snapshot to diff and no tracked state to mark `Modified`. `SaveChanges` looks at its (empty) change tracker, finds nothing to do, and returns `0`. No error, no exception - just a silent no-op that looks like a database bug. Three straightforward ways to fix it. **1. `ctx.Update(...)` - mark the whole entity Modified.** Simplest, but it sets *every* column to `Modified`, so the `UPDATE` rewrites all columns regardless of what actually changed. ```csharp ctx.Update(post); // attaches as Modified (all properties) ctx.SaveChanges(); // UPDATE Posts SET Title=..., Body=..., ... WHERE Id = post.Id ``` *What just happened:* `Update` attaches the detached object to the context and stamps it `Modified` wholesale, so `SaveChanges` has something to write. The cost: you overwrite every column from whatever's on `post` - including any the client didn't intend to change. **2. `Attach` + set state explicitly.** When you want finer control over which properties are dirty. ```csharp ctx.Attach(post); ctx.Entry(post).Property(p => p.Title).IsModified = true; // only Title ctx.SaveChanges(); ``` *What just happened:* `Attach` brings `post` in as `Unchanged`. Marking just `Title` as modified makes the resulting `UPDATE` touch only that one column - the same minimal-write behavior as the tracked path. **3. Load-then-copy.** The safest pattern, and what most production code does: load the real tracked entity, copy the allowed fields onto it, then save. ```csharp var existing = ctx.Posts.First(p => p.Id == post.Id); // tracked, with snapshot existing.Title = post.Title; // copy only what you allow ctx.SaveChanges(); // normal diff-and-UPDATE ``` *What just happened:* you're back on the happy path. `existing` is tracked, so the change tracker diffs it normally and writes only the columns you copied - and it guards against a client smuggling in fields you never meant to expose, since you control which properties get copied. > ⚠️ If an update "works locally but does nothing in the web app," your entity is almost certainly detached. Check `ctx.Entry(entity).State` - if it says `Detached`, that's your answer. ## Recap - A `DbContext` is a **unit of work** with a **change tracker**: it snapshots every entity it loads and diffs against that snapshot on save. - **You don't call an update method.** Load → mutate a property → `SaveChanges`, and EF emits an `UPDATE` for only the changed columns. Delete with `Remove`. - Every tracked entity has a **state** - `Added`, `Unchanged`, `Modified`, `Deleted`, or `Detached` - which you can inspect or set via `ctx.Entry(e).State`. - `SaveChanges` **batches** all pending inserts/updates/deletes into one transaction and returns the number of affected rows. - **Detached entities** (objects from a web request, not loaded by this context) aren't tracked - mutating them does nothing on save. Fix with `ctx.Update(...)`, `Attach` + per-property state, or the safer load-then-copy. ## Quick check ```quiz [ { "q": "You load a Post, set post.Title, and call SaveChanges. What SQL does EF Core generate?", "choices": ["Nothing - you forgot to call an Update method", "An UPDATE touching only the Title column", "An UPDATE rewriting every column on the row", "An INSERT for a new Post"], "answer": 1, "explain": "The entity is tracked, so SaveChanges diffs it against its snapshot, sees only Title changed, and emits an UPDATE for just that column." }, { "q": "A controller receives a Post deserialized from the request body, sets a property, and calls SaveChanges. Nothing changes in the database. Why?", "choices": ["The transaction rolled back", "The object is detached, so the context isn't tracking it and has nothing to save", "SaveChanges only handles inserts", "You must call Remove first"], "answer": 1, "explain": "An object from the request body was never loaded by this context, so it's Detached. With no snapshot and no tracked state, SaveChanges finds nothing to do - a silent no-op." }, { "q": "What does SaveChanges return?", "choices": ["The saved entity", "true if any change was written", "The number of rows affected", "The new primary key"], "answer": 2, "explain": "SaveChanges batches all pending changes into one transaction and returns the count of rows affected." } ] ``` --- # Relationships The mental model for this phase: **a relationship is a foreign key plus navigation properties.** That's it. The database side is the same boring thing it's always been - a column in one table that points at the primary key of another. EF Core's contribution is the *navigation property*: a C# reference (or list) that lets you walk from one object to its related objects without writing the join yourself. EF reads the **shapes** of your classes - a `List` here, a `Blog` reference there, a `BlogId` int - and infers the foreign key and the relationship from them. If the underlying concepts feel shaky - what a foreign key *is*, why a join table exists for many-to-many - read [Relationships & Keys](/guides/relationships-and-keys) first. This phase assumes you know the database side and focuses on how EF Core projects it onto C# classes. > 📝 We've been building a **blog** schema: `Blog`, `Post`, and now we'll add `Tag`. The relationships are the natural ones - a blog has many posts, and posts and tags belong to each other in a many-to-many. By the end you'll be able to read a pair of entity classes and predict exactly what foreign key EF will create. ## One-to-many: the FK convention The bread-and-butter relationship. One blog, many posts. You express it with **two navigation properties and one foreign key**, and EF Core wires the rest by convention. ```csharp public class Blog { public int Id { get; set; } public string Url { get; set; } = ""; public List Posts { get; set; } = new(); // one-to-many: a blog has many posts } public class Post { public int Id { get; set; } public string Title { get; set; } = ""; public int BlogId { get; set; } // foreign key (convention: