Entitätseigenschaften

Jeder Entitätstyp in Ihrem Modell verfügt über eine Reihe von Eigenschaften, die EF Core aus der Datenbank lesen und schreiben wird. Wenn Sie eine relationale Datenbank verwenden, werden Entitätseigenschaften tabellenspalten zugeordnet.

Eingeschlossene und ausgeschlossene Eigenschaften

In der Konvention werden alle öffentlichen Eigenschaften mit einem Getter und einem Setter im Modell enthalten.

Bestimmte Eigenschaften können wie folgt ausgeschlossen werden:

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

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

Spaltennamen

Wenn Sie eine relationale Datenbank verwenden, werden Entitätseigenschaften tabellenspalten zugeordnet, die denselben Namen wie die Eigenschaft aufweisen.

Wenn Sie Ihre Spalten lieber mit unterschiedlichen Namen konfigurieren möchten, können Sie dies als folgenden Codeausschnitt tun:

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

    public string Url { get; set; }
}

Spaltendatentypen

Wenn Sie eine relationale Datenbank verwenden, wählt der Datenbankanbieter einen Datentyp basierend auf dem .NET-Typ der Eigenschaft aus. Außerdem werden andere Metadaten berücksichtigt, z. B. die konfigurierte maximale Länge, ob die Eigenschaft Teil eines Primärschlüssels ist usw.

Beispielsweise SQL Server DateTime eigenschaften Spalten und string Eigenschaften spalten zugeordnet (oder nvarchar(450) für Eigenschaften datetime2(7)nvarchar(max), die als Schlüssel verwendet werden).

Sie können Ihre Spalten auch so konfigurieren, dass sie einen genauen Datentyp für eine Spalte angeben. Der folgende Code konfiguriert Url z. B. als Nicht-Unicode-Zeichenfolge mit maximaler Länge 200 und dezimaler Länge mit Genauigkeit 5 und Rating Skalierung von 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; }
}

Maximale Länge

Das Konfigurieren einer maximalen Länge bietet einen Hinweis auf den Datenbankanbieter über den entsprechenden Spaltendatentyp, der für eine bestimmte Eigenschaft ausgewählt werden soll. Die maximale Länge gilt nur für Array-Datentypen, z string . B. und byte[].

Hinweis

Entity Framework führt keine Überprüfung der maximalen Länge durch, bevor Daten an den Anbieter übergeben werden. Es ist bis zum Anbieter oder Datenspeicher erforderlich, um nach Bedarf zu überprüfen. Wenn Sie beispielsweise auf SQL Server abzielen, führt das Überschreiten der maximalen Länge zu einer Ausnahme, da der Datentyp der zugrunde liegenden Spalte keine übermäßigen Daten gespeichert werden kann.

Im folgenden Beispiel führt die Konfiguration einer maximalen Länge von 500 dazu, dass eine Spalte des Typs nvarchar(500) auf SQL Server erstellt werden soll:

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

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

Genauigkeit und Skalierung

Einige relationale Datentypen unterstützen die Genauigkeits- und Skalierungsaspekte; diese Steuern, welche Werte gespeichert werden können, und wie viel Speicher für die Spalte benötigt wird. Welche Datentypen Genauigkeit und Skalierung unterstützen, ist datenbankabhängig, aber in den meisten Datenbanken decimal und DateTime Typen unterstützen diese Facetten. Für decimal Eigenschaften definiert Die Genauigkeit definiert die maximale Anzahl von Ziffern, die zum Ausdrücken eines beliebigen Werts erforderlich sind, und skaliert die maximale Anzahl von Dezimalstellen, die benötigt werden. Bei DateTime Eigenschaften definiert Die Genauigkeit definiert die maximale Anzahl von Ziffern, die zum Ausdrücken von Sekundenbrüchen erforderlich sind, und die Skalierung wird nicht verwendet.

Hinweis

Entity Framework führt keine Überprüfung der Genauigkeit oder Skalierung durch, bevor Daten an den Anbieter übergeben werden. Es ist bis zum Anbieter oder Datenspeicher erforderlich, um die Überprüfung entsprechend zu überprüfen. Wenn sie beispielsweise auf SQL Server ausgerichtet werden, erlaubt eine Spalte des Datentyps datetime nicht, dass die Genauigkeit festgelegt werden kann, während eine datetime2 Genauigkeit zwischen 0 und 7 inklusive bestehen kann.

Im folgenden Beispiel führt das Konfigurieren der Score Eigenschaft mit Genauigkeit 14 und Skalierung 2 zu einer Spalte des Typs, die auf SQL Server erstellt wird, und das Konfigurieren LastUpdated der Eigenschaft mit Genauigkeit 3 führt zu einer Spalte des Typs decimal(14,2)datetime2(3):

Hinweis

Die Datenanmerkung zum Konfigurieren von Genauigkeit und Skalierung wurde in EF Core 6.0 eingeführt.

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

Die Skalierung wird niemals ohne erste Definition der Genauigkeit definiert, sodass die Datenanmerkung für die Definition der Skalierung ist [Precision(precision, scale)].

Unicode

In einigen relationalen Datenbanken sind verschiedene Typen vorhanden, um Unicode- und Nicht-Unicode-Textdaten darzustellen. In SQL Server wird beispielsweise verwendet, nvarchar(x) um Unicode-Daten in UTF-16 darzustellen, während varchar(x) sie zum Darstellen von Nicht-Unicode-Daten verwendet wird (siehe die Notizen zu SQL Server UTF-8-Unterstützung). Für Datenbanken, die dieses Konzept nicht unterstützen, hat die Konfiguration keine Auswirkung.

Texteigenschaften werden standardmäßig als Unicode konfiguriert. Sie können eine Spalte wie folgt konfigurieren:

