/ /

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

In MongoDB applications, you can use the ObjectId type as a unique identifier for a document. Consider using ObjectId instances in place of GUIDs in MongoDB applications where possible.

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 GUIDs como BsonBinaryData valores do 3subtipo. Como 3 o subtipo não padronizou 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

If you're using the .NET/C# Driver to automap your C# classes to document schemas, you can add the BsonGuidRepresentation attribute to a GUID property to specify its representation. This attribute accepts a value from the GuidRepresentation enum.

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