/ /

/ /

Librerías de clientes

Driver C#/.NET

Actualizar

Actualiza a la versión 3.x

Overview

Esta página describe los cambios que podrías necesitar hacer a tu aplicación cuando actualices el Driver .NET/C# a la versión 3.x.

Cómo actualizar

Esta página enumera los posibles cambios disruptivos introducidos por una versión 3.x del driver .NET/C#. Para actualizar el driver .NET/C# a la versión 3.x, siga estos pasos:

Revisar la Compatibilidad página para asegurar que la nueva versión del driver sea compatible con las versiones de MongoDB Server a las que se conecta tu aplicación y con la versión de .NET o del framework .NET en la que se ejecuta tu aplicación.
Si usas una versión 2.x del controlador .NET/C#, actualiza a la v2.30. Para hacerlo, sigue el Guía de actualización v2.x.
Aborda los cambios disruptivos descritos en la sección Cambios disruptivos de la versión 3.0 .
Ejemplo
Si estás actualizando el controlador de la v2.14 a la v3.0, primero utiliza la v2.x guía de actualización para actualizar su controlador a la versión2.30. Luego, aborda todos los cambios disruptivos para la v3.0.

Versión 3.5 cambio disruptivo

El controlador deja de ser compatible con MongoDB Server 4.0 y anteriores. Debes actualizar tu servidor MongoDB a la versión v4.2 o posterior.
Para aprender a actualizar tu implementación de MongoDB Server, consulta notas de versión en el manual de MongoDB Server.
Para aprender más sobre la compatibilidad entre las versiones del driver .NET/C# y las versiones de MongoDB Server, visita la página de Compatibilidad.

Versión 3.0 cambio disruptivo

