Conversiones de valoresValue Conversions

Nota

Esta característica es nueva en EF Core 2.1.This feature is new in EF Core 2.1.

Convertidores de valores, permiten valores de propiedad que se puede convertir al leer o escribir en la base de datos.Value converters allow property values to be converted when reading from or writing to the database. Esta conversión puede ser de un valor a otro del mismo tipo (por ejemplo, cifrado de cadenas) o de un valor de un tipo a un valor de otro tipo (por ejemplo, convertir valores de enumeración hacia y desde cadenas en la base de datos.)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.)

Aspectos básicosFundamentals

Convertidores de valores se especifican en términos de un ModelClrType y un ProviderClrType.Value converters are specified in terms of a ModelClrType and a ProviderClrType. El tipo de modelo es el tipo de .NET de la propiedad del tipo de entidad.The model type is the .NET type of the property in the entity type. El tipo de proveedor es el tipo de .NET lo entendido el proveedor de base de datos.The provider type is the .NET type understood by the database provider. Por ejemplo, para guardar las enumeraciones como cadenas en la base de datos, el tipo de modelo es el tipo de la enumeración y el tipo de proveedor es 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. Estos dos tipos pueden ser el mismo.These two types can be the same.

Las conversiones se definen mediante dos Func árboles de expresión: uno de ModelClrType a ProviderClrType y otra de ProviderClrType a ModelClrType.Conversions are defined using two Func expression trees: one from ModelClrType to ProviderClrType and the other from ProviderClrType to ModelClrType. Árboles de expresión se usan para que se pueden compilar en el código de acceso de la base de datos para las conversiones eficaz.Expression trees are used so that they can be compiled into the database access code for efficient conversions. Para las conversiones de complejas, el árbol de expresión puede ser una sola llamada a un método que realiza la conversión.For complex conversions, the expression tree may be a simple call to a method that performs the conversion.

Configuración de un convertidor de valoresConfiguring a value converter

Conversiones de valores se definen en las propiedades de la OnModelCreating de su DbContext.Value conversions are defined on properties in the OnModelCreating of your DbContext. Por ejemplo, considere la posibilidad de un tipo enum y entidad definido como: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
}

A continuación, se pueden definir conversiones en OnModelCreating para almacenar los valores de enumeración como cadenas (por ejemplo, "Burro", "Mula",...) en la base de datos: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));
}

Nota

Un null valor nunca se pasará a un convertidor de valores.A null value will never be passed to a value converter. Esto facilita la implementación de las conversiones y les permite compartir entre las propiedades que aceptan valores NULL y que no aceptan valores NULL.This makes the implementation of conversions easier and allows them to be shared amongst nullable and non-nullable properties.

La clase ValueConverterThe ValueConverter class

Una llamada a HasConversion como se indicó anteriormente, se creará un ValueConverter de instancia y establézcalo en la propiedad.Calling HasConversion as shown above will create a ValueConverter instance and set it on the property. El ValueConverter en su lugar, se pueden crear explícitamente.The ValueConverter can instead be created explicitly. Por ejemplo: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);

Esto puede ser útil cuando varias propiedades usan la misma conversión.This can be useful when multiple properties use the same conversion.

Nota

Actualmente no hay ninguna forma de especificar en un mismo lugar que todas las propiedades de un tipo determinado deben usar el mismo convertidor de valores.There is currently no way to specify in one place that every property of a given type must use the same value converter. Esta característica se considerará una versión futura.This feature will be considered for a future release.

Convertidores de tipos integradosBuilt-in converters

