/ /

Driver C#/ .NET

Serialização

Página inicial do Docs

Bibliotecas do cliente

Driver C#/ .NET

Serialização

GUIDs

Visão geral

Neste guia, você verá como serializar identificadores globalmente únicos (GUIDs), também conhecidos como identificadores universalmente únicos (UUIDs).

Dica

ObjectId

Em aplicativos MongoDB, você pode usar o tipo ObjectId como identificador exclusivo para um documento. Considere o uso de instâncias ObjectId no lugar de GUIDs em aplicativos MongoDB sempre que possível.

GUIDs no MongoDB

Um GUID é um número inteiro de 16bytes que você pode usar como um ID único para um documento do MongoDB. O bloco de código a seguir mostra um exemplo de GUID:

00112233-4455-6677-8899-aabbccddeeff

Originalmente, o MongoDB representava os GUIDs como valores BsonBinaryData do subtipo 3. Como o subtipo 3 não padronizado a ordem de bytes dos GUIDs durante a codificação, diferentes drivers do MongoDB codificaram GUIDs com diferentes ordens de bytes.

As abas a seguir mostram diferentes codificações de driver do GUID anterior para o BsonBinaryData subtipo 3:

33221100-5544-7766-8899-aabbccddeeff

00112233-4455-6677-8899-aabbccddeeff

77665544-3322-1100-ffee-ddccbbaa9988

Para padronizar a ordem de bytes GUID entre os aplicativos, adicionamos BsonBinaryData subtipo 4, que todos os drivers do MongoDB codificam da mesma maneira. Se sua aplicação usa GUIDs, recomendamos o uso do BsonBinaryData subtipo 4 para armazená-los.

Observação

GUIDs vazios

Ao serializar valores Guid.Empty, o driver .NET/C# trata esses valores como IDs não definidos. Os IDs desconfigurados recebem um novo GUID quando inseridos em uma coleção. O exemplo a seguir demonstra este comportamento:

var doc = new MyDocument { Name = "Test" }; // Id will default to Guid.Empty
collection.InsertOne(doc); // doc.Id will now contain a generated GUID, not Guid.Empty

Para armazenar documentos com um valor Guid.Empty como ID na coleção, desative a geração automática de ID usando um objeto MongoCollectionSettings. O seguinte exemplo de código demonstra como desativar a geração automática de ID:

var collectionSettings = new MongoCollectionSettings { AssignIdOnInsert = false }
var collection = database.GetCollection<MyDocument>("MyCollection", collectionSettings);

Para obter uma lista de todos os BsonBinaryData subtipos , consulte a documentação da API para BsonBinarySubType enumeração.

Serializando GUIDs

Embora recomendamos o uso do subtipo 4 para todos os novos BsonBinaryData GUIDs, algumas coleções mais antigas do MongoDB podem conter alguns campos GUID que usam subtipo 3 e outras que usam subtipo 4. Para levar em conta essas diferenças, o Driver .NET/C# gerencia a serialização de GUID no nível de propriedades individuais.

O driver .NET/C# usa a enumeração GuidRepresentation para representar os diferentes subtipos BsonBinaryData . A tabela a seguir mostra os membros da enumeração GuidRepresentation e os subtipos BsonBinaryData correspondentes:

Nó do GuidRepresentation	Subtipo BsonBinaryData
`Standard`	4
`CSharpLegacy`	3
`JavaLegacy`	3
`PythonLegacy`	3
`Unspecified`	N/A

As representações GUID CSharpLegacy, JavaLegacy e PythonLegacy são todas equivalentes ao BsonBinaryData subtipo 3, mas usam ordens de bytes diferentes.

Observação

Construir GUIDs Legados

Para construir valores de GUID legado (subtipo 3), você deve usar o construtor BsonBinaryData() para especificar explicitamente o tipo de GUID legado passando o parâmetro GuidRepresentation.CSharpLegacy. O seguinte código demonstra como criar um GUID legado para usar em um filtro de query:

var guid = new Guid("00112233-4455-6677-8899-aabbccddeeff");
var legacyGuid = new BsonBinaryData(guid, GuidRepresentation.CSharpLegacy);
var filter = new BsonDocument("legacyGuidField", legacyGuid);

As seções a seguir descrevem as maneiras pelas quais você pode configurar a representação GUID no seu aplicativo.

Configurar com Atributos

Se estiver usando o driver .NET/C# para automatizar suas classes C# para esquemas de documento, você pode adicionar o atributo BsonGuidRepresentation a uma propriedade GUID para especificar sua representação. Este atributo aceita um valor do enumeração.

O exemplo de código a seguir especifica a representação GUID Standard para a propriedade G :

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

Configurar no código

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 a seguir cria uma instância da classe GuidSerializer para serializar propriedades que usam o subtipo BsonBinaryData 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 BsonBinaryData, 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.

Importante

Se você não registrar globalmente um serializador, deverá aplicar o atributo BsonGuidRepresentation a cada propriedade GUID serializável. Caso contrário, o driver lançará uma exceção ao tentar serializar a propriedade.

Serializando Objetos

Você pode usar um ObjectSerializer para serializar objetos hierárquicos para subdocumentos. Para garantir que os GUIDs nesses objetos sejam serializados e desserializados corretamente, selecione a representação correta do GUID 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

BSON