升级到版本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#驱动程序，请升级到 v 2.30 。为此，请遵循v 2 .x升级指南。

3. 解决版本3.0重大更改部分中描述的重大更改。

   例子

   如果您要将驾驶员从 v 2.14升级到 v 3.0 ，请先使用 v 2 .x升级指南将驾驶员升级到 v 2.30 。然后，解决v 3.0的所有重大更改。

版本 3.0破坏性变更

• 该驾驶员不再支持MongoDB Server v 3.6及更早版本。您必须将MongoDB Server升级到4.0或更高版本。

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

  如要进一步了解 .NET/C# 驱动程序版本与 MongoDB Server 版本之间的兼容性，请访问兼容性页面。

• 该驾驶员删除了对.NET Core 2 .x 和.NET Framework 4.6的支持。您必须升级到.NET Core 3 .x 或更高版本，或者.NET Framework 4.7.2或更高版本。

  要详细学习；了解.NET/ C#驾驶员版本和.NET版本之间的兼容性，请访问兼容性页面。

• 该驾驶员会删除 mongocsharpdriver NuGet包，它在驾驶员版本1 .x 中实现了旧版 .x API2 。如果您使用的是 v1 .x API，则必须迁移到新API。

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

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

• 该驾驶员不再支持MONGODB-CR身份验证机制。要学习；了解有关在.NET/ C#驱动程序中配置身份验证的更多信息，请参阅身份验证机制。

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

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

• LINQ 2提供商已从此版本的驾驶员中删除。必须对所有 LINQ 查询使用 LINQ 3 。

• 上一个版本的.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文档映射到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值序列化为 v 3.0中的字符串，应用[BsonRepresentation(BsonType.String)]属性应用于该字段。

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

• 默认，驾驶员将DateTimeOffset值序列化为BSON文档。在以前版本的驾驶员中，驾驶员默认将这些值序列化为BSON数组。要将DateTimeOffset值序列化为 v 3.0中的大量，应用[BsonRepresentation(BsonType.Array)]属性应用于该字段。

• 默认JSON输出模式为宽松扩展JSON ，这是一种基于描述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 (AWS)身份验证，您必须将MongoDB.Driver.Authentication.AWS包添加到项目中，并在应用程序的引导代码中注册身份验证提供者程序。要学习；了解有关将 AWS身份验证与.NET/ C#驱动程序结合使用的更多信息，请参阅MONGODB-AWS。

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

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

• 该驾驶员包含对BsonValue类的以下更改：

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

  • 添加 AsNullableLocalTime 和 AsNullableUniversalTime 属性。

  • 删除AsDateTime 属性。使用 AsUniversalTime 属性。

  • 删除AsNullableDateTime 属性。使用 AsNullableUniversalTime 属性。