Sdílet prostřednictvím

Vlastnosti entity

  • Článek

Každý typ entity ve vašem modelu má sadu vlastností, které EF Core bude číst a zapisovat z databáze. Pokud používáte relační databázi, vlastnosti entity se mapují na sloupce tabulky.

Zahrnuté a vyloučené vlastnosti

Podle konvencebudou do modelu zahrnuty všechny veřejné vlastnosti s getterem a setter.

Konkrétní vlastnosti lze vyloučit následujícím způsobem:

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

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

Názvy sloupců

Podle konvence se při použití relační databáze vlastnosti entity mapují na sloupce tabulky se stejným názvem jako vlastnost.

Pokud dáváte přednost konfiguraci sloupců s různými názvy, můžete to udělat jako následující fragment kódu:

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

    public string Url { get; set; }
}

Datové typy sloupců

Při použití relační databáze zprostředkovatel databáze vybere datový typ na základě typu .NET vlastnosti. Bere také v úvahu další metadata, jako jsou nakonfigurovaná maximální délka, zda je vlastnost součástí primárního klíče atd.

Zprostředkovatel SQL Serveru například mapuje DateTime vlastnosti na datetime2(7) sloupce a string vlastnosti na nvarchar(max) sloupce (nebo nvarchar(450) pro vlastnosti, které se používají jako klíč).

Sloupce můžete také nakonfigurovat tak, aby určily přesný datový typ sloupce. Například následující kód konfiguruje Url jako řetězec bez kódování Unicode s maximální délkou 200 a Rating jako desítkové číslo s přesností 5 a měřítkem 2:

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; }
}

Maximální délka

Konfigurace maximální délky poskytuje zprostředkovateli databáze nápovědu o příslušném datovém typu sloupce, který se má pro danou vlastnost zvolit. Maximální délka se vztahuje pouze na datové typy pole, jako jsou string a byte[].

Poznámka

Entity Framework neprovádí žádné ověření maximální délky před předáním dat zprostředkovateli. Je na poskytovateli nebo úložišti dat, jestli je to vhodné. Pokud například cílíte na SQL Server, překročení maximální délky způsobí výjimku, protože datový typ podkladového sloupce nepovolí uložení nadbytečných dat.

V následujícím příkladu konfigurace maximální délky 500 způsobí vytvoření sloupce typu nvarchar(500) na SQL Serveru:

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

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

Přesnost a měřítko

Některé relační datové typy podporují přesnost a měřítko; určují, jaké hodnoty se dají uložit a kolik úložiště je pro sloupec potřeba. Které datové typy podporují přesnost a měřítko, závisí na konkrétní databázi, ale ve většině databází typy decimal a DateTime tyto vlastnosti skutečně podporují. U decimal vlastností definuje přesnost maximální počet číslic potřebných k vyjádření libovolné hodnoty, kterou sloupec bude obsahovat, a měřítko definuje maximální počet potřebných desetinných míst. U DateTime vlastností definuje přesnost maximální počet číslic potřebných k vyjádření zlomků sekund a měřítko se nepoužívá.

Poznámka

Entity Framework neprovádí žádné ověření přesnosti nebo škálování před předáním dat zprostředkovateli. Je na poskytovateli nebo úložišti dat, aby podle potřeby ověřili správnost. Například při cílení na SQL Server sloupec datového typu datetime neumožňuje nastavit přesnost, zatímco datetime2 může mít přesnost mezi 0 a 7 včetně.

V následujícím příkladu konfigurace vlastnosti Score s přesností 14 a škálováním 2 způsobí vytvoření sloupce typu decimal(14,2) na SQL Serveru a konfigurace vlastnosti LastUpdated přesnosti 3 způsobí sloupec typu datetime2(3):

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

Měřítko není nikdy definováno bez první definice přesnosti, takže datová poznámka pro definování měřítka je [Precision(precision, scale)].

Unicode

V některých relačních databázích existují různé typy, které představují textová data Unicode a jiná než Unicode. Například na SQL Serveru se nvarchar(x) používá k reprezentaci dat Unicode v UTF-16, zatímco varchar(x) slouží k reprezentaci dat, která nejsou unicode (ale podívejte se na poznámky na SQL Server UTF-8 podporují). Pro databáze, které tento koncept nepodporují, nemá konfigurace žádný vliv.

Ve výchozím nastavení jsou vlastnosti textu nakonfigurované jako Unicode. Sloupec můžete nakonfigurovat jako jiný než Unicode následujícím způsobem:

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

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

Povinné a volitelné vlastnosti

