實體屬性

發行項
09/12/2023

模型中的每個實體類型都有一組屬性，EF Core 會從資料庫讀取和寫入這些屬性。如果您使用關係資料庫，實體屬性會對應至資料表資料行。

包含和排除的屬性

依照慣例，具有 getter 和 setter 的所有公用屬性都會包含在模型中。

您可以排除特定屬性，如下所示：

資料註解
Fluent API

public class Blog
{
    public int BlogId { get; set; }
    public string Url { get; set; }

    [NotMapped]
    public DateTime LoadedFromDatabase { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Ignore(b => b.LoadedFromDatabase);
}

資料行名稱

依照慣例，使用關係資料庫時，實體屬性會對應至名稱與屬性相同的資料表資料行。

如果您想要以不同的名稱設定資料行，可以執行下列程式碼片段：

資料註解
Fluent API

public class Blog
{
    [Column("blog_id")]
    public int BlogId { get; set; }

    public string Url { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Property(b => b.BlogId)
        .HasColumnName("blog_id");
}

資料行資料類型

使用關係資料庫時，資料庫提供者會根據屬性的 .NET 類型選取資料類型。它也會考慮其他中繼資料，例如設定的最大長度、屬性是否為主鍵的一部分等等。

例如，SQL Server 會將屬性對應至資料行，並將 string 屬性對應 DateTime 至 nvarchar(max) 資料行（或對應 nvarchar(450) 至做為索引鍵的屬性）。 datetime2(7)

您也可以設定資料行來指定資料行的確切資料類型。例如，下列程式碼會 Url 設定為長度上限 200 的非 unicode 字串，並以 Rating 有效位數 5 和小 2 數位數的十進位格式設定：

資料註解
Fluent API

public class Blog
{
    public int BlogId { get; set; }

    [Column(TypeName = "varchar(200)")]
    public string Url { get; set; }

    [Column(TypeName = "decimal(5, 2)")]
    public decimal Rating { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>(
        eb =>
        {
            eb.Property(b => b.Url).HasColumnType("varchar(200)");
            eb.Property(b => b.Rating).HasColumnType("decimal(5, 2)");
        });
}

最大長度

設定最大長度會為資料庫提供者提供有關指定屬性選擇之適當資料行資料類型的提示。長度上限僅適用于陣列資料類型，例如 string 和 byte[] 。

注意

Entity Framework 不會在將資料傳遞至提供者之前，對長度上限進行任何驗證。它由提供者或資料存放區來驗證是否適當。例如，當以 SQL Server 為目標時，超過最大長度會導致例外狀況，因為基礎資料行的資料類型不允許儲存多餘的資料。

在下列範例中，設定長度上限為 500 會導致在 SQL Server 上建立類型 nvarchar(500) 的資料行：

資料註解
Fluent API

public class Blog
{
    public int BlogId { get; set; }

    [MaxLength(500)]
    public string Url { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Property(b => b.Url)
        .HasMaxLength(500);
}

有效位數和小數位數

某些關聯式資料類型支援有效位數和小數位數 Facet;這些控制項可控制可儲存的值，以及資料行需要多少儲存體。哪些資料類型支援精確度和小數位數是資料庫相依的，但在大部分的資料庫 decimal 和 DateTime 類型中，都支援這些 Facet。對於 decimal 屬性，precision 會定義表示資料行將包含之任何值所需的位數上限，而小數位數則定義所需的小數位數上限。對於 DateTime 屬性，精確度會定義表示秒數所需的位數上限，而且不會使用小數位數。

注意

Entity Framework 不會在將資料傳遞至提供者之前，對有效位數或小數位數進行任何驗證。提供者或資料存放區會視需要驗證。例如，以 SQL Server 為目標時，資料類型 datetime 的資料行不允許設定有效位數，而 datetime2 0 到 7 之間可以包含有效位數。

在下列範例中，將屬性設定 Score 為有效位數 14 且小數位數 2 會導致在 SQL Server 上建立類型 decimal(14,2) 的資料行，而將 LastUpdated 屬性設定為具有有效位數 3 會導致類型 datetime2(3) 的資料行：

資料註解
Fluent API

public class Blog
{
    public int BlogId { get; set; }
    [Precision(14, 2)]
    public decimal Score { get; set; }
    [Precision(3)]
    public DateTime LastUpdated { get; set; }
}

在未先定義有效位數的情況下，永遠不會定義小數位數，因此定義小數位數的資料批註是 [Precision(precision, scale)] 。

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Property(b => b.Score)
        .HasPrecision(14, 2);

    modelBuilder.Entity<Blog>()
        .Property(b => b.LastUpdated)
        .HasPrecision(3);
}

在未先定義有效位數的情況下，永遠不會定義小數位數，因此用於定義小數位數的 Fluent API 是 HasPrecision(precision, scale) 。

Unicode

在某些關係資料庫中，有不同類型的代表 Unicode 和非 Unicode 文字資料。例如，在 SQL Server 中， nvarchar(x) 是用來代表 UTF-16 中的 Unicode 資料，而 varchar(x) 用來代表非 Unicode 資料（但請參閱 SQL Server UTF-8 支援的附注）。對於不支援此概念的資料庫，設定這沒有任何作用。

文字屬性預設會設定為 Unicode。您可以將資料行設定為非 Unicode，如下所示：

資料註解
Fluent API

public class Book
{
    public int Id { get; set; }
    public string Title { get; set; }

