使用 Fluent API 配置/映射属性和类型

使用实体框架 Code First 时，默认行为是使用一组 EF 中内嵌的约定将 POCO 类映射到表。但是，有时您无法或不想遵守这些约定，需要将实体映射到约定指示外的其他对象。

您主要可使用两种方法来配置 EF 使之在映射数据时绕开约定，这两种方法就是注释和 EF Fluent API。注释仅涵盖一部分 Fluent API 功能，因此有一些情况是无法使用注释实现的。本文旨在演示如何使用 Fluent API 来配置属性。

除了控制映射之外，Fluent API 和注释还可用于配置约束，如字段长度或必需属性，此时这些配置的约束将影响 Code First 所创建的数据库以及实体框架所执行的验证。

内容

简介

通常通过重写派生 DbContext 上的 OnModelCreating 方法来访问 Code First Fluent API。以下示例旨在显示如何使用 Fluent API 执行各种任务，您可以将代码复制出来并进行自定义，使之适用于您的模型。如果您想查看可按原样使用这些示例的模型，本文末尾提供了该模型。

属性映射

Property 方法用于为每个属于实体或复杂类型的属性配置特性。Property 方法用于获取给定属性的配置对象。配置对象上的选项特定于要配置的类型；例如，IsUnicode 只能用于字符串属性。

配置主键

有关主键的实体框架约定如下：

1. 您的类定义名称为“ID”或“Id”的属性

2. 或类名后跟“ID”或“Id”。

要显式将某个属性设置为主键，可使用 HasKey 方法。在以下示例中，使用了 HasKey 方法对 OfficeAssignment 类型配置 InstructorID 主键。

modelBuilder.Entity<OfficeAssignment>().HasKey(t => t.InstructorID);

配置组合主键

以下示例配置要作为 Department 类型的组合主键的 DepartmentID 和 Name 属性。

modelBuilder.Entity<Department>().HasKey(t => new { t.DepartmentID, t.Name });

关闭数值主键的标识

以下示例将 DepartmentID 属性设置为 System.ComponentModel.DataAnnotations.DatabaseGeneratedOption.None，以指示该值不由数据库生成。

modelBuilder.Entity<Department>().Property(t => t.DepartmentID) 
    .HasDatabaseGeneratedOption(DatabaseGeneratedOption.None);

指定属性的最大长度

在以下示例中，Name 属性不应超过 50 个字符。如果其值超过 50 个字符，则出现 DbEntityValidationException 异常。如果 Code First 基于此模型创建数据库，它还会将 Name 列的最大长度设置为 50 个字符。

modelBuilder.Entity<Department>().Property(t => t.Name).HasMaxLength(50);

将属性配置为必需

在下面的示例中，Name 属性是必需的。如果不指定 Name，则出现 DbEntityValidationException 异常。如果 Code First 基于此模型创建数据库，则用于存储此属性的列将不可为空。

modelBuilder.Entity<Department>().Property(t => t.Name).IsRequired();

指定不将 CLR 属性映射到数据库中的列

以下示例显示如何指定 CLR 类型的属性不映射到数据库中的列。

modelBuilder.Entity<Department>().Ignore(t => t.Budget);

将 CLR 属性映射到数据库中的特定列

以下示例将 Name CLR 属性映射到 DepartmentName 数据库列。

modelBuilder.Entity<Department>() 
    .Property(t => t.Name) 
    .HasColumnName("DepartmentName");

重命名模型中未定义的外键

如果您选择不对 CLR 类型定义外键，但希望指定它在数据库中应使用的名称，请编码如下：

modelBuilder.Entity<Course>() 
    .HasRequired(c => c.Department) 
    .WithMany(t => t.Courses) 
    .Map(m => m.MapKey("ChangedDepartmentID"));

配置字符串属性是否支持 Unicode 内容

默认情况下，字符串为 Unicode（SQL Server 中的 nvarchar）。您可以使用 IsUnicode 方法指定字符串应为 varchar 类型。

modelBuilder.Entity<Department>() 
    .Property(t => t.Name) 
    .IsUnicode(false);

配置数据库列的数据类型

HasColumnType 方法支持映射到相同基本类型的不同表示。使用此方法并不支持在运行时执行任何数据转换。请注意，IsUnicode 是将列设置为 varchar 的首选方法，因为它与数据库无关。

modelBuilder.Entity<Department>() 
    .Property(p => p.Name) 
    .HasColumnType("varchar");

