/ /

/ /

Librerías de clientes

Driver C#/.NET

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

ObjectId

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

GUID en MongoDB

Un GUID es un número entero de 16bytes que puedes usar como un ID único para un documento de MongoDB. El siguiente bloque de código muestra un ejemplo de GUID:

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 GUID entre aplicaciones, hemos añadido BsonBinaryData subtipo 4, que todos los controladores de MongoDB codifican de la misma manera. Si su aplicación usa GUID, se recomienda usar el BsonBinaryData subtipo 4 para almacenarlos.

Nota

GUIDs vacíos

Al serializar valores Guid.Empty, el controlador .NET/C# trata estos valores como IDs no establecidos. Las identificaciones no establecidas reciben un nuevo GUID al ser insertadas 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 Guid.Empty valor como ID en la colección, desactiva la generación automática de ID utilizando un objeto MongoCollectionSettings. El siguiente ejemplo de código demuestra cómo desactivar 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 nuevos GUID de BsonBinaryData, algunas colecciones antiguas de MongoDB podrían contener algunos campos de GUID que utilizan el subtipo 3 y otros que utilizan el subtipo 4. Para tener en cuenta estas diferencias, el controlador .NET/C# gestiona la serialización de GUID a nivel de propiedades individuales.

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

nodo de GuidRepresentation	Subtipo de 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), se debe usar el constructor BsonBinaryData() para especificar explícitamente el tipo de GUID heredado pasando el parámetro GuidRepresentation.CSharpLegacy. El siguiente código demuestra cómo crear un GUID heredado para usarlo en un 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);

Las siguientes secciones describen las formas en que puedes configurar la representación GUID en tu 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 el código

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 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

Cuando trabajes con dos subtipos BsonBinaryData, 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 utilizar el atributo BsonGuidRepresentation para denotar cualquier propiedad GUID de otro subtipo.

Importante

Si no registras un serializador globalmente, debes aplicar el atributo BsonGuidRepresentation a cada propiedad GUID serializable. De lo contrario, el controlador lanzará una excepción si intenta serializar la propiedad.

Serializando 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 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

BSON