/ /

/ /

Librerías de clientes

Driver C#/.NET

Fundamentals

Serialización

GUIDs

Overview

En esta guía, puedes aprender cómo serializar identificadores globalmente únicos (GUIDs), también conocidos como identificadores únicos universales (UUIDs).

Tip

En las aplicaciones MongoDB, ObjectId puede usarse como un identificador único para un documento. Considera usar ObjectId en lugar de un GUID en las aplicaciones de MongoDB cuando 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 más 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 asume que todos los GUID de un documento utilizan el mismo subtipo BsonBinaryData. En este modo, la representación GUID es controlada por el lector o el escritor, no por el serializador.

V2 es el/la GuidRepresentationMode por defecto.

Nota

Cuando se lance la versión 3 del controlador .NET/C#, el soporte para GuidRepresentationMode.V2 se eliminará del driver y V3 se convertirá en por defecto.

V3

GuidRepresentationMode.V3 permite que los campos en el mismo documento utilicen diferentes formatos de GUID. En este modo, la representación de GUID se controla a nivel de propiedad, configurando el 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
La llamada al método BsonBinaryData.ToGuid() sin el parámetro GuidRepresentation solo funciona en GUIDs de subtipo 4.

Nota

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

Serialización de GUID en V3

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

Si está utilizando el controlador .NET/C# para automatic mappeo de tus clases C# a esquemas de documentos, puedes usar el atributo BsonGuidRepresentation 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 es equivalente a BsonBinaryData subtipo 4. Otras representaciones GUID en el controlador .NET/C#, como CSharpLegacy, JavaLegacy y PythonLegacy, son equivalentes al subtipo 3 pero usan diferentes órdenes de bytes.

Si estás escribiendo tu propio código de serialización, puedes usar la clase GuidSerializer para serializar y deserializar valores individuales de GUID hacia y desde campos BSON. Para garantizar que el driver gestione correctamente los GUIDs, utilice el parámetro GuidRepresentation cuando cree 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

Cuando trabajas con dos subtipos, puedes combinar un serializador global con el atributo de propiedad BsonGuidRepresentation. Por ejemplo, puedes registrar un serializador global para el subtipo GUID más utilizado y luego usar el atributo BsonGuidRepresentation para denotar 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 su aplicación, como durante la fase de inicialización. El serializador que registre se utilizará a nivel global cada vez que sea necesario un serializador de objetos y no se haya especificado de otro modo.

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