升级到版本 3.0

Overview

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

如何升级

本页列出了.NET/ C#驱动程序版本 3.0 引入的潜在重大更改。要将.NET/ C#驱动程序升级到版本 3.0，请按照以下步骤操作：

1. 查看 兼容性 页面，确保新的驱动程序版本与应用程序连接到的MongoDB Server版本以及应用程序运行所在的.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 Server v3.6 及更早版本的支持。您必须将MongoDB Server升级到 v4.0 或更高版本。

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

  要详细学习；了解.NET/C#驱动程序版本和MongoDB Server版本之间的兼容性，请访问兼容性页面。

• 该驱动程序删除对.NET Core 2.x 和.NET 框架 4.6 的支持。您必须升级到.NET Core 3.x 或更高版本，或者.NET 框架 4.7.2 或更高版本。

  To learn more about the compatibility between .NET/C# driver versions and .NET versions, visit the Compatibility page.

• The driver removes the mongocsharpdriver NuGet package, which implements the legacy v1.x API in driver versions 2.x. If you're using the v1.x API, you must migrate to the new API.

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

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

• The driver drops support for the MONGODB-CR authentication mechanism. To learn more about configuring authentication in the .NET/C# Driver, see Authentication Mechanisms.

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

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

• LINQ2提供商已从此版本的驱动程序中删除。必须对所有 LINQ 查询使用 LINQ3。

  默认下，使用客户端投影的查询会引发 ExpressionNotSupportedException 错误。 要启用客户端投影，请将 TranslationOptions对象的 EnableClientSideProjections属性设立为 true。 您可以将此 TranslationOptions对象传递给 AggregateOptions 或 FindOptions对象，为单个查询启用客户端投影，或者传递给 MongoClientSettings对象，为应用程序中的所有查询启用客户端投影。

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

  • BsonBinaryData(Guid) 构造函数已被删除。要从 GUID 构造 BsonBinaryData对象，请使用 BsonBinaryData.Create(Guid, GuidRepresentation) 构造函数。要查看创建传统 GUID 的示例，请参阅 GUID序列化指南中的“构造传统 GUID”说明。

  • BsonBinaryData.GuidRepresentation属性已被删除。

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

  • 已删除使用 BsonTypeMapper 类进行 GUID 转换。 要将 GUID 值转换为BSON，请使用 BsonBinaryData(<GUID>, GuidRepresentation.Standard) 构造函数。

  仅当您直接序列化和反序列化BSON文档时，上述更改才会影响您的应用程序。 如果您仅将MongoDB文档映射到 POCO，则 GuidRepresentationMode不会影响您的应用程序。

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

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

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

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

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

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

• JSON默认JSON输出模式为宽松扩展JSONJSON stringJSONBSON，这是一种基于描述BSON文档的JSON标准的字符串格式。宽松扩展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对象，而不是大量。

• 要使用Amazon Web Services (Amazon Web Services)身份验证，您必须将 MongoDB.Driver.Authentication.AWS包添加到项目中，并在应用程序的引导代码中注册身份验证提供者。 要学习；了解有关通过.NET/ C#驱动程序使用Amazon Web Services身份验证的更多信息，请参阅Amazon Web Services IAM 身份验证。

• 要使用In-正在使用的加密，您必须将 MongoDB.Driver.Encryption包添加到您的项目中，并在应用程序的引导代码中注册加密机制。要学习；了解有关在.NET .NET/C# C#驱动程序中使用正在使用的加密的更多信息，请参阅MongoDBMongoDB Server Server手册中的正在使用的正在使用的加密。

• 如果尝试将浮点 Infinity 或 NaN 值序列化或反序列化为整数表示形式，驱动程序会抛出 OverflowException。要学习；了解有关浮点 Infinity 和 NaN 值的更多信息，请参阅 Double.NaN、Double.PositiveInfinity 和 Double.NegativeInfinity。在 MSDN 上。

• 该驱动程序包含对 BsonValue 类的以下更改：

  • 从 AsLocalTime 和 AsUniversalTime 属性中删除 [Obsolete] 属性。

  • 添加 AsNullableLocalTime 和 AsNullableUniversalTime 属性。

  • 删除 AsDateTime属性。请改用AsUniversalTime属性。

  • 删除 AsNullableDateTime属性。请改用 AsNullableUniversalTime 属性。

• 驱动程序会从 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 接口。

• 驱动程序要求应用程序使用 GuidSerializer 和 ObjectSerializer 类显式配置如何序列化 GUID。构建新应用程序的.NET/ C#驱动程序用户可以通过注册来实现全局 GuidSerializer。我们建议使用较旧应用程序的用户在实现全局 GuidSerializer 时验证所有 GUIDs 是否都以相同的方式进行序列化。您还可以根据具体情况配置 GUID 序列化，而无需注册全局 GuidSerializer。

  要学习；了解有关 GUID 序列化的更多信息，请参阅 GUID指南。

• 默认下，驱动程序将 TimeOnly 值序列化为表示 Ticks 的BSON int64 值。上一个版本的驱动程序默认将 TimeOnly 值序列化为BSON文档。

  要在 v3.0 或更高版本中将 TimeOnly 值序列化为文档，请使用 BsonType.Document 表示形式注册 TimeOnlySerializer，如以下示例所示：

  BsonSerializer.RegisterSerializer(new TimeOnlySerializer(BsonType.Document));

  您还可以应用BsonRepresentation(BsonType.Document) TimeOnly字段，如以下示例所示：

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