文档菜单
文档首页
/
语言
/
C#/.NET
/
C#/.NET
/
升级

升级到 3.0 版本

本页内容

  • 概述
  • 如何升级
  • 3.0 版本的重大更改

概述

本页描述了在将 .NET/C# 驱动程序升级到 3.0 版本时，您可能需要对应用程序进行的更改。

如何升级

本页列出了由 .NET/C# 驱动程序 3.0 版本引入的可能破坏性更改。要将 .NET/C# 驱动程序升级到 3.0 版本，请按照以下步骤操作

  1. 审查兼容性 页面，以确保新驱动程序版本与您的应用程序连接的 MongoDB 服务器版本以及您的应用程序运行的 .NET 或 .NET 框架版本兼容。

  2. 如果您正在使用 2.x 版本的 .NET/C# 驱动程序，请升级到 v2.30。要这样做，请按照 v2.x 升级指南。

  3. 解决在版本 3.0 破坏性更改 部分中描述的破坏性更改。

    示例

    如果您正在将驱动程序从 v2.14 升级到 v3.0，首先使用 v2.x 升级指南将您的驱动程序升级到 v2.30。然后，解决 v3.0 的所有破坏性更改。

版本 3.0 破坏性更改

  • 驱动程序停止支持 MongoDB 服务器 v3.6 及更早版本。您必须将 MongoDB 服务器升级到 v4.0 或更高版本。

    要了解如何升级您的 MongoDB 服务器部署，请参阅 MongoDB 服务器手册中的 发行说明。

    要了解更多关于 .NET/C# 驱动程序版本和 MongoDB 服务器版本之间的兼容性信息，请访问 兼容性 页面。

  • 驱动程序停止支持 .NET Core 2.x 和 .NET Framework 4.6。您必须升级到 .NET Core 3.x 或更高版本，或 .NET Framework 4.7.2 或更高版本。

    要了解更多关于 .NET/C# 驱动程序版本和 .NET 版本之间的兼容性信息，请访问 兼容性 页面。

  • 驱动程序移除了mongocsharpdriver NuGet 包，该包在 2.x 版本的驱动程序中实现了过时的 v1.x API。如果你正在使用 v1.x API，必须迁移到新的 API。

  • 在MongoDB.Driver.Core 命名空间中的类、方法和属性在 v2.30 版本中被弃用，并标记为 internal。如果驱动程序为弃用的类、方法或属性提供了替代方案，v2.30 版本的编译器消息将显示它。

  • 在驱动程序之前版本中被弃用的 MongoDB.Bson 命名空间中的方法、属性和构造函数已被删除。如果驱动程序为弃用的方法、属性或构造函数提供了替代方案，v2.30 版本的编译器消息将显示它。

  • 驱动程序放弃了对 MONGODB-CR 认证机制的 support。有关在 .NET/C# 驱动程序中配置认证的更多信息，请参阅 Authentication Mechanisms。

  • 驱动程序用 IQueryable 接口替换了 IMongoQueryable 接口，遵循了大多数其他 LINQ 提供程序的模式。如果你的应用程序中包含对 IMongoQueryable 的引用，请将它们替换为 IQueryable。

  • 驱动程序移除了 ClusterBuilder.ConfigureSdamLogging() 方法。要配置应用程序中的日志记录，请参阅 Logging 指南。

  • 此版本的驱动程序已删除 LINQ2 提供程序。你必须使用 LINQ3 来执行所有 LINQ 查询。

    使用客户端投影的查询默认将抛出 ExpressionNotSupportedException 错误。要启用客户端投影，将 TranslationOptions 对象的 EnableClientSideProjections 属性设置为 true。您可以传递此 TranslationOptions 对象到一个 AggregateOptions 或 FindOptions 对象以启用单个查询的客户端投影，或传递到一个 MongoClientSettings 对象以启用应用程序中所有查询的客户端投影。

  • 之前的 .NET/C# 驱动程序支持两种 GUID 表示模式。在 3.0 版本中，GuidRepresentationMode.V3 是唯一支持的模式。此更改对驱动程序有以下影响

    • 已删除 BsonBinaryData(Guid) 构造函数。要从 GUID 构造 BsonBinaryData 对象，请使用 BsonBinaryData.Create(Guid, GuidRepresentation) 构造函数。

    • 已删除 BsonBinaryData.GuidRepresentation 属性。

    • 您只能在子类型为4的BsonBinaryData对象上调用BsonBinaryData.ToGuid()方法。如果对象有其他子类型，您必须调用BsonBinaryData.ToGuid(GuidRepresentation)方法并指定子类型。

    前面的更改仅影响您直接序列化和反序列化BSON文档的应用程序。如果您只将MongoDB文档映射到POCOs，则GuidRepresentationMode不会影响您的应用程序。

    有关在.NET/C#驱动程序中序列化GUID的更多信息，请参阅GUIDs页面。

  • 异常类及其相关类型不再包含[Serializable]属性，因此不再支持Microsoft旧版序列化API。要了解如何使用.NET/C#驱动程序序列化对象，请参阅序列化指南。

  • TLS 1.0和1.1不再受支持。您必须使用TLS 1.2或更高版本。要了解有关.NET/C#驱动程序中TLS/SSL配置的更多信息，请参阅在连接上启用TLS。

  • 默认情况下，驱动程序将Decimal128和decimal值序列化为BSONDecimal128值。在驱动程序的先前版本中，默认情况下将这些值序列化为BSONstring值。要在v3.0中将decimal或Decimal128值序列化为字符串，将[BsonRepresentation(BsonType.String)]属性应用于字段。

    要了解有关在序列化期间指定BSON类型的更多信息，请参阅POCOs页面上的自定义序列化部分。

  • 默认情况下，驱动程序将DateTimeOffset值序列化为BSON文档。在驱动程序的先前版本中，默认情况下将这些值序列化为BSON数组。要在v3.0中将DateTimeOffset值序列化为数组，将[BsonRepresentation(BsonType.Array)]属性应用于字段。

  • 默认的JSON输出模式是Relaxed Extended JSON，这是一种基于JSON标准的字符串格式，用于描述BSON文档。Relaxed Extended JSON以牺牲类型保留为代价强调了可读性和互操作性。

    要使用不同的JSON输出模式，创建一个新的JsonWriterSettings对象。将此对象的OutputMode属性设置为JsonOutputMode枚举中的一个值，然后在序列化文档时将其传递给ToJson()方法。以下代码示例显示了如何将BSON文档序列化为Strict JSON：

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

  • MongoClient构造函数只接受一个Credential对象，而不是一个数组。

  • 要使用亚马逊网络服务（AWS）身份验证，您必须将 MongoDB.Driver.Authentication.AWS 包添加到您的项目中，并在应用程序的启动代码中注册身份验证提供者。有关使用 .NET/C# 驱动程序与 AWS 身份验证的更多信息，请参阅 AWS 身份和访问管理。

  • 要使用使用中加密，您必须将 MongoDB.Driver.Encryption 包添加到您的项目中，并在应用程序的启动代码中注册加密机制。有关使用 .NET/C# 驱动程序中使用中加密的更多信息，请参阅 MongoDB 服务器手册中的 使用中加密。

  • 如果您尝试将浮点数 Infinity 或 NaN 的值序列化为整数表示形式，驱动程序将抛出 OverflowException 异常。有关浮点数 Infinity 和 NaN 的更多信息，请参阅 MSDN 上的 Double.NaN, Double.PositiveInfinity, 和 Double.NegativeInfinity.。

  • 驱动程序对 BsonValue 类进行了以下更改：

  • 驱动程序从 MongoClient.Cluster 中移除单个集群事件。要监听集群事件，请调用 ClusterBuilder.Subscribe() 方法。

  • 如果集合中任何类型使用标量区分符，则在集合上执行以下任何操作时，驱动程序都会抛出异常

    • 调用 Aggregate().OfType<T>() 方法，如下例所示

      collection.Aggregate().OfType<T>()

    • 调用 Aggregate().Match(item => item is T) 方法，如下例所示

      collection.Aggregate().Match(item => item is T)

    要在集合上使用上述任一方法，您可以对集合中的每个类应用分层区分符。有关如何操作，请参阅 多态对象 页面。

    或者，您可以用不同的方式检查每个项的类型。例如，您可以调用 Where() 方法，并传递一个表达式，该表达式将项的类型与您正在寻找的类型进行比较，如下例所示

    collection.AsQueryable().Where(item => item.GetType() == typeof(T));

    有关类型区分符的更多信息，请参阅 多态对象。

  • 驱动程序已使用继承未设计用于扩展的某些类型进行密封。这包括以下更改

    • 驱动程序将所有混凝土序列化器进行封印。要实现自定义序列化器，请实现IBsonSerializer接口。

    • 驱动程序将MongoClient、MongoDatabase和MongoCollection类进行封印。我们建议直接使用IMongoClient、IMongoDatabase和IMongoCollection接口。

返回

2.x 版本