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:
Revisa la página de compatibilidad para garantizar que la nueva versión del driver sea compatible con las versiones del MongoDB Server a las que se conecta tu aplicación y con la versión de .NET o del Marco .NET en la que se ejecuta tu aplicación.
Si utilizas la versión 2.x del controlador .NET/C#, actualiza a la v2.30. Para ello, siga la Guía de actualización a 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.13 cambio disruptivo
El driver ahora rechaza el BSON sin formato mal formado. Escribir un documento o arreglo BSON sin procesar genera un
ArgumentExceptionsi su longitud declarada es inconsistente con el búfer. El driver ignora los bytes que superan la longitud declarada.El driver ya no realiza internado de valores
BsonSymbol, yBsonSymbolTableestá obsoleto. UtiliceBsonSymbol.Create()o la conversión implícita de string en su lugar.El driver ahora rechaza los subtipos binarios fuera del rango 0 a 255. Esto afecta a la clase
BsonBinaryData, al lector JSON (BinData,HexDatay la representación heredada$type) y al escritor binario.PushEach()yAddToSetEach()con un solo valor ahora siempre renderizan$each, yPullAll()con un solo valor ahora siempre renderiza$pullAll. Las versiones anteriores del driver descomprimían un solo valor o lo renderizaban como$pull.La sobrecarga
PatternProperty()que toma una expresión de campo está obsoleta y genera una advertencia del compilador. UtiliceProperty()para configurar un campo específico. El driver ahora coincide con los nombres de campo que pasa aPatternProperty()tanto como nombres de campo literales como expresiones regulares.La serialización de GeoJSON lanza un
BsonSerializationExceptioncuando un nodo extra tiene el mismo nombre que un nodo declarado.El cifrado automático pasa el nombre de la base de datos a
libmongocryptcomo UTF-8 en lugar de usar la página de códigos ANSI de Windows. Las base de datos con nombres que no son ASCII ahora coinciden con sus namespace de mapa de esquema.Si utiliza una clave de diccionario, una clave
BsonDocumento un nombreMql.Fieldque MongoDB Server reinterpretaría, la traducción de LINQ ahora lanza unaNotSupportedException. Esto incluye nombres que contienen ".", nombres que comienzan con "$" al principio de una ruta y operador posicionales.Para determinar si dos instancia
MongoClientpueden compartir un clúster, el driver utiliza SHA-256 para comparar sus certificados de cliente completos. También comprueba si cada certificado tiene una llave privada. El driver lee estos ajustes del objetoSslSettingsde cada cliente. Las versiones anteriores del driver solo comparaban el emisor del certificado y el número de serie.FindOneAndReplace()lanza unaArgumentExceptioncuando el primer nombre de elemento del documento de reemplazo comienza con "$", coherente con el comportamiento deReplaceOne().
Versión 3.10 cambio disruptivo
El controlador deja de ser compatible con MongoDB Server 4.2 y anteriores. Debes actualizar tu servidor MongoDB a la versión v4.4 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.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 el espacio de nombres
MongoDB.Driver.Coreque se declararon obsoletos en la versión2.30 están marcados comointernal. Si el controlador proporciona un reemplazo para una clase, método o propiedad obsoletos, los mensajes del compilador en v2.30 lo indicarán.Los métodos, propiedades y constructores en el namespace
MongoDB.Bsonque 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
IMongoQueryablecon la interfazIQueryable, siguiendo el patrón utilizado por la mayoría de los otros proveedores de LINQ. Si su aplicación contiene referencias aIMongoQueryable, reemplácelas conIQueryable.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
ExpressionNotSupportedExceptionpor defecto. Para habilitar las proyecciones del lado del cliente, establezca la propiedadEnableClientSideProjectionsde un objetoTranslationOptionsentrue. Puedes pasar este objetoTranslationOptionsa un objetoAggregateOptionsoFindOptionspara habilitar proyecciones del lado del cliente para una sola query, o a un objetoMongoClientSettingspara 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.V3es el único modo soportado. Este cambio tiene los siguientes efectos sobre el driver:El
BsonBinaryData(Guid)constructor se ha eliminado. Para construir un objetoBsonBinaryDataa partir de un GUID, utilice el constructorBsonBinaryData.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 objetosBsonBinaryDatade tipo 4. Si el objeto tiene cualquier otro subtipo, debes llamar al métodoBsonBinaryData.ToGuid(GuidRepresentation)y especificar el subtipo.Se ha eliminado la conversión GUID mediante el uso de la clase
BsonTypeMapper. Para convertir los valores deGUIDa BSON, use el constructorBsonBinaryData(<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
GuidRepresentationModeno 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
Decimal128ydecimalcomo valores BSONDecimal128. En versiones anteriores del controlador, este serializaba estos valores como valores BSONstringpor defecto. Para serializar un valor dedecimaloDecimal128como 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
DateTimeOffsetcomo documentos BSON. En versiones anteriores del controlador, este serializó estos valores como arreglos BSON por defecto. Para serializar un valorDateTimeOffsetcomo 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 propiedadOutputModede este objeto en un valor del enumeradoJsonOutputModey, a continuación, pase el objeto al métodoToJson()para serializar el documento. El siguiente ejemplo de código muestra cómo serializar un documento BSON a JSON estricto:// Configure JsonWriterSettingsvar jsonWriterSettings = new JsonWriterSettings{ OutputMode = JsonOutputMode.Strict}; // Serialize the document to JSON using the configured settingsvar json = document.ToJson(jsonWriterSettings);El constructor de
MongoClientacepta sólo un objetoCredentialen lugar de un arreglo.Para utilizar la autenticación de Amazon Web Services (AWS), debe agregar el paquete
MongoDB.Driver.Authentication.AWSa 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.Encryptiona 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
InfinityoNaNde punto flotante a una representación integral, el controlador lanza unOverflowException. Para obtener más información sobre los valores de punto flotanteInfinityyNaN, 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 propiedadesAsLocalTimeyAsUniversalTime.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,MongoDatabaseyMongoCollection. Recomendamos usar directamente las interfacesIMongoClient,IMongoDatabaseyIMongoCollection.
El controlador requiere que las aplicaciones configuren explícitamente cómo serializar GUIDS usando las clases
GuidSerializeryObjectSerializer. Los usuarios del Driver .NET/C# que desarrollan nuevas aplicaciones pueden implementar unGuidSerializerglobal registrándolo. Recomendamos que los usuarios que tengan aplicaciones más antiguas verifiquen que todoGUIDsesté serializado de la misma manera al implementar unGuidSerializerglobal. También puedes configurar la serialización deGUIDcaso por caso sin registrar unaGuidSerializerglobal.Para obtener más información sobre la serialización de GUID, consulta la guía GUIDs.
Por defecto, el controlador serializa los valores
TimeOnlycomo valores BSONint64que representanTicks. Las versiones anteriores del controlador serializaban los valoresTimeOnlycomo documentos BSON por defecto.Para serializar un valor de
TimeOnlycomo documento en .NET/C# Driver v3.0 a v3.5, registra el tipoTimeOnlycon unBsonClassMapSerializer, 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);Nota
Actualización de la funcionalidad TimeOnly para la v3.6 y posteriores
Para serializar un valor
TimeOnlycomo un documento en .NET/C# Driver v3.6 o posterior, registre unTimeOnlySerializercon una representaciónBsonType.Document, como se muestra en el siguiente ejemplo:BsonSerializer.RegisterSerializer(new TimeOnlySerializer(BsonType.Document));También se puede aplicar el atributo
BsonRepresentation(BsonType.Document)a camposTimeOnly, como se muestra en el ejemplo siguiente:public class Person{ [BsonRepresentation(BsonType.Document)] public TimeOnly TimeBirth { get; set; }}