Object-Relational Mappers

Understanding the Role of the Entity Framework Core

The Building Blocks of the Entity Framework

global using Microsoft.EntityFrameworkCore;
global using Microsoft.EntityFrameworkCore.ChangeTracking;
global using Microsoft.EntityFrameworkCore.Design;
global using Microsoft.EntityFrameworkCore.Metadata;
global using Microsoft.EntityFrameworkCore.Metadata.Builders;

global using System.ComponentModel.DataAnnotations;
global using System.ComponentModel.DataAnnotations.Schema;

The DbContext Class

The DbContext class is the ringleader component of EF Core and provides access to the database through the Database property. DbContext manages the ChangeTracker instance, exposes the virtual OnModelCreating() method for access to the Fluent API, holds all the DbSet<T> properties, and supplies the SaveChanges method to persist data to the data store. It is not used directly, but through a custom class that inherits DbContext. It is in the derived class that the DbSet<T> properties are placed.

Creating a Derived DbContext

namespace AutoLot.Samples;

public class ApplicationDbContext : DbContext
{
  public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
    : base(options)
  {
  }
}

Configuring the DbContext

The Design-Time DbContext Factory

namespace AutoLot.Samples;

public class ApplicationDbContextFactory : IDesignTimeDbContextFactory<ApplicationDbContext>
{
  public ApplicationDbContext CreateDbContext(string[] args)
  {
    var optionsBuilder = new DbContextOptionsBuilder<ApplicationDbContext>();
    var connectionString = @"..."
    optionsBuilder.UseSqlServer(connectionString);
    Console.WriteLine(connectionString);
    return new ApplicationDbContext(optionsBuilder.Options);
  }
}

OnModelCreating

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
  // Fluent API calls go here
}

Saving Changes

Transaction and Save Point Support

Explicit Transactions and Execution Strategies

Saving/Saved Changes Events

The DbSet<T> Class

For each entity type (T) in your object model, add a property of type DbSet<T> to the derived DbContext class. The DbSet<T> class is a specialized collection property used to interact with the database provider to read, add, update, or delete records in the database. Each DbSet<T> provides a number of core services for the database interactions, including translating LINQ queries against a DbSet<T> into the database queries.

The DbSet<T> type implements IQueryable<T> which enables the use of LINQ queries to retrieve records from the database. DbSet<T> also supports extension methods you would have learned in Chapter 13 like ForEach(), Select(), and All().

It is much more common to use the methods on the DbSet<T> properties than the more general methods on the derived DbContext.

The ChangeTracker

The ChangeTracker instance tracks the state for objects loaded into DbSet<T> within a DbContext instance.

If you need to check the state of an object:

EntityState state = context.Entry(entity).State;

ChangeTracker Events

public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
  : base(options)
{
...
  ChangeTracker.StateChanged += ChangeTracker_StateChanged;
  ChangeTracker.Tracked += ChangeTracker_Tracked;
}

The StateChanged Event

private void ChangeTracker_StateChanged(object sender, EntityStateChangedEventArgs e)
{
  if (e.OldState == EntityState.Modified && e.NewState == EntityState.Unchanged)
  {
    Console.WriteLine($"An entity of type {e.Enttry.Entity.GetType().Name} was updated.");
  }
}

The Tracked Event

Resetting DbContext State

Entities

Entity Properties and Database Columns

Table Mapping Schemes

Table-Per-Hierarchy Mapping

public class ApplicationDbContext : DbContext
{
  public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
    : base(options) { }
  public DbSet<Car> Cars { get; set; }
}

Table-per-Type Mapping

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
  modelBuilder.Entity<BaseEntity>().ToTable("BaseEntities");
  modelBuilder.Entity<Car>().ToTable("Cars");
}

Navigation Properties and Foreign Keys

Navigation properties represent how entity classes relate to each other and enable code to traverse from one entity instance to another. By definition, a navigation property is any property that maps to a nonscalar type as defined by the database provider. In practice, navigation properties map to another entity (called reference navigation properties) or a collection of another entity (called collection navigation properties). On the database side, navigation properties are translated into foreign key relationships between tables. EF Core directly supports one-to-one, one-to-many, and many-to-many relationships. Entity classes can also have navigation properties that point back to themselves.

Missing Foreign Key Properties

One-to-Many Relationships

public abstract class BaseEntity
{
  public int Id { get; set; }
  public byte[] TimeStamp { get; set; }
}

