/ /

/ /

Librerías de clientes

Driver C#/.NET

Actualizar

Actualizar a la versión 3.x

Overview

Esta página describe los cambios que podría necesitar realizar en su aplicación cuando actualice el controlador .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 el Página de compatibilidad para garantizar que la nueva versión del controlador sea compatible con las versiones de MongoDB Server a las que se conecta su aplicación y la versión de .NET o .NET Framework en la que se ejecuta su aplicación.
Si está utilizando una versión 2.x del controlador .NET/C#, actualice a la versión2.30. Para ello, siga las instrucciones Guía de actualización de v2.x.
Aborde los cambios importantes descritos en la sección Cambios 3.0 importantes de la versión.
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 ya no es compatible con MongoDB Server 4.0 y versiones anteriores. Debe actualizar su MongoDB Server a la versión4.2 o posterior.
Para saber cómo actualizar su implementación de MongoDB Server, consulte las Notas de la versión en el manual de MongoDB Server.
Para obtener más información sobre la compatibilidad entre las versiones del controlador .NET/C# y las versiones de MongoDB Server, visite la página de Compatibilidad.

Cambios importantes en la versión 3.0

El controlador ya no es compatible con MongoDB Server v3.6 y versiones anteriores. Debe actualizar su MongoDB Server a v4.0 o posterior.
Para saber cómo actualizar su implementación de MongoDB Server, consulte las Notas de la versión en el manual de MongoDB Server.
Para obtener más información sobre la compatibilidad entre las versiones del controlador .NET/C# y las versiones de MongoDB Server, visite 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 controlador elimina el paquete NuGet mongocsharpdriver, que implementa la1 API v.x heredada en las 2 versiones.x del controlador. Si utiliza la1 API v.x, debe migrar a la nueva API.
Las clases, métodos y propiedades en el MongoDB.Driver.Core Los espacios de nombres obsoletos en la versión v2.30 están marcados como internal. Si el controlador proporciona un reemplazo para una clase, método o propiedad obsoletos, los mensajes del compilador en la versión 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 por la interfaz IQueryable, siguiendo el patrón utilizado por la mayoría de los demás proveedores LINQ. Si su aplicación contiene referencias a IMongoQueryable, reemplácelas por IQueryable.
El controlador elimina el ClusterBuilder.ConfigureSdamLogging() método. Para configurar el registro en su aplicación, consulte la Guía de registro.
El proveedor LINQ2 se ha eliminado de esta versión del controlador. Debe usar 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:
- Se BsonBinaryData(Guid) ha eliminado el constructor. Para construir un BsonBinaryData objeto a partir de un GUID, utilice el BsonBinaryData.Create(Guid, GuidRepresentation) constructor. Para ver un ejemplo de creación de un GUID heredado, consulte la nota "Construir GUIDs 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 GUID en el controlador .NET/C#, consulte la página GUID.
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.
De forma predeterminada, el controlador serializa los valores Decimal128 y decimal como valores BSON Decimal128. En versiones anteriores, los serializaba como valores BSON string. Para serializar un valor decimal o Decimal128 como una cadena en v3.0, aplique el atributo [BsonRepresentation(BsonType.String)] al campo.
Para obtener más información sobre cómo especificar tipos BSON durante la serialización, consulte la sección Serialización personalizada de la página POCO.
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 usar un modo de salida JSON diferente, cree un nuevo objeto JsonWriterSettings. Establezca la propiedad OutputMode de este objeto con un valor de la enumeración JsonOutputMode y, a continuación, pase el objeto al método ToJson() al 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 usar el cifrado en uso, debe agregar el MongoDB.Driver.Encryption paquete a su proyecto y registrar el mecanismo de cifrado en el código de arranque de su aplicación. Para obtener más información sobre el uso del cifrado en uso con el controlador .NET/C#, consulte Cifrado en uso en el manual del servidor MongoDB.
Si intenta serializar o deserializar un valor de coma flotante Infinity o NaN a una representación integral, el controlador lanza OverflowException un. Para obtener más información sobre los valores de coma flotante Infinity NaN y, consulte Double.NaN, Double.PositiveInfinity y Double.NegativeInfinity en MSDN.
El controlador 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 AsDateTime propiedad. En su lugar, utiliza la propiedad AsUniversalTime.
- Elimina la AsNullableDateTime propiedad. En su lugar, utiliza la propiedad AsNullableUniversalTime.
El controlador elimina eventos individuales del clúster MongoClient.Cluster de. Para escuchar eventos del clúster, llame 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.
Como alternativa, puede comprobar el tipo de cada elemento de una forma diferente. Por ejemplo, puede llamar al método Where() y pasar una expresión que compare el tipo del elemento con el tipo que busca, 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 fueron diseñados para la extensión 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 las interfaces IMongoClient, IMongoDatabase y IMongoCollection directamente.
El controlador requiere que las aplicaciones configuren explícitamente cómo serializar los GUID mediante las clases GuidSerializer y ObjectSerializer. Los usuarios del controlador .NET/C# que creen nuevas aplicaciones pueden implementar un GuidSerializer global registrándolo. Recomendamos a los usuarios con aplicaciones antiguas que verifiquen que todos los GUIDs se serialicen de la misma manera al implementar un GuidSerializer global. También puede configurar la serialización de GUID caso por caso sin registrar un GuidSerializer global.
Para obtener más información sobre la serialización GUID, consulte la guía de GUID.

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 un documento en v3.0 o posterior, registre 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