Skip to content

Commit c55efc1

Browse files
author
rstam
committed
1.8 release notes.
1 parent 590101b commit c55efc1

File tree

2 files changed

+345
-4
lines changed

2 files changed

+345
-4
lines changed

‎Release Notes/Change Log v1.8-Driver.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ PushEachOptions.cs
1616
new options class used with UpdateBuilder.PushEach
1717

1818
QueryBuilder.cs
19-
added new GetIntersects methods
19+
added new GeoIntersects methods
2020
added new Near method overloads for GetJsonPoints
2121
Or method now returns { } if any sub query is { }
2222
added new Within method overload for GetJsonPolygon
@@ -224,15 +224,15 @@ MongoConnectionStringBuilder.cs
224224
added AuthenticationSource
225225

226226
MongoCredential.cs
227-
now represents any credential, not just username/password
227+
now represents any type of credential, not just username/password
228228
new Identity property is an abstract concept that replaces Username
229229
new Evidence property is an abstract concept that replaces Password (some kind of evidence that proves the Identity)
230230
new Mechanism property represents the authentication mechanism to be used
231231
new Source property represents where the identity is sourced from (returns Identity.Source)
232232
obsoleted Password property
233233
changed Username property to return Identity.Username
234234
new CreateGssapiCredential factory methods
235-
new CreateMongoCrCredential factory methods
235+
new CreateMongoCRCredential factory methods
236236
changed format of ToString result (and it no longer includes the password)
237237
new private FromComponents helper method
238238

‎Release Notes/Release Notes v1.8.md

