/ /

/ /

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 de v2.x.
Aborda los cambios disruptivos descritos en la sección Cambios disruptivos de la versión 3.0 .
Ejemplo
Si va a actualizar el controlador de la versión 76002.14 a3.0 la 7800, primero utilice la guía de actualización de la2 versión 4.x para actualizarlo a la versión2.30 8100. Después, solucione todos los cambios importantes para la versión 8300.3.0

Cambios importantes en la versión 3.5

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.

Cambios importantes en la versión 3.0

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 las versiones .NET, visite la página 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.
Se han eliminado los métodos, propiedades y constructores del espacio de nombres MongoDB.Bson que estaban obsoletos en versiones anteriores del controlador. 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 ya no admite el MONGODB-CR mecanismo de autenticación. Para obtener más información sobre la configuración de la autenticación en el controlador .NET/C#, consulte 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 generarán un error ExpressionNotSupportedException de forma predeterminada. Para habilitar las proyecciones del lado del cliente, establezca la propiedad EnableClientSideProjections de un objeto TranslationOptions en true. Puede pasar este objeto TranslationOptions a un objeto AggregateOptions o FindOptions para habilitar las proyecciones del lado del cliente para una sola consulta, o a un objeto MongoClientSettings para habilitarlas para todas las consultas de 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 compatible. Este cambio tiene los siguientes efectos en el controlador:
- 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 se puede llamar al método BsonBinaryData.ToGuid() en objetos BsonBinaryData del subtipo 4. Si el objeto tiene otro subtipo, se debe llamar al método BsonBinaryData.ToGuid(GuidRepresentation) y especificar el subtipo.
- Se ha eliminado la conversión de GUID mediante la clase BsonTypeMapper. Para convertir valores GUID a BSON, utilice el constructor BsonBinaryData(<GUID>, GuidRepresentation.Standard).
Los cambios anteriores solo afectan a su aplicación si serializa y deserializa documentos BSON directamente. Si asigna sus documentos MongoDB solo a POCO, el GuidRepresentationMode no afecta a su 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 [Serializable] atributo y, por lo tanto, ya no son compatibles con la API de serialización heredada de Microsoft. Para aprender a usar el controlador .NET/C# para serializar objetos, consulte la guía de 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.
De forma predeterminada, el controlador serializa los valores DateTimeOffset como documentos BSON. En versiones anteriores, serializaba estos valores como matrices BSON. Para serializar un valor DateTimeOffset como una matriz en v3.0, aplique el atributo [BsonRepresentation(BsonType.Array)] al campo.

El modo de salida JSON predeterminado es JSON Extendido Relajado, un formato de cadena basado en el estándar JSON que describe documentos BSON. JSON Extendido Relajado prioriza la legibilidad y la interoperabilidad, a costa de la preservación de tipos.

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 usar la autenticación de Amazon Web Services (AWS), debe agregar el MongoDB.Driver.Authentication.AWS paquete a su proyecto y registrar el proveedor de autenticación en el código de arranque de su aplicación. Para obtener más información sobre el uso de la autenticación de AWS con el controlador .NET/C#, consulte Autenticación de 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 de una colección utiliza un discriminador escalar, el controlador genera una excepción si realiza cualquiera 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, consulte 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 concretos. Para implementar un serializador personalizado, implemente 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.

De forma predeterminada, 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 de forma predeterminada.

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

Cambios importantes en la versión 3.5

Cambios importantes en la versión 3.0