[CSHARP-446] 1.4.1 Breaking change SetDocumentId is not quite documented (or good at all) Created: 18/Apr/12  Updated: 02/Apr/15  Resolved: 22/Apr/12

Status: Closed
Project: C# Driver
Component/s: None
Affects Version/s: 1.4.1
Fix Version/s: 1.4.2

Type: Improvement Priority: Major - P3
Reporter: Roman Kuzmin Assignee: Robert Stam
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

Thank you for the new version.

Release notes:
> There are no breaking changes in this release.

There is a breaking change. It is mentioned in "Change Log v1.4.1-Bson.txt":
BsonDocument.cs
changed SetDocumentId to assume Id is already of type BsonValue

Thus, when I call it with `int`, as I used to, then I get the exception:
Unable to cast object of type 'System.Int32' to type 'MongoDB.Bson.BsonValue'.

The method `SetDocumentId(object id)` is confusing now. It accepts `object id` but internally does:
var idBsonValue = (BsonValue)id;

This is unsafe and even not documented in code comments. Either this method should accept `BsonValue` or it should handle any suitable objects, as it did before.



 Comments   
Comment by Robert Stam [ 22/Apr/12 ]

BsonDocument methods GetDocumentId and SetDocumentId have been changed to be temporarily backward compatible with 1.4.0 and earlier. However, these methods were intended to be private, and all IBsonSerializable methods that were accidentally made public have been marked as deprecated and will be made private by explicit implementation in a future release.

Comment by Robert Stam [ 22/Apr/12 ]

SetDocumentId should have been a private method but leaked out to the public API of BsonDocument because the IBsonSerializable methods were not explicitly implemented.

We did not expect this to be a breaking change because we thought of the SetDocumentId method as being internal. The expected usage of SetDocumentId is that the callers will always pass in an id of the expected type, and in the case of BsonDocument the expected type is a BsonValue (hence the cast to BsonValue). The previous implementation of this method violated that expectation by converting any object type passed to BsonValue (it should have been a BsonValue already).

For 1.4.2 we will revert the behavior of SetDocumentId to be backward compatible with 1.4, but at the same time we are going to mark it as obsolete and in a subsequent release we are going to remove it from the public API.

The best way to set the _id of a BsonDocument is:

document["_id"] = id;

Note that GetDocumentId method also has a breaking change. It now always returns a BsonValue. It also is going to be marked obsolete and removed from the public API in a subsequent release.

Generated at Wed Feb 07 21:36:51 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.