POCOs

Serializar propiedades de solo lectura

Si una propiedad es de solo lectura, el automapper no la incluye en el mapa de clases para la serialización. Para forzar al automapper a incluir una propiedad en el mapa de clases, aplique la [BsonElement] atribuir a la propiedad.

El siguiente ejemplo de código aplica el atributo [BsonElement] a la propiedad Upc de la clase Clothing. Upc es una propiedad de solo lectura porque tiene un método get pero ningún método set.

public class Clothing
{
    public ObjectId Id { get; set; }
    public string Name { get; set; }
    public bool InStock { get; set; }
    public double Price { get; set; }
    public List<string> ColorSelection { get; set; }
    [BsonElement]
    public int Upc { get; }
}

También puede agregar una propiedad de solo lectura al registrar el mapa de clase, como se muestra en el siguiente ejemplo:

BsonClassMap.RegisterClassMap<Clothing>(classMap =>
{
    classMap.AutoMap();
    classMap.MapProperty(c => c.Upc);
});

Establecer nombres de campos

El controlador serializa las propiedades POCO en campos BSON con el mismo nombre y mayúsculas. Para almacenar una propiedad con un nombre diferente, utilice el atributo [BsonElement()]. El siguiente código asigna la propiedad YearBuilt de la clase House al campo year_built del documento BSON serializado:

public class House
{
    public Guid Id { get; set; }
    [BsonElement("year_built")]
    public int YearBuilt { get; set; }
}

Si bien es común utilizar la convención de nombres de Pascal al definir clases de C#, el uso del atributo [BsonElement()] le permite seleccionar una convención de nombres diferente o personalizada en su colección MongoDB.

var camelCaseConvention = new ConventionPack { new CamelCaseElementNameConvention() };
ConventionRegistry.Register("CamelCase", camelCaseConvention, type => true);

Seleccionar tipo de representación

Para serializar una propiedad de C# a un tipo BSON específico, use el atributo [BsonRepresentation()]. Esto solo funciona si el tipo primitivo de C# es convertible al tipo BSON especificado.

En el siguiente ejemplo de código, el controlador serializa la propiedad YearBuilt, definida como char en C#, como un tipo BSON Int32:

public class House
{
    public Guid Id { get; set; }
    [BsonRepresentation(BsonType.Int32)]
    public char YearBuilt { get; set; }
}

Para obtener más información sobre las conversiones de tipos válidas, consulte la Especificación de conversiones de C#.

Establecer orden de campos

El controlador serializa las propiedades en los campos BSON en el orden en que se especifican en el POCO. Para almacenar las propiedades en un orden personalizado que coincida con un esquema existente, puede especificar el parámetro con nombre Order en el atributo [BsonElement()]. En el siguiente ejemplo de código, el controlador almacena la propiedad YearBuilt después de la propiedad Style:

public class House
{
    public Guid Id { get; set; }
    [BsonElement(Order = 2)]
    public int YearBuilt { get; set; }
    [BsonElement(Order = 1)]
    public string Style { get; set; }
}

Si alguna propiedad no tiene explícitamente un Order, el driver las serializará en el orden por defecto después de aquellas que sí lo tengan.

Identificar Id la propiedad

Por defecto, el controlador asigna cualquier propiedad pública llamada Id, id, o _id al campo BSON _id. Para seleccionar explícitamente la propiedad que se asignará al campo _id, utiliza el atributo [BsonId()]. El siguiente ejemplo de código asigna la propiedad Identifier al campo _id:

public class House
{
    [BsonId]
    public string Identifier { get; set; }
}

public class House
{
   [BsonId(IdGenerator = typeof(CombGuidGenerator))]
   public Guid Id { get; set; }
}

public class House
{
   public Guid Id { get; set; }
}

public class House
{
   public ObjectId Id { get; set; }
}

public class House
{
   [BsonRepresentation(BsonType.ObjectId)]
   public string Id { get; set; }
}

public class House
{
   [BsonId(IdGenerator = typeof(StringObjectIdGenerator))]
   public string Id { get; set; }
}

public class House
{
   [BsonId(IdGenerator = typeof(BsonObjectIdGenerator))]
   public BsonObjectId Id { get; set; }
}

BsonClassMap.RegisterClassMap<House>(classMap =>
{
   classMap.AutoMap();
   classMap.MapIdMember(h => h.Id).SetIdGenerator(CombGuidGenerator.Instance);
});

BsonSerializer.RegisterIdGenerator(
  typeof(Guid),
  CombGuidGenerator.Instance
);

public class House
{
    [BsonId(IdGenerator = typeof(NullIdChecker))]
    public Guid Id { get; set; }
}

Omitir campos

Para evitar que el controlador serialice un campo específico, utilice el atributo [BsonIgnore]. El siguiente código muestra cómo evitar que el controlador serialice la propiedad YearBuilt:

