4
4
Upgrade Driver Versions
5
5
=======================
6
6
7
+ .. toctree::
8
+ :titlesonly:
9
+ :maxdepth: 1
10
+
11
+ /upgrade/v2
12
+ /upgrade/v3
13
+
7
14
.. facet::
8
15
:name: genre
9
16
:values: reference
@@ -20,218 +27,22 @@ Upgrade Driver Versions
20
27
Overview
21
28
--------
22
29
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.
49
32
A breaking change is a modification of a convention or a behavior starting in
50
33
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.
116
35
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+}
144
37
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>`.
228
41
229
- Version 2.14 Release Support Changes
230
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
42
+ .. _csharp-breaking-changes:
231
43
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
+ --------------
235
46
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