System.Text.Json default DateTimeZoneHandling

[btecu]

In JSON.NET you can:

JsonConvert.DefaultSettings = () => new JsonSerializerSettings {
    DateTimeZoneHandling = DateTimeZoneHandling.Utc
};

Is there anything similar in System.Text.Json?
If there is not an option to set the default, can it be passed in manually?

Also, what is the default (Local, Utc, Unspecified)?

[steveharter]

cc @layomia on dates

Since a DateTime can be set in each of those formats (e.g. with and without the timezone\offset), the reader\writer (and thus the serializer) uses what is available and uses\assumes an ISO 8601 format to represent that.

[layomia]

@btecu the ISO 8601 profile is used by default in the serializer, e.g. 2019-07-26T16:59:57-05:00.

For deserializing, if the datetime offset is given as "hh:mm", a DateTime with DateTimeKind.Local is created. "Z" will give DateTimeKind.Utc. If no offset is given, then a DateTime with DateTimeKind.Unspecified is created.
The reverse mapping applies to serialization: writing a DateTime with DateTimeKind.Local will yield an ISO representation with an "hh:mm"-formatted offset, and so on.

For more on DateTime and DateTimeOffset support in System.Text.Json, and how you can implement custom parsing or formatting, see https://docs.microsoft.com/en-us/dotnet/standard/datetime/system-text-json-support.

[mpashkovskiy]

@btecu unfortunately the only way, I think, to have the similar option in System.Text.Json is to do:

services.AddControllers()
    .AddJsonOptions(options =>
     {
         options.JsonSerializerOptions.Converters.Add(new DateTimeConverter());
     });

and implement DateTimeConverter like that

public class DateTimeConverter : JsonConverter<DateTime>
{
    public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return DateTime.Parse(reader.GetString());
    }

    public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
    {
         writer.WriteStringValue(value.ToUniversalTime().ToString("yyyy'-'MM'-'dd'T'HH':'mm':'ssZ"));
    }
}

[dalle]

This extends @mpashkovskiy solution and relies on the functionality in Utf8JsonReader/Utf8JsonWriter for actual parsing/formatting.

public class DateTimeConverter : JsonConverter<DateTime>
{
    public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return reader.GetDateTime().ToUniversalTime();
    }

    public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
    {
         writer.WriteStringValue(value.ToUniversalTime());
    }
}

[danilobreda]

This solution should come natively so that we have the best possible performance. JsonConverter creates problems when poorly implemented.
Sometimes we can't control which Kind of datetime because of its origin being an ORM for example ... needing a .ToUniversalTime() just to satisfy json deserealization by adding a +00:00 or "Z"
This solution should be reviewed. :(

[amay5027]

Just adding to @mpashkovskiy solution, you could use the SpecifyKind method in .Net to do this as follows:

    public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return DateTime.Parse(reader.GetString());
    }

    public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(DateTime.SpecifyKind(value, DateTimeKind.Utc));
    }

[maulik-modi]

@davidfowl and @JamesNK , what do you guys recommend here? We are building up new project using System.Text.json, want to ensure we use the right guidance and get benefit from system.text.json.

[ysbakker]

Just adding to @mpashkovskiy solution, you could use the SpecifyKind method in .Net to do this as follows:

    public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return DateTime.Parse(reader.GetString());
    }

    public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(DateTime.SpecifyKind(value, DateTimeKind.Utc));
    }

Exactly what I was looking for! I save all DateTime as UTC in the database because I have different timezones in development and production. I then parse the UTC time to local time in the client, but by default the json serializer didn't append a "Z" so I had to do some ugly string concatenation to make it work. This solves that issue by specifying that the date is already in UTC and will therefore return a nice ISO string that javascript also understands. The issue with using DateTime.ToUniversalTime() in my case is that it assumes I save the timestamps in my local timezone.

[maulik-modi]

@ysbakker , javascript is not sending string ending with "Z"?

[ysbakker]

@ysbakker , javascript is not sending string ending with "Z"?

Date.prototype.toISOString() creates an ISO-compliant string, so this includes a "Z". You can try (new Date()).toISOString(), it should automatically convert to UTC too.

