Entitetsegenskaper

Varje entitetstyp i din modell har en uppsättning egenskaper som EF Core läser och skriver från databasen. Om du använder en relationsdatabas mappas entitetsegenskaper till tabellkolumner.

Inkluderade och exkluderade egenskaper

Enligt konventioninkluderas alla publika egenskaper med en getter och en setter i modellen.

Specifika egenskaper kan undantas på följande sätt:

Dataannoteringar

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

Kolumnnamn

Enligt konventionen mappas entitetsegenskaper till tabellkolumner med samma namn som egenskapen när du använder en relationsdatabas.

Om du föredrar att konfigurera kolumner med olika namn kan du göra det som följande kodfragment:

Dataannoteringar

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

Kolumndatatyper

När du använder en relationsdatabas väljer databasprovidern en datatyp baserat på egenskapens .NET-typ. Den tar också hänsyn till andra metadata, till exempel den konfigurerade maximal längd, om egenskapen är en del av en primärnyckel osv.

SQL Server-providern mappar till exempel DateTime egenskaper till datetime2(7) kolumner och string egenskaper till nvarchar(max) kolumner (eller till nvarchar(450) för egenskaper som används som en nyckel).

Du kan också konfigurera kolumnerna för att ange en exakt datatyp för en kolumn. Följande kod konfigurerar till exempel Url som en icke-unicode-sträng med maximal längd på 200 och Rating som decimal med precision på 5 och skala 2:

Data Annotationer

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

Maxlängden

Att konfigurera en maximal längd ger en ledtråd till databasprovidern om vilken kolumndatatyp som ska väljas för en viss egenskap. Maximal längd gäller endast för matrisdatatyper, till exempel string och byte[].

Anteckning

Entity Framework utför ingen validering av maximal längd innan data skickas till providern. Det är upp till providern eller datalagret att verifiera om det är lämpligt. När du till exempel riktar in dig på SQL Server resulterar överskriden maximal längd i ett undantag eftersom datatypen för den underliggande kolumnen inte tillåter att överflödiga data lagras.

I följande exempel gör konfigurationen av en maximal längd på 500 att en kolumn av typen nvarchar(500) skapas på SQL Server:

Dataanalyser

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

Precision och skalning

Vissa relationsdatatyper stöder precisions- och skalningsfasetter. dessa styr vilka värden som kan lagras och hur mycket lagringsutrymme som behövs för kolumnen. Vilka datatyper som stöder precision och skalning är databasberoende, men i de flesta databaser decimal och DateTime typer stöder dessa fasetter. För decimal egenskaper definierar precision det maximala antalet siffror som behövs för att uttrycka ett värde som kolumnen ska innehålla, och skala definierar det maximala antalet decimaler som behövs. För DateTime egenskaper definierar precision det maximala antalet siffror som behövs för att uttrycka bråkdelar av sekunder och skala används inte.

Not

Entity Framework utför ingen validering av precision eller skalning innan data skickas till providern. Det är upp till providern eller datalagret att verifiera efter behov. När du till exempel riktar in dig på SQL Server tillåter en kolumn av datatyp datetime inte att precisionen anges, medan en datetime2 kan ha precision mellan 0 och 7.

I följande exempel gör konfigurationen av egenskapen Score med precision 14 och skalning 2 att en kolumn av typen decimal(14,2) skapas på SQL Server, och om du konfigurerar egenskapen LastUpdated med precision 3 orsakas en kolumn av typen datetime2(3):

Dataannoteringar

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

Skala definieras aldrig utan att först definiera precision, så dataanteckningen för att definiera skalan är [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);
}

Skala definieras aldrig utan att först definiera precision, så Fluent API för att definiera skalan är HasPrecision(precision, scale).

Unicode

I vissa relationsdatabaser finns olika typer för att representera Unicode- och icke-Unicode-textdata. I SQL Server används till exempel nvarchar(x) för att representera Unicode-data i UTF-16, medan varchar(x) används för att representera icke-Unicode-data (men se anteckningarna om SQL Server UTF-8 stöder). För databaser som inte stöder det här konceptet har det ingen effekt att konfigurera detta.

