/ /

/ /

Librerías de clientes

Driver C#/.NET

Serialización

GUIDs

Overview

En esta guía, puede aprender a serializar identificadores únicos globales (GUID), también conocidos como identificadores únicos universales (UUID).

Tip

ObjectId

En las aplicaciones MongoDB, puede usar el tipo ObjectId como identificador único para un documento. Considere usar ObjectId instancias en lugar de GUID en aplicaciones MongoDB cuando sea posible.

GUID en MongoDB

Un GUID es un entero de 16bytes que se puede usar como identificador único para un documento de MongoDB. El siguiente bloque de código muestra un GUID de ejemplo:

00112233-4455-6677-8899-aabbccddeeff

Originalmente, MongoDB representaba los GUID como BsonBinaryData valores del 3subtipo. Dado que 3 el subtipo no estandarizaba el orden de bytes de los GUID durante la codificación, los distintos controladores de MongoDB codificaban los GUID con distintos órdenes de bytes.

Las siguientes pestañas muestran diferentes codificaciones de controlador del GUID anterior al subtipo BsonBinaryData 3:

33221100-5544-7766-8899-aabbccddeeff

00112233-4455-6677-8899-aabbccddeeff

77665544-3322-1100-ffee-ddccbbaa9988

Para estandarizar el orden de bytes de los GUID en todas las aplicaciones, añadimos el subtipo BsonBinaryData 4, que todos los controladores de MongoDB codifican de la misma manera. Si su aplicación utiliza GUID, recomendamos usar el subtipo BsonBinaryData 4 para almacenarlos.

Nota

GUID vacíos

Al serializar valores Guid.Empty, el controlador .NET/C# los trata como IDs no definidos. Estos IDs reciben un nuevo GUID al insertarse en una colección. El siguiente ejemplo demuestra este comportamiento:

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 almacenar documentos con un valor Guid.Empty como ID en la colección, desactive la generación automática de ID mediante un objeto MongoCollectionSettings. El siguiente ejemplo de código muestra cómo deshabilitar la generación automática de ID:

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

Para obtener una lista de todos los subtipos BsonBinaryData, consulte la documentación de la API para la enumeración BsonBinarySubType.

Serialización de GUID

Aunque recomendamos usar el subtipo 4 para todos los GUID BsonBinaryData nuevos, algunas colecciones antiguas de MongoDB podrían contener campos GUID que usan el subtipo 3 y otros que usan el subtipo 4. Para compensar estas diferencias, el controlador .NET/C# gestiona la serialización de GUID a nivel de propiedades individuales.

El controlador .NET/C# utiliza la enumeración GuidRepresentation para representar los diferentes subtipos BsonBinaryData. La siguiente tabla muestra los miembros de la enumeración GuidRepresentation y los subtipos BsonBinaryData correspondientes:

Miembro de GuidRepresentation	Subtipo BsonBinaryData
`Standard`	4
`CSharpLegacy`	3
`JavaLegacy`	3
`PythonLegacy`	3
`Unspecified`	N/A

Las representaciones GUID CSharpLegacy, JavaLegacy y PythonLegacy son todas equivalentes al subtipo BsonBinaryData 3, pero utilizan órdenes de bytes diferentes.

Nota

Construir GUID heredados

Para construir valores GUID heredados (subtipo 3), debe usar el constructor BsonBinaryData() para especificar explícitamente el tipo de GUID heredado mediante el parámetro GuidRepresentation.CSharpLegacy. El siguiente código muestra cómo crear un GUID heredado para usarlo en un filtro de consulta:

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

Las siguientes secciones describen las formas en que puede configurar la representación GUID en su aplicación.

Configurar con atributos

Si está utilizando el controlador .NET/C# para Para automatizar la asignación de clases de C# a esquemas de documentos, puede agregar el BsonGuidRepresentation atributo a una propiedad GUID para especificar su representación. Este atributo acepta un valor de la enumeración GuidRepresentation.

El siguiente ejemplo de código especifica la representación GUID Standard para la propiedad G:

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

Configurar en código

Si escribe su propio código de serialización, puede usar la clase GuidSerializer para serializar y deserializar valores GUID individuales desde y hacia campos BSON. Para garantizar que el controlador gestione los GUID correctamente, use el parámetro GuidRepresentation al construir un GuidSerializer.

El siguiente ejemplo de código crea una instancia de la clase GuidSerializer para serializar propiedades que usan el subtipo BsonBinaryData 4:

var guidSerializer = new GuidSerializer(GuidRepresentation.Standard);

Si la mayoría de sus GUID usan la misma representación, puede registrar un GuidSerializer globalmente. Para crear y registrar un GuidSerializer, ejecute el siguiente código al principio de su aplicación, por ejemplo, durante la fase de arranque:

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

Tip

Al trabajar con dos subtipos BsonBinaryData, se puede combinar un serializador global con el atributo de propiedad BsonGuidRepresentation. Por ejemplo, se puede registrar un serializador global para el subtipo GUID más utilizado y luego usar el atributo BsonGuidRepresentation para indicar cualquier propiedad GUID de otro subtipo.

Importante

Si no registra globalmente un serializador, debe aplicar el atributo BsonGuidRepresentation a cada propiedad GUID serializable. De lo contrario, el controlador genera una excepción al intentar serializar la propiedad.

Serialización de objetos

Puede usar un ObjectSerializer para serializar objetos jerárquicos en subdocumentos. Para garantizar que los GUID de estos objetos se serialicen y deserialicen correctamente, seleccione la representación GUID correcta al construir su ObjectSerializer.

El siguiente ejemplo de código muestra cómo crear un ObjectSerializer para una representación GUID de subtipo 4:

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

Si su aplicación depende de un ObjectSerializer para serializar cualquier GUID, también debe registrar el serializador al principio de la aplicación, por ejemplo, durante la fase de arranque. El serializador que registre se usará globalmente siempre que se necesite un serializador de objetos y no se especifique lo contrario.

Para registrar tu ObjectSerializer, pásalo al método BsonSerializer.RegisterSerializer():

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

Información Adicional

Para aprender más sobre cualquiera de los métodos o tipos analizados en esta guía, consulta la siguiente documentación de API:

Volver

Objetos polimórficos

BSON