Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.

Actualiza a la versión 3.x

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.

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:

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

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

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

  • El driver ahora rechaza el BSON sin formato mal formado. Escribir un documento o arreglo BSON sin procesar genera un ArgumentException si 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, y BsonSymbolTable está obsoleto. Utilice BsonSymbol.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, HexData y la representación heredada $type) y al escritor binario.

  • PushEach() y AddToSetEach() con un solo valor ahora siempre renderizan $each, y PullAll() 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. Utilice Property() para configurar un campo específico. El driver ahora coincide con los nombres de campo que pasa a PatternProperty() tanto como nombres de campo literales como expresiones regulares.

  • La serialización de GeoJSON lanza un BsonSerializationException cuando un nodo extra tiene el mismo nombre que un nodo declarado.

  • El cifrado automático pasa el nombre de la base de datos a libmongocrypt como 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 BsonDocument o un nombre Mql.Field que MongoDB Server reinterpretaría, la traducción de LINQ ahora lanza una NotSupportedException. Esto incluye nombres que contienen ".", nombres que comienzan con "$" al principio de una ruta y operador posicionales.

  • Para determinar si dos instancia MongoClient pueden 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 objeto SslSettings de cada cliente. Las versiones anteriores del driver solo comparaban el emisor del certificado y el número de serie.

  • FindOneAndReplace() lanza una ArgumentException cuando el primer nombre de elemento del documento de reemplazo comienza con "$", coherente con el comportamiento de ReplaceOne().

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

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

  • 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.Core que se declararon obsoletos en la versión2.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 v2.30 lo indicará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 JsonWriterSettingsvar jsonWriterSettings = new JsonWriterSettings{ OutputMode = JsonOutputMode.Strict}; // Serialize the document to JSON using the configured settingsvar 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:

  • 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 de TimeOnly como documento en .NET/C# Driver v3.0 a v3.5, 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);

    Nota

    Actualización de la funcionalidad TimeOnly para la v3.6 y posteriores

    Para serializar un valor TimeOnly como un documento en .NET/C# Driver v3.6 o posterior, registre un TimeOnlySerializer con una representación BsonType.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 campos TimeOnly, como se muestra en el ejemplo siguiente:

    public class Person{ [BsonRepresentation(BsonType.Document)] public TimeOnly TimeBirth { get; set; }}