WertkonvertierungenValue Conversions

Hinweis

Dieses Feature ist neu in EF Core 2.1.This feature is new in EF Core 2.1.

Wertkonverter ermöglichen die konvertiert werden, wenn die Variable gelesen oder geschrieben werden, in der Datenbank.Value converters allow property values to be converted when reading from or writing to the database. Diese Konvertierung kann von einem Wert in eine andere vom selben Typ (z. B. Verschlüsselung Zeichenfolgen) oder aus einem Wert eines Typs in einen Wert eines anderen Typs (z. B. Konvertieren von Enum-Werte in und aus Zeichenfolgen in der Datenbank.)This conversion can be from one value to another of the same type (for example, encrypting strings) or from a value of one type to a value of another type (for example, converting enum values to and from strings in the database.)

GrundlagenFundamentals

Wertkonverter sind hinsichtlich der angegebenen ein ModelClrType und ProviderClrType.Value converters are specified in terms of a ModelClrType and a ProviderClrType. Der Typ des Modells ist der Typ .NET die Eigenschaft im Entitätstyp.The model type is the .NET type of the property in the entity type. Der Anbietertyp ist der .NET-Typ, der vom Datenbankanbieter verstanden.The provider type is the .NET type understood by the database provider. Z. B. um Enumerationen als Zeichenfolgen in der Datenbank zu speichern, der Typ des Modells ist der Typ der Enumeration; Anbietertyp ist String.For example, to save enums as strings in the database, the model type is the type of the enum, and the provider type is String. Diese beiden Typen können identisch sein.These two types can be the same.

Konvertierungen werden definiert, unter Verwendung zweier Func Ausdrucksbaumstrukturen: von ModelClrType zu ProviderClrType und das andere von ProviderClrType zu ModelClrType.Conversions are defined using two Func expression trees: one from ModelClrType to ProviderClrType and the other from ProviderClrType to ModelClrType. Ausdrucksbaumstrukturen werden verwendet, sodass sie in der Datenbank-Zugriffscode für effiziente Konvertierungen kompiliert werden können.Expression trees are used so that they can be compiled into the database access code for efficient conversions. Bei komplexen Konvertierungen wird möglicherweise die Ausdrucksbaumstruktur einen einfachen Aufruf an eine Methode, die die Konvertierung durchführt.For complex conversions, the expression tree may be a simple call to a method that performs the conversion.

Konfigurieren einen WertkonverterConfiguring a value converter

Konvertierungen werden in Eigenschaften definiert die OnModelCreating von Ihrem DbContext.Value conversions are defined on properties in the OnModelCreating of your DbContext. Betrachten Sie beispielsweise einen Typ für Enumerationen und Entität, die als definiert:For example, consider an enum and entity type defined as:

public class Rider
{
    public int Id { get; set; }
    public EquineBeast Mount { get; set; }
}

public enum EquineBeast
{
    Donkey,
    Mule,
    Horse,
    Unicorn
}

Konvertierungen in definiert werden, können OnModelCreating Enum-Werte als Zeichenfolgen (z. B. "Donkey", "Mule",...) in der Datenbank zu speichern:Then conversions can be defined in OnModelCreating to store the enum values as strings (for example, "Donkey", "Mule", ...) in the database:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder
        .Entity<Rider>()
        .Property(e => e.Mount)
        .HasConversion(
            v => v.ToString(),
            v => (EquineBeast)Enum.Parse(typeof(EquineBeast), v));
}

Hinweis

Ein null Wert wird nie auf einen Wertkonverter übergeben werden.A null value will never be passed to a value converter. Dies erleichtert die Implementierung der Konvertierungen und ermöglicht es ihnen, die von NULL-Werte zulässt und nicht auf NULL festlegbare Eigenschaften gemeinsam genutzt werden.This makes the implementation of conversions easier and allows them to be shared amongst nullable and non-nullable properties.

Die ValueConverter-KlasseThe ValueConverter class

Aufrufen von HasConversion wie oben gezeigt erstellt eine ValueConverter -Instanz und für die Eigenschaft festgelegt wird.Calling HasConversion as shown above will create a ValueConverter instance and set it on the property. Die ValueConverter stattdessen explizit erstellt werden können.The ValueConverter can instead be created explicitly. Zum Beispiel:For example:

var converter = new ValueConverter<EquineBeast, string>(
    v => v.ToString(),
    v => (EquineBeast)Enum.Parse(typeof(EquineBeast), v));

modelBuilder
    .Entity<Rider>()
    .Property(e => e.Mount)
    .HasConversion(converter);

Dies kann nützlich sein, wenn mehrere Eigenschaften auf die gleiche Konvertierung verwenden.This can be useful when multiple properties use the same conversion.

Hinweis

Derzeit besteht keine Möglichkeit, um an einem Ort anzugeben, dass jede Eigenschaft eines bestimmten Typs den gleichen Wertkonverter verwenden muss.There is currently no way to specify in one place that every property of a given type must use the same value converter. Dieses Feature wird für ein zukünftiges Release berücksichtigt.This feature will be considered for a future release.

Integrierte KonverterBuilt-in converters

