Skip to content

DOCSP-43838 - Upgrade Guides #239

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Sep 26, 2024
Merged

DOCSP-43838 - Upgrade Guides #239

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
42f3bed
wip
mongoKart Sep 25, 2024
3f8345a
fixes
mongoKart Sep 25, 2024
442ee12
change to 3.0
mongoKart Sep 26, 2024
76ddcf6
feedback
mongoKart Sep 26, 2024
d5395b2
Apply suggestions from code review
mongoKart Sep 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions snooty.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ toc_landing_pages = [
"/usage-examples",
"/fundamentals",
"/fundamentals/serialization",
"/upgrade",
]

intersphinx = [
Expand All @@ -30,6 +31,7 @@ mongo-community = "MongoDB Community Edition"
mongo-enterprise = "MongoDB Enterprise Edition"
docs-branch = "master" # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)
version-number = "3.0"
last-version-2-number = "2.29"
version = "v{+version-number+}"
example = "https://raw.githubusercontent.com/mongodb/docs-csharp/{+docs-branch+}/source/includes/code-examples"
stable-api = "Stable API"
Expand Down
227 changes: 19 additions & 208 deletions source/upgrade.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,13 @@
Upgrade Driver Versions
=======================

.. toctree::
:titlesonly:
:maxdepth: 1

/upgrade/v2
/upgrade/v3

.. facet::
:name: genre
:values: reference
Expand All @@ -20,218 +27,22 @@ Upgrade Driver Versions
Overview
--------

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

Before you upgrade, perform the following actions:

- Ensure the new version is compatible with the {+mdb-server+} versions
your application connects to and the {+framework+} version your
application runs on. See the :ref:`.NET/C# Driver Compatibility <csharp-compatibility-tables>`
page for this information.
- Address any breaking changes between the current version of the driver
your application is using and your planned upgrade version in the
:ref:`Breaking Changes <csharp-breaking-changes>` section. To learn
more about the {+mdb-server+} release compatibility changes, see the
:ref:`<csharp-server-release-changes>` section.

.. tip::

To minimize the number of changes your application may require when
upgrading driver versions in the future, use the
:ref:`{+stable-api+} <csharp-stable-api>`.

.. _csharp-breaking-changes:

Breaking Changes
----------------

Use the guides on this page to identify the potentially *breaking changes* that each
version of the {+driver-short+} introduces.
A breaking change is a modification of a convention or a behavior starting in
a specific version of the driver. This type of change may prevent your application from
working properly if not addressed before upgrading the driver.

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

.. _csharp-breaking-changes-3.0:

Version 3.0 Potential Breaking Change
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- This version of the driver removes support for the
``MONGODB-CR`` authentication mechanism. To learn more about
configuring authentication in the {+driver-short+}, see
:ref:`Authentication Mechanisms. <csharp-authentication-mechanisms>`

- This version of the driver replaces the ``IMongoQueryable`` interface with the
``IQueryable`` interface, following the pattern used by most other LINQ providers. If your
application contains references to ``IMongoQueryable``, replace them with ``IQueryable``.

- This version removes the ``ClusterBuilder.ConfigureSdamLogging()`` method.
To configure logging in your application, see the :ref:`csharp-logging` guide.

- The LINQ2 provider has been removed from this version of the driver.
You must use LINQ3 for all LINQ queries.

- Previous versions of the {+driver-short+} supported two GUID representation modes.
In version 3.0, ``GuidRepresentationMode.V3`` is the only supported mode. This change
has the following effects on the driver:

- The ``BsonBinaryData(Guid)`` constructor has been removed. To construct a ``BsonBinaryData``
object from a GUID, use the ``BsonBinaryData.Create(Guid, GuidRepresentation)`` constructor.
- The ``BsonBinaryData.GuidRepresentation`` property has been removed.
- You can call the ``BsonBinaryData.ToGuid()`` method only on ``BsonBinaryData``
objects of subtype 4. If the object has any other subtype, you must call the
``BsonBinaryData.ToGuid(GuidRepresentation)`` method and specify the subtype.

The preceding changes affect your application only if you serialize and deserialize
BSON documents directly. If you map your MongoDB documents only to :ref:`csharp-poco`,
the ``GuidRepresentationMode`` doesn't affect your application.

To learn more about serializing GUIDs in the {+driver-short+}, see the
:ref:`GUIDs <csharp-guids>` page.

- Exception classes and their related types no longer contain the ``[Serializable]``
attribute, and therefore no longer support the Microsoft legacy serialization API. To
learn how to use the {+driver-short+} to serialize objects, see the
:ref:`csharp-serialization` guide.

- TLS 1.0 and 1.1 are no longer supported. You must use TLS 1.2 or higher. To learn
more about configuring TLS/SSL in the {+driver-short+}, see :ref:`<csharp-tls>`.

.. _csharp-breaking-changes-2.28.0:

Version 2.28.0 Potential Breaking Change
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- All {+driver-short+} components are strongly named. If you are using driver version
2.28 or later, and your application has dependencies that reference multiple
{+driver-short+} versions, you must create
binding redirects, as shown in the following example:

.. code-block:: csharp
working properly if you don't address it.

<configuration>
<runtime>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
<dependentAssembly>
<assemblyIdentity name="MongoDB.Driver"
publicKeyToken="94992a530f44e321"
culture="neutral" />
<bindingRedirect oldVersion="2.28.0.0"
newVersion="<version number to use>" />
</dependentAssembly>
<dependentAssembly>
<assemblyIdentity name="MongoDB.Bson"
publicKeyToken="94992a530f44e321"
culture="neutral" />
<bindingRedirect oldVersion="2.28.0.0"
newVersion="<version number to use>" />
</dependentAssembly>
<dependentAssembly>
<assemblyIdentity name="MongoDB.Driver.Core"
publicKeyToken="94992a530f44e321"
culture="neutral" />
<bindingRedirect oldVersion="2.28.0.0"
newVersion="<version number to use>" />
</dependentAssembly>
</assemblyBinding>
</runtime>
</configuration>
.. tip:: {+stable-api+}

.. _csharp-breaking-changes-2.21.0:

Version 2.21.0 Breaking Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- The function signature of ``Render`` methods in the Atlas Search builders
changed. The following code snippet shows the function signature prior
to the change and after the change:

.. code-block:: csharp

// Render function signature prior to v2.21.0
Render(IBsonSerializer<TDocument> documentSerializer, IBsonSerializerRegistry serializerRegistry);

// Render function signature in v2.21.0 and later
Render(SearchDefinitionRenderContext<TDocument> renderContext);

Version 2.19.0 Breaking Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- The ``ObjectSerializer`` only allows deserialization of
types that are considered safe. If not specified otherwise, the
``ObjectSerializer`` uses the types returned by
``ObjectSerializer.DefaultAllowedTypes``.

To learn more about the ``ObjectSerializer``, visit the
:ref:`FAQ <csharp-faq-object-serializer>`. For more information on
``DefaultAllowedTypes``, visit the `API Documentation
<https://mongodb.github.io/mongo-csharp-driver/2.19/apidocs/html/P_MongoDB_Bson_Serialization_Serializers_ObjectSerializer_DefaultAllowedTypes.htm>`__.

- The default ``LinqProvider`` has been changed to LINQ3. The ``LinqProvider``
can be configured for LINQ2 in ``MongoClientSettings`` as shown in the
following code example:

.. code-block:: csharp

var connectionString = "<connection string>";
var clientSettings = MongoClientSettings
.FromConnectionString(connectionString);
clientSettings.LinqProvider = LinqProvider.V2;
var client = new MongoClient(clientSettings);

Version 2.14.0 Breaking Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- This {+driver-long+} version removed support for {+framework+} v4.5.2 or earlier; the minimum
{+framework+} supported is v4.7.2.

- This version of the {+driver-long+} does not support .NET Standard v1.5; the minimum .NET
Standard supported is v2.0.

Version 2.13.0 Breaking Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- The ``slave0k`` connection string option was removed; the
``readPreference`` option is now used instead.


.. _csharp-server-release-changes:

Server Release Compatibility Changes
------------------------------------

A server release compatibility change is a modification
to the {+driver-long+} that discontinues support for a set of
MongoDB Server versions.

The driver discontinues support for a {+mdb-server+} version after it
reaches end-of-life (EOL).

To learn more about the MongoDB support for EOL products see the `Legacy
Support Policy <https://www.mongodb.com/support-policy/legacy>`__.

To learn more about the compatibility between .NET/C# driver versions
and {+mdb-server+} versions, visit the
:ref:`Compatibility <csharp-compatibility-tables>` page.

Version 3.0 Release Support Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The v3.0 driver drops support for {+mdb-server+} v3.6 and earlier. To
use driver v3.0 or later, your {+mdb-server+} must be v4.0 or
later.
To minimize the number of changes your application might require when
you upgrade driver versions in the future, consider using the
:ref:`{+stable-api+} <csharp-stable-api>`.

Version 2.14 Release Support Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _csharp-breaking-changes:

The v2.14 driver drops support for {+mdb-server+} v3.4 and earlier. To
use any driver from v2.14 and later, your {+mdb-server+} must be v3.6 or
later.
Upgrade Guides
--------------

To learn how to upgrade your {+mdb-server+} deployment, see
:manual:`Release Notes </release-notes/>` in the {+mdb-server+} manual.
- :ref:`csharp-upgrade-v2`
- :ref:`csharp-upgrade-v3`
Loading
Loading