Menu Docs
Página inicial do Docs
/ / /
Driver C#/ .NET
/ /

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

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.

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.

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

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 .

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.

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

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

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.

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.

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

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.

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.

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

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

  • BsonClassMap

  • RegisterClassMap

  • AutoMap

Voltar

Serialização