GUIDs

Nesta página

Visão geral

GuidRepresentationMode
V2
V3
Serializar GUIDs na V3
Serializar objetos na V3
Informações adicionais

Visão geral

Neste guia, você pode aprender a serializar identificadores globais exclusivos (GUIDs), também conhecidos como identificadores universalmente exclusivos (UUIDs).

Dica

Em aplicativos do MongoDB, ObjectId pode ser usado como um identificador único para um documento. Recomendamos usar ObjectId no lugar de um GUID com aplicativos do MongoDB sempre que possível.

Um GUID é um número inteiro de 16 bytes que você pode usar como um ID único para um documento do MongoDB. Originalmente, os GUIDs no MongoDB eram representados como valores BsonBinaryData do subtipo 3. O subtipo 3 não padronizava a ordem dos bytes durante a serialização, o que gerava uma serialização inconsistente entre os drivers do MongoDB. Para padronizar a ordem de bytes e garantir a serialização consistente entre os drivers, criamos o BsonBinaryData subtipo 4.

Observação

Use BsonBinaryData do subtipo 4 para todos os novos GUIDs.

GuidRepresentationMode

Em muitas coleções do MongoDB, todos os campos GUID utilizam o mesmo subtipo do BsonBinaryData. Coleções mais antigas, no entanto, podem conter alguns campos GUID que usam o subtipo 3 e outros que usam o subtipo 4. Para garantir que o driver serialize e desserialize todos os GUIDs corretamente, você deve definir a propriedade BsonDefaults.GuidRepresentationMode para um dos seguintes valores GuidRepresentationMode:

V2

GuidRepresentationMode.V2 assume que todos os GUIDs em um documento usam o mesmo subtipo BsonBinaryData. Neste modo, a representação do GUID é controlada pelo leitor ou gravador, não pelo serializador.

V2 é o GuidRepresentationMode padrão.

Observação

Quando a versão 3 do driver .NET/C# for lançada, o suporte para GuidRepresentationMode.V2 será removido do driver e o V3 se tornará padrão.

V3

GuidRepresentationMode.V3 permite que campos no mesmo documento usem formatos GUID diferentes. Neste modo, a representação GUID é controlada no nível da propriedade ao configurar o serializador para cada propriedade.

Para usar o GuidRepresentationMode.V3, execute a seguinte linha de código. Você deve executar este código durante a fase de inicialização do seu aplicativo, antes de criar um objeto MongoClient.

BsonDefaults.GuidRepresentationMode = GuidRepresentationMode.V3;

A execução no modo V3 altera o comportamento do driver das seguintes formas:

O método BsonBinaryReader.ReadBinaryData() ignora readerSettings.GuidRepresentation
O método BsonBinaryWriter.WriteBinaryData() ignora writerSettings.GuidRepresentation
O método JsonReader.ReadBinaryData() ignora readerSettings.GuidRepresentation
JsonWriter ignora writerSettings.GuidRepresentation
Chamar o método BsonBinaryData.ToGuid() sem o parâmetro GuidRepresentation funciona somente em GUIDs do subtipo 4.

Observação

Você não pode usar GuidRepresentationMode.V2 e GuidRepresentationMode.V3 em um único aplicativo.

Serializar GUIDs na V3

GuidRepresentationMode.V3 gerencia a serialização de GUID no nível de propriedades individuais. Este modo é mais flexível do que V2, mas também significa que você deve garantir que cada campo GUID seja serializado e desserializado corretamente.

Se usar o Driver .NET/C# para automatizar suas classes C# para documentar esquemas, você pode utilizar o BsonGuidRepresentation atributo em uma propriedade GUID para especificar a representação:

public class Widget
{
    public int Id { get; set; }
   [BsonGuidRepresentation(GuidRepresentation.Standard)]
   public Guid G { get; set; }
}

Observação

GuidRepresentation.Standard é equivalente a BsonBinaryData do subtipo 4. Outras representações GUID no Driver .NET/C#, como CSharpLegacy, JavaLegacy e PythonLegacy, são equivalentes ao subtipo 3, mas usam ordens de bytes diferentes.

Se você gravar seu próprio código de serialização, você pode usar a classe GuidSerializer para serializar e desserializar valores GUID individuais de e para campos BSON. Para garantir que o driver gerencie corretamente os GUIDs, use o parâmetro GuidRepresentation ao construir um GuidSerializer.

A amostra de código abaixo cria uma instância do GuidSerializer para serializar representações GUID do subtipo 4:

var guidSerializer = new GuidSerializer(GuidRepresentation.Standard);

Se a maioria dos seus GUIDs usar a mesma representação, você poderá registrar um GuidSerializer globalmente. Para criar e registrar um GuidSerializer, execute o código abaixo no início do seu aplicativo, por exemplo, durante a fase de inicialização:

BsonSerializer.RegisterSerializer(new GuidSerializer(GuidRepresentation.Standard));

Dica

Ao trabalhar com dois subtipos, você pode combinar um serializador global com o atributo de propriedade BsonGuidRepresentation. Por exemplo, você pode registrar um serializador global para o subtipo de GUID mais usado e, em seguida, usar o atributo BsonGuidRepresentation para indicar qualquer propriedade GUID de outro subtipo.

Serializar objetos na V3

Você pode usar um ObjectSerializer para serializar objetos hierárquicos para subdocumentos. Para garantir que GUIDs nestes objetos sejam serializados e desserializados corretamente ao utilizar o V3, você deve selecionar a representação GUID correta ao construir seu ObjectSerializer.

A amostra de código abaixo ensina como criar um ObjectSerializer para uma representação GUID do subtipo 4:

var objectDiscriminatorConvention = BsonSerializer.LookupDiscriminatorConvention(typeof(object));
var objectSerializer = new ObjectSerializer(objectDiscriminatorConvention, GuidRepresentation.Standard);

Se o seu aplicativo depender de um ObjectSerializer para serializar qualquer GUID, você também deverá registrar o serializador no início do aplicativo, por exemplo, durante a fase de inicialização. O serializador registrado será usado globalmente sempre que um serializador de objeto for necessário e não tiver sido especificado de outra forma.

Para registrar seu ObjectSerializer, passe para o método BsonSerializer.RegisterSerializer():

var objectDiscriminatorConvention = BsonSerializer.LookupDiscriminatorConvention(typeof(object));
var objectSerializer = new ObjectSerializer(objectDiscriminatorConvention, GuidRepresentation.Standard);
BsonSerializer.RegisterSerializer(objectSerializer);

Informações adicionais

Para saber mais sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API:

Voltar

Objetos polimórficos

Transações