POCOs

Serializar Propiedades de Solo Lectura

Si una propiedad es de solo lectura, el automapeador 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, aplica el [BsonElement] atributo 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 no un 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 añadir una propiedad de solo lectura al registrar el mapa de clases, como se muestra en el siguiente ejemplo:

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

Establecer nombres de campos

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

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

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

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

Seleccionar Representación de Tipo

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 el orden del campo

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.

Identifica la propiedad Id

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 driver serialice un campo especificado, utiliza el atributo [BsonIgnore]. El siguiente código muestra cómo se puede impedir 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 defines la propiedad YearBuilt, el campo no se guarda en MongoDB.

Omitir campos vacíos

Por defecto, el controlador serializa las propiedades no inicializadas con valores null. Para omitir las propiedades vacías durante la serialización, utilize el atributo [BsonIgnoreIfNull]. El siguiente código muestra cómo puedes 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 indicar al controlador que ignore una propiedad que contenga un valor null cuando registre el mapa de clases, como se muestra en el siguiente ejemplo:

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

Personaliza los valores por defecto

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

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

El siguiente ejemplo de código aplica 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);
});

Por defecto, el Driver .NET/C# serializa todas las propiedades, incluidas aquellas que contienen valores predeterminados. Para indicar al driver que ignore una propiedad que tiene el valor por defecto, utiliza 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 datos (0 para las propiedades de int), el driver 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);
});

Se puede tanto especificar un valor por defecto diferente para una propiedad como indicar al driver que ignore la propiedad si contiene este valor por defecto. Para ello, aplique ambos 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, esta tendrá el valor por defecto 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 de DateTime, use 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; }
}

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 puedes especificar una o las dos de las opciones anteriores DateTime al registrar el mapa de clases:

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 DateOnly

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

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

• DocumentFormat: Esta opción solo se aplica si estableces la propiedad Representation en BsonType.Document y, de lo contrario, se ignora. Puedes establecer DocumentFormat en uno de los siguientes valores de enumeración DateOnlyDocumentFormat:

  • DateTimeTicks (por defecto): El documento contiene DateTime (BsonType.DateTime) y Ticks (BsonType.Int64) campos

  • YearMonthDayEl 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 que tiene un valor DateOnly. El atributo indica al controlador que almacene el valor como un documento anidado que contiene campos para el año, mes y día dados.

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

El enumerador DictionaryRepresentation define los formatos en los que el Driver .NET/C# puede serializar una instancia Dictionary. Este enumerado incluye los siguientes nodos:

• 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 a un BsonArray. Cada entrada en el diccionario es un BsonArray anidado de dos elementos que contiene la clave de la entrada y el valor de la entrada.

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

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 se puede especificar el formato de serialización de un diccionario al registrar el mapa de clases, 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()]

• [BsonIgnoreIfDefault]

• [BsonDateTimeOptions()]

• [BsonDictionaryOptions()]

• ConventionPack

• InsertOne()