Vlastnost je považována za volitelnou, pokud může obsahovat null. Pokud null není platná hodnota, která se má přiřadit k vlastnosti, považuje se za požadovanou vlastnost. Při mapování na schéma relační databáze se požadované vlastnosti vytvoří jako sloupce bez hodnoty null a volitelné vlastnosti se vytvoří jako sloupce s možnou hodnotou null.

Konvence

Podle konvence bude vlastnost, jejíž typ .NET může obsahovat hodnotu null, nakonfigurována jako volitelná, zatímco vlastnosti, jejichž typ .NET nemůže obsahovat hodnotu null, budou nakonfigurovány podle potřeby. Například všechny vlastnosti s typy hodnot .NET (int, decimal, boolatd.) jsou nakonfigurovány podle potřeby a všechny vlastnosti s typy hodnot s možnou hodnotou null (int?, decimal?, bool?atd.) jsou nakonfigurovány jako volitelné.

C# 8 zavedl novou funkci s názvem nulovatelné odkazové typy (NRT), která umožňuje přidat k odkazovým typům poznámky, jež označují, zda mohou legálně obsahovat hodnotu null či nikoliv. Tato funkce je ve výchozím nastavení povolená v nových šablonách projektů, ale v existujících projektech zůstane zakázaná, pokud se explicitně nerozhodnete. Nulovatelné referenční typy ovlivňují chování EF Core následujícím způsobem:

  • Pokud jsou zakázané odkazové typy s možnou hodnotou null, jsou všechny vlastnosti s odkazovými typy .NET nakonfigurovány jako volitelné podle konvence (například string).
  • Pokud jsou povolené odkazové typy s možnou hodnotou null, vlastnosti se nakonfigurují na základě nullability jejich typu v C# .NET: string? bude nakonfigurováno jako volitelné, ale string bude nakonfigurováno jako povinné.

Následující příklad ukazuje typ entity s povinnými a volitelnými vlastnostmi, přičemž funkce odkazu s možnou hodnotou null je zakázaná a povolená:

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
}

Použití referenčních typů s možnou hodnotou null se doporučuje, protože umožňuje přenášet informaci o nullabilitě vyjádřené v kódu jazyka C# do modelu EF Core a do databáze. Tím se eliminuje nutnost použít rozhraní Fluent API nebo datové anotace k vyjádření stejného konceptu dvakrát.

Poznámka

Při povolování odkazových typů s možnou hodnotou null u existujícího projektu buďte opatrní: vlastnosti typu odkazu, které byly dříve nakonfigurovány jako volitelné, budou nyní nakonfigurovány podle potřeby, pokud nejsou explicitně opatřeny poznámkami, aby byly nullable. Při správě schématu relační databáze může dojít k vygenerování migrací, které změní hodnotu null sloupce databáze.

Další informace o odkazových typech s možnou hodnotou null a o tom, jak je používat s EF Core, najdete na vyhrazené stránce dokumentace pro tuto funkci.

Explicitní konfigurace

Vlastnost, která by byla volitelná podle konvence, je možné nakonfigurovat tak, aby se vyžadovala následujícím způsobem:

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

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

Řazení sloupců

Kolaci lze definovat u textových sloupců, čímž se určí jejich porovnávání a řazení. Například následující fragment kódu konfiguruje sloupec SQL Serveru tak, aby nerozlišovali malá a velká písmena:

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

Pokud všechny sloupce v databázi potřebují použít určitou kolaci, definujte kolaci na úrovni databáze.

Obecné informace o podpoře kolací v EF Core najdete na stránce dokumentace kolací .

Komentáře ke sloupcům

Můžete nastavit libovolný textový komentář, který se nastaví ve sloupci databáze, což vám umožní dokumentovat schéma v databázi:

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

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

Pořadí sloupců

Ve výchozím nastavení, když se vytváří tabulka s Migrace, EF Core nejprve řadí sloupce primárního klíče, následované vlastnostmi typu entity a vlastněnými typy, a nakonec vlastnosti ze základních typů. Můžete ale zadat jiné pořadí sloupců:

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; }
}

cs-CZ: Rozhraní Fluent API lze použít k přepsání pořadí určeného pomocí atributů, včetně řešení konfliktů, kdy atributy na různých vlastnostech stanovují stejnou pořadovou hodnotu.

Všimněte si, že v obecném případě většina databází podporuje řazení sloupců pouze při vytváření tabulky. To znamená, že atribut pořadí sloupců nelze použít k opětovnému uspořádání sloupců v existující tabulce.