Entitás tulajdonságai

Cikk
01/15/2025

A modell minden entitástípusa rendelkezik egy tulajdonságkészlettel, amelyet az EF Core az adatbázisból fog olvasni és írni. Ha relációs adatbázist használ, az entitástulajdonságok táblázatoszlopokra vannak leképezve.

Belefoglalt és kizárt tulajdonságok

A konvenciószerint a modell tartalmazza a getter és a setter összes nyilvános tulajdonságát.

Az egyes tulajdonságok az alábbiak szerint zárhatók ki:

Adat annotációk
Fluent API-kezelés

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

Oszlopnevek

Konvenció szerint a relációs adatbázis használatakor az entitástulajdonságok a tulajdonsággal azonos nevű táblaoszlopokra vannak leképezve.

Ha más néven szeretné konfigurálni az oszlopokat, ezt a következő kódrészlettel teheti meg:

adatjegyzetek
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");
}

Oszlop adattípusai

Relációs adatbázis használatakor az adatbázis-szolgáltató kiválaszt egy adattípust a tulajdonság .NET-típusa alapján. Figyelembe veszi az egyéb metaadatokat is, például a konfigurált maximális hossz, hogy a tulajdonság egy elsődleges kulcs része-e stb.

Az SQL Server-szolgáltató például a DateTime tulajdonságokat a datetime2(7) oszlopokra képezi le, a string tulajdonságokat pedig a nvarchar(max) oszlopokra (vagy a kulcsként használt tulajdonságokat a nvarchar(450) oszlopokra).

Az oszlopokat úgy is konfigurálhatja, hogy pontos adattípust adjon meg egy oszlophoz. A következő kód például a Url nem Unicode-sztringként konfigurálja, amelynek maximális hossza 200, és Rating decimálisként, 5 pontosságával és 2skálájával:

adatjegyzetek
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)");
        });
}

Maximális hossz

A maximális hossz konfigurálása tippeket ad az adatbázis-szolgáltatónak az adott tulajdonsághoz kiválasztandó oszlop adattípusára vonatkozóan. A maximális hossz csak tömbadattípusokra vonatkozik, például string és byte[].

Jegyzet

Az Entity Framework nem ellenőrzi a maximális hosszt, mielőtt adatokat ad át a szolgáltatónak. Szükség esetén az ellenőrzés a szolgáltató vagy az adattár feladata. Ha például az SQL Servert célozza, a maximális hossz túllépése kivételt eredményez, mivel a mögöttes oszlop adattípusa nem teszi lehetővé a felesleges adatok tárolását.

Az alábbi példában az 500-ra vonatkozó maximális hossz konfigurálásával létrejön egy nvarchar(500) típusú oszlop az SQL Serveren:

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

Pontosság és skálázás

Egyes relációs adattípusok támogatják a pontosságot és a méretezési aspektusokat; ezek szabályozzák, hogy milyen értékek tárolhatók, és mennyi tárhelyre van szükség az oszlophoz. A pontosságot és a skálázást támogató adattípusok adatbázis-függőek, de a legtöbb adatbázisban decimal és DateTime típusok támogatják ezeket az aspektusokat. A decimal tulajdonságok esetében a pontosság határozza meg az oszlopban található értékek kifejezéséhez szükséges számjegyek maximális számát, a méretezés pedig a szükséges tizedesjegyek maximális számát határozza meg. A DateTime tulajdonságok esetében a pontosság határozza meg a másodperc törtrészeinek kifejezéséhez szükséges számjegyek maximális számát, és a skálázás nem használatos.

Jegyzet

Az Entity Framework nem végez ellenőrzést a pontosságon vagy a skálázáson, mielőtt adatokat ad át a szolgáltatónak. Az adatok megfelelő módon történő ellenőrzése a szolgáltatótól vagy az adattárolótól függ. Az SQL Server megcélzásakor például egy datetime adattípusú oszlop nem teszi lehetővé a pontosság beállítását, míg egy datetime2 0 és 7 közötti pontosságú lehet.

Az alábbi példában a Score tulajdonság 14 pontosságúra és a 2. skálázásra való konfigurálásával létrejön egy decimal(14,2) típusú oszlop az SQL Serveren, és ha a LastUpdated tulajdonságot 3 pontosságúra konfigurálja, az datetime2(3)típusú oszlopot eredményez:

adathozzáfűzések
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; }
}

A skálát soha nem határozzák meg a pontosság meghatározása előtt, így a skála meghatározására szolgáló adatazonosító [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);
}

A skálázás soha nem határozható meg a pontosság első definiálása nélkül, ezért a skálázás definiálásához használt Fluent API HasPrecision(precision, scale).

Unicode

Egyes relációs adatbázisokban különböző típusok jelölik a Unicode és a nem Unicode szöveges adatokat. Az SQL Serverben például a nvarchar(x) az Unicode-adatok UTF-16 formátumban való ábrázolására szolgál, míg a varchar(x) a nem Unicode-adatokra vonatkozik. (Azonban lásd az SQL Server UTF-8 támogatásának megjegyzéseit.) Az olyan adatbázisok esetében, amelyek nem támogatják ezt a koncepciót, a konfigurálásnak nincs hatása.

A szövegtulajdonságok alapértelmezés szerint Unicode-ként vannak konfigurálva. Az oszlopokat az alábbiak szerint konfigurálhatja nem Unicode-ként:

Adatjelölések
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);
}

Kötelező és nem kötelező tulajdonságok