public class House
{
    public Guid Id { get; set; }
    [BsonIgnore]
    public int YearBuilt { get; set; }
    public string Style { get; set; }
}

Incluso si define la propiedad YearBuilt, el campo no se guarda en MongoDB.

Omitir campos vacíos

De forma predeterminada, el controlador serializa las propiedades no inicializadas con valores null. Para ignorar las propiedades vacías durante la serialización, utilice el atributo [BsonIgnoreIfNull]. El siguiente código muestra cómo evitar que el controlador serialice la propiedad Style si no está inicializada:

public class House
{
    public Guid Id { get; set; }
    [BsonIgnoreIfNull]
    public string Style { get; set; }
    public int YearBuilt { get; set; }
}

También puede indicarle al controlador que ignore una propiedad que contenga un valor null cuando registre el mapa de clase, como se muestra en el siguiente ejemplo:

BsonClassMap.RegisterClassMap<House>(classMap =>
{
   classMap.AutoMap();
   classMap.MapMember(h => h.Style).SetIgnoreIfNull(true);
});

Personalizar valores predeterminados

En C#, una propiedad tiene un valor predeterminado hasta que se le asigna uno. El valor predeterminado depende del tipo de dato de la propiedad. Por ejemplo, el valor predeterminado para una propiedad de tipo referencia es null.

Para especificar un valor predeterminado diferente para una propiedad, aplique el atributo [BsonDefaultValue()] a la propiedad y pase el valor predeterminado deseado como argumento.

Los siguientes ejemplos de código aplican el atributo [BsonDefaultValue()] a la propiedad YearBuilt. Hasta que se le asigne un valor a esta propiedad, su valor es 1900.

public class House
{
    public Guid Id { get; set; }
    [BsonDefaultValue(1900)]
    public int YearBuilt { get; set; }
}

También puede especificar un valor predeterminado diferente para una propiedad cuando registra el mapa de clase, como se muestra en el siguiente ejemplo:

BsonClassMap.RegisterClassMap<House>(classMap =>
{
   classMap.AutoMap();
   classMap.MapMember(h => h.YearBuilt).SetDefaultValue(1900);
});

De forma predeterminada, el controlador .NET/C# serializa todas las propiedades, incluidas aquellas con valores predeterminados. Para indicarle al controlador que ignore una propiedad con el valor predeterminado, utilice el atributo [BsonIgnoreIfDefault].

El siguiente ejemplo de código aplica el atributo [BsonIgnoreIfDefault] a la propiedad YearBuilt. Si el valor de esta propiedad es el predeterminado para su tipo de dato (0 para las propiedades int), el controlador no lo serializará.

public class House
{
    public Guid Id { get; set; }
    [BsonIgnoreIfDefault]
    public int YearBuilt { get; set; }
}

También puede indicarle al controlador que ignore una propiedad que contenga el valor predeterminado cuando registre el mapa de clase, como se muestra en el siguiente ejemplo:

BsonClassMap.RegisterClassMap<House>(classMap =>
{
   classMap.AutoMap();
   classMap.MapMember(h => h.YearBuilt).SetIgnoreIfDefault(true);
});

Puede especificar un valor predeterminado diferente para una propiedad e indicar al controlador que la ignore si contiene dicho valor. Para ello, aplique los atributos [BsonDefaultValue()] y [BsonIgnoreIfDefault] a la propiedad, como se muestra en el siguiente ejemplo de código:

public class House
{
    public Guid Id { get; set; }
    [BsonDefaultValue(1900)]
    [BsonIgnoreIfDefault]
    public int YearBuilt { get; set; }
}

El ejemplo de código anterior establece el siguiente comportamiento de serialización:

• Si no se ha asignado un valor a la propiedad YearBuilt, tiene el valor predeterminado especificado de 1900.

• Dado que 1900 es el valor predeterminado para esta propiedad, el controlador ignorará la propiedad si tiene este valor.

Personalizar la serialización de DateTime

Para personalizar cómo el controlador .NET/C# serializa las propiedades DateTime, utilice el atributo [BsonDateTimeOptions()] y especifique la configuración deseada como argumento.

Si una propiedad DateTime representa solo una fecha, puede aplicarle el atributo [BsonDateTimeOptions(DateOnly = true)]. Si lo hace, el controlador no realizará ninguna conversión de zona horaria en el valor.

En el siguiente ejemplo de código, la clase PatientRecord usa un DateTime para la propiedad DateOfBirth. El atributo [BsonDateTimeOptions(DateOnly = true)] indica que la propiedad solo contiene una fecha.

public class PatientRecord
{
    public Guid Id { get; set; }
    [BsonDateTimeOptions(DateOnly = true)]
    public DateTime DateOfBirth { get; set; }
}

