Entiteitseigenschappen

Elk entiteitstype in uw model heeft een set eigenschappen, die EF Core uit de database leest en schrijft. Als u een relationele database gebruikt, worden entiteitseigenschappen toegewezen aan tabelkolommen.

Opgenomen en uitgesloten eigenschappen

Volgens de -conventieworden alle publieke eigenschappen met een getter en een setter opgenomen in het model.

Specifieke eigenschappen kunnen als volgt worden uitgesloten:

gegevensaantekeningen

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

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

Fluent API

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

Kolomnamen

Bij het gebruik van een relationele database worden entiteitseigenschappen standaard toegewezen aan tabelkolommen met dezelfde naam als de eigenschap.

Als u uw kolommen liever met verschillende namen wilt configureren, kunt u dit doen als het volgende codefragment:

gegevensaantekeningen

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

    public string Url { get; set; }
}

Fluent API

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

Kolomgegevenstypen

Wanneer u een relationele database gebruikt, selecteert de databaseprovider een gegevenstype op basis van het .NET-type van de eigenschap. Er wordt ook rekening gehouden met andere metagegevens, zoals de geconfigureerde maximale lengte, of de eigenschap deel uitmaakt van een primaire sleutel, enzovoort.

De SQL Server-provider wijst bijvoorbeeld DateTime eigenschappen toe aan datetime2(7) kolommen en string eigenschappen toe aan nvarchar(max) kolommen (of aan nvarchar(450) voor eigenschappen die worden gebruikt als sleutel).

U kunt uw kolommen ook configureren om een exact gegevenstype voor een kolom op te geven. Met de volgende code wordt bijvoorbeeld Url geconfigureerd als een niet-Unicode-tekenreeks met maximale lengte van 200 en Rating als decimaal met precisie van 5 en schaal van 2:

gegevensaantekeningen

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

Fluent API

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

Maximumlengte

Het configureren van een maximale lengte biedt een hint aan de databaseprovider over het juiste kolomgegevenstype om voor een bepaalde eigenschap te kiezen. De maximale lengte is alleen van toepassing op matrixgegevenstypen, zoals string en byte[].

Notitie

Entity Framework voert geen validatie van de maximale lengte uit voordat gegevens worden doorgegeven aan de provider. Het is aan de provider of het gegevensarchief om, indien van toepassing, te valideren. Als u bijvoorbeeld SQL Server wilt instellen, resulteert het overschrijden van de maximale lengte in een uitzondering, omdat het gegevenstype van de onderliggende kolom niet toestaat dat overtollige gegevens worden opgeslagen.

Als u in het volgende voorbeeld een maximale lengte van 500 configureert, wordt een kolom van het type nvarchar(500) gemaakt op SQL Server:

gegevensaantekeningen

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

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

Fluent API

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

Precisie en schaal

Sommige relationele gegevenstypen ondersteunen de precisie en schaal van facetten; deze bepalen welke waarden kunnen worden opgeslagen en hoeveel opslagruimte er nodig is voor de kolom. Welke gegevenstypen precisie en schaal ondersteunen, zijn afhankelijk van databases, maar in de meeste databases decimal en DateTime typen worden deze facetten wel ondersteund. Voor decimal eigenschappen definieert precisie het maximum aantal cijfers dat nodig is om een willekeurige waarde uit te drukken die de kolom bevat en de schaal bepaalt het maximum aantal decimalen dat nodig is. Voor DateTime eigenschappen definieert precisie het maximum aantal cijfers dat nodig is om fracties van seconden uit te drukken en wordt de schaal niet gebruikt.

Notitie

Entity Framework voert geen validatie van precisie of schaal uit voordat gegevens worden doorgegeven aan de provider. Het is aan de provider of het gegevensarchief om waar nodig te valideren. Bijvoorbeeld, wanneer u zich richt op SQL Server, staat een kolom van het gegevenstype datetime niet toe dat de precisie wordt ingesteld, terwijl een kolom van het type datetime2 een precisie kan hebben tussen 0 en 7, inclusief.

In het volgende voorbeeld zorgt het configureren van de eigenschap Score voor precisie 14 en schaal 2 ervoor dat een kolom van het type decimal(14,2) wordt gemaakt op SQL Server. Als u de eigenschap LastUpdated zo configureert dat precisie 3 is, wordt een kolom van het type datetime2(3)veroorzaakt:

gegevensaantekeningen

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

Schaal wordt nooit gedefinieerd zonder eerst precisie te definiëren, dus de gegevensaantekening voor het definiëren van de schaal is [Precision(precision, scale)].

Fluent API

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

Schaal wordt nooit gedefinieerd zonder eerst precisie te definiëren, dus de Fluent-API voor het definiëren van de schaal is HasPrecision(precision, scale).

Unicode

In sommige relationele databases bestaan er verschillende typen om Unicode- en niet-Unicode-tekstgegevens weer te geven. In SQL Server wordt nvarchar(x) bijvoorbeeld gebruikt om Unicode-gegevens in UTF-16 weer te geven, terwijl varchar(x) wordt gebruikt om niet-Unicode-gegevens weer te geven (maar zie de opmerkingen in SQL Server UTF-8-ondersteuning). Voor databases die dit concept niet ondersteunen, heeft het configureren hiervan geen effect.