El controlador deja de soportar MongoDB Server v3.6 y versiones anteriores. Debes actualizar tu servidor MongoDB a la versión v4.0 o posterior.
Para aprender a actualizar tu implementación de MongoDB Server, consulta notas de versión en el manual de MongoDB Server.
Para aprender más sobre la compatibilidad entre las versiones del driver .NET/C# y las versiones de MongoDB Server, visita la página de Compatibilidad.
El driver deja de dar soporte a .NET Core 2.x y .NET Framework 4.6. Debes actualizar a .NET Core 3.x o posterior, o .NET Framework 4.7.2 o posterior.
Para obtener más información sobre la compatibilidad entre las versiones del controlador .NET/C# y .NET, visita la página de Compatibilidad.
El driver remueve el paquete NuGet mongocsharpdriver, que implementa la versión heredada v1.x API en versiones de controlador 2.x. Si estás usando la versión v1.x API, debes migrar a la nueva API.
Las clases, métodos y propiedades en la MongoDB.Driver.Core El namespace que se desaprobó en la versión2.30 está marcado como internal. Si el controlador proporciona un reemplazo para una clase, método o propiedad obsoleto, los mensajes del compilador en v2.30 lo mostrarán.
Los métodos, propiedades y constructores en el namespace MongoDB.Bson que fueron desaprobados en versiones anteriores del driver han sido removidos. Si el controlador proporciona un reemplazo para un método, propiedad o constructor obsoleto, los mensajes del compilador en v2.30 lo mostrarán.
El controlador deja de admitir el mecanismo de autenticación MONGODB-CR. Para aprender más sobre cómo configurar la autenticación en MongoDB .NET/C# Driver, consulta los Mecanismos de autenticación.
El controlador reemplaza la interfaz IMongoQueryable con la interfaz IQueryable, siguiendo el patrón utilizado por la mayoría de los otros proveedores de LINQ. Si su aplicación contiene referencias a IMongoQueryable, reemplácelas con IQueryable.
El driver remueve el método ClusterBuilder.ConfigureSdamLogging(). Para configurar el registro en tu aplicación, consulta la guía Registro.
El proveedor LINQ2 se eliminó de esta versión del controlador. Debes utilizar LINQ3 para todas las consultas LINQ.
Las consultas que utilizan proyecciones del lado del cliente lanzarán un error ExpressionNotSupportedException por defecto. Para habilitar las proyecciones del lado del cliente, establezca la propiedad EnableClientSideProjections de un objeto TranslationOptions en true. Puedes pasar este objeto TranslationOptions a un objeto AggregateOptions o FindOptions para habilitar proyecciones del lado del cliente para una sola query, o a un objeto MongoClientSettings para habilitar proyecciones del lado del cliente para todas las queries en una aplicación.
Las versiones anteriores del controlador .NET/C# admitían dos modos de representación GUID. En la versión 3.0, GuidRepresentationMode.V3 es el único modo soportado. Este cambio tiene los siguientes efectos sobre el driver:
- El BsonBinaryData(Guid) constructor se ha eliminado. Para construir un objeto BsonBinaryData a partir de un GUID, utilice el constructor BsonBinaryData.Create(Guid, GuidRepresentation). Para ver un ejemplo de cómo crear un GUID heredado, consulta la nota Construir GUID heredados en la guía de Serialización de GUID.
- Se ha eliminado la propiedad BsonBinaryData.GuidRepresentation.
- Solo puedes llamar al método BsonBinaryData.ToGuid() en objetos BsonBinaryData de tipo 4. Si el objeto tiene cualquier otro subtipo, debes llamar al método BsonBinaryData.ToGuid(GuidRepresentation) y especificar el subtipo.
- Se ha eliminado la conversión GUID mediante el uso de la clase BsonTypeMapper. Para convertir los valores de GUID a BSON, use el constructor BsonBinaryData(<GUID>, GuidRepresentation.Standard).
Los cambios anteriores afectan tu aplicación únicamente si serializas y deserializas documentos BSON directamente. Si solo asignas tus documentos de MongoDB a POCOs, el GuidRepresentationMode no afecta a tu aplicación.
Para obtener más información sobre la serialización de GUIDs en el controlador .NET/C#, consulta la página sobre GUIDs.
Las clases de excepción y sus tipos relacionados ya no contienen el atributo [Serializable] y, por tanto, ya no son compatibles con la API de serialización obsoleta de Microsoft. Para aprender cómo usar el controlador .NET/C# para serializar objetos, consulta la guía sobre Serialización.
TLS 1.0 y 1.1 ya no son compatibles. Debes usar TLS 1.2 o superior. Para aprender más sobre la configuración de TLS/SSL en el controlador .NET/C#, consulta Habilitar TLS en una conexión.
Por defecto, el driver serializa los valores de Decimal128 y decimal como valores BSON Decimal128. En versiones anteriores del controlador, este serializaba estos valores como valores BSON string por defecto. Para serializar un valor de decimal o Decimal128 como un string en v3.0, aplicar el atributo [BsonRepresentation(BsonType.String)] al campo.
Para obtener más información sobre cómo especificar BSON types durante la serialización, consulte la sección Serialización personalizada de la página POCOs.
Por defecto, el controlador serializa los valores DateTimeOffset como documentos BSON. En versiones anteriores del controlador, este serializó estos valores como arreglos BSON por defecto. Para serializar un valor DateTimeOffset como un arreglo en v3.0, aplica el atributo [BsonRepresentation(BsonType.Array)] al campo.

El modo de output JSON por defecto es JSON Extendida Relajada, un formato de string basado en el estándar JSON que describe documentos BSON. Relaxed Extended JSON pone énfasis en la legibilidad e interoperabilidad a costa de preservar el tipo.

Para utilizar un modo de salida JSON diferente, cree un nuevo objeto JsonWriterSettings. Establezca la propiedad OutputMode de este objeto en un valor del enumerado JsonOutputMode y, a continuación, pase el objeto al método ToJson() para serializar el documento. El siguiente ejemplo de código muestra cómo serializar un documento BSON a JSON estricto:

// Configure JsonWriterSettings
var jsonWriterSettings = new JsonWriterSettings
{
    OutputMode = JsonOutputMode.Strict
};
// Serialize the document to JSON using the configured settings
var json = document.ToJson(jsonWriterSettings);

