/ /

/ /

升级到版本 3.x

Overview

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

如何升级

本页列出了 3.x .NET/C# 驱动程序版本引入的潜在破坏性变更 (breaking change)。要将.NET/C#驱动程序升级到版本 3.x，请按照以下步骤操作：

查看兼容性页面，确保新的驱动程序版本与应用程序连接到的MongoDB Server版本以及应用程序运行所在的.NET或.NET框架版本兼容。
如果您使用的是 2 .x 版本的.NET/ C#驱动程序，请升级到 v 2.30。为此，请遵循 v2 .x升级指南。
解决版本3.0 重大更改部分中描述的重大更改。

例子
如果要将驱动程序从 v2.14 升级到 v3.0，请先使用 v2.x升级指南，将驱动程序升级到 v2.30。然后，解决v3.0 的所有重大更改。

版本 3.5破坏性变更

该驱动程序删除对MongoDB Server 4.0 及更早版本的支持。您必须将MongoDB Server升级到 v4.2 或更高版本。

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

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

版本 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 或更高版本。

要了解有关.NET/C# 驱动程序版本和 .NET 版本之间兼容性的更多信息，请访问兼容性页面。
该驱动程序删除了 mongocsharpdriver NuGet 包，该包实现了旧版 v1.x。驱动程序版本 2.x 中的 API。如果您使用的是 v1.x API，您必须迁移到新的 API。
在 v2.30 中已弃用的 MongoDB.Driver.Core命名空间中的类、方法和属性被标记为 internal。如果驱动程序为已弃用的类、方法或属性提供了替代项，则 v2.30 中的编译器消息将显示它。
在驱动程序先前版本中已弃用的 MongoDB.Bson命名空间中的方法、属性和构造函数已被删除。如果驱动程序提供了已弃用的方法、属性或构造函数的替代项，则 v2.30 中的编译器消息将显示它。
该驱动程序取消了对 MONGODB-CR 身份验证机制的支持。要了解有关在 .NET/C# 驱动程序中配置身份验证的更多信息，请参阅身份验证机制。
驱动程序将 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 值序列化为文档，请向 BsonClassMapSerializer 注册 TimeOnly 类型，如以下示例所示：

var timeOnlyClassMap = new BsonClassMap<TimeOnly>(cm =>
     cm.AutoMap()).Freeze();
var serializer = new BsonClassMapSerializer<TimeOnly>(timeOnlyClassMap);
BsonSerializer.RegisterSerializer(serializer);

后退

版本2 .x

来年

版本 2.0 至 2.18

升级到版本 3.x

Overview

如何升级

例子

版本 3.5破坏性变更

版本 3.0破坏性变更