Textegenskaper konfigureras som Unicode som standard. Du kan konfigurera en kolumn som icke-Unicode på följande sätt:

Dataanteckningar

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

Obligatoriska och valfria egenskaper

En egenskap anses vara valfri om den är giltig för att den ska innehålla null. Om null inte är ett giltigt värde som ska tilldelas till en egenskap anses det vara en obligatorisk egenskap. När du mappar till ett relationsdatabasschema skapas nödvändiga egenskaper som icke-nullbara kolumner och valfria egenskaper skapas som nullbara kolumner.

Konventioner

Enligt konventionen konfigureras en egenskap vars .NET-typ kan innehålla null som valfri, medan egenskaper vars .NET-typ inte kan innehålla null konfigureras efter behov. Till exempel konfigureras alla egenskaper med .NET-värdetyper (int, decimal, boolosv.) efter behov och alla egenskaper med nullbara .NET-värdetyper (int?, decimal?, bool?osv.) konfigureras som valfria.

C# 8 introducerade en ny funktion som heter nullable reference types (NRT), som gör att referenstyper kan kommenteras, vilket anger om det är giltigt för dem att innehålla null eller inte. Den här funktionen är aktiverad som standard i nya projektmallar, men förblir inaktiverad i befintliga projekt om du inte uttryckligen har valt den. Nullbara referenstyper påverkar EF Cores beteende på följande sätt:

• Om nullbara referenstyper är inaktiverade konfigureras alla egenskaper med .NET-referenstyper som valfria av konventionen (till exempel string).
• Om nullbara referenstyper är aktiverade konfigureras egenskaper baserat på C#-nullbarheten för deras .NET-typ: string? konfigureras som valfri, men string konfigureras efter behov.

I följande exempel visas en entitetstyp med obligatoriska och valfria egenskaper, med den nullbara referensfunktionen inaktiverad och aktiverad:

Utan NRT (standard)

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
}

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

Användning av nullbara referenstyper rekommenderas eftersom den flödar nullabiliteten uttryckt i C#-kod till EF Cores modell och till databasen, och undanröjer användningen av Fluent API eller dataanteckningar för att uttrycka samma begrepp två gånger.

Anmärkning

Var försiktig när du aktiverar nullbara referenstyper i ett befintligt projekt: Referenstypegenskaper som tidigare har konfigurerats som valfria konfigureras nu efter behov, såvida de inte uttryckligen kommenteras som null. När du hanterar ett relationsdatabasschema kan det leda till att migreringar genereras som ändrar databaskolumnens nullbarhet.

Mer information om null-referenstyper och hur du använder dem med EF Core finns på sidan för dedikerad dokumentation för den här funktionen.

Explicit konfiguration

En egenskap som är valfri enligt konventionen kan konfigureras så att den krävs på följande sätt:

Dataannoteringar

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

Kolumnens kollationeringar

En sortering kan definieras i textkolumner och bestämma hur de jämförs och sorteras. Till exempel konfigurerar följande kodfragment en SQL Server-kolumn så att den är skiftlägesokänslig.

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

Om alla kolumner i en databas behöver använda en viss sortering definierar du sorteringen på databasnivå i stället.

Allmän information om EF Core-stöd för sortering finns på sidan sorteringsdokumentation.

Kolumnkommentar

Du kan ange en godtycklig textkommentare som anges i databaskolumnen så att du kan dokumentera schemat i databasen:

Dataannotationer

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

Kolumnordning

Som standard, när du skapar en tabell med Migreringar, ordnar EF Core primärnyckelkolumner först, följt av egenskaper hos entitetstyper och ägda typer, och slutligen egenskaper från bastyper. Du kan dock ange en annan kolumnordning:

Data Annotations

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

Api:et Fluent kan användas för att åsidosätta ordning som görs med attribut, inklusive att lösa eventuella konflikter när attribut på olika egenskaper anger samma ordernummer.

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

Observera att i det allmänna fallet stöder de flesta databaser endast ordningskolumner när tabellen skapas. Det innebär att kolumnordningsattributet inte kan användas för att ordna om kolumner i en befintlig tabell.