    [Unicode(false)]
    [MaxLength(22)]
    public string Isbn { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Book>()
        .Property(b => b.Isbn)
        .IsUnicode(false);
}

必要和選擇性屬性

如果屬性是有效的屬性，則會將其視為選擇性，以便包含 null 。如果 null 不是指派給屬性的有效值，則會將其視為必要的屬性。對應至關係資料庫架構時，必要屬性會建立為不可為 Null 的資料行，而選擇性屬性會建立為可為 Null 的資料行。

慣例

依照慣例，.NET 類型可以包含 Null 的屬性將會設定為選擇性，而 .NET 類型不能包含 Null 的屬性則會視需要設定。例如，所有具有 .NET 實值型別的屬性（ int 、 booldecimal 、等）都設定為必要，且所有具有可為 Null .NET 實值型別的屬性（ int? 、 bool?decimal? 、等等）都會設定為選擇性。

C# 8 引進了稱為可為 Null 參考型別（NRT）的新功能，允許批註參考型別，指出它們是否有效，以包含 Null。這項功能預設會在新的專案範本中啟用，但除非明確加入宣告，否則在現有專案中會保持停用。可為 Null 的參考類型會以下列方式影響 EF Core 的行為：

如果停用可為 Null 的參考型別，所有具有 .NET 參考型別的屬性都會依慣例設定為選擇性屬性（例如， string 。
如果啟用可為 Null 的參考類型，則會根據其 .NET 類型的 C# 可為 Null 性來設定屬性： string? 將會設定為選擇性，但 string 會視需要設定。

下列範例顯示具有必要和選擇性屬性的實體類型，並停用並啟用可為 Null 的參考功能：

沒有 NRT （預設值）
使用 NRT

public class CustomerWithoutNullableReferenceTypes
{
    public int Id { get; set; }

    [Required] // Data annotations needed to configure as required
    public string FirstName { get; set; }

    [Required] // Data annotations needed to configure as required
    public string LastName { get; set; }

    public string MiddleName { get; set; } // Optional by convention
}

public class Customer
{
    public int Id { get; set; }
    public string FirstName { get; set; } // Required by convention
    public string LastName { get; set; } // Required by convention
    public string? MiddleName { get; set; } // Optional by convention

    // Note the following use of constructor binding, which avoids compiled warnings
    // for uninitialized non-nullable properties.
    public Customer(string firstName, string lastName, string? middleName = null)
    {
        FirstName = firstName;
        LastName = lastName;
        MiddleName = middleName;
    }
}

建議使用可為 Null 的參考型別，因為它會將 C# 程式碼中表示的 Null 性流向 EF Core 的模型和資料庫，並消除使用 Fluent API 或資料批註來表示相同概念兩次。

注意

在現有專案上啟用可為 Null 的參考型別時請小心：先前設定為選擇性的參考型別屬性現在會視需要設定，除非它們已明確標注為可為 Null。管理關係資料庫架構時，這可能會導致產生移轉，以改變資料庫資料行的 Null 性。

如需可為 Null 參考型別以及如何搭配 EF Core 使用的詳細資訊，請參閱此功能的專用檔頁面。

明確設定

依慣例可設定為必要屬性，如下所示：

資料註解
Fluent API

public class Blog
{
    public int BlogId { get; set; }

    [Required]
    public string Url { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Property(b => b.Url)
        .IsRequired();
}

資料行定序

您可以在文字資料行上定義定序，以判斷其比較和排序方式。例如，下列程式碼片段會將 SQL Server 資料行設定為不區分大小寫：

modelBuilder.Entity<Customer>().Property(c => c.Name)
    .UseCollation("SQL_Latin1_General_CP1_CI_AS");

如果資料庫中的所有資料行都需要使用特定定序，請改為在資料庫層級定義定序。

有關 EF Core 對定序支援的一般資訊，請參閱定序檔頁面。

資料行批註

您可以設定在資料庫資料行上設定的任意文字批註，讓您在資料庫中記錄架構：

資料註解
Fluent API

public class Blog
{
    public int BlogId { get; set; }

    [Comment("The URL of the blog")]
    public string Url { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>()
        .Property(b => b.Url)
        .HasComment("The URL of the blog");
}

資料行順序

根據預設，使用移轉建立資料表時，EF Core 會先排序主鍵資料行，後面接著實體類型和擁有類型的屬性，最後是基底類型的屬性。不過，您可以指定不同的資料行順序：

資料註解
Fluent API

public class EntityBase
{
    [Column(Order = 0)]
    public int Id { get; set; }
}

public class PersonBase : EntityBase
{
    [Column(Order = 1)]
    public string FirstName { get; set; }

    [Column(Order = 2)]
    public string LastName { get; set; }
}

public class Employee : PersonBase
{
    public string Department { get; set; }
    public decimal AnnualSalary { get; set; }
}

Fluent API 可用來覆寫使用屬性所做的排序，包括解決不同屬性上的屬性指定相同的訂單號碼時所發生的任何衝突。

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Employee>(x =>
    {
        x.Property(b => b.Id)
            .HasColumnOrder(0);

        x.Property(b => b.FirstName)
            .HasColumnOrder(1);

        x.Property(b => b.LastName)
            .HasColumnOrder(2);
    });
}

請注意，在一般情況下，大部分的資料庫只支援建立資料表時排序資料行。這表示資料行順序屬性無法用來重新排序現有資料表中的資料行。