/ /

/ /

Librerías de clientes

Driver C#/.NET

Fundamentals

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

En las aplicaciones MongoDB, ObjectId Se puede usar como identificador único de un documento. Considere usar ObjectId en lugar de un GUID con aplicaciones MongoDB siempre que sea posible.

Un GUID es un entero de 16 bytes que puede usar como un ID único para un documento de MongoDB. Originalmente, los GUIDs en MongoDB se representaban como valores BsonBinaryData de subtipo 3. El subtipo 3 no estandarizaba el orden de los bytes durante la serialización, lo que llevaba a una serialización inconsistente entre los diferentes drivers de MongoDB. Para estandarizar el orden de los bytes y asegurar una serialización coherente entre los diferentes drivers, creamos BsonBinaryData subtipo 4.

Nota

Usa el BsonBinaryData subtipo 4 para todos los nuevos GUID.

Modo de representación Guid

En muchas colecciones de MongoDB, todos los campos GUID usan el mismo subtipo BsonBinaryData. Sin embargo, algunas colecciones antiguas pueden contener campos GUID que usan el subtipo 3 y otros que usan el subtipo 4. Para garantizar que el controlador serialice y deserialice todos los GUID correctamente, debe establecer la propiedad BsonDefaults.GuidRepresentationMode con uno de los siguientes valores GuidRepresentationMode:

V2

GuidRepresentationMode.V2 Se asume que todos los GUID de un documento usan el mismo subtipo BsonBinaryData. En este modo, la representación de los GUID la controla el lector o el escritor, no el serializador.

V2 es el valor predeterminado GuidRepresentationMode.

Nota

Cuando se lance la versión 3 del controlador .NET/C#, se eliminará la compatibilidad con GuidRepresentationMode.V2 del controlador y V3 pasará a ser el predeterminado.

V3

GuidRepresentationMode.V3 Permite que los campos de un mismo documento utilicen diferentes formatos GUID. En este modo, la representación de GUID se controla a nivel de propiedad mediante la configuración del serializador para cada propiedad.

Para usar GuidRepresentationMode.V3, ejecute la siguiente línea de código. Debe ejecutar este código durante la fase de arranque de su aplicación, antes de crear un objeto MongoClient.

BsonDefaults.GuidRepresentationMode = GuidRepresentationMode.V3;

Ejecutar en modo V3 cambia el comportamiento del controlador de las siguientes maneras:

El método BsonBinaryReader.ReadBinaryData() ignora readerSettings.GuidRepresentation
El método BsonBinaryWriter.WriteBinaryData() ignora writerSettings.GuidRepresentation
El método JsonReader.ReadBinaryData() ignora readerSettings.GuidRepresentation
JsonWriter ignores writerSettings.GuidRepresentation
Llamar al método BsonBinaryData.ToGuid() sin el parámetro GuidRepresentation solo funciona en GUID del subtipo 4.

Nota

No puedes usar GuidRepresentationMode.V2 y GuidRepresentationMode.V3 en una sola aplicación.

Serialización de GUID en V3

GuidRepresentationMode.V3 Gestiona la serialización de GUID a nivel de propiedades individuales. Este modo es más flexible que V2, pero también implica que debe asegurarse de que cada campo GUID se serialice y deserialice correctamente.

Si está utilizando el controlador .NET/C# para Para automatizar sus clases de C# para documentar esquemas, puede usar el BsonGuidRepresentation atributo en una propiedad GUID para especificar la representación:

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

Nota

GuidRepresentation.Standard Equivale al subtipo BsonBinaryData 4. Otras representaciones GUID en el controlador .NET/C#, como CSharpLegacy, JavaLegacy y PythonLegacy, son equivalentes al subtipo 3, pero utilizan órdenes de bytes diferentes.

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 código de muestra crea una instancia de GuidSerializer para serializar representaciones GUID de subtipo 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, 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.

Serialización de objetos en V3

Puede usar un ObjectSerializer para serializar objetos jerárquicos en subdocumentos. Para garantizar que los GUID de estos objetos se serialicen y deserialicen correctamente al usar V3, debe seleccionar 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

Transacciones