Hinweis

Die Datenanmerkung zum Konfigurieren von Unicode wurde in EF Core 6.0 eingeführt.

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

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

Erforderliche und optionale Eigenschaften

Eine Eigenschaft wird als optional betrachtet, wenn sie gültig ist, um sie enthalten nullzu können. Wenn null kein gültiger Wert für eine Eigenschaft zugewiesen wird, gilt es als erforderliche Eigenschaft. Bei der Zuordnung zu einem relationalen Datenbankschema werden erforderliche Eigenschaften als nicht nullable Spalten erstellt, und optionale Eigenschaften werden als nullable Spalten erstellt.

Konventionen

In der Konvention wird eine Eigenschaft, deren .NET-Typ NULL enthalten kann, als optional konfiguriert, während Eigenschaften, deren .NET-Typ keine NULL enthalten kann, wie erforderlich konfiguriert werden. Beispielsweise werden alle Eigenschaften mit .NET-Werttypen (, , usw.) als erforderlich konfiguriert, und alle Eigenschaften mit nullablen .NET-Werttypen (int?int, decimal?decimalboolbool?usw.) werden als optional konfiguriert.

C# 8 hat ein neues Feature namens Nullable Reference Types (NRT) eingeführt, mit dem Verweistypen annotiert werden können, die angibt, ob es gültig ist, null oder nicht zu enthalten. Dieses Feature ist standardmäßig in neuen Projektvorlagen aktiviert, bleibt jedoch in vorhandenen Projekten deaktiviert, es sei denn, es wurde explizit entschieden. Nullable Referenztypen wirken sich auf das Verhalten von EF Core auf die folgende Weise aus:

  • Wenn nullable Referenztypen deaktiviert sind, werden alle Eigenschaften mit .NET-Referenztypen als optional durch Konvention konfiguriert (z string. B. ).
  • Wenn nullable Referenztypen aktiviert sind, werden Eigenschaften basierend auf der C# nullability ihres .NET-Typs konfiguriert: string? wird als optional konfiguriert, aber string wie erforderlich konfiguriert.

Im folgenden Beispiel wird ein Entitätstyp mit erforderlichen und optionalen Eigenschaften angezeigt, wobei das Null-Referenzfeature deaktiviert und aktiviert ist:

public class CustomerWithoutNullableReferenceTypes
{
    public int Id { get; set; }

    [Required] // Data annotations needed to configure as required
    public string FirstName { get; set; }

    [Required]
    public string LastName { get; set; } // Data annotations needed to configure as required

    public string MiddleName { get; set; } // Optional by convention
}

Die Verwendung von nullablen Referenztypen wird empfohlen, da es die Nullbarkeit, die im C#-Code ausgedrückt wird, zum EF Core-Modell und zur Datenbank fließt und die Verwendung der Fluent-API oder Datenanmerkungen abgibt, um dasselbe Konzept zweimal auszudrücken.

Hinweis

Achten Sie bei der Aktivierung von Nullable-Referenztypen auf einem vorhandenen Projekt: Referenztypeigenschaften, die zuvor als optional konfiguriert wurden, werden jetzt als erforderlich konfiguriert, es sei denn, sie werden explizit als Nullwert bezeichnet. Beim Verwalten eines relationalen Datenbankschemas kann dies dazu führen, dass Migrationen generiert werden, die die Nullbarkeit der Datenbankspalte ändern.

Weitere Informationen zu nullablen Referenztypen und deren Verwendung mit EF Core finden Sie auf der dedizierten Dokumentationsseite für dieses Feature.

Explizite Konfiguration

Eine Eigenschaft, die optional nach Konvention sein würde, kann wie folgt konfiguriert werden:

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

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

Spaltensortierungen

Hinweis

Dieses Feature wurde in EF Core 5.0 eingeführt.

Eine Sortierung kann auf Textspalten definiert werden, und bestimmt, wie sie verglichen und sortiert werden. Der folgende Codeausschnitt konfiguriert beispielsweise eine SQL Server Spalte als Groß-/Kleinschreibung:

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

Wenn alle Spalten in einer Datenbank eine bestimmte Sortierung verwenden müssen, definieren Sie stattdessen die Sortierung auf Datenbankebene.

Allgemeine Informationen zur EF Core-Unterstützung für Sortierungen finden Sie auf der Seite zur Sortierungsdokumentation.

Spaltenkommentare

Sie können einen beliebigen Textkommentar festlegen, der auf der Datenbankspalte festgelegt wird, sodass Sie Ihr Schema in der Datenbank dokumentieren können:

Hinweis

Das Festlegen von Kommentaren über Datenanmerkungen wurde in EF Core 5.0 eingeführt.

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

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

Spaltenreihenfolge

Hinweis

Dieses Feature wurde in EF Core 6.0 eingeführt.

Beim Erstellen einer Tabelle mit Migrationen sortiert EF Core zuerst Primärschlüsselspalten, gefolgt von Eigenschaften des Entitätstyps und besitzereigenen Typen und schließlich Eigenschaften aus Basistypen. Sie können jedoch eine andere Spaltenreihenfolge angeben:

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

Die Fluent-API kann verwendet werden, um die Sortierung mit Attributen außer Kraft zu setzen, einschließlich der Auflösung von Konflikten, wenn Attribute auf verschiedenen Eigenschaften dieselbe Bestellnummer angeben.

Beachten Sie, dass die meisten Datenbanken das Sortieren von Spalten nur beim Erstellen der Tabelle unterstützen. Dies bedeutet, dass das Attribut für die Spaltenreihenfolge nicht verwendet werden kann, um Spalten in einer vorhandenen Tabelle neu zu sortieren.