EF Core incluye un conjunto de predefinidos ValueConverter clases, que se encuentran en el Microsoft.EntityFrameworkCore.Storage.ValueConversion espacio de nombres.EF Core ships with a set of pre-defined ValueConverter classes, found in the Microsoft.EntityFrameworkCore.Storage.ValueConversion namespace. Estos son:These are:

  • BoolToZeroOneConverter -Bool a cero y unoBoolToZeroOneConverter - Bool to zero and one
  • BoolToStringConverter -Bool a cadenas como "Y" y "N"BoolToStringConverter - Bool to strings such as "Y" and "N"
  • BoolToTwoValuesConverter -Bool a los dos valores.BoolToTwoValuesConverter - Bool to any two values
  • BytesToStringConverter -Matriz de bytes en cadena codificada en Base64BytesToStringConverter - Byte array to Base64-encoded string
  • CastingConverter -Las conversiones que requieren solo una conversión de tipoCastingConverter - Conversions that require only a type cast
  • CharToStringConverter -Char cadena de carácter únicoCharToStringConverter - Char to single character string
  • DateTimeOffsetToBinaryConverter -DateTimeOffset al valor de 64 bits con codificación binariaDateTimeOffsetToBinaryConverter - DateTimeOffset to binary-encoded 64-bit value
  • DateTimeOffsetToBytesConverter -DateTimeOffset a la matriz de bytesDateTimeOffsetToBytesConverter - DateTimeOffset to byte array
  • DateTimeOffsetToStringConverter -DateTimeOffset a cadenaDateTimeOffsetToStringConverter - DateTimeOffset to string
  • DateTimeToBinaryConverter -Fecha y hora al valor de 64 bits incluido DateTimeKindDateTimeToBinaryConverter - DateTime to 64-bit value including DateTimeKind
  • DateTimeToStringConverter -DateTime a stringDateTimeToStringConverter - DateTime to string
  • DateTimeToTicksConverter -Fecha y hora en ciclosDateTimeToTicksConverter - DateTime to ticks
  • EnumToNumberConverter -Enumeración número subyacenteEnumToNumberConverter - Enum to underlying number
  • EnumToStringConverter -Enum a cadenaEnumToStringConverter - Enum to string
  • GuidToBytesConverter -Guid en la matriz de bytesGuidToBytesConverter - Guid to byte array
  • GuidToStringConverter -Guid en cadenaGuidToStringConverter - Guid to string
  • NumberToBytesConverter -Cualquier valor numérico para la matriz de bytesNumberToBytesConverter - Any numerical value to byte array
  • NumberToStringConverter -Cualquier valor numérico en cadenaNumberToStringConverter - Any numerical value to string
  • StringToBytesConverter -Cadena bytes UTF8StringToBytesConverter - String to UTF8 bytes
  • TimeSpanToStringConverter -TimeSpan a cadenaTimeSpanToStringConverter - TimeSpan to string
  • TimeSpanToTicksConverter -Intervalo de tiempo en pasosTimeSpanToTicksConverter - TimeSpan to ticks

Tenga en cuenta que EnumToStringConverter se incluye en esta lista.Notice that EnumToStringConverter is included in this list. Esto significa que no hay ninguna necesidad de especificar la conversión de forma explícita, como se indicó anteriormente.This means that there is no need to specify the conversion explicitly, as shown above. En su lugar, use el convertidor de tipos integrado:Instead, just use the built-in converter:

var converter = new EnumToStringConverter<EquineBeast>();

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

Tenga en cuenta que todos los convertidores integrados tienen estados y por lo que una sola instancia puede compartirse con seguridad entre varias propiedades.Note that all the built-in converters are stateless and so a single instance can be safely shared by multiple properties.

Conversiones predefinidasPre-defined conversions

Para las conversiones comunes para el que existe un convertidor de tipos integrado, no hay ninguna necesidad especificar explícitamente el convertidor.For common conversions for which a built-in converter exists there is no need to specify the converter explicitly. En su lugar, se configura simplemente se debe usar el tipo de proveedor y EF utilizará automáticamente el convertidor integrado apropiado.Instead, just configure which provider type should be used and EF will automatically use the appropriate built-in converter. Enumeración para las conversiones de cadenas se usan como un ejemplo anterior, pero EF realmente hacen esto automáticamente si se configura el tipo de proveedor: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>();

Lo mismo se puede lograr si se especifica explícitamente el tipo de columna.The same thing can be achieved by explicitly specifying the column type. Por ejemplo, si el tipo de entidad se define como para: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; }
}

A continuación, los valores de enumeración se guardará como cadenas en la base de datos sin ninguna configuración adicional en OnModelCreating.Then the enum values will be saved as strings in the database without any further configuration in OnModelCreating.

LimitacionesLimitations

Hay algunas limitaciones conocidas de actuales del sistema de conversión de valor:There are a few known current limitations of the value conversion system:

  • Como se mencionó anteriormente, null no se puede convertir.As noted above, null cannot be converted.
  • Actualmente no hay ninguna manera de distribuir una conversión de una propiedad a varias columnas o viceversa.There is currently no way to spread a conversion of one property to multiple columns or vice-versa.
  • Uso de conversiones de valores puede afectar a la capacidad de EF Core para traducir expresiones a SQL.Use of value conversions may impact the ability of EF Core to translate expressions to SQL. Para estos casos, se registrará una advertencia.A warning will be logged for such cases. Eliminación de estas limitaciones se está considerando para una versión futura.Removal of these limitations is being considered for a future release.