/ /

Fundamentals

Serialización

Docs Home

Librerías de clientes

Driver C#/.NET

Fundamentals

Serialización

Personalizar el mapeo de clases

Overview

En esta guía, puedes aprender cómo personalizar el modo en que el Controlador MongoDB .NET/C# mapea documentos BSON hacia y desde clases de C#. Debe leer esta página para aprender más sobre el comportamiento de asignación de clase por defecto, 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 vez de un BsonDocument, para representar datos en una colección de MongoDB, el controlador .NET/C# crea automáticamente un mapa de clase que se utiliza para serializar o deserializar los datos. Este mapeo se realiza al hacer coincidir el nombre del campo en el documento con el nombre de la propiedad en la clase.

Importante

El tipo de la propiedad en tu clase debe coincidir con el tipo del campo en el documento. El Driver .NET/C# crea una instancia de un serializador basado en el tipo de la propiedad de la clase. Si los tipos no coinciden cuando el controlador intenta deserializar los datos, el serializador lanza una excepción.

Creación manual de un mapa de clase

Puedes omitir la funcionalidad de asignación de clases automática del driver y definir manualmente el mapa de clases utilizando el método RegisterClassMap().

El siguiente ejemplo define una clase de 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 clases 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 clases antes de que sea necesario en su código. Recomendamos registrar mapas de clases antes de inicializar una conexión con MongoDB.

También puede asignar manualmente un subconjunto de propiedades de la clase, mientras permite que el controlador asigne automáticamente las propiedades restantes. Para hacer esto, registre un mapa de clases y llame al método AutoMap() antes de especificar manualmente sus 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 driver serializa y deserializa documentos a nivel de clase usando atributos con la clase o llamando a métodos mientras registra un mapa de clases.

Ignorar elementos extra

Cuando un documento BSON se deserializa a una clase en C#, el controlador .NET/C# examina el nombre de cada campo en el documento e intenta encontrar un nombre de propiedad coincidente en la clase. Por defecto, si un campo en el documento no tiene una coincidencia en la clase, el controlador lanza 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 extra al registrar un mapa de clase:

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

Mapeo con constructores

Por defecto, el controlador .NET/C# mapea automáticamente una clase si la clase tiene un constructor sin argumentos. Este constructor puede tener cualquier modificador de acceso, incluyendo private. Para que el controlador utilice un constructor que acepte argumentos, agrega el atributo BsonConstructor al constructor. Luego, el controlador examina el tipo y asigna los argumentos del constructor a las correspondientes propiedades o campos de la clase.

Para la siguiente clase Person, el controlador usa el constructor marcado con el atributo BsonConstructor para crear un mapa de clases. El argumento name se asigna a la propiedad Name y el argumento age se asigna 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 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 que se utilizará cuando registre su mapa de clases:

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));
});

Personaliza la serialización de propiedades

Se puede personalizar cómo el controlador serializa una propiedad de clase añadiendo atributos a la propiedad. Para obtener más información sobre la serialización de propiedades personalizadas, consulta Serialización personalizada.

Soporte de elementos extra

Puedes diseñar tu clase C# para almacenar cualquier elemento extra en tu documento que no tenga propiedades de clase correspondientes. Para ello, la clase debe tener una propiedad de tipo BsonDocument para guardar los elementos extra.

El siguiente código utiliza el atributo BsonExtraElements con la propiedad ExtraElements para indicar al driver 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 extra 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, al convertirla nuevamente a BSON, los elementos adicionales pueden no conservar el mismo orden que tenían en el documento original.

Serializar propiedades dinámicamente

Puedes usar un método para determinar si serializar o no una propiedad. Para que el controlador use automáticamente el método al serializar, debes anteponer el nombre del método con ShouldSerialize, seguido del nombre de la propiedad a la que se aplica el método. Cuando el controlador ve un método con esta convención de nombres, utiliza ese método para determinar si serializar o no las propiedades que tienen el nombre de propiedad proporcionado.

El siguiente ejemplo crea un método que sólo serializa la propiedad Age si su valor no es igual a 0. El driver 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 más información sobre el uso de clases C#, consulta POCOs.

Documentación de la API

Volver

Serialización

POCOs