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
- Campos de omissão
- Ignore elementos adicionais
- Identificar campo de ID
- 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ê pode aprender a personalizar a maneira como o Driver MongoDB .NET/C# 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 precisar personalizar a maneira como o driver serializa ou desserializa seus dados.
Você também pode usar atributos POCO para definir o comportamento da serialização . Para saber mais, consulte o guia dePOCOs do.
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
Quando registrar um mapa de classe
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 da classe aplicando atributos à classe ou chamando métodos enquanto registra um mapa de classe .
Campos de omissão
Você pode evitar que campos especificados sejam serializados usando o método UnmapMember()
ao registrar um mapa de classe .
O exemplo seguinte mostra como criar um mapa de classe para evitar que a propriedade Age
seja serializada:
BsonClassMap.RegisterClassMap<Person>(classMap => { classMap.AutoMap(); classMap.UnmapMember(p => p.Age); });
Dica
Para saber como definir esse comportamento usando um atributo de campo, consulte a seção Omitir campos do guia POCOs.
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.
[ ]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); });
Identificar campo de ID
Por padrão, o driver mapeia qualquer propriedade pública denominada Id
, id
ou _id
para o campo BSON _id
. Para selecionar explicitamente a propriedade a ser mapeada para o campo _id
, use o método de mapa de classe MapIdMember()
.
A seguinte amostra de código mapeia a propriedade Identifier
para o campo _id
:
BsonClassMap.RegisterClassMap<Person>(classMap => { classMap.AutoMap(); classMap.MapIdMember(p => p.Identifier); });
IDs de string
Se você estiver usando strings para representar seus IDs de documento, poderá usar o método de mapa de classe IdMemberMap.SetSerializer()
para serializar esses valores para instâncias ObjectId
no MongoDB. Dessa forma, você pode personalizar como seus valores de ID são representados em seu aplicação enquanto adere às práticas recomendadas do MongoDB para gerenciamento de ID no banco de dados.
O exemplo a seguir direciona o driver a serializar valores de ID de string como valores ObjectId
:
BsonClassMap.RegisterClassMap<Person>(classMap => { classMap.AutoMap(); classMap.IdMemberMap.SetSerializer(new StringSerializer(BsonType.ObjectId)); });
Se quiser que o driver gere cadeias hexadecimais válidas de 24dígitos para usar como seus valores de ID, você pode encadear o método SetIdGenerator()
ao método MapIdMember()
e passar uma instância de StringObjectIdGenerator
:
BsonClassMap.RegisterClassMap<Person>(classMap => { classMap.AutoMap(); classMap.MapIdMember(p => p.Identifier).SetIdGenerator(StringObjectIdGenerator.Instance); });
Para saber mais sobre geradores de ID, consulte a seção Especificar um gerador de ID do guia POCOs.
IDs GUID
Se seu aplicação usar GUIDs como identificadores exclusivos em seus documentos, você poderá registrar um mapa de classe para especificar como os valores Guid
são serializados. Por padrão, o driver utiliza o tipo GuidGenerator
para gerar um valor único para a propriedade ID. Você deve especificar a representação GUID inicializando um GuidSerializer
.
O seguinte código especifica a representação do GUID do Standard
ao registrar o mapa de classe :
BsonClassMap.RegisterClassMap<Person>(classMap => { classMap.AutoMap(); classMap.IdMemberMap.SetSerializer(new GuidSerializer(GuidRepresentation.Standard)); });
Para saber mais sobre a serialização de GUIDs, consulte o guia de GUIDs.
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;} [ ] 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;} [ ] 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.