Skip to content

Commit 1d62b60

Browse files
DOCSP-43838 - Upgrade Guides (#239)
Co-authored-by: Jordan Smith <[email protected]>
1 parent d3c0037 commit 1d62b60

File tree

4 files changed

+283
-208
lines changed

4 files changed

+283
-208
lines changed

snooty.toml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ toc_landing_pages = [
66
"/usage-examples",
77
"/fundamentals",
88
"/fundamentals/serialization",
9+
"/upgrade",
910
]
1011

1112
intersphinx = [
@@ -30,6 +31,7 @@ mongo-community = "MongoDB Community Edition"
3031
mongo-enterprise = "MongoDB Enterprise Edition"
3132
docs-branch = "master" # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)
3233
version-number = "3.0"
34+
last-version-2-number = "2.29"
3335
version = "v{+version-number+}"
3436
example = "https://raw.githubusercontent.com/mongodb/docs-csharp/{+docs-branch+}/source/includes/code-examples"
3537
stable-api = "Stable API"

source/upgrade.txt

Lines changed: 19 additions & 208 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@
44
Upgrade Driver Versions
55
=======================
66

7+
.. toctree::
8+
:titlesonly:
9+
:maxdepth: 1
10+
11+
/upgrade/v2
12+
/upgrade/v3
13+
714
.. facet::
815
:name: genre
916
:values: reference
@@ -20,218 +27,22 @@ Upgrade Driver Versions
2027
Overview
2128
--------
2229

23-
In this section, you can identify essential changes you must make to your
24-
application when you upgrade your driver to a new version.
25-
26-
Before you upgrade, perform the following actions:
27-
28-
- Ensure the new version is compatible with the {+mdb-server+} versions
29-
your application connects to and the {+framework+} version your
30-
application runs on. See the :ref:`.NET/C# Driver Compatibility <csharp-compatibility-tables>`
31-
page for this information.
32-
- Address any breaking changes between the current version of the driver
33-
your application is using and your planned upgrade version in the
34-
:ref:`Breaking Changes <csharp-breaking-changes>` section. To learn
35-
more about the {+mdb-server+} release compatibility changes, see the
36-
:ref:`<csharp-server-release-changes>` section.
37-
38-
.. tip::
39-
40-
To minimize the number of changes your application may require when
41-
upgrading driver versions in the future, use the
42-
:ref:`{+stable-api+} <csharp-stable-api>`.
43-
44-
.. _csharp-breaking-changes:
45-
46-
Breaking Changes
47-
----------------
48-
30+
Use the guides on this page to identify the potentially *breaking changes* that each
31+
version of the {+driver-short+} introduces.
4932
A breaking change is a modification of a convention or a behavior starting in
5033
a specific version of the driver. This type of change may prevent your application from
51-
working properly if not addressed before upgrading the driver.
52-
53-
The breaking changes in this section are categorized by the driver version that
54-
introduced them. When upgrading driver versions, address all the breaking
55-
changes between the current and upgrade versions. For example, if you
56-
are upgrading the driver from v2.0 to v2.20, address all breaking changes from
57-
the version after v2.0 including any listed under v2.20.
58-
59-
.. _csharp-breaking-changes-3.0:
60-
61-
Version 3.0 Potential Breaking Change
62-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
63-
64-
- This version of the driver removes support for the
65-
``MONGODB-CR`` authentication mechanism. To learn more about
66-
configuring authentication in the {+driver-short+}, see
67-
:ref:`Authentication Mechanisms. <csharp-authentication-mechanisms>`
68-
69-
- This version of the driver replaces the ``IMongoQueryable`` interface with the
70-
``IQueryable`` interface, following the pattern used by most other LINQ providers. If your
71-
application contains references to ``IMongoQueryable``, replace them with ``IQueryable``.
72-
73-
- This version removes the ``ClusterBuilder.ConfigureSdamLogging()`` method.
74-
To configure logging in your application, see the :ref:`csharp-logging` guide.
75-
76-
- The LINQ2 provider has been removed from this version of the driver.
77-
You must use LINQ3 for all LINQ queries.
78-
79-
- Previous versions of the {+driver-short+} supported two GUID representation modes.
80-
In version 3.0, ``GuidRepresentationMode.V3`` is the only supported mode. This change
81-
has the following effects on the driver:
82-
83-
- The ``BsonBinaryData(Guid)`` constructor has been removed. To construct a ``BsonBinaryData``
84-
object from a GUID, use the ``BsonBinaryData.Create(Guid, GuidRepresentation)`` constructor.
85-
- The ``BsonBinaryData.GuidRepresentation`` property has been removed.
86-
- You can call the ``BsonBinaryData.ToGuid()`` method only on ``BsonBinaryData``
87-
objects of subtype 4. If the object has any other subtype, you must call the
88-
``BsonBinaryData.ToGuid(GuidRepresentation)`` method and specify the subtype.
89-
90-
The preceding changes affect your application only if you serialize and deserialize
91-
BSON documents directly. If you map your MongoDB documents only to :ref:`csharp-poco`,
92-
the ``GuidRepresentationMode`` doesn't affect your application.
93-
94-
To learn more about serializing GUIDs in the {+driver-short+}, see the
95-
:ref:`GUIDs <csharp-guids>` page.
96-
97-
- Exception classes and their related types no longer contain the ``[Serializable]``
98-
attribute, and therefore no longer support the Microsoft legacy serialization API. To
99-
learn how to use the {+driver-short+} to serialize objects, see the
100-
:ref:`csharp-serialization` guide.
101-
102-
- TLS 1.0 and 1.1 are no longer supported. You must use TLS 1.2 or higher. To learn
103-
more about configuring TLS/SSL in the {+driver-short+}, see :ref:`<csharp-tls>`.
104-
105-
.. _csharp-breaking-changes-2.28.0:
106-
107-
Version 2.28.0 Potential Breaking Change
108-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
109-
110-
- All {+driver-short+} components are strongly named. If you are using driver version
111-
2.28 or later, and your application has dependencies that reference multiple
112-
{+driver-short+} versions, you must create
113-
binding redirects, as shown in the following example:
114-
115-
.. code-block:: csharp
34+
working properly if you don't address it.
11635

117-
<configuration>
118-
<runtime>
119-
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
120-
<dependentAssembly>
121-
<assemblyIdentity name="MongoDB.Driver"
122-
publicKeyToken="94992a530f44e321"
123-
culture="neutral" />
124-
<bindingRedirect oldVersion="2.28.0.0"
125-
newVersion="<version number to use>" />
126-
</dependentAssembly>
127-
<dependentAssembly>
128-
<assemblyIdentity name="MongoDB.Bson"
129-
publicKeyToken="94992a530f44e321"
130-
culture="neutral" />
131-
<bindingRedirect oldVersion="2.28.0.0"
132-
newVersion="<version number to use>" />
133-
</dependentAssembly>
134-
<dependentAssembly>
135-
<assemblyIdentity name="MongoDB.Driver.Core"
136-
publicKeyToken="94992a530f44e321"
137-
culture="neutral" />
138-
<bindingRedirect oldVersion="2.28.0.0"
139-
newVersion="<version number to use>" />
140-
</dependentAssembly>
141-
</assemblyBinding>
142-
</runtime>
143-
</configuration>
36+
.. tip:: {+stable-api+}
14437

145-
.. _csharp-breaking-changes-2.21.0:
146-
147-
Version 2.21.0 Breaking Changes
148-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
149-
150-
- The function signature of ``Render`` methods in the Atlas Search builders
151-
changed. The following code snippet shows the function signature prior
152-
to the change and after the change:
153-
154-
.. code-block:: csharp
155-
156-
// Render function signature prior to v2.21.0
157-
Render(IBsonSerializer<TDocument> documentSerializer, IBsonSerializerRegistry serializerRegistry);
158-
159-
// Render function signature in v2.21.0 and later
160-
Render(SearchDefinitionRenderContext<TDocument> renderContext);
161-
162-
Version 2.19.0 Breaking Changes
163-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
164-
165-
- The ``ObjectSerializer`` only allows deserialization of
166-
types that are considered safe. If not specified otherwise, the
167-
``ObjectSerializer`` uses the types returned by
168-
``ObjectSerializer.DefaultAllowedTypes``.
169-
170-
To learn more about the ``ObjectSerializer``, visit the
171-
:ref:`FAQ <csharp-faq-object-serializer>`. For more information on
172-
``DefaultAllowedTypes``, visit the `API Documentation
173-
<https://mongodb.github.io/mongo-csharp-driver/2.19/apidocs/html/P_MongoDB_Bson_Serialization_Serializers_ObjectSerializer_DefaultAllowedTypes.htm>`__.
174-
175-
- The default ``LinqProvider`` has been changed to LINQ3. The ``LinqProvider``
176-
can be configured for LINQ2 in ``MongoClientSettings`` as shown in the
177-
following code example:
178-
179-
.. code-block:: csharp
180-
181-
var connectionString = "<connection string>";
182-
var clientSettings = MongoClientSettings
183-
.FromConnectionString(connectionString);
184-
clientSettings.LinqProvider = LinqProvider.V2;
185-
var client = new MongoClient(clientSettings);
186-
187-
Version 2.14.0 Breaking Changes
188-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
189-
190-
- This {+driver-long+} version removed support for {+framework+} v4.5.2 or earlier; the minimum
191-
{+framework+} supported is v4.7.2.
192-
193-
- This version of the {+driver-long+} does not support .NET Standard v1.5; the minimum .NET
194-
Standard supported is v2.0.
195-
196-
Version 2.13.0 Breaking Changes
197-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
198-
199-
- The ``slave0k`` connection string option was removed; the
200-
``readPreference`` option is now used instead.
201-
202-
203-
.. _csharp-server-release-changes:
204-
205-
Server Release Compatibility Changes
206-
------------------------------------
207-
208-
A server release compatibility change is a modification
209-
to the {+driver-long+} that discontinues support for a set of
210-
MongoDB Server versions.
211-
212-
The driver discontinues support for a {+mdb-server+} version after it
213-
reaches end-of-life (EOL).
214-
215-
To learn more about the MongoDB support for EOL products see the `Legacy
216-
Support Policy <https://www.mongodb.com/support-policy/legacy>`__.
217-
218-
To learn more about the compatibility between .NET/C# driver versions
219-
and {+mdb-server+} versions, visit the
220-
:ref:`Compatibility <csharp-compatibility-tables>` page.
221-
222-
Version 3.0 Release Support Changes
223-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
224-
225-
The v3.0 driver drops support for {+mdb-server+} v3.6 and earlier. To
226-
use driver v3.0 or later, your {+mdb-server+} must be v4.0 or
227-
later.
38+
To minimize the number of changes your application might require when
39+
you upgrade driver versions in the future, consider using the
40+
:ref:`{+stable-api+} <csharp-stable-api>`.
22841

229-
Version 2.14 Release Support Changes
230-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
42+
.. _csharp-breaking-changes:
23143

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

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

0 commit comments

Comments
 (0)