Vlastnosti entit

  • Č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 konvence budou 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ý typ sloupce

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 je nakonfigurovaná maximální délka, zda je vlastnost součástí primárního klíče atd.

SQL Server například mapuje DateTime vlastnosti na datetime2(7) sloupce a string vlastnosti na nvarchar(max) sloupce (nebo na nvarchar(450) 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 desetinnou čárkou 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, například 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 omezující vlastnosti měřítka; tyto ovládací prvky 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 škálování jsou závislé na databázi, ale ve většině databází decimal a DateTime typů tyto omezující vlastnosti 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. Podle potřeby je na poskytovateli nebo úložišti dat. Například při cílení na SQL Server sloupec datového typu datetime neumožňuje nastavit přesnost, zatímco datetime2 sloupec může mít přesnost mezi 0 a 7 včetně.

V následujícím příkladu Score konfigurace vlastnosti s přesností 14 a škálování 2 způsobí vytvoření sloupce typu decimal(14,2) na SQL Serveru a konfigurace LastUpdated vlastnosti s přesností 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 se nikdy nedefinuje 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 v SQL Serveru nvarchar(x) se používá k reprezentaci dat Unicode v UTF-16, zatímco varchar(x) se používá k reprezentaci dat jiného než Unicode (ale viz poznámky na podporu UTF-8 SYSTÉMU SQL Server). 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 je platná pro to, aby obsahovala null. Pokud null není platná hodnota, která má být přiřazena k vlastnosti, je považována za povinnou 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, bool, atd.) jsou nakonfigurovány jako povinné 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 odkazovatelné odkazové typy s možnou hodnotou null( NRT), která umožňuje, aby odkazové typy byly opatřeny poznámkami, které označují, zda jsou platné, aby obsahovaly hodnotu null nebo ne. 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. Odkazové typy s možnou hodnotou null 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 budou nakonfigurovány na základě hodnoty nullability jazyka C#jejich typu .NET: string? budou nakonfigurovány jako volitelné, ale string budou nakonfigurovány podle potřeby.

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 tokuje hodnotu nullability vyjádřenou v kódu jazyka C# do modelu EF Core a do databáze a obviňuje použití rozhraní Fluent API nebo datových poznámek 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; }
}

Kolace sloupců

Kolaci je možné definovat u textových sloupců a určit jejich porovná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 ef Core pro kolace najdete na stránce dokumentace ke kolaci.

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í při vytváření tabulky s migracemi ef Core nejprve objednává sloupce primárního klíče, za nimiž následují vlastnosti typu entity a vlastněné 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; }
}

Rozhraní Fluent API lze použít k přepsání řazení provedených pomocí atributů, včetně řešení jakýchkoli konfliktů, když atributy na různých vlastnostech určují stejné číslo objednávky.

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.