El constructor de MongoClient acepta sólo un objeto Credential en lugar de un arreglo.
Para utilizar la autenticación de Amazon Web Services (AWS), debe agregar el paquete MongoDB.Driver.Authentication.AWS a su proyecto y registrar el proveedor de autenticación en el código bootstrap de su aplicación. Para obtener más información sobre cómo utilizar la autenticación de AWS con el controlador .NET/C#, consulta Autenticación IAM de AWS.
Para utilizar la encriptación en uso, debes agregar el paquete MongoDB.Driver.Encryption a tu proyecto y registrar el mecanismo de cifrado en el código de configuración de tu aplicación. Aprende más sobre cómo usar cifrado en uso con el driver .NET/C# en Cifrado en uso en el manual del MongoDB Server.
Si intentas serializar o deserializar un valor Infinity o NaN de punto flotante a una representación integral, el controlador lanza un OverflowException. Para obtener más información sobre los valores de punto flotante Infinity y NaN, consulta Double.NaN, Double.PositiveInfinity, y Double.NegativeInfinity. en MSDN.
El driver incluye los siguientes cambios en la clase BsonValue:
- Elimina el atributo [Obsolete] de las propiedades AsLocalTime y AsUniversalTime.
- Agrega las propiedades AsNullableLocalTime y AsNullableUniversalTime.
- Elimina la propiedad AsDateTime. En su lugar, utiliza la propiedad AsUniversalTime.
- Elimina la propiedad AsNullableDateTime. En su lugar, utilice la propiedad AsNullableUniversalTime.
El driver remueve eventos individuales del clúster de MongoClient.Cluster. Para suscribirse a eventos de clúster, llama al método ClusterBuilder.Subscribe().
Si algún tipo en una colección utiliza un discriminador escalar, el controlador lanzará una excepción si realizas alguna de las siguientes acciones en la colección:
- Llame al método Aggregate().OfType<T>(), como en el siguiente ejemplo:
  collection.Aggregate().OfType<T>()
- Llame al método Aggregate().Match(item => item is T), como en el siguiente ejemplo:
  collection.Aggregate().Match(item => item is T)
Para utilizar cualquiera de los métodos anteriores en una colección, se puede aplicar un discriminador jerárquico a cada clase de la colección. Consulte la página de Objetos polimórficos para aprender cómo.
Alternativamente, puedes comprobar el tipo de cada ítem de una manera diferente. Por ejemplo, puedes llamar al método Where() y pasar una expresión que compare el tipo del elemento con el tipo que buscas, como en el siguiente ejemplo:
```
collection.AsQueryable().Where(item => item.GetType() == typeof(T));
```
Para obtener más información sobre los discriminadores de tipos, consulta Objetos polimórficos.
El controlador ha sellado algunos tipos que no estaban diseñados para desarrollos adicionales mediante herencia. Esto incluye los siguientes cambios:
- El controlador sella todos los serializadores de hormigón. Para implementar un serializador personalizado, implementar la interfaz IBsonSerializer.
- El controlador sella las clases MongoClient, MongoDatabase y MongoCollection. Recomendamos usar directamente las interfaces IMongoClient, IMongoDatabase y IMongoCollection.
El controlador requiere que las aplicaciones configuren explícitamente cómo serializar GUIDS usando las clases GuidSerializer y ObjectSerializer. Los usuarios del Driver .NET/C# que desarrollan nuevas aplicaciones pueden implementar un GuidSerializer global registrándolo. Recomendamos que los usuarios que tengan aplicaciones más antiguas verifiquen que todo GUIDs esté serializado de la misma manera al implementar un GuidSerializer global. También puedes configurar la serialización de GUID caso por caso sin registrar una GuidSerializer global.
Para obtener más información sobre la serialización de GUID, consulta la guía GUIDs.

Por defecto, el controlador serializa los valores TimeOnly como valores BSON int64 que representan Ticks. Las versiones anteriores del controlador serializaban los valores TimeOnly como documentos BSON por defecto.

Para serializar un valor TimeOnly como documento en la v3.0 o posterior, registra el tipo TimeOnly con un BsonClassMapSerializer como se muestra en el siguiente ejemplo:

var timeOnlyClassMap = new BsonClassMap<TimeOnly>(cm =>
     cm.AutoMap()).Freeze();
var serializer = new BsonClassMapSerializer<TimeOnly>(timeOnlyClassMap);
BsonSerializer.RegisterSerializer(serializer);

Volver

Versión 2.x

Versiones 2.0 a 2.18

Overview

Cómo actualizar

Ejemplo

Versión 3.5 cambio disruptivo

Versión 3.0 cambio disruptivo