Mapeamento de classe

Nesta página

Visão geral

Mapeamento automático de classe
Crie um mapa de classe manualmente
Personalize a serialização de classe
Ignore elementos adicionais
Mapeamento com construtores
Personalize a serialização de propriedade
Suporte para elementos adicionais
Serialize propriedades dinamicamente
Informações adicionais
Documentação da API

Visão geral

Neste guia, você aprenderá a personalizar a maneira como o driver .NET/C# do MongoDB mapeia documentos BSON, de e para classes C#. Leia esta página para saber mais sobre o comportamento de mapeamento de classe padrão, ou se você precisar personalizar a maneira como o driver serializa ou desserializa seus dados.

Mapeamento automático de classe

Ao usar uma classe, em vez de um BsonDocument, para representar dados em uma coleção do MongoDB, o driver .NET/C# cria automaticamente um mapa de classe usado para serializar ou desserializar seus dados. Ele faz esse mapeamento combinando o nome do campo no documento com o nome da propriedade na classe.

Importante

O tipo da propriedade na sua classe deve corresponder ao tipo do campo no documento. O driver .NET/C# instancia um serializador com base no tipo de propriedade em sua classe. Se os tipos não corresponderem quando o driver tenta desserializar os dados, o serializador lançará uma exceção.

Crie um mapa de classe manualmente

Você pode ignorar a funcionalidade de mapeamento de classe automática do driver e definir manualmente o mapa de classe utilizando o método RegisterClassMap().

O exemplo abaixo define uma classe Person:

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

O código abaixo demonstra como registrar o mapa de classe para a classe Person:

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

Importante

Você deve registrar um mapa de classe antes que ele seja necessário em seu código. Recomendamos registrar mapas de classe antes de inicializar uma conexão com o MongoDB.

Você também pode mapear manualmente um subconjunto de propriedades de classe e, ao mesmo tempo, permitir que o driver mapeie automaticamente as propriedades restantes. Para tal, registre um mapa de classe e chame o método AutoMap() antes de especificar manualmente suas propriedades.

No exemplo de código abaixo, o método AutoMap() mapeia todas as propriedades da classe Person e, em seguida, ajusta manualmente o mapeamento para o campo Hobbies:

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

Personalize a serialização de classe

Você pode personalizar como o driver serializa e desserializa documentos no nível de classe usando atributos com a classe ou por métodos de chamada ao registrar um mapa de classe.

Ignore elementos adicionais

Quando um documento BSON é desserializado para uma classe C#, o driver .NET/C# examina o nome de cada campo no documento e tenta encontrar um nome de propriedade correspondente na classe. Por padrão, se um campo no documento não tiver uma correspondência na classe, o driver lançará uma exceção.

Você pode optar por ignorar qualquer elemento que não tenha uma propriedade de classe correspondente usando o atributo BsonIgnoreExtraElements. Isso evita que o driver lance uma exceção e mapeia quaisquer outros campos que tenham propriedades de classe correspondentes.

O exemplo abaixo mostra como adicionar um atributo BsonIgnoreExtraElements a uma classe.

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

Você também pode ignorar quaisquer elementos adicionais ao registrar um mapa de classe:

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

Mapeamento com construtores

Por padrão, o Driver .NET/C# pode mapear automaticamente uma classe somente se a classe tiver um construtor sem argumentos. Se você deseja que o driver utilize um construtor que aceite um ou mais argumentos, você poderá adicionar o atributo BsonConstructor no construtor. Nesse caso, o driver examina os tipos para determinar como mapear os argumentos do construtor para propriedades ou campos da classe.

Quando o driver cria um mapa de classe para a seguinte classe do Person, ele utilizará o construtor marcado com o atributo BsonConstructor. O argumento name irá mapear para a propriedade Name e o argumento age irá mapear para a propriedade 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;
    }
}

Dica

Múltiplos atributos do BsonConstructor

Se houver mais de um construtor com o atributo BsonConstructor, o driver usará o construtor que possui a maioria dos parâmetros com campos correspondentes no documento.

Você também pode especificar o construtor a ser utilizado ao registrar seu mapa de classe:

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

Personalize a serialização de propriedade

Você pode personalizar como o driver serializa uma propriedade de classe adicionando atributos à propriedade. Para obter mais informações sobre serialização de propriedade personalizada, consulte Serialização personalizada.

Suporte para elementos adicionais

Você pode projetar sua classe C# para armazenar quaisquer elementos adicionais em seu documento que não tenham propriedades de classe correspondentes. Para tal, sua classe deve ter uma propriedade do tipo BsonDocument para conter os elementos adicionais.

O código abaixo usa o atributo BsonExtraElements com a propriedade ExtraElements para direcionar o driver para armazenar elementos adicionais:

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

Você também pode apoiar elementos adicionais ao inicializar um mapa de classe da seguinte maneira:

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

Observação

Após o driver serializar uma classe com elementos adicionais de volta ao BSON, os elementos adicionais podem não estar na mesma ordem que estavam no documento original.

Serialize propriedades dinamicamente

Você pode utilizar um método para determinar se deseja serializar ou não uma propriedade. Para que o driver utilize automaticamente o método ao fazer a serialização, você deve inserir ShouldSerialize como prefixo no nome, seguido pelo nome da propriedade à qual o método se aplica. Quando o driver vê um método com essa convenção de nomenclatura, ele usa esse método para determinar se deve ou não serializar propriedades que tenham o nome de propriedade fornecido.

O exemplo abaixo cria um método que somente serializa a propriedade Age se seu valor não for igual a 0. O driver não serializa quaisquer propriedades cujos valores não cumpram 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;
    }
}

Você também pode especificar o método ao registrar um mapa de classe:

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

Informações adicionais

Para obter mais informações sobre o uso de classes C#, consulte POCOs.

Documentação da API

Voltar

Serialização

POCOs