Lines changed: 342 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,343 @@
11
C# Driver Version 1.8 Release Notes
2-
===================================
2+
===================================
3+
4+
This is a major release.
5+
6+
This release has two major goals: to support the new features of the 2.4 release
7+
of the server and to begin preparing the path for some major cleanup in the 2.0
8+
release of the driver by marking as obsolete in the 1.8 items that we plan to
9+
remove in the 2.0 release.
10+
11+
An online version of these release notes is available at:
12+
13+
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Release%20Notes%20v1.8.md
14+
15+
File by file change logs are available at:
16+
17+
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.8-Bson.txt
18+
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.8-Driver.txt
19+
20+
The full list of JIRA issues resolved in this release is available at:
21+
22+
https://jira.mongodb.org/secure/IssueNavigator.jspa?mode=hide&requestId=13193
23+
24+
Documentation on the C# driver can be found at:
25+
26+
http://www.mongodb.org/display/DOCS/CSharp+Language+Center
27+
http://api.mongodb.org/csharp/current/
28+
29+
General changes
30+
===============
31+
32+
In this release we are deprecating a large number of methods that we intend to
33+
remove in a subsequent release. With few exceptions, these deprecated methods
34+
still exist and continue to work as they used to, so you can choose when to
35+
transition off of them. Because they are deprecated they will result in
36+
compile time warnings.
37+
38+
BSON Library Changes
39+
====================
40+
41+
Changes to the IO classes
42+
-------------------------
43+
44+
The ReadBinaryData, ReadObjectId and ReadRegularExpression methods have simplified
45+
signatures. There is a new ReadBytes method, as well as new ReadRawBsonArray
46+
and ReadRawBsonDocument methods.
47+
48+
The WriteBinaryData, WriteObjectId and WriteRegularExpression methods have simplified
49+
signatures. There is a new WriteBytes method, as well as new WriteRawBsonArray
50+
and WriteRawBsonDocument methods.
51+
52+
The settings classes for the binary readers and writers now have an Encoding property
53+
that you can use to provide an encoding. The value you supply must be an instance of a
54+
UTF8Encoding, but you can configure that encoding any way you want. In particular,
55+
you would want to configure lenient decoding if you have existing data that does not
56+
conform strictly to the UTF8 standard.
57+
58+
BsonDocument object model changes
59+
---------------------------------
60+
61+
We are deprecating all the static Create factory methods and encourage you to
62+
simply call the constructors instead. We are also no longer attempting to
63+
cache any precreated instances of any BSON value (e.g. BsonInt32.Zero). These
64+
classes are so light weight that there is no need to cache them.
65+
66+
A really helpful change is that you can now use indexers on documents and
67+
arrays without having to use AsBsonDocument or AsBsonArray first. You can
68+
now write:
69+
70+
var zip = person["Addresses"][0]["Zip"].AsString;
71+
72+
instead of
73+
74+
var zip = person["Addresses"].AsBsonArray[0].AsBsonDocument["Zip"].AsString;
75+
76+
The new LazyBsonDocument and LazyBsonArray classes allow you to defer
77+
deserialization of elements until you first access them. The document or
78+
array is kept in its raw byte form until you first access it, at which point
79+
one level is deserialized. This can be a big performance win if you only
80+
access some parts of a large document.
81+
82+
The new RawBsonDocument and RawBsonArray classes are similar to their lazy
83+
counterparts, except that the data is always kept in raw bytes form only
84+
and any elements you access are deserialized every time you access them.
85+
86+
The new Lazy and Raw classes are useful when you want to copy large documents
87+
from one place to another and only need to examine a small part of the
88+
documents.
89+
90+
New conventions system for automatically creating class maps
91+
------------------------------------------------------------
92+
93+
The BsonClassMapSerializer relies on class maps to control how it
94+
serializes documents. These class maps have to be created. The easiest
95+
way to create the class maps is to let the driver create them automatically,
96+
which it does based on a number of conventions that control the process.
97+
The implementation of the conventions system is completely new in this
98+
release. Conventions implemented using the old conventions architecture
99+
are still supported but will be based on deprecated classes and interfaces
100+
and should be rewritten to use the new architecture.
101+
102+
Deserialization can now call constructors or static factory methods
103+
-------------------------------------------------------------------
104+
105+
You can now identify constructors or static factory methods that can
106+
be used during deserialization to instantiate objects. This means that
107+
it is now possible to deserialize immutable classes. During deserialization
108+
values from the serialized document are matched to parameters of a constructor
109+
or static factory method. If there is more than one possible constructor
110+
or factory method then the one with the most matching parameters is chosen.
111+
112+
Standard serializers are now created and registered as late as possible
113+
-----------------------------------------------------------------------
114+
115+
The standard built-in serializers are now created and instantiated as late
116+
as possible, giving you a chance to create and register your own if you
117+
prefer. You can either register the standard built-in serializers with
118+
different default serialization options, or you can write and register
119+
your own.
120+
121+
BsonDocument object model serialization standardized
122+
----------------------------------------------------
123+
124+
Serialization of BsonDocument object model classes has been completely
125+
moved to IBsonSerializer based classes. The existing ReadFrom/WriteTo
126+
methods in the BsonDocument object model have been deprecated.
127+
128+
Driver Changes
129+
==============
130+
131+
New authentication model
132+
------------------------
133+
134+
In previous versions of the driver there was only one kind of credential
135+
(a username/password credential) and there was a mapping that specified
136+
which credential to use for each database being accessed. Based on that
137+
mapping the driver would determine which credential was needed for the
138+
database being accessed and would ensure that the connection being used
139+
was authenticated properly.
140+
141+
The authentication model on the server has changed drastically, and it is no
142+
longer required that the credential used to access a database be stored
143+
in that same database. Therefore it is impossible to determine in advance
144+
which credential is the one that will give you access to a database. So
145+
now the drivers simply work with a list of credentials, with no attempt
146+
to figure out which credential should be used with which database. Instead,
147+
all connections are authenticated against all of the credentials supplied.
148+
149+
Strict enforcement of MaxConnectionIdleTime and MaxConnectionLifeTime
150+
---------------------------------------------------------------------
151+
152+
Previously these values were only loosely enforced and were treated more
153+
like hints. Now they are enforced strictly. This helps prevent network
154+
errors in certain environments where the networking infrastructure will
155+
terminate connections that are idle for a certain amount of time or that
156+
have been open too long (for example, some firewalls and Azure).
157+
158+
Driver no longer opens and closes a connection every 10 seconds
159+
---------------------------------------------------------------
160+
161+
The driver pings the state of any server it is connected to once every
162+
10 seconds. In earlier releases it would open and close a new connection
163+
each time. While this guaranteed that the ping would happen wihtout delay
164+
it had the unfortunate consequence of filling the server logs with
165+
messages reporting the opening and closing of the connections. The
166+
driver now tries to reuse an existing connection for the ping, and will
167+
only open a new one if it can't acquire an existing one rapidly.
168+
169+
Removed DeprecatedQuery and DeprecatedQueryBuilder classes
170+
----------------------------------------------------------
171+
172+
These classes have been deprecated for several releases now and have
173+
been removed entirely.
174+
175+
Changes to Fields builder
176+
-------------------------
177+
178+
There is a new ElemMatch method to select which elements of an array
179+
to include in the result documents.
180+
181+
Changes to Query builder
182+
------------------------
183+
184+
The new GeoIntersects method supports the $geoIntersects query operator with
185+
GeoJson values. In addition, new overloads of Near and Within support
186+
using GeoJson values with these existing query operators.
187+
188+
Changes to Update builder
189+
-------------------------
190+
191+
New SetOnInsert method to support the $setOnInsert update operator.
192+
193+
New overload of PushEach that has a PushEachOptions parameter that can
194+
be used to provide advanced options to the $pushEach update operator.
195+
196+
Changes to Index builder
197+
------------------------
198+
199+
Added support for creating hashed and 2dsphere indexes.
200+
201+
GeoJson object model
202+
--------------------
203+
204+
The GeoJson object model is a type-safe in memory representation of GeoJSON
205+
objects. When these objects are serialized to BSON documents the resulting
206+
BSON documents will be valid GeoJSON documents. You can use the GeoJson
207+
object model to represent GeoJSON properties in your POCOs and to provide
208+
values to the new methods added to the Query builder to support GeoJson queries.
209+
210+
Simplified settings classes
211+
---------------------------
212+
213+
The settings classes have been simplified a bit and we have standardized how
214+
settings are stored internally and how default values are applied. See the
215+
comments below on the different settings classes.
216+
217+
MongoClientSettings
218+
-------------------
219+
220+
The CredentialsStore and DefaultCredentials properties have been replaced by
221+
the new Credentials property. The CredentialsStore property was a mapping from
222+
a database name to the credential to use to access that database. The Credentials
223+
property is simply a list of credentials that will be used with all connections,
224+
regardless of which database is being accessed.
225+
226+
There is a new SslSettings property that lets you control every aspect of an
227+
SSL connection to the server.
228+
229+
The new ReadEncoding and WriteEncoding settings can be used to configure the
230+
details of UTF8 encoding.
231+
232+
MongoServerSettings
233+
-------------------
234+
235+
While this class has not yet been deprecated, it eventually will be. We recommend
236+
you always use MongoClientSettings instead.
237+
238+
The new settings added to MongoClientSettings have also been added to
239+
MongoServerSettings.
240+
241+
MongoDatabaseSettings
242+
---------------------
243+
244+
The database name has been moved out of the settings class and is now an
245+
argument to the GetDatabase method. Therefore the DatabaseName property
246+
has been deprecated.
247+
248+
The proper way to create an instance of MongoDatabaseSettings is to call the
249+
constructor. The CreateDatabaseSettings method of MongoServer is deprecated.
250+
251+
The Credentials property has been removed. It is no longer necessary (or
252+
possible) to provide a credential at the database level.
253+
254+
The new ReadEncoding and WriteEncoding settings can be used to configure the
255+
details of UTF8 encoding. If not set, they are inherited from the server
256+
settings.
257+
258+
MongoCollectionSettings
259+
-----------------------
260+
261+
The big change is that the name of the collection and the default document type
262+
have been moved out of the settings class and are now arguments of the
263+
GetCollection method. As part of this change the MongoCollection<TDefaultDocument>
264+
subclass is deprecated, as have the CollectionName and DefaultDocumentType
265+
properties.
266+
267+
The proper way to create an instance of MongoCollectionSettings is to call the
268+
constructor. The CreateCollectionSettings method of MongoDatabase is deprecated.
269+
270+
The new ReadEncoding and WriteEncoding settings can be used to configure the
271+
details of UTF8 encoding. If not set, they are inherited from the database
272+
settings.
273+
274+
New LINQ features
275+
-----------------
276+
277+
You can now add WithIndex to LINQ queries to provide an index hint, and you
278+
can use Explain to have the server explain how the resulting MongoDB query
279+
was executed.
280+
281+
MongoServer changes
282+
-------------------
283+
284+
MongoServer no longer maintains a mapping from database settings to MongoDatabase
285+
instances, and therefore GetDatabase no longer returns the same instance
286+
every time it is called with the same parameters. MongoDatabase is a light
287+
weight object so there is not much benefit in caching it, and by returning
288+
a new instance every time, GetDatabase no longer has to use a lock to be
289+
thread safe.
290+
291+
The indexers for getting a database are deprecated, so use:
292+
293+
var database = server.GetDatabase("test");
294+
295+
instead of:
296+
297+
var database = server["test"];
298+
299+
All of the methods that take adminCredentials have been removed. It is no
300+
longer possible to provide admin credentials for just one operation. You
301+
have to provide the admin credentials in your MongoClientSettings if you
302+
need to run admin commands. If you want to keep your admin credentials
303+
separate from your regular credentials create two (or more) instances
304+
of MongoClient with different MongoClientSettings.
305+
306+
MongonDatabase changes
307+
----------------------
308+
309+
MongoDatabase no longer maintains a mapping from collection settings to
310+
MongoCollection instances, and therefore GetCollection not longer returns
311+
the same instance every time it is called with the same parameters.
312+
MongoCollection is a light weight object so there is not much benefit
313+
in caching it, and by returning a new instance every time, GetCollection
314+
no longer has to use a lock to be thread safe.
315+
316+
The indexers for getting a collection are deprecated, so use:
317+
318+
var collection = database.GetCollection<TDocument>("test");
319+
320+
instead of:
321+
322+
var collection = database["test"]; // note: indexers can't have type parameters
323+
324+
One reason we are deprecating the indexers is that they can't have type
325+
parameters, so there is no way to specify the default document type when
326+
using an indexer.
327+
328+
All of the methods that take adminCredentials have been removed. It is no
329+
longer possible to provide admin credentials for just one operation. You
330+
have to provide the admin credentials in your MongoClientSettings if you
331+
need to run admin commands.
332+
333+
MongoCollection changes
334+
-----------------------
335+
336+
InsertBatch has always had the capability to break large batches into smaller
337+
batches that fit within the server's maximum message length. There has been a
338+
slight change in 1.8 to how those sub batches are processed. If you are using
339+
a WriteConcern of Unacknowledged and the ContinueOnError flag is false, then
340+
the driver will insert a GetLastError command after each sub batch except the
341+
last to detect whether an error occurred. This is necessary to implement the
342+
semantics of ContinueOnError being false, where an error in one of the sub
343+
batches should prevent all following sub batches from being sent.

0 commit comments

Comments
 (0)