release notes v1.1

7/31/2019 Release Notes v1.1

1/10

C# Driver Version 1.1 Release Notes===================================

This is a significant release of the C# driver, with many new features and improvements. There are also a fewbreaking changes, which should affect very few users as they are mostly at a very low level. Because there aresome breaking changes make sure to read these release notes and be prepared to make some minor changes.

HighlightsBsonDocument.Parse allows you to easily parse a JSON stringNew Shell JsonOutputMode (it's now the default)Many JsonReader improvementsSupport for new regular expressions options (i, m, x, and s)Support for custom type mappers that can be registered with BsonTypeMapperDeserializer optimized to not look for discriminator when not necessaryNew IsClassMapRegistered method in BsonClassSerializerIf a class defines a ShouldSerializeXyz method it is called to determine if

property Xyz should be serializedDriver now throws EndOfStreamException instead of hanging when server closes

socketBsonDateTime now supports full range of valid BSON DateTime values (not just

.NET range)

New GuidRepresentation enum and UuidStandard or UuidLegacy BsonBinarySubTypesId values of 0 and BsonNull.Value are no longer prohibited (unless you want

them to be)GenerateDocument method of IIdGenerator now has access to container (i.e. co

llection) and documentDriver is more PowerShell (and metadata) friendly by adding non-generic vers

ions of all generic methodsMapReduce output can now be sent to a collection in a different databaseValidateCollectionResult supports new embedded document result (or parses st

ring when connected to older servers)FindAndModify no longer throws an exception when no matching document is fou

nd

FindAndRemove no longer throws an exception when no matching document is foundSave now works correctly with a compound _idTailable cursors are supportedNew MongoServerInstance class represents a physical instance of a MongoDB se

rverNew MongoBuildInfo class has information about server versionGridFS Download and Upload methods now verify MD5 hash to detect transmissio

n errorsConnecting to a replica set is faster because it returns as soon as primary

is found

Shell output mode

The purpose of this new JsonOutputMode is to generate JSON strings that can be directly pasted into the MongoDB shell. Itis now the default JsonOutputMode.

GuidRepresentation and UuidStandard or UuidLegacy BsonBinarySubTypes

In the past, three drivers have supported UUIDs: C#, Java and Python. All threehave used BSON binary sub type 3 to storeUUIDs, but unfortunately they have all used different byte orders to store the U


2/10

UID, making sharing UUID data between thedrivers and the MongoDB shell difficult. In the future all drivers will standardize on network byte order for UUIDs, anda new binary sub type 4 will be used for these UUIDs. Binary sub type 3 will indicate that the UUID is stored in a driverdependent byte order. Eventually binary sub type 3 will be deprecated.

This version of the C# driver defaults to GuidRepresentation CSharpLegacy, whichmeans that unless you take someaction it will continue to behave exactly like the previous version. Note that the driver allows you to configure theGuidRepresentation at the server, database and collection level. The lowest level at which it can be configured is thecollection, which means that all UUIDs in the same collection must be stored using the same representation. This may soundlike a limitation, but it actually should help keep things from getting too confusing. If you absolutely must write codethat handles a mix of UUID representations in the same collection configure theGuidRepresentation to Unspecified and useBsonDocuments instead of POCOs, and work directly at the level of BsonBinaryDatainstances.

Note: make sure that whatever you set the GuidRepresentation to matches what isactually stored in the collection. If

you want to change the GuidRepresentation for a collection the existing data must be converted as well. We will be providingan offline utility for converting GUIDs between the various representations.

Breaking changesMany error messages changed slightly (only breaking if you were relying on t

he text of the error message)Some methods throw a different exception (only breaking if you were catching

them)BsonReader ReadDateTime return type changedBsonWriter WriteDateTime parameter type changedIBsonSerializable interface changedIBsonSerializer interface changed

IIdGenerator interface changedSeveral properties of MongoServer removedUpdate builder Rename return type changed

BSON Library changes--------------------

BsonBaseReader.csReadDateTime returns long instead of DateTimeAdded ReadName method

BsonBaseWriter.csAdded overloads of WriteBinaryData that take a guidRepresentation parameterWriteDateTime value parameter is now a long instead of a DateTime

BsonBinaryReader.csAdded GuidRepresentation propertyReadDateTime returns long instead of DateTime

BsonBinaryReaderSettings.csAdded GuidRepresentation property


3/10

BsonBinaryWriter.csAdded GuidRepresentation propertyWriteBinaryData now takes a guidRepresentation parameterWriteDateTime value parameter is now a long instead of a DateTime

BsonBinaryWriterSettings.csAdded GuidRepresentation property

BsonBuffer.csLoadFrom now throws an EndOfStreamException instead of hanging when server c

loses socket

BsonDocumentReader.csAdded settings fieldAdded GuidRepresentation propertyReadDateTime returns long instead of DateTime

BsonDocumentReaderSettings.csNew classAdded GuidRepresentation property

BsonDocumentWriter.csAdded settings field

Added GuidRepresentation propertyWriteBinaryData now takes a guidRepresentation parameterWriteDateTime value parameter is now a long instead of a DateTime

BsonDocumentWriterSettings.csNew classAdded GuidRepresentation property

BsonReader.csAdded GuidRepresentation propertyAdded some new Create overloadsReadDateTime returns long instead of DateTimeAdded ReadName method

BsonWriter.csAdded GuidRepresentation propertyAdded some new Create overloadsAdded overloads of WriteBinaryData that take a guidRepresentation parameterWriteDateTime value parameter is now a long instead of a DateTime

ContextType.csClass is now public

JsonOutputMode.cs

Added new Shell value (shell output mode is now the default for ToJson)

JsonReader.csAdded new settings fieldAdded GuidRepresentation propertyAdded support for double constants positive and negative Infinity, NaNAdded support for BinData constants (with or without "new" keyword)Added support for Date constants (with or without "new" keyword)Added support for ISODate constants (with or without "new" keyword)Added support for NumberLong constants (with or without "new" keyword)Added support for ObjectId constants (with or without "new" keyword)


4/10

ReadDateTime returns long instead of DateTimeJsonReaderSettings.cs

New classAdded GuidRepresentation property

JsonScanner.csAdded support for left and right parenthesis (required for "new" keyword)Added support for single quoted strings (in addition to existing support for

double quoted strings)

JsonToken.csAdded new LeftParen and RightParen values to JsonTokenType enumChanged type of value field of DateTimeJsonToken from DateTime to BsonDateTi

me

JsonWriter.csAdded support for new Shell JsonOutputMode (so named because output can be p

asted into mongo shell)Added GuidRepresentation propertyWriteBinaryData now takes a guidRepresentation parameterWriteBinaryData now supports BinData constant in Shell output modeWriteDateTime value parameter is now a long instead of a DateTimeWriteDateTime now supports ISODate constant in Shell output mode

WriteDouble now always outputs decimal point so doubles can be identified visuallyWriteInt64 now supports NumberLong constant in Shell output modeWriteRegularExpression now escapes empty pattern and special characters

JsonWriterSettings.csAdded GuidRepresentation propertyDefault JsonOutputMode is now Shell

BsonArray.csAdded ToList method

BsonBinaryData.cs

Added GuidRepresentation property (only relevant if subType is UuidStandardor UuidLegacy)Added new constructors and Create methodsAdded ToGuid overload that allows GuidRepresentation to be specified

BsonBinarySubType.csSubType 3 is now called UuidLegacySubType 4 is new and is called UuidStandard

BsonDateTime.csNow supports full range of valid BsonDateTime values (not just range of Date

Time)Added new constructors and Create methods

Added IsValidDateTime propertyAdded MillisecondsSinceEpoch propertyValue now throws an exception if IsValidDateTime is false

BsonDocument.csChanged constructors with Hashtable to IDictionaryAdded Parse method to parse BsonDocument from JSON stringChanged Add methods with Hashtable to IDictionaryAdded ToString method (calls ToJson)


5/10

BsonDocumentWrapper.csAdded non-generic Create methodAdded non-generic CreateMultiple method

BsonRegularExpression.csConstructor now unescapes empty pattern and special charactersConstructor now maps .NET options to new server options (i, m, x and s)ToRegex now maps new server options (i, m, x and s) to .NET optionsToString escapes special characters

BsonTimestamp.csRawValue property now returns null

BsonTypeMapper.csAdded support for custom type mappersAdded support for mappping IDictionary valuesAdded RegisterCustomTypeMapper methodTryMapToBsonValue returns false instead of throwing exception when value is

null

BsonValue.csAdded AsBsonDateTime propertyAdded IsBsonDateTime propertyIsDateTime only returns true if IsValidDateTime also returns true

IsGuid now returns true for UuidStandard or UuidLegacyReadFrom uses GuidRepresentation of reader when a UuidLegacy value is readWriteTo converts UuidLegacy value to GuidRepresentation of writer (if not Un

specified)

GuidConvert.csNew helper class that converts to and from the various GuidRepresentationsAdded FromBytes methodAdded ToBytes method

GuidRepresentation.csNew enum that represents the various representations for GuidsValues are: Unspecified, Standard, CSharpLegacy, JavaLegacy and PythonLegacy

ICustomBsonTypeMapper.csNew interface implemented by custom type mappers that can be registered with

the BsonTypeMapperAdded TryMapToBsonValue method

DiscriminatorConventions.csGetActualType now calls EnsureKnownTypesAreRegisteredGetActualType is optimized to not check input for discriminator when not req

uired

IdGenerators.csAdded new BsonObjectIdGenerator (similar to existing ObjectIdGenerator)

Refactored GenerateId method of CombGuidGeneratorGenerateId methods now take container and document parameters

BsonPrimitiveSerializers.csMoved ToLocalTimeHelper and ToUniversalTimeHelper to BsonUtils.csGuidSerializer Deserialize uses GuidRepresentation of bsonReaderGuidSerializer Serialize uses GuidRepresentation of bsonWriter

BsonValueSerializers.csBsonBinaryDataSerializer Deserialize uses GuidRepresentation of bsonReader


6/10

BsonBinaryDataSerializer Serialize uses GuidRepresentation of bsonWriterBsonDateTimeSerializer no longer delegates to DateTimeSerializer

DictionaryGenericSerializer.csDictionarySerializer Serialize now uses TKey and TValue as nominal types so

"_t" discriminator is no longer written when not needed

NetPrimitiveSerializers.csAdded IPAddressSerializerAdded IPEndPointSerialzier

BsonClassMap.csUses BsonSerializer.ConfigLock instead of staticLock to prevent deadlocksAdded IsClassMapRegistered methodAutoMapMember now supports ShouldSerializeXyz methods

BsonClassMapSerializer.csDeserialize has better error message when attempt is made to deserialize a s

truct (which is not supported)SetDocumentId has better error message when attempt is made to use it with a

struct (which is not supported)SerializeMember now calls ShouldSerializeXyz if it exists

BsonDefaultSerializer.cs

Uses BsonSerializer.ConfigLock instead of staticLock to prevent deadlocksAdded IsTypeDiscriminated methodLookupActualType now calls EnsureKnownTypesAreRegistered first

BsonMemberMap.csAdded ShouldSerializeMethod propertyAdded SetShouldSerializeMethod method

BsonSerializer.csUses BsonSerializer.ConfigLock instead of staticLock to prevent deadlocksAdded UseNullIdChecker propertyAdded UseZeroIdChecker propertyLookupIdGenerator no longer uses NullIdChecker or ZeroIdChecker unless told

to do so

IBsonSerializable.csGetDocumentId now has out idNominalType parameter

IBsonSerializer.csGetDocumentId now has out idNominalType parameter

IIdGenerator.csGenerateId now has container and document parameters

BsonDefaults.csAdded GuidRepresentation property

BsonExtensionMethods.csAdded non-generic overloads of ToBsonAdded non-generic overloads of ToBsonDocumentAdded non-generic overloads to ToJson

BsonUtils.csAdded ToDateTimeFromMillisecondsSinceEpoch methodAdded ToLocalTime methodAdded ToMillisecondsSinceEpoch method


7/10

Added ToUniversalTime method

Driver changes--------------

MapReduceOptionsBuilder.csAdded new overload of Replace that takes databaseName parameterAdded new overload of Merge that takes databaseName parameterAdded new overload of Reduce that takes databaseName parameter

QueryBuilder.csType of queries parameter to And method changed to IMongoQuery[]And method ignores any elements of the queries array that are nullType of query parameter to ElemMatch method changed to IMongoQueryAdded new Nor methodType of queries parameter to Or method changed to IMongoQuery[]Or method ignores any elements of the queries array that are nullType of size parameter to Size method changed to int (was already int in Que

ry, changed in QueryBuilder)

UpdateBuilder.csReturn type of Rename method changed to UpdateBuiler (so Renames can now be

chained)Added non-generic overload of Replace method

GeoNearResult.csGeoNearResult and related classes refactored to be PowerShell friendlyNew non-generic abstract base classes introduced (GeoNearResult, GeoNearHit)Changes should not break existing code

MapReduceResult.csCollectionName now handles compound result element { db : ..., collection :

... }Added DatabaseName propertyAdded non-generic overload of GetInlineResultsAs

GetResults now handles output collections sent to a different databaseAdded non-generic overload of GetResultsAsGetResultsAs not handles output collections sent to a different database

ValidateCollectionResult.csNow works with either old string format result or new document format resultAdded DataSize propertyAdded DeletedCount propertyAdded DeletedSize propertyAdded Errors propertyAdded ExtentCount propertyAdded FirstExtent propertyAdded FirstExtentDetails property

Added IndexCount propertyAdded IsValid propertyAdded KeysPerIndex propertyAdded LastExtent propertyAdded LastExtentSize propertyAdded Padding propertyAdded RecordCount propertyAdded Warning propertyAdded ExtentDetails nested class


8/10

CollectionOptionsDocument.csCommandDocument.csFieldsDocument.csGeoNearOptionsDocument.csGroupByDocument.csIndexKeysDocument.csIndexOptionsDocument.csMapReduceOptionsDocument.csQueryDocument.csScopeDocument.csSortByDocument.csUpdateDocument.cs

Added constructors with IDictionary parameter

UpdateWrapper.csRemoved constructor that was missing nominalType parameterAdded nominalType parameter to non-generic overload of Create

MongoCollection.csDrop now returns a CommandResult instead of voidAdded non-generic overload of FindAllAsFindAndModify no longer throws an exception if there is no matching documentFindAndRemove no longer throws an exception if there is no matching documentAdded non-generic version of FindAs

Added non-generic versions of FindOneAsAdded non-generic version of FindOneByIdAsAdded non-generic versions of GeoNearAsAdded non-generic versions of Insert and InsertBatchAdded non-generic versions of SaveSave now works with compound _id valuesSave now supports generating new _id values for strings represented external

ly as ObjectIdAdded Insert methods to MongoCollection

MongoCollectionSettings.csAdded GuidRepresentation property

MongoConnectionStringBuilder.csAdded GuidRepresentation property

MongoCursor.csMongoCursor is now a non-generic abstract base classMongoCursor now derives from MongoCursorAdded SerializationOptions propertyAdded SetSerializationOptions method

MongoCursorEnumerator.cs

class is now publicconnection is now returned to connection pool between calls to GetMoreadded support for tailable cursors

Added IsDead propertyAdded IsServerAwaitCapable property

MongoDatabase.csonly force commands to primary when connected to a replica setAdded new overload of AddUser that takes a MongoUser parameterAdded new overload of CreateConnection that takes only collection name param

eterAdded non-generic version of CreateCollectionSettingsDropCollection no longer throws an exception if the collection doesn't exist


9/10

Added support for nolock to EvalAdded non-generic overload of FetchDBRefAsAdded FindAllUsers methodAdded FindUser methodAdded non-generic overloads of GetCollectionAdded new overload of RemoveUser method that takes a MongoUser parameterAdded non-generic overloads of RunCommandAs

MongoDatabaseSettings.csAdded GuidRepresentation property

MongoServer.csnow uses new MongoServerInstance class to track server(s) it is connected toConnectionPool property moved to MongoServerInstanceMaxDocumentSize and MaxMessageLength moved to MongoServerInstanceEndPoints property removedReplicaSet property removedSecondaryConnectionPools property removedAdded MaxServerCount propertyAdded ServerCount propertyCreate method now throws exception if more than MaxServerCount instances are

createdAdded UnregisterServer methodAdded Arbiters property

Added BuildInfo property (delegates to primary MongoServerInstance)Added Instance and Instances propertyAdded Passives propertyAdded Primary propertyAdded ReplicaSetName propertyAdded Secondaries propertyConnect now returns as soon as primary is found when connecting to a replica

set (without waiting for all secondaries to respond)Added non-generic overload of FetchDBRefAsAdded Ping methodAdded non-generic overloads of RunAdminCommandAsAdded Shutdown method

MongoServerAddress.csComparison of host names is now case insensitive

MongoServerBuildInfo.csnew classAdded Bits property (returns 32 or 64)Added GitVersion property (the git commit Id)Added SysInfo propertyAdded Version propertyAdded VersionString property

MongoServerInstances.csnew class

Added Address propertyAdded BuildInfo propertyAdded ConnectException propertyAdded ConnectionPool propertyAdded EndPoint propertyAdded IsArbiter propertyAdded IsPassive propertyAdded IsPrimary propertyAdded IsSecondary propertyAdded MaxDocumentSize property


10/10

Added MaxMessageLength propertyAdded State property

MongoServerSettings.csAdded GuidRepresentation property

MongoUrl.csAdded GuidRepresentation property

MongoUrlBuilder.csAdded GuidRepresentation propertySetting ReplicaSetName implies ReplicaSet ConnectionModeSetting Servers seed list to more than one server implies ReplicaSet Connect

ionModeNow supports escaping special characters in username in password (using URL

escape rules)

MongoUser.csnew classAdded Username propertyAdded PasswordHash propertyAdded IsReadOnly property

MongoGridFS.cs

Download method now verifies the MD5 hashFind and FindAll methods now return a real MongoCursor, so cursor methods like SetSkip and SetLimit can be used

Upload method now verifies the MD5 hash

MongoGridFSStream.csAdded UpdateMD5 property (useful when file is updated many times and you wan

t to do MD5 calculation just once at the end)Fixed a bug that resulted in metadata not being properly set when file was c

reated

MongoDefaults.csAdded GuidRepresentation property (it's an alias for the same property in Bs

onDefaults)Added MaxDocumentSize (it's an alias for the same property in BsonDefaults)