Docs Menu
Docs Home
/
Languages
/
C#
/
EF Core Provider

Upgrade Provider Version

On this page

  • Overview
  • Breaking Changes

Overview

In this section, you can identify essential changes you must make to your application when you upgrade your provider to a new version.

Before you upgrade, perform the following actions:

  • Ensure the new version is compatible with the MongoDB Server version your application connects to and the .NET version your application runs on. See the Compatibility section for this information.

  • Address any breaking changes between the current version of the provider your application is using and your planned upgrade version in the Breaking Changes section.

Breaking Changes

A breaking change is a modification of a convention or a behavior starting in a specific version of the provider. This type of change might prevent your application from working properly if not addressed before upgrading the provider.

The breaking changes in this section are categorized by the provider version that introduced them. When upgrading provider versions, address all the breaking changes between the current and upgrade versions. For example, if you are upgrading the provider from v8.0 to v8.5, address all breaking changes from the version after v8.0, including any listed under v8.5.

Version 8.2.0 Breaking Changes

Version 8.2.0 of the EF Core Provider does not directly introduce any breaking changes. However, the underlying .NET/C# Driver introduces many potentially breaking changes in the v3.0 release, which might affect your application. To learn more about the breaking changes in v3.0 of the .NET/C# Driver, see the Upgrade to Version 3.0 guide in the .NET/C# Driver documentation.

Version 8.1.0 Breaking Changes

  • Updated the EF Core Provider to run all changes as MongoDB transactions. If your application uses MongoDB Server earlier than v5.0, or does not run in a replica set, you must make the following changes to your application:

    • If your application is configured for a MongoDB Server version earlier than v5.0, you must upgrade to MongoDB Server v5.0 or later.

    • If your application runs on a standalone server, you must reconfigure your standalone server to a single-instance replica set. To learn more about how to reconfigure your standalone server, see Convert a Standalone Self-Managed mongod to a Replica Set in the MongoDB Server manual.

    • If your application runs in a container environment, switch to a single-instance replica set container if one is available.

    To avoid snapshot issues during transactions, call the EnsureCreated() or EnsureCreatedAsync() method during your application start-up, rather than creating the collection or database implicitly.

    Note

    Calling the EnsureCreated() or EnsureCreatedAsync() method throws an error if your application is running on a shared cluster. Applications running on free and shared clusters should not call these methods.

    If you don't want to ensure optimistic concurrency with transactions, you can disable automatic transactions by setting Database.AutoTransactionBehavior = AutoTrasactionBehavior.Never on your DbContext subclass during your application setup.

  • Changed the default GUID storage format from CSharpLegacy binary format to Standard format. If your database contains existing GUIDs that are not in Standard format, we recommend converting them to Standard format.

  • The CamelCaseElementNameConvention converts the casing of owned entities based on their property name instead of their class name. If your application uses the CamelCaseElementNameConvention, the casing of your data might change.

For more information about the breaking changes in this version, see the Breaking Changes section of the provider repository on GitHub.

Back

What's New