/ /

/ /

Librerías de clientes

Driver C#/.NET

Fundamentals

Serialización

Mapeo de clases

Overview

En esta guía, aprenderá a personalizar la forma en que el controlador MongoDB .NET/C# asigna documentos BSON a y desde clases de C#. Consulte esta página para obtener más información sobre el comportamiento predeterminado de asignación de clases o si necesita personalizar la forma en que el controlador serializa o deserializa sus datos.

Mapeo automático de clases

Cuando se utiliza una clase, en lugar de una BsonDocumentPara representar datos en una colección de MongoDB, el controlador .NET/C# crea automáticamente un mapa de clases que utiliza para serializar o deserializar los datos. Esta asignación se realiza haciendo coincidir el nombre del campo en el documento con el nombre de la propiedad en la clase.

Importante

El tipo de la propiedad en la clase debe coincidir con el tipo del campo en el documento. El controlador .NET/C# instancia un serializador según el tipo de la propiedad en la clase. Si los tipos no coinciden al intentar deserializar los datos, el serializador genera una excepción.

Creación manual de un mapa de clases

Puede omitir la funcionalidad de mapeo automático de clases del controlador y definir manualmente el mapa de clases utilizando el método RegisterClassMap().

El siguiente ejemplo define una clase Person:

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public List<string> Hobbies {get; set;}
}

El siguiente código demuestra cómo registrar el mapa de clase para la clase Person:

BsonClassMap.RegisterClassMap<Person>(classMap =>
{
    classMap.MapMember(p => p.Name);
    classMap.MapMember(p => p.Age);
    classMap.MapMember(p => p.Hobbies);
});

Importante

Debe registrar un mapa de clase antes de que sea necesario en su código. Recomendamos registrar los mapas de clase antes de inicializar una conexión con MongoDB.

También puede asignar manualmente un subconjunto de propiedades de clase, permitiendo que el controlador asigne automáticamente las propiedades restantes. Para ello, registre un mapa de clase y llame al método AutoMap() antes de especificar manualmente las propiedades.

En el siguiente ejemplo de código, el método AutoMap() asigna todas las propiedades de la clase Person y luego ajusta manualmente la asignación para el campo Hobbies:

BsonClassMap.RegisterClassMap<Person>(classMap =>
{
    classMap.AutoMap();
    classMap.MapMember(p => p.Hobbies).SetElementName("favorite_hobbies");
});

Personalizar la serialización de clases

Puede personalizar cómo el controlador serializa y deserializa documentos a nivel de clase utilizando atributos con la clase o llamando métodos mientras registra un mapa de clase.

Ignorar elementos adicionales

Cuando un documento BSON se deserializa a una clase de C#, el controlador .NET/C# examina el nombre de cada campo del documento e intenta encontrar un nombre de propiedad coincidente en la clase. De forma predeterminada, si un campo del documento no coincide con la clase, el controlador genera una excepción.

Se puede optar por ignorar cualquier elemento que no tenga una propiedad de clase coincidente utilizando el atributo BsonIgnoreExtraElements. Esto evita que el controlador arroje una excepción y asigna cualquier otro campo que tenga propiedades de clase coincidentes.

El siguiente ejemplo muestra cómo agregar un atributo BsonIgnoreExtraElements a una clase.

[BsonIgnoreExtraElements]
public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public List<string> Hobbies {get; set;}
}

También puedes ignorar cualquier elemento adicional al registrar un mapa de clase:

BsonClassMap.RegisterClassMap<Person>(classMap =>
{
     classMap.AutoMap();
     classMap.SetIgnoreExtraElements(true);
});

Mapeo con constructores

De forma predeterminada, el controlador .NET/C# solo puede asignar automáticamente una clase si esta tiene un constructor sin argumentos. Si desea que el controlador utilice un constructor que acepte uno o más argumentos, puede agregarle el atributo BsonConstructor. En este caso, el controlador examina los tipos para determinar cómo asignar los argumentos del constructor a las propiedades o campos de la clase.

Cuando el controlador crea un mapa de clase para la siguiente clase Person, utilizará el constructor marcado con el atributo BsonConstructor. El argumento name se asignará a la propiedad Name y el argumento age a la propiedad Age.

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public List<string> Hobbies {get; set;}
    [BsonConstructor]
    public Person(string name, string age)
    {
        Name = name;
        Age = age;
    }
}

Tip

Múltiples atributos de BsonConstructor

Si hay más de un constructor con el atributo BsonConstructor, el controlador utiliza el constructor que tiene la mayor cantidad de parámetros con campos coincidentes en el documento.

También puede especificar el constructor a utilizar al registrar su mapa de clase:

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public List<string> Hobbies {get; set;}
    public Person(string name, string age)
    {
        Name = name;
        Age = age;
    }
}
BsonClassMap.RegisterClassMap<Person>(classMap =>
{
    classMap.AutoMap();
    classMap.MapCreator(p => new Person(p.Name, p.Age));
});

Personalizar la serialización de propiedades

Puede personalizar la forma en que el controlador serializa una propiedad de clase añadiéndole atributos. Para obtener más información sobre la serialización de propiedades personalizadas, consulte Serialización personalizada.

Elementos adicionales de soporte

Puedes diseñar tu clase de C# para que almacene cualquier elemento adicional en tu documento que no tenga propiedades de clase coincidentes. Para ello, tu clase debe tener una propiedad de tipo BsonDocument que contenga los elementos adicionales.

El siguiente código utiliza el atributo BsonExtraElements con la propiedad ExtraElements para indicarle al controlador que almacene elementos adicionales:

public class Person
{
    public string Name { get; set;
    public int Age { get; set; }
    public List<string> Hobbies {get; set;}
    [BsonExtraElements]
    public BsonDocument ExtraElements {get; set;}
}

También puedes admitir elementos adicionales al inicializar un mapa de clase de la siguiente manera:

BsonClassMap.RegisterClassMap<Person>(classMap =>
{
    classMap.AutoMap();
    classMap.MapExtraElementsMember(p => p.ExtraElements);
});

Nota

Después de que el controlador serializa una clase con elementos adicionales en BSON, es posible que los elementos adicionales no estén en el mismo orden en que estaban en el documento original.

Serializar propiedades dinámicamente

Puede usar un método para determinar si se serializa una propiedad. Para que el controlador use el método automáticamente al serializar, debe anteponer ShouldSerialize al nombre del método, seguido del nombre de la propiedad a la que se aplica. Cuando el controlador detecta un método con esta convención de nomenclatura, lo usa para determinar si se serializan las propiedades que tienen el nombre de propiedad proporcionado.

El siguiente ejemplo crea un método que solo serializa la propiedad Age si su valor no es igual a 0. El controlador no serializa ninguna propiedad cuyos valores no cumplan este requisito:

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public List<string> Hobbies {get; set;}
    public bool ShouldSerializeAge()
    {
       return Age != 0;
    }
}

También puedes especificar el método al registrar un mapa de clases:

BsonClassMap.RegisterClassMap<Employee>(classMap =>
{
    classMap.AutoMap();
    classMap.MapMember(p => c.Age).SetShouldSerializeMethod(
        obj => ((Person) obj).Age != 0
    );
});

Información Adicional

Para obtener más información sobre el uso de clases C#, consulte POCO.

Documentación de la API

Volver

Serialización

POCOs