[CSHARP-357] Add a way to convert all DateTime values in a BsonDocument to local or universal time Created: 18/Nov/11  Updated: 02/Apr/15  Resolved: 03/Jan/12

Status: Closed
Project: C# Driver
Component/s: None
Affects Version/s: 1.3
Fix Version/s: 1.4

Type: Improvement Priority: Minor - P4
Reporter: Robert Stam Assignee: Robert Stam
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Depends
depends on CSHARP-567 Improvements to BsonDateTime class Closed
Backwards Compatibility: Minor Change

 Description   

When a BsonDocument is read back from the database all DateTime values are in UTC. It would be nice to have a helper method that walked the BsonDocument and converted all DateTime values to LocalTime. For example:

var document = collection.FindOne(); // DateTimes are in UTC
document.ToLocalTime(); // converts any DateTime values found to LocalTime (in place)

While less frequently useful, for symmetry there should probably be a ToUniversalTime method as well.

An alternative to consider is whether there should be a mode (on the collection?) that would cause all DateTimes to be automatically converted to LocalTime without having to call a helper method. Although the helper method is by far simpler to implement.

As an aside, I recommend that you always keep your DateTimes in UTC throughout, and only convert them to LocalTime when displaying them to the user. But I know that many developers prefer to just do a wholesale conversion to LocalTime after reading from the database, so this helper method would be attractive to them.



 Comments   
Comment by Craig Wilson [ 10/Sep/12 ]

Based on this new ticket, we are removing support for the AsLocalTime and AsUniversalTime properties in version 2.0.

Comment by Robert Stam [ 03/Jan/12 ]

See the comments above. BsonDateTime no longer has a DateTime value field, only a millisecondsSinceEpoch field. In addition, instead of providing a way to convert all DateTime values to local (not possible since BsonDateTime is by definition in UTC) we are providing two new properties that let you extract the value as a .NET DateTime in either local or UTC time (see AsLocalTime and AsUniversalTime).

Comment by Robert Stam [ 03/Jan/12 ]

Thanks for the feedback. I agree. And anyway, once I remove the redundant DateTime field there would be no way convert to local time anyway. So the conversion will happen when you access the new ToLocalDateTime propery.

Comment by Craig Wilson [ 03/Jan/12 ]

Sounds good. My opinion here is as follows:

Forget converting the entire document into local vs. utc time. I like your last proposal where you simply have two properties, one for local and one for Universal. The implicit conversion to DataTime should be in utc time. So, if a developer wants local time, they can access the AsLocal property. Otherwise, they get Utc. I think that is sufficient.

Comment by Robert Stam [ 30/Dec/11 ]

I'm actually considering changing the implementation of the BsonDateTime class so that it only has the long millisecondsSinceEpoch field (removing the DateTime value field).

The original rational for having both fields was that a .NET DateTime has higher resolution than a BSON DateTime, and I didn't want to lose the extra resolution prematurely. Once we serialized and deserialized a BsonDateTime it could no longer be helped since the serialized form determines the resolution.

My current thinking is that this is just misleading. Better to lose the resolution the instant you create an instance of BsonDateTime, and avoid creating the illusion that a BsonDateTime might have higher resolution than it actually does.

Another rational for keeping the DateTime around with its higher resolution was that the ultimate serialized resolution might depend on the external format used. While binary BSON might be limited to millisecond resolution, a JSON file where DateTimes were serialized as ISODate string constants could conceivably maintain the full .NET resolution.

Once again, this is misleading, and it is probably better for a BSON DateTime to have the same resolution no matter where it resides, be that in memory, in a binary BSON document or in a text based JSON document.

As for the timezone question, an alternative proposal would be to provide alternative properties that could be used to convert millisecondsSinceEpoch (which by definition is in UTC) to either a local or a UTC DateTime. For example:

var bsonDateTime =  new BsonDateTime(DateTime.UtcNow);
var localTime = bsonDateTime.AsLocalDateTime;
var utcTime = bsonDateTime.AsUniversalDateTime;

Any comments?

Comment by Craig Wilson [ 15/Dec/11 ]

BsonDateTime always represents times in utc. Do you see this change going down to that level to allow for BsonDateTime to have a local vs. utc component?

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