public class Make : BaseEntity
{
  public string Name { get; set; }
  public IEnumerable<Car> Cars { get; set; } = new List<Car>();
}

public class Car : BaseEntity
{
  public string Color { get; set; }
  public string PetName { get; set; }
  public int MakeId { get; set; }
  public Make MakeNavigation { get; set; }
}

public DbSet<Car> Cars { get; set; }
public DbSet<Make> Makes [ get; set; }

One-to-One Relationships

public class Radio : BaseEntity
{
  public bool HasTweeters { get; set; }
  public bool HasSubWoofers { get; set; }
  public string RadioId { get; set; }
  public int CarId { get; set; }
  public Car CarNavigation { get; set; }
}

public class Car : BaseEntity
{
  public Radio RadioNavigation { get; set; }
}

public DbSet<Radio> Radios { get; set; }

Many-to-Many Relationships

public class Driver : BaseEntity
{
  public string FirstName { get; set; }
  public string LastName { get; set; }
  public IEnumerable<Car> Cars { get; set; } = new List<Car>();
}

public class Car : BaseEntity
{
  public string Color { get; set; }
  public string PetName { get; set; }
  public int MakeId { get; set; }
  public Make MakeNavigation { get; set; }
  public Radio RadioNavigation { get; set; }
  public IEnumerable<Driver> Drivers { get; set; } = new List<Driver>();
}

Many-to-Many Prior to EF Core 5

public class Driver
{
...
  public IEnumerable<CarDriver> CarDrivers { get; set; }
}

public class Car
{
...
  public IEnumerable<CarDriver> CarDrivers { get; set; }
}

public class CarDriver
{
  public int CarId {get;set;}
  public Car CarNavigation {get;set;}
  public int DriverId {get;set;}
  public Driver DriverNavigation {get;set;}
}

Cascade behavior

Optional Relationships

Required Relationships

Entity Conventions

The conventions are always enabled unless overruled by data annotations or code in the Fluent API.

Mapping Properties to Columns

Overriding EF Core Conventions

protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
{
  configurationBuilder.Properties<string>().HaveMaxLength(50);
}

Entity Framework Data Annotations

Data annotations are C# attributes that are used to further shape your entities. Data annotations override any conflicting conventions.

Annotations and Navigation Properties

The Fluent API

Class and Property Methods

Class and Property Mapping

[Table("Inventory", Schema="dbo")]
[Index(nameof(MakeId), Name = "IX_Inventory_MakeId")]
public class Car : BaseEntity
{
  private string_color;
  [Required, StringLength(50)]
  public string Color
  {
    get => _color;
    set => _color = value;
  }
  [Required, StringLength(50)]
  public string PetName { get; set; }
  public int MakeId { get; set; }
  [ForeignKey(nameof(MakeId))]
  public Make MakeNavigation { get; set; }
  public Radio RadioNavigation { get; set; }
  [InverseProperty(nameof(Driver.Cards))]
  public IEnumerable<Driver> Drivers { get; set; }
}

modelBuilder.Entity<Car>(entity =>
{
  entity.ToTable("Inventory", "dbo");
});

Keys and Indices

modelBuilder.Entity<Car>(entity =>
{
  entity.ToTable("Inventory","dbo");
  entity.HadKey(e=>e.Id);
});

entity.HasIndex(e => e.MakeId, "IX_Inventory_MakeId").IsUnique();

Field Size and Nullability

modelBuilder.Entity<Car>(entity =>
{
...
  entity.Property(e => e.Color)
    .IsRequired()
    .HasMaxLength(50);
  entity.Property(e => e.PetName)
    .IsRequired()
    .HasMaxLength(50);
});

Default Values

RowVersion/Concurrency Tokens

SQL Server Sparse Columns

Computed Columns

Check Constraints

One-to-Many Relationships

One-to-One Relationships

Many-to-Many Relationships

Excluding Entities from Migrations

Using IEntityTypeConfiguration Classes

Conventions, Annotations, and the Fluent API, Oh My!

 At this point in the chapter, you might be wondering which of the three options to use to shape your entities and their relationship to each other and the data store. The answer is all three. The conventions are always active (unless you override them with data annotations or the Fluent API). The data annotations can do almost everything the Fluent API methods can do and keep the information in the entity class themselves, which can increase code readability and support. The Fluent API is the most powerful of all three. Whether you use data annotations or the Fluent API, know that data annotations overrule the built-in conventions, and the methods of the Fluent API overrule everything.

Owned Entity Types