diff --git a/docs/en/release-info/migration-guides/MongoDB-Driver-2-to-3.md b/docs/en/release-info/migration-guides/MongoDB-Driver-2-to-3.md new file mode 100644 index 0000000000..18392bc991 --- /dev/null +++ b/docs/en/release-info/migration-guides/MongoDB-Driver-2-to-3.md @@ -0,0 +1,58 @@ +# Migrating from MongoDB Driver 2 to 3 + +## Introduction + +The release of MongoDB Driver 3 includes numerous user-requested fixes and improvements that were deferred in previous versions due to backward compatibility concerns. It also features internal improvements to reduce technical debt and enhance maintainability. One major update is the removal of a significant portion of the public API (primarily from `MongoDB.Driver.Core`), which was not intended for public use. The removed APIs were marked as deprecated in version 2.30.0. + +For a complete list of breaking changes and upgrade guidelines, please refer to the [upgrade guide](https://www.mongodb.com/docs/drivers/csharp/current/upgrade/v3/). + +## Repository Changes + +Some method signatures in the `MongoDbRepository` class have been updated, primarily to accommodate the removal of `IMongoQueryable`. The specific changes are as follows: + +- The `GetMongoQueryable` method has been renamed to `GetQueryable`. +- The `GetMongoQueryableAsync` method has been renamed to `GetQueryableAsync`. + +Please update your application by searching for and replacing these method calls. + +> The return value of the `GetQueryableAsync` method is `IQueryable`, which can be used directly to perform queries, similar to EF Core. Remove all instances of `IMongoQueryable` in your project and replace them with `IQueryable`. + +**Previous code example:** + +```csharp +var myEntity = await (await GetMongoQueryableAsync()).As>().FirstOrDefaultAsync(x => x.Id == id); +``` + +**Updated code example:** + +```csharp +var myEntity = await GetQueryableAsync().FirstOrDefaultAsync(x => x.Id == id); +``` + +## Unit Test Changes + +Previously, we used the [EphemeralMongo](https://github.com/asimmon/ephemeral-mongo) library for unit testing. However, it does not support the latest version of [MongoDB.Driver 3.x](https://github.com/mongodb/mongo-go-driver). You should replace it with [MongoSandbox](https://github.com/wassim-k/MongoSandbox). + +In your unit test project files, replace the following: + +```xml + + + + +``` + +With: + +```xml + + + + +``` + +In your unit test classes, replace `using EphemeralMongo` with `using MongoSandbox`. + +## Official Upgrade Guide + +We recommend reviewing the [upgrade guide](https://www.mongodb.com/docs/drivers/csharp/current/upgrade/v3/) for MongoDB Driver 3 to ensure a smooth migration process.