Teksteigenschappen zijn standaard geconfigureerd als Unicode. U kunt een kolom als volgt configureren als niet-Unicode:

gegevensaantekeningen

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

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

Fluent API

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

Vereiste en optionele eigenschappen

Een eigenschap wordt als optioneel beschouwd als deze geldig is om nullte bevatten. Als null geen geldige waarde is die aan een eigenschap moet worden toegewezen, wordt deze beschouwd als een vereiste eigenschap. Wanneer de toewijzing aan een relationeel databaseschema wordt toegewezen, worden de vereiste eigenschappen gemaakt als niet-nullable kolommen en worden optionele eigenschappen gemaakt als null-kolommen.

Verdragen

Volgens de conventie wordt een eigenschap waarvan het .NET-type null kan bevatten, geconfigureerd als optioneel, terwijl eigenschappen waarvan het .NET-type geen null mag bevatten, naar behoefte worden geconfigureerd. Alle eigenschappen met .NET-waardetypen (int, decimal, bool, enzovoort) zijn bijvoorbeeld geconfigureerd als vereist en alle eigenschappen met nullable .NET-waardetypen (int?, decimal?, bool?, enzovoort) zijn geconfigureerd als optioneel.

C# 8 heeft een nieuwe functie geïntroduceerd met de naam nullable reference types (NRT), waarmee verwijzingstypen kunnen worden geannoteerd, waarmee wordt aangegeven of deze geldig zijn om null te bevatten of niet. Deze functie is standaard ingeschakeld in nieuwe projectsjablonen, maar blijft uitgeschakeld in bestaande projecten, tenzij expliciet is aangemeld. Nullable-verwijzingstypen zijn van invloed op het gedrag van EF Core op de volgende manier:

• Als nullable-verwijzingstypen zijn uitgeschakeld, worden alle eigenschappen met .NET-verwijzingstypen geconfigureerd als optioneel volgens conventie (bijvoorbeeld string).
• Als null-verwijzingstypen zijn ingeschakeld, worden eigenschappen geconfigureerd op basis van de C#-null-waarde van het .NET-type: string? wordt geconfigureerd als optioneel, maar string wordt zo nodig geconfigureerd.

In het volgende voorbeeld ziet u een entiteitstype met vereiste en optionele eigenschappen, waarbij de null-referentiefunctie is uitgeschakeld en ingeschakeld:

zonder NRT (standaardinstelling)

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
}

met NRT-

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

Het gebruik van nullable referentietypen wordt aanbevolen omdat het de nullability die in C#-code wordt uitgedrukt naar het model en de database doorstroomt, en het daardoor overbodig maakt om de Fluent-API of data-annotaties te gebruiken om hetzelfde concept tweemaal uit te drukken.

Notitie

Wees voorzichtig bij het inschakelen van null-referentietypen voor een bestaand project: eigenschappen van verwijzingstypen die eerder als optioneel zijn geconfigureerd, worden nu geconfigureerd als vereist, tenzij ze expliciet worden geannoteerd om nullable te zijn. Bij het beheren van een relationeel databaseschema kan dit ertoe leiden dat migraties worden gegenereerd waardoor de null-waarde van de databasekolom wordt gewijzigd.

Zie voor meer informatie over null-referentietypen en hoe u ze kunt gebruiken met EF Core, de speciale documentatiepagina voor deze functie.

Expliciete configuratie

Een eigenschap die over het algemeen optioneel zou zijn, kan als volgt worden geconfigureerd om verplicht te zijn:

gegevensaantekeningen

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

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

Fluent API

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

Kolomsorteringen

Een sortering kan worden gedefinieerd voor tekstkolommen, om te bepalen hoe deze worden vergeleken en geordend. Met het volgende codefragment wordt bijvoorbeeld een SQL Server-kolom zo geconfigureerd dat deze niet hoofdlettergevoelig is:

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

Als alle kolommen in een database een bepaalde sortering moeten gebruiken, definieert u in plaats daarvan de sortering op databaseniveau.

Algemene informatie over EF Core-ondersteuning voor sorteringen vindt u op de documentatiepagina voor sortering.

Kolomopmerkingen

U kunt een willekeurige tekstcommentaar instellen die wordt ingesteld op de databasekolom, zodat u uw schema in de database kunt documenteren:

gegevensaantekeningen

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

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

Fluent API-

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

Kolomvolgorde

Bij het maken van een tabel met Migrationsworden primaire-sleutelkolommen eerst door EF Core gesorteerd, gevolgd door eigenschappen van het entiteitstype en de eigendomstypen en ten slotte eigenschappen van basistypen. U kunt echter een andere kolomvolgorde opgeven:

gegevensaantekeningen

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

De Fluent-API kan worden gebruikt om volgorde te overschrijven die is gemaakt met kenmerken, waaronder het oplossen van conflicten wanneer kenmerken op verschillende eigenschappen hetzelfde ordernummer opgeven.

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

In het algemeen bieden de meeste databases alleen ondersteuning voor het ordenen van kolommen wanneer de tabel wordt gemaakt. Dit betekent dat het kenmerk kolomvolgorde niet kan worden gebruikt om kolommen in een bestaande tabel opnieuw te orden.