Skip to content

Commit 393d4d7

Browse files
author
rstam
committed
First draft of the Release Notes for 1.4. Changed to .md format so that it will display nicely when viewed in github.
1 parent 1c5c7de commit 393d4d7

File tree

3 files changed

+348
-4
lines changed

3 files changed

+348
-4
lines changed

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ driver home: http://github.com/mongodb/mongo-csharp-driver
44

55
mongodb home: http://www.mongodb.org/
66

7-
apidoc: http://api.mongodb.org/csharp/ (coming soon)
7+
apidoc: http://api.mongodb.org/csharp/
88

99
### Questions and Bug Reports
1010

‎Release Notes/Release Notes v1.4.md

Lines changed: 347 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,347 @@
1+
C# Driver Version 1.4 Release Notes
2+
===================================
3+
4+
The major feature of this release is support for LINQ queries. Some of the other
5+
changes (e.g. new IBsonSerializer methods) are also in support of the new LINQ
6+
implementation.
7+
8+
File by file change logs are available at:
9+
10+
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.4-Bson.txt
11+
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Change%20Log%20v1.4-Driver.txt
12+
13+
These release notes describe the changes at a higher level, and omit describing
14+
some of the minor changes.
15+
16+
Breaking changes
17+
----------------
18+
19+
There are some breaking changes in this release. Some of them are only breaking
20+
at the binary level and are easily taken care of by simply recompiling your
21+
application. Others require minor changes to your source code. Many of the
22+
breaking changes are in low level classes, and these won't affect most users,
23+
unless for example you are doing things like writing custom serializers.
24+
25+
Please read these release notes carefully before adopting the new 1.4 release
26+
of the C# driver to determine if any of the breaking changes affect you.
27+
28+
LINQ query support
29+
------------------
30+
31+
As stated previously, the major feature of this release is support for LINQ
32+
queries. These release notes don't describe the new LINQ support, for that
33+
please refer to the online LINQ tutorial at:
34+
35+
http://www.mongodb.org/display/DOCS/CSharp+Driver+LINQ+Tutorial
36+
37+
(Please note that the LINQ tutorial won't be available until several weeks
38+
after the 1.4 release has been shipped. Sorry.)
39+
40+
CLS compliance
41+
--------------
42+
43+
Both the MongoDB.Bson.dll and MongoDB.Driver.dll libraries have been marked
44+
as CLS compliant, which should make them more useful from other .NET languages.
45+
Most of the changes required to make the libraries CLS compliant are not even
46+
visible in the public interface.
47+
48+
Release builds
49+
--------------
50+
51+
Starting with the 1.4 version we are shipping Release builds of the DLLs.
52+
53+
Code formatting changes
54+
-----------------------
55+
56+
In response to popular demand the code base has been reformatted using the
57+
default Visual Studio C# code formatting settings. We have also adopted
58+
the convention of prefixing instance field names with a single "_" and static
59+
fields names with a double "__" (while this convention for static fields is
60+
not common it is very useful). One of the nice benefits of these conventions
61+
is that the drop down menu in Visual Studio that displays class members ends
62+
up grouping all static fields first, followed by instance fields, followed by
63+
the rest of the properties and methods.
64+
65+
BSON library changes
66+
====================
67+
68+
ArraySerializationOptions
69+
-------------------------
70+
71+
This new class allows you to specify serialization options for array-like
72+
members. Initially the only option available is to specify serialization
73+
options for the items of the array. When using attributes to specify
74+
serialization options any attributes that don't apply to the collection as a
75+
whole implictly apply to the items of the collection.
76+
77+
BsonDateTime is now a pure BSON DateTime value
78+
----------------------------------------------
79+
80+
In previous versions the BsonDateTime class stored its value twice in two
81+
different private fields: _millisecondsSinceEpoch (a long) and _value (a .NET
82+
DateTime). The idea was that you could store a .NET DateTime without losing any
83+
precision. However, that turns out to be confusing because as soon as you save
84+
the BsonDateTime value to the database and read it back you are going to lose
85+
precision anyway, so you might as well lose it right up front and not make
86+
false promises.
87+
88+
BsonDateTime also has two new helper methods: ToLocalTime and ToUniversalTime.
89+
These methods convert the BSON DateTime to either local or UTC .NET DateTime
90+
values. There are also new AsLocalTime and AsUniversalTime properties in
91+
BsonValues that can be used to convert BsonValues to .NET DateTime values (like
92+
all AsXyz properties in BsonValue they throw an InvalidCastException if the
93+
BsonValue is not actually a BsonDateTime).
94+
95+
BsonIgnoreExtraElements attribute
96+
---------------------------------
97+
98+
The BsonIgnoreExtraElements attribute has a new property called Inherited. If
99+
this property is set to true then all classes derived from this one will
100+
automatically inherit this setting, which makes it easy to set it for an
101+
entire class hierarchy at once.
102+
103+
BsonIgnoreIfDefault attribute
104+
-----------------------------
105+
106+
This new attribute allows you to specify that you want a field to be ignored
107+
during serialization if it has the default value. This replaces the
108+
SerializeDefaultValue parameter of the BsonDefaultValue attribute. By making
109+
this a separate attribute you can specify that you want the default value
110+
ignored without having to specify the default value as well.
111+
112+
BsonReader: CurrentBsonType vs GetCurrentBsonType
113+
-------------------------------------------------
114+
115+
In previous versions the CurrentBsonType property had side effects. In general
116+
it is bad form for the get accessor of a property to have side effects, as even
117+
something as simple as looking at the value of the property in a debugger can
118+
have unintended consequences. Therefore, in the 1.4 release the CurrentBsonType
119+
property has no side effects. The previous behavior is now implemented in the
120+
GetCurrentBsonType method. While this is mostly an internal change, *if* you
121+
have written a custom serializer that used the CurrentBsonType property and
122+
were relying on its side effects you will have to change your custom serializer
123+
to call GetCurrentBsonType instead.
124+
125+
ConventionProfile new conventions
126+
---------------------------------
127+
128+
The ConventionProfile class has two new conventions: IgnoreIfDefaultConvention
129+
and SerializationOptionsConvention. Also, the SerializeDefaultValueConvention
130+
has been obsoleted in favor of the new IgnoreIfDefaultConvention.
131+
132+
DictionarySerializationOptions
133+
------------------------------
134+
135+
This class has a new property called ItemSerializationOptions that can be used
136+
to specify the options to use when serializing the value of the items in the
137+
dictionary. When using attributes to specify serialization options, any
138+
attributes that don't apply to the dictionary as a whole implicitly apply to
139+
the value of the items in the dictionary.
140+
141+
ExtraElements
142+
-------------
143+
144+
Previous versions of the C# driver allowed you to specify a field of the class
145+
to be used to store any extra elements encountered during deserialization.
146+
However, this field *had* to be of type BsonDocument, which meant introducing
147+
a dependency on the driver into your data model classes (which some developers
148+
don't want to do). You now have the additional option of declaring your
149+
ExtraElements field to be of type IDictionary<string, object> instead.
150+
151+
IBsonSerializationOptions
152+
-------------------------
153+
154+
The IBsonSerializationOptions has several new methods. ApplyAttribute is used
155+
during the AutoMap process to apply an attribute to some serialization options
156+
that are being built incrementally (starting from the default serialization
157+
options). This provides an extensible mechanism for applying new attributes to
158+
new serialization options classes. The Clone and Freeze methods are introduced
159+
to allow serialization options to be converted to read-only once initialization
160+
is complete to provide thread safety.
161+
162+
IBsonSerializer
163+
---------------
164+
165+
The IBsonSerializer has several new methods. GetDefaultSerializationOptions
166+
provides an initial set of serialization options that any serialization
167+
attributes found can be applied against. GetItemSerializationInfo provides
168+
serialization info about the items and applies only to serializers for
169+
collection-like classes. GetMemberSerializationInfo provides serialization
170+
info about members of a class. The last two are used in the implementation
171+
of LINQ queries.
172+
173+
Image/Bitmap serializers
174+
------------------------
175+
176+
New serializers have been provided for the Image abstract base class and the
177+
Bitmap class derived from it.
178+
179+
ISupportInitialize
180+
------------------
181+
182+
The ISupportInitialize interface defines two methods: BeginInit and EndInit.
183+
The BsonClassMapSerializer now checks whether the class being deserialized
184+
implements this interface, and if so, calls BeginInit just before it starts
185+
to deserialize a value, and EndInit just after it has finished. You can
186+
use this feature to do any pre- or post-processing.
187+
188+
ObjectId/BsonObjectId creation
189+
------------------------------
190+
191+
ObjectId (and BsonObjectId) have a new constructor that allows you to supply
192+
the timestamp as a .NET DateTime value and it will automatically be converted
193+
to seconds since the Unix Epoch. These new constructors are useful if you want
194+
to create artificial ObjectIds to use in range based ObjectId queries (in
195+
which case you will usually set the machine, pid and increment fields to zero).
196+
197+
There are also two new overloads of GenerateNewId that allow you to provide
198+
the desired timestamp as either an int or a .NET DateTime. These new overloads
199+
are useful if you need to create backdated ObjectIds.
200+
201+
TimeSpanSerializationOptions
202+
----------------------------
203+
204+
You can now choose any of the following representations for a TimeSpan: string,
205+
double, Int32 or Int64. In addition, when using any of the numeric
206+
representations, you can use the Units property to choose the units that the
207+
numeric value is in (choose from: Ticks, Days, Hours, Minutes, Seconds,
208+
Milliseconds and Nanoseconds).
209+
210+
Driver changes
211+
==============
212+
213+
Authentication support improved
214+
-------------------------------
215+
216+
Operations that require admin credentials previously required you to set the
217+
DefaultCredentials of MongoServerSettting to admin credentials. But that is
218+
undesirable because it provides the client code full access to all databases,
219+
essentially negating the benefit of using authentication in the first place.
220+
In the 1.4 release all operations that require admin credentials have a new
221+
overload where you can provide the needed credentials; you no longer have to
222+
set the DefaultCredentials. Another option is to store credentials for the
223+
admin database in the new MongoCredentialsStore.
224+
225+
Connection pool defaults changed
226+
--------------------------------
227+
228+
The default value of WaitQueueMultiple has been changed from 1.0 to 5.0 and the
229+
default value of WaitQueueTimeout has been changed from 0.5 seconds to 2
230+
minutes. These new values are taken from the Java driver, where they have
231+
reportedly been working well for users running under heavy loads. These new
232+
values mean that many more threads can be waiting for a lot longer time
233+
before a timeout occurs and an exception is thrown.
234+
235+
Exceptions are no longer caught and rethrown when possible
236+
----------------------------------------------------------
237+
238+
Wherever possible exception handling code that used to use catch exceptions
239+
and rethrow them after processing them has been changed to roughly equivalent
240+
code that uses try/finally to accomplish the same objective. This is specially
241+
helpful if you are running the debugger set to stop whenever an exception is
242+
thrown.
243+
244+
IBsonSerializable semi-deprecated
245+
---------------------------------
246+
247+
The LINQ support relies heavily on the new methods added to IBsonSerializer.
248+
Because of this it is highly encouraged that in the future you always opt to
249+
write an IBsonSerializer for your class instead of having it implement
250+
IBsonSerializable (see the notes for MongoDBRef and SystemProfileInfo for
251+
examples of where the driver itself has switched from IBsonSerializable to
252+
using a IBsonSerializer). IBsonSerializable still has a modest role to play
253+
in classes that just need to be serialized quickly and simply and for which we
254+
won't be writing LINQ queries (for example, the driver's Builders and Wrappers
255+
still use IBsonSerializable).
256+
257+
LINQ query support
258+
------------------
259+
260+
As mentioned earlier in the release notes more information about the new
261+
support for LINQ queries can be found in the forthcoming LINQ tutorial:
262+
263+
http://www.mongodb.org/display/DOCS/CSharp+Driver+LINQ+Tutorial
264+
265+
Locking issues
266+
--------------
267+
268+
A number of locking issues related to connection pooling have been resolved.
269+
These issues were particularly likely to occur if you had more threads than
270+
the maximum size of the connection pool and were using the connections heavily
271+
enough that the connection pool could be used up.
272+
273+
MongoCredentialsStore
274+
---------------------
275+
276+
You can now create a credentials store which contains credentials for multiple
277+
databases (the name of the database is the key and the credentials are the
278+
value). The credentials store must be set up (in the MongoServerSettings)
279+
before you call MongoServer.Create, so it is only intended for scenarios
280+
where you have a fixed set of credentials that aren't going to change at runtime.
281+
282+
MongoDBRef no longer implements IBsonSerializable
283+
-------------------------------------------------
284+
285+
MongoDBRef used to handle its own serialization by virtue of implementing
286+
IBsonSerializable. But the IBsonSerializable interface is not helpful when we
287+
try to add support for writing LINQ queries against components of a MongoDBRef.
288+
Instead, there is now a MongoDBRefSerializer which handles serialization of
289+
MongoDBRefs, while at the same time implementing GetMemberSerializationInfo
290+
which enables the LINQ implementation to support LINQ queries against
291+
MongoDBRefs.
292+
293+
MongoInsertOptions/MongoUpdateOptions constructor changed
294+
---------------------------------------------------------
295+
296+
The constructors for MongoInsertOptions and MongoUpdateOptions used to require
297+
that the collection be passed in as a parameter. The purpose was to allow
298+
the constructor to inherit some of the options from the collection settings.
299+
To the developer however, this was awkward, as it required providing the
300+
collection where it seemed to be redundant. By handling default values in a
301+
different way we no longer require the collection to be supplied to the
302+
constructors. The old constructors (that require the collection parameter) are
303+
still temporarily supported but have been marked as deprecated with a warning.
304+
305+
MongoServer Admin properties and methods removed
306+
------------------------------------------------
307+
308+
The following Admin properties and methods have been removed from MongoServer:
309+
AdminDatabase, GetAdminDatabase, RunAdminCommand, and RunAdminCommandAs. The
310+
reason for removing them is that many developers would never use them anyway,
311+
and adding new overloads for providing admin credentials would have resulted
312+
in even more of these rarely used properties and methods. If you were using
313+
any of these methods or properties they can easily be replaced with calls to
314+
methods of an instance of MongoDatabase (use one of the overloads of
315+
GetDatabase with "admin" as the database to get a reference to the admin
316+
database).
317+
318+
RequestStart/RequestDone
319+
------------------------
320+
321+
Recall that the purpose of RequestStart is to tell the driver that a series of
322+
operations should all be done using the same connection (which in the case of a
323+
replica set also implies using the same member of the connection set). Which
324+
member of a replica set was chosen depended on the slaveOk parameter: a value
325+
of false meant that the primary had to be used, and a value of true meant that
326+
an arbitrary secondary would be used. A new overload of RequestStart now allows
327+
the caller to specify which member should be used, which can be very useful for
328+
implementing custom query routing algorithms or for querying specific members
329+
of a replica set. In general though, keep in mind that you should *not* be
330+
using RequestStart unless you have an unusual scenario which requires it.
331+
332+
SocketTimeout default changed
333+
-----------------------------
334+
335+
The default value for SocketTimeout has been changed from 30 seconds to 0,
336+
which is a special value meaning to use the operating system default value,
337+
which in turn is infinity. If you actually wanted a SocketTimeout you now
338+
have to set it yourself. The SocketTimeout is currently a server setting, but
339+
most likely in a future release it will be possible to set it at the
340+
individual operation level.
341+
342+
SystemProfileInfo no longer implements IBsonSerializable
343+
--------------------------------------------------------
344+
345+
See the notes for MongoDBRef. SystemProfileInfo no longer implements
346+
IBsonSerializable for the same reasons, and there is a new
347+
SystemProfileInfoSerializer instead.

‎Release Notes/Release Notes v1.4.txt

Lines changed: 0 additions & 3 deletions
This file was deleted.

0 commit comments

Comments
 (0)