配置复杂类型的属性

对复杂类型配置标量属性有两种方法。

可以对 ComplexTypeConfiguration 调用 Property。

modelBuilder.ComplexType<Details>() 
    .Property(t => t.Location) 
    .HasMaxLength(20);

也可以使用点表示法访问复杂类型的属性。

modelBuilder.Entity<OnsiteCourse>() 
    .Property(t => t.Details.Location) 
    .HasMaxLength(20);

将属性配置为用作乐观并发令牌

要指定实体中的某个属性表示并发令牌，可使用 ConcurrencyCheck 特性或 IsConcurrencyToken 方法。

modelBuilder.Entity<OfficeAssignment>() 
    .Property(t => t.Timestamp) 
    .IsConcurrencyToken();

也可以使用 IsRowVersion 方法将属性配置为数据库中的行版本。将属性设置为行版本会自动将它配置为乐观并发令牌。

modelBuilder.Entity<OfficeAssignment>() 
    .Property(t => t.Timestamp) 
    .IsRowVersion();

类型映射

将类指定为复杂类型

按约定，没有指定主键的类型将被视为复杂类型。在一些情况下，Code First 不会检测复杂类型（例如，如果您有名为“ID”的属性，但不想将它用作主键）。在此类情况下，您将使用 Fluent API 显式指定某类型是复杂类型。

modelBuilder.ComplexType<Details>();

指定不将 CLR 实体类型映射到数据库中的表

以下示例显示如何排除一个 CLR 类型，使之不映射到数据库中的表。

modelBuilder.Ignore<OnlineCourse>();

将 CLR 实体类型映射到数据库中的特定表

Department 的所有属性都将映射到名为 t_ Department 的表中的列。

modelBuilder.Entity<Department>()  
    .ToTable("t_Department");

您也可以这样指定架构名称：

modelBuilder.Entity<Department>()  
    .ToTable("t_ Department", "school");

映射“每个层次结构一张表 (TPH)”继承

在 TPH 映射情形下，继承层次结构中的所有类型都将映射到同一个表。鉴别器列用于标识每行的类型。使用 Code First 创建模型时，TPH 参与继承层次结构的类型所用的默认策略。默认情况下，鉴别器列将添加到名为“Discriminator”的表，且层次结构中每个类型的 CLR 类型名称都将用作鉴别器值。可以使用 Fluent API 修改默认行为。

modelBuilder.Entity<Course>()  
    .Map<Course>(m => m.Requires("Type").HasValue("Course"))  
    .Map<OnsiteCourse>(m => m.Requires("Type").HasValue("OnsiteCourse"));

映射“每个类型一张表 (TPT)”继承

在 TPT 映射情形下，所有类型分别映射到不同的表。仅属于某个基类型或派生类型的属性存储在映射到该类型的一个表中。映射到派生类型的表还会存储一个将派生表与基表联接的外键。

modelBuilder.Entity<Course>().ToTable("Course");  
modelBuilder.Entity<OnsiteCourse>().ToTable("OnsiteCourse");

映射“每个具体类一张表 (TPC)”继承

在 TPC 映射情形下，层次结构中的所有非抽象类型分别映射到不同的表。映射到派生类的表与映射到数据库中基类的表并无关系。类的所有属性（包括继承属性）都将映射到相应表的列。

调用 MapInheritedProperties 方法来配置每个派生类型。MapInheritedProperties 将继承自基类的所有属性重新映射到派生类的表中的新列。

注意：因为属于 TPC 继承层次结构的表并不使用同一个主键，因此，如果您让数据库生成的值具有相同标识种子，则在映射到子类的表中执行插入操作时，会产生重复的实体键。要解决此问题，可以为每个表指定不同的初始种子值，或关闭主键属性的标识。当使用 Code First 时，标识就是整数键属性的默认值。

modelBuilder.Entity<Course>() 
    .Property(c => c.CourseID) 
    .HasDatabaseGeneratedOption(DatabaseGeneratedOption.None); 
 
modelBuilder.Entity<OnsiteCourse>().Map(m => 
{ 
    m.MapInheritedProperties(); 
    m.ToTable("OnsiteCourse"); 
}); 
 
modelBuilder.Entity<OnlineCourse>().Map(m => 
{ 
    m.MapInheritedProperties(); 
    m.ToTable("OnlineCourse"); 
});

将实体类型的 CLR 属性映射到数据库中的多个表（实体拆分）

