[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 is a breaking change. It is mentioned in "Change Log v1.4.1-Bson.txt": Thus, when I call it with `int`, as I used to, then I get the exception: The method `SetDocumentId(object id)` is confusing now. It accepts `object id` but internally does: 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:
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. |