A tulajdonság akkor tekinthető opcionálisnak, ha érvényes, hogy tartalmazza a null-t. Ha null nem egy tulajdonsághoz hozzárendelendő érvényes érték, akkor kötelező tulajdonságnak minősül. Relációsadatbázis-sémára való leképezéskor a szükséges tulajdonságok nem null értékű oszlopokként jönnek létre, a választható tulajdonságok pedig null értékű oszlopokként jönnek létre.

Egyezmények

Konvenció szerint az a tulajdonság, amelynek .NET-típusa null értéket tartalmazhat, nem kötelezőként lesz konfigurálva, míg azok a tulajdonságok, amelyek .NET-típusa nem tartalmazhat null értéket, szükség szerint lesznek konfigurálva. A .NET-értéktípusokkal (int, decimal, boolstb.) rendelkező tulajdonságok például igény szerint vannak konfigurálva, a null értékű .NET-értéktípusokkal (int?, decimal?, bool?stb.) rendelkező tulajdonságok pedig választhatóként vannak konfigurálva.

A C# 8 bevezette a null értékű referenciatípusok (NRT)nevű új funkciót, amely lehetővé teszi a hivatkozástípusok jegyzetekkel való megjelölését, jelezve, hogy érvényes-e arra, hogy null vagy nem tartalmúak legyenek. Ez a funkció alapértelmezés szerint engedélyezve van az új projektsablonokban, de a meglévő projektekben továbbra is le van tiltva, kivéve, ha kifejezetten engedélyezte. A null értékű hivatkozástípusok a következő módon befolyásolják az EF Core működését:

Ha a null értékű hivatkozástípusok le vannak tiltva, a .NET-referenciatípusokkal rendelkező összes tulajdonság konvenció szerint választhatóként van konfigurálva (például string).
Ha engedélyezve vannak a null értékű hivatkozástípusok, a tulajdonságok a .NET-típus C#-nullabilitása alapján lesznek konfigurálva: string? nem kötelezőként lesz konfigurálva, de a string szükség szerint lesz konfigurálva.

Az alábbi példa egy olyan entitástípust mutat be, amely kötelező és nem kötelező tulajdonságokkal rendelkezik, a null értékű hivatkozási funkció pedig le van tiltva vagy engedélyezve van.

NRT (alapértelmezett) nélkül
NRT-vel

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

A nullálható referenciatípusok használata ajánlott, mivel a C#-kódban kifejezett nullitást átadja az EF Core modelljének és az adatbázisnak, és elkerüli a Fluent API vagy az Adatjegyzetek használatát ugyanazon fogalom kétszeri kifejezésére.

Jegyzet

Körültekintően járjon el, ha null értékű hivatkozástípusokat engedélyez egy meglévő projektben: a korábban nem kötelezőként konfigurált referenciatípus-tulajdonságok mostantól szükség szerint lesznek konfigurálva, kivéve, ha explicit módon null értékűre vannak állítva. Relációs adatbázisséma kezelésekor előfordulhat, hogy migrálások jönnek létre, amelyek megváltoztatják az adatbázisoszlop nullképességét.

A null értékű referenciatípusokról és azok EF Core-beli használatáról további információért lásd a funkció dedikált dokumentációs oldalát.

Explicit konfiguráció

A konvenció szerint nem kötelező tulajdonság konfigurálható úgy, hogy az a következőképpen legyen kötelező:

Adatannotációk
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();
}

Oszlopkollációk

A rendezés definiálható szövegoszlopokon, amelyek meghatározzák az összehasonlítás módját és sorrendjét. Az alábbi kódrészlet például úgy állít be egy SQL Server oszlopot, hogy az ne legyen érzékeny a kis- és nagybetűkre.

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

Ha egy adatbázis összes oszlopának egy bizonyos rendezést kell használnia, adja meg a rendezést az adatbázis szintjén.

A rendezés EF Core-támogatásával kapcsolatos általános információk a rendezési dokumentációoldalán találhatók.

Oszlop megjegyzései

Beállíthat egy tetszőleges szöveges megjegyzést, amely be lesz állítva az adatbázis oszlopában, így dokumentálhatja a sémát az adatbázisban:

Adatjelölések
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");
}

Oszlopsorrend

Alapértelmezés szerint, amikor egy táblát hoz létre a Migrationshasználatával, az EF Core először az elsődleges kulcs oszlopait rendezi, majd az entitástípus és a saját típusok tulajdonságait, végül pedig az alaptípusok tulajdonságait. Megadhat azonban egy másik oszlopsorrendet:

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

A Fluent API az attribútumokkal végzett rendelés felülbírálására használható, beleértve az ütközések feloldását is, ha a különböző tulajdonságok attribútumai ugyanazt a rendelésszámot adják meg.

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

Vegye figyelembe, hogy a legtöbb adatbázis általában csak a tábla létrehozásakor támogatja az oszlopok rendezését. Ez azt jelenti, hogy az oszloprend attribútum nem használható egy meglévő tábla oszlopainak átrendezésére.

Megosztás a következőn keresztül:

Entitás tulajdonságai

Belefoglalt és kizárt tulajdonságok

Oszlopnevek

Oszlop adattípusai

Maximális hossz

Pontosság és skálázás

Unicode

Kötelező és nem kötelező tulajdonságok

Egyezmények

Explicit konfiguráció

Oszlopkollációk

Oszlop megjegyzései

Oszlopsorrend

További források