EF Core umfasst eine Reihe von vordefinierten ValueConverter Klassen finden Sie in der Microsoft.EntityFrameworkCore.Storage.ValueConversion Namespace.EF Core ships with a set of pre-defined ValueConverter classes, found in the Microsoft.EntityFrameworkCore.Storage.ValueConversion namespace. Diese lauten wie folgt:These are:

  • BoolToZeroOneConverter -"Bool" an, und 0 (null)BoolToZeroOneConverter - Bool to zero and one
  • BoolToStringConverter -"Bool", um Zeichenfolgen wie "Y" und "N"BoolToStringConverter - Bool to strings such as "Y" and "N"
  • BoolToTwoValuesConverter -"Bool", um zwei WertenBoolToTwoValuesConverter - Bool to any two values
  • BytesToStringConverter -Byte-Array in Base64-codierte ZeichenfolgeBytesToStringConverter - Byte array to Base64-encoded string
  • CastingConverter -Konvertierungen, die nur eine Typumwandlung erfordernCastingConverter - Conversions that require only a type cast
  • CharToStringConverter -Von char, um die einzelnen Zeichen bestehende ZeichenfolgeCharToStringConverter - Char to single character string
  • DateTimeOffsetToBinaryConverter -DateTimeOffset Binär codierte 64-Bit-WertDateTimeOffsetToBinaryConverter - DateTimeOffset to binary-encoded 64-bit value
  • DateTimeOffsetToBytesConverter -DateTimeOffset Byte-arrayDateTimeOffsetToBytesConverter - DateTimeOffset to byte array
  • DateTimeOffsetToStringConverter -DateTimeOffset ZeichenfolgeDateTimeOffsetToStringConverter - DateTimeOffset to string
  • DateTimeToBinaryConverter – DateTime, DateTimeKind einschließlich 64-Bit-WertDateTimeToBinaryConverter - DateTime to 64-bit value including DateTimeKind
  • DateTimeToStringConverter -DateTime ZeichenfolgeDateTimeToStringConverter - DateTime to string
  • DateTimeToTicksConverter -DateTime in ticksDateTimeToTicksConverter - DateTime to ticks
  • EnumToNumberConverter -Anzahl der zugrunde liegenden EnumerationEnumToNumberConverter - Enum to underlying number
  • EnumToStringConverter -Zeichenfolge EnumerationEnumToStringConverter - Enum to string
  • GuidToBytesConverter -Guid in Byte-arrayGuidToBytesConverter - Guid to byte array
  • GuidToStringConverter -Guid ZeichenfolgeGuidToStringConverter - Guid to string
  • NumberToBytesConverter – Alle numerischen Wert in Byte-arrayNumberToBytesConverter - Any numerical value to byte array
  • NumberToStringConverter – Alle numerischen Wert in eine ZeichenfolgeNumberToStringConverter - Any numerical value to string
  • StringToBytesConverter -Von string in UTF8-bytesStringToBytesConverter - String to UTF8 bytes
  • TimeSpanToStringConverter -TimeSpan ZeichenfolgeTimeSpanToStringConverter - TimeSpan to string
  • TimeSpanToTicksConverter -TimeSpan TicksTimeSpanToTicksConverter - TimeSpan to ticks

Beachten Sie, dass EnumToStringConverter in dieser Liste enthalten ist.Notice that EnumToStringConverter is included in this list. Dies bedeutet, dass keine Notwendigkeit besteht, wie oben gezeigt, explizit angeben, die Konvertierung.This means that there is no need to specify the conversion explicitly, as shown above. Verwenden Sie stattdessen einfach die integrierten Konverter:Instead, just use the built-in converter:

var converter = new EnumToStringConverter<EquineBeast>();

modelBuilder
    .Entity<Rider>()
    .Property(e => e.Mount)
    .HasConversion(converter);

Beachten Sie, dass alle integrierten Konverter zustandslos sind und daher eine einzelne Instanz sicher für mehrere Eigenschaften gemeinsam an.Note that all the built-in converters are stateless and so a single instance can be safely shared by multiple properties.

Vordefinierte KonvertierungenPre-defined conversions

Für allgemeine Konvertierungen, die für die integrierten Konverter vorhanden ist ist es nicht notwendig, den Konverter explizit anzugeben.For common conversions for which a built-in converter exists there is no need to specify the converter explicitly. Stattdessen einfach konfigurieren, welcher Typ verwendet werden soll, und EF verwendet automatisch den entsprechenden integrierten Konverter.Instead, just configure which provider type should be used and EF will automatically use the appropriate built-in converter. Enumeration, zeichenfolgenkonvertierungen werden als Beispiel oben verwendet, aber EF übernimmt dies automatisch, wenn der Anbietertyp konfiguriert ist:Enum to string conversions are used as an example above, but EF will actually do this automatically if the provider type is configured:

modelBuilder
    .Entity<Rider>()
    .Property(e => e.Mount)
    .HasConversion<string>();

Dasselbe kann durch explizites Angeben des Spaltentyps erreicht werden.The same thing can be achieved by explicitly specifying the column type. Wenn der Entitätstyp definiert ist z.B. so:For example, if the entity type is defined like so:

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

    [Column(TypeName = "nvarchar(24)")]
    public EquineBeast Mount { get; set; }
}

Und dann die Enum-Werte als Zeichenfolgen in der Datenbank ohne weitere Konfiguration in gespeichert werden OnModelCreating.Then the enum values will be saved as strings in the database without any further configuration in OnModelCreating.

EinschränkungenLimitations

Es gibt einige bekannte aktuelle Einschränkungen des Systems Konvertierung Wert:There are a few known current limitations of the value conversion system:

  • Wie bereits erwähnt, null kann nicht konvertiert werden.As noted above, null cannot be converted.
  • Derzeit besteht keine Möglichkeit, eine Konvertierung von einer Eigenschaft in mehrere Spalten oder umgekehrt zu verteilen.There is currently no way to spread a conversion of one property to multiple columns or vice-versa.
  • Verwendung von Konvertierungen kann es sich um die Fähigkeit von EF Core, die in SQL übersetzen auswirken.Use of value conversions may impact the ability of EF Core to translate expressions to SQL. Für solche Fälle wird eine Warnung protokolliert werden.A warning will be logged for such cases. Zum Entfernen dieser Einschränkungen ist für eine spätere Version in Betracht gezogen.Removal of these limitations is being considered for a future release.