También puede usar el atributo [BsonDateTimeOptions()] para especificar el DateTimeKind de una propiedad DateTime. En el siguiente ejemplo de código, la clase PatientRecord tiene una propiedad AppointmentTime de tipo DateTime. El atributo [BsonDateTimeOptions(Kind = DateTimeKind.Local)] indica que el componente de tiempo del valor de la propiedad está en hora local. Cuando el controlador serializa esta propiedad, convierte la hora a UTC, el formato estándar para las horas almacenadas en MongoDB.

public class PatientRecord
{
    public Guid Id { get; set; }
    [BsonDateTimeOptions(Kind = DateTimeKind.Local)]
    public DateTime AppointmentTime { get; set; }
}

También puede especificar una o ambas de las opciones DateTime anteriores al registrar el mapa de clase:

BsonClassMap.RegisterClassMap<House>(classMap =>
{
   classMap.AutoMap();
   classMap.MapMember(p => p.DateOfBirth)
      .SetSerializer(new DateTimeSerializer(dateOnly: true));
   classMap.MapMember(p => p.AppointmentTime)
      .SetSerializer(new DateTimeSerializer(DateTimeKind.Local));
});

Serialización personalizada de solo fecha

Para personalizar cómo el controlador .NET/C# serializa las propiedades DateOnly, [BsonDateOnlyOptions()] utilice el atributo y especifique las siguientes configuraciones:

• Representation:Establezca una instancia BsonType que especifica cómo se almacena el valor DateOnly en MongoDB.

• DocumentFormatEsta opción solo se aplica si se establece la propiedad Representation en BsonType.Document; de lo contrario, se ignora. Puede establecer DocumentFormat en uno de los siguientes valores de enumeración DateOnlyDocumentFormat:

  • DateTimeTicks (predeterminado): el documento contiene los campos DateTime (BsonType.DateTime) y Ticks (BsonType.Int64)

  • YearMonthDay:El documento contiene los campos Year, Month y Day, que tienen valores BsonType.Int32

En el siguiente ejemplo de código, la clase PatientRecord contiene una propiedad DateOfBirth con un valor DateOnly. El atributo indica al controlador que almacene el valor como un documento anidado que contiene los campos para el año, mes y día especificados.

public class PatientRecord
{
    public Guid Id { get; set; }
    [BsonDateOnlyOptions(BsonType.Document, DateOnlyDocumentFormat.YearMonthDay)]
    public DateOnly DateOfBirth { get; set; }
}

BsonSerializer.RegisterSerializer(
    new DateOnlySerializer(BsonType.Document, DateOnlyDocumentFormat.YearMonthDay)
);

Personalizar la serialización del diccionario

La enumeración DictionaryRepresentation define los formatos en los que el controlador .NET/C# puede serializar una instancia Dictionary. Esta enumeración incluye los siguientes miembros:

• Documento: (Predeterminado) El controlador serializa Dictionary BsonDocumentcomo. Cada entrada del diccionario es un BsonElement con un nombre igual a la clave de la entrada y un valor igual al valor de la entrada. Esta representación solo se puede usar cuando todas las claves del diccionario son cadenas que también son BsonElement nombres válidos.

• ArrayOfArrays: El controlador serializa el diccionario en BsonArray un. Cada entrada del diccionario es un anidado de dos elementos BsonArray que contiene la clave y el valor de la entrada.

• ArrayOfDocuments: El controlador serializa el diccionario en BsonArray un. Cada entrada del diccionario es un anidado BsonDocument { k : key, v : value }con el formato. Dado que las claves y los valores están etiquetados con nombres de elementos, se puede consultar este formato de forma más intuitiva que con ArrayOfArrays un.

En el siguiente ejemplo de código, la propiedad RoomSizes es un diccionario que contiene cada habitación de una casa y su tamaño correspondiente. El atributo [BsonDictionaryOptions()] indica al controlador .NET/C# que serialice esta propiedad en un objeto BsonArray y cada entrada del diccionario en un objeto BsonDocument con la forma { k : "<room>", v : <size> }.

public class House
{
    public Guid Id { get; set; }
    [BsonDictionaryOptions(DictionaryRepresentation.ArrayOfDocuments)]
    public Dictionary<string, float> RoomSizes { get; set; }
}

También puede especificar el formato de serialización de un diccionario cuando registra el mapa de clase, como se muestra en el siguiente ejemplo:

BsonClassMap.RegisterClassMap<House>(classMap =>
{
    classMap.AutoMap();
    classMAp.MapMember(h => h.RoomSizes)
      .SetSerializer(new DictionaryInterfaceImplementerSerializer<Dictionary<string, float>>
      (DictionaryRepresentation.ArrayOfDocuments));
});

Documentación de la API

Para aprender más sobre cualquiera de los métodos o tipos analizados en esta guía, consulta la siguiente documentación de API:

• [BsonElement()]

• [BsonRepresentation()]

• [BsonId()]

• [BsonIgnorar()]

• [BsonDefaultValue()]

• [BsonIgnorarSiPredeterminado]

• [BsonDateTimeOptions()]

• [Opciones del Diccionario Bson()]

• ConventionPack

• InsertOne()