[xenod]

Is there still no built in feature for forcing deserializer to add 'Z' to the end? I also need this feature.

We used this in Json.NET:

jsonSerializerSettings.DateTimeZoneHandling = DateTimeZoneHandling.Utc; //Make sure that Json dates are formatted with a 'Z' on the end! jsonSerializerSettings.DateFormatHandling = DateFormatHandling.IsoDateFormat;

[backnotprop]

public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
return DateTime.Parse(reader.GetString());
}

public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
{
    writer.WriteStringValue(DateTime.SpecifyKind(value, DateTimeKind.Utc));
}

Same, except it was @dalle's solution that worked for me. This has been a world of pain for a globally distributed system.

[maulik-modi]

@backnotprop , @dalle , @amay5027 and @davidfowl ,

We decided not to use JsonConverter and instead pass DateTime as string for two reasons:

1. We want to provide friendly message in case date time format is incorrect, we expect ISO8601 format for all incoming datetime inputs
2. return DateTime.Parse(reader.GetString()); provides datetime in local timezone, we instead store UTC DateTime

Our solution was to wrap in an extension method:

static class DateTimeExtensions
{
const string ISO8601DateTimeSecondsFormat = "yyyy-MM-ddTHH:mm:ssZ";
public static DateTime? ToDateTime(this string eventDateTime)
{
if(DateTime.TryParseExact(eventDateTime, ISO8601DateTimeSecondsFormat,
                                             CultureInfo.InvariantCulture,
                                             DateTimeStyles.RoundtripKind,
                                             out DateTime dateTimeWithSeconds))
  return dateTimeWithSeconds;
else
 return null;
}

Your thoughts?

[killerwife]

Also stumbled upon this issue, since every other system expects and ISO string in json. This does sound like an unnecessary hack.

[maulik-modi]

@rbhanda , Do we have an option to set this globally like Json.NET in .NET 6 ? Can you add it to backlog of .NET 7 otherwise?

JsonConvert.DefaultSettings = () => new JsonSerializerSettings {
    DateTimeZoneHandling = DateTimeZoneHandling.Utc
};

[seekingtheoptimal]

In almost every typical client-server web system the server uses and stores dates in UTC (default behavior for SQL DateTime mapping with EF Core for example), while browsers should show the local timezone as users are from all around the internet. Having this feature in a similar fashion to json.net - even if not making it the default behavior to break things - would just make a lot of sense.

[eiriktsarpalis]

@amay5027 Note that the DateTime.SpecifyKind method does not convert the date to the new kind, it will simply swap the DateTimeKind and keep the same ticks value, which is not what most users would expect (it's certainly not how DateTimeZoneHandling works in Json.NET). I would recommend using the workaround as proposed in #1566 (comment) instead.

This solution should come natively so that we have the best possible performance. JsonConverter creates problems when poorly implemented.

@danilobreda what are the performance issues you are identified with the proposed workarounds? It would seem to me that the solution proposed in #1566 (comment) would be as fast as a native feature.

Also stumbled upon this issue, since every other system expects and ISO string in json. This does sound like an unnecessary hack.

@killerwife the default DateTime serialization uses ISO 8601. I believe the ask here is whether we should introduce a feature that automatically converts the TZ offsets on the serialization layer.

[danilobreda]

@eiriktsarpalis I won't know what the performance issues are, and that's the idea. Using a solution that comes natively doesn't bring that kind of questioning.
This was already solved by newtonsoft, a configuration should exist for which way the conversion should take place. For UTC Always, or use Kind of property (default). #1566 (comment)

[eiriktsarpalis]

I won't know what the performance issues are, and that's the idea. Using a solution that comes natively doesn't bring that kind of questioning.

I personally wouldn't agree with this line of thinking. Ultimately not every requested feature will find its way as an OOTB feature (or it may take multiple releases before it does). As such I wholeheartedly encourage building successful third-party extension libraries (there are quite a few quality ones already out there). As a maintainer I would prioritize addressing extensibility concerns in the core infrastructure over complete feature parity with other offerings.

Bottom line in this case, I would argue that the custom converter proposed here as a workaround would be just as fast (and likely faster) than a configurable built-in converter.

This was already solved by newtonsoft, a configuration should exist for which way the conversion should take place. For UTC Always, or use Kind of property (default).

I believe that the Newtonsoft offering might simply reflect the fact that earlier versions of the library didn't use ISO 8601 when serializing dates. This has been the only supported format in STJ from day 1, and as such any TZ information is always accurately represented in the underlying JSON.

I guess I'm trying to better understand the motivating use cases, and I can only think of the following:

1. The application uses DateTime instead of DateTimeOffset when representing dates, resulting in bugs when comparing dates of different kinds.
2. The application uses DateTime.Now instead of DateTime.UtcNow and the host TZ itself is not UTC, resulting in local TZ offsets leaking in server responses.

Am I forgetting something?

[danilobreda]

@eiriktsarpalis Applications that used JSON.NET with DateTimeZoneHandling = DateTimeZoneHandling.Utc and migrated to System.Text.Json.

[AndiRudi]

This is a really annoying thing when you want to upgrade to .net 6 because the default de-serialiser of a view model will add the timezone given by the frontend. If you forward this to a Postgres database you will get an error like Cannot write DateTimeOffset with Offset=02:00:00 to PostgreSQL type .... Or am I missing something?

[eithe]

Edit: Please do not use this, see replies from @eiriktsarpalis and @OskarKlintrot below.

For anyone who uses DateTime?, here is a nullable variant of @dalle's solution:

public class NullableDateTimeConverter : JsonConverter<DateTime?>
{
    public override DateTime? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return reader.TryGetDateTime(out var value) ? value.ToUniversalTime() : null;
    }

    public override void Write(Utf8JsonWriter writer, DateTime? value, JsonSerializerOptions options)
    {
        if (value.HasValue)
        {
            writer.WriteStringValue(value.Value.ToUniversalTime());
        }
        else
        {
            writer.WriteNullValue();
        }
    }
}

[eiriktsarpalis]

For anyone who uses DateTime?

Writing dedicated converters for nullable types is not recommended. Authoring a custom converter for the underlying struct should suffice, the generic nullable converter will compose with that.

[OskarKlintrot]

And you can access the other converters from inside your converter (to avoid doing the convertion yourself if there's already a perfectly good converter at your disposal once you done with type checks or whatever you want to do):

options.GetConverter(typeof(DateTime))

[eithe]

Thanks @eiriktsarpalis and @OskarKlintrot, will edit.

[HarelM]

Would be great to have some build it converter in .Net for these kind of scenarios.
I'm trying to migrate my project from Newtonsoft.JSON to system.text.json and a lot of places are failing, some related to this, some related to other issues.
I don't want to write a generic datetime converter that can parse a date well.
I have an external API that is written in python that has a date of the format: 2021-08-30 23:26:46 for example. Previously it just worked.
When I migrated to STJ this started failing. While I get the performance advantages of assuming everything is ISO, I still think there should be an easy way to say: "hey, converter, this date isn't well formatted, but let's make sure you are able to parse it" without writing a converter that was already written hundreds of times...

[Astral100]

If the goal is to get pure local time (by stripping timezone part from the datetime), then one solution I found is to change the contract of the received object properties to DateTimeOffset as described here (in EDIT2 part): https://stackoverflow.com/questions/78450474/how-to-strip-off-timezone-part-from-datetime-to-leave-only-local-datetime-part/78450521?noredirect=1#comment138306952_78450521

And then you could use .DateTime on the DateTimeOffset property.

[jgador]

Hi @dalle

Thank you for the solution above! It's almost there, but I noticed one subtle issue. When calling reader.GetDateTime(), the DateTimeKind is set to Unspecified if the input doesn't contain time zone information. The code converts the date time to UTC even though the original time zone is unknown. What we want is to treat the time as UTC when time zone information is present. If the DateTimeKind is not provided, we assume the value is already in UTC.

Here's my proposed solution to handle this correctly:

public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
    var date = reader.GetDateTime();

    return date.Kind == DateTimeKind.Utc
        ? date
        : DateTime.SpecifyKind(date, DateTimeKind.Utc);
}