实体拆分允许一个实体类型的属性分散在多个表中。在以下示例中，Department 实体拆分到两个表中：Department 和 DepartmentDetails。实体拆分通过多次调用 Map 方法将一部分属性映射到特定表。

modelBuilder.Entity<Department>() 
    .Map(m => 
    { 
        m.Properties(t => new { t.DepartmentID, t.Name }); 
        m.ToTable("Department"); 
    }) 
    .Map(m => 
    { 
        m.Properties(t => new { t.DepartmentID, t.Administrator, t.StartDate, t.Budget }); 
        m.ToTable("DepartmentDetails"); 
    });

将多个实体类型映射到数据库中的一个表（表拆分）

以下示例将使用同一个主键的两个实体类型映射到同一个表。

modelBuilder.Entity<OfficeAssignment>() 
    .HasKey(t => t.InstructorID); 
             
modelBuilder.Entity<Instructor>() 
    .HasRequired(t => t.OfficeAssignment) 
    .WithRequiredPrincipal(t => t.Instructor); 
 
modelBuilder.Entity<Instructor>().ToTable("Instructor"); 
 
modelBuilder.Entity<OfficeAssignment>().ToTable("Instructor");

示例中使用的模型

以下 Code First 模型用于本页的示例。

using System.Data.Entity; 
using System.Data.Entity.ModelConfiguration.Conventions; 
// add a reference to System.ComponentModel.DataAnnotations DLL 
using System.ComponentModel.DataAnnotations; 
using System.Collections.Generic; 
using System; 
 
public class SchoolEntities : DbContext 
{ 
    public DbSet<Course> Courses { get; set; } 
    public DbSet<Department> Departments { get; set; } 
    public DbSet<Instructor> Instructors { get; set; } 
    public DbSet<OfficeAssignment> OfficeAssignments { get; set; } 
 
    protected override void OnModelCreating(DbModelBuilder modelBuilder) 
    { 
        // Configure Code First to ignore PluralizingTableName convention 
        // If you keep this convention then the generated tables will have pluralized names. 
        modelBuilder.Conventions.Remove<PluralizingTableNameConvention>(); 
    } 
} 
 
public class Department 
{ 
    public Department() 
    { 
        this.Courses = new HashSet<Course>(); 
    } 
    // Primary key 
    public int DepartmentID { get; set; } 
    public string Name { get; set; } 
    public decimal Budget { get; set; } 
    public System.DateTime StartDate { get; set; } 
    public int? Administrator { get; set; } 
 
    // Navigation property 
    public virtual ICollection<Course> Courses { get; private set; } 
} 
 
public class Course 
{ 
    public Course() 
    { 
        this.Instructors = new HashSet<Instructor>(); 
    } 
    // Primary key 
    public int CourseID { get; set; } 
 
    public string Title { get; set; } 
    public int Credits { get; set; } 
 
    // Foreign key 
    public int DepartmentID { get; set; } 
 
    // Navigation properties 
    public virtual Department Department { get; set; } 
    public virtual ICollection<Instructor> Instructors { get; private set; } 
} 
 
public partial class OnlineCourse : Course 
{ 
    public string URL { get; set; } 
} 
 
public partial class OnsiteCourse : Course 
{ 
    public OnsiteCourse() 
    { 
        Details = new Details(); 
    } 
 
    public Details Details { get; set; } 
} 
 
public class Details 
{ 
    public System.DateTime Time { get; set; } 
    public string Location { get; set; } 
    public string Days { get; set; } 
} 
     
public class Instructor 
{ 
    public Instructor() 
    { 
        this.Courses = new List<Course>(); 
    } 
 
    // Primary key 
    public int InstructorID { get; set; } 
    public string LastName { get; set; } 
    public string FirstName { get; set; } 
    public System.DateTime HireDate { get; set; } 
 
    // Navigation properties 
    public virtual ICollection<Course> Courses { get; private set; } 
} 
 
public class OfficeAssignment 
{ 
    // Specifying InstructorID as a primary 
    [Key()] 
    public Int32 InstructorID { get; set; } 
 
    public string Location { get; set; } 
 
    // When the Entity Framework sees Timestamp attribute 
    // it configures ConcurrencyCheck and DatabaseGeneratedPattern=Computed. 
    [Timestamp] 
    public Byte[] Timestamp { get; set; } 
 
    // Navigation property 
    public virtual Instructor Instructor { get; set; } 
}