Runtime: Add documentation for date formats in S.T.JSON

[rynowak]

Filing this per @ahsonkhan request

We don't have a good document to point users at for understanding how to use dates with System.Text.Json. JSON.NET was very tolerant in the set of date formats that it would accept, and this will be a common question. There's a lot of existing code out there that works with formats other than ISO 8601.

[ahsonkhan]

cc @layomia

[layomia]

cc @jeremykuhne

[ericstj]

@JeremyKuhne are you working on this one?

[JeremyKuhne]

Yeah, I'll take this.

[ericstj]

We should create a topic document that summarizes the algorithm here:
https://github.com/dotnet/corefx/blob/6cd505d9aaabe656707766dee22e9aec0404568f/src/System.Text.Json/src/System/Text/Json/JsonHelpers.Date.cs#L88-L423

And how this relates to https://github.com/dotnet/docs/blob/ef122199e3f0a37761974e4de5ed9fcd36cd7cbe/docs/standard/base-types/standard-date-and-time-format-strings.md

This probably belongs in its own markdown file in the docs repo. To start lets draft a markdown and open a PR in docs repo in some place like https://github.com/dotnet/docs/tree/master/docs/core, https://github.com/dotnet/docs/tree/master/docs/standard and tag @mairaw to get this hooked up correctly into the doc tree. We should probably reference it from the relevant portions of the API docs.

[ahsonkhan]

The other component of documentation is the workaround for working with non-ISO dates (which involves creating a custom JsonConverter). Including such samples would be quite helpful (particularly in the porting guide), and I vaguely recall @JeremyKuhne had written something up about custom converters to allow other DateTime formats to work.

[ahsonkhan]

With this doc PR merged (https://github.com/dotnet/docs/pull/13526), I believe the work left is to
link the doc from the relevant APIs:

We should probably reference it from the relevant portions of the API docs.

Utf8JsonReader and JsonElement GetDateTime{Offset}, and WriteString{Value}(DateTime{Offset}) APIs are good candidates. For example:

https://docs.microsoft.com/en-us/dotnet/api/system.text.json.utf8jsonreader.getdatetime?view=netcore-3.0#System_Text_Json_Utf8JsonReader_GetDateTime
https://docs.microsoft.com/en-us/dotnet/api/system.text.json.utf8jsonwriter.writestringvalue?view=netcore-3.0#System_Text_Json_Utf8JsonWriter_WriteStringValue_System_DateTimeOffset_

And add reader/writer/document related documentation:
https://github.com/dotnet/docs/pull/13526#discussion_r314139635

[ericstj]

@layomia can this be closed now?

[layomia]

@ericstj I'll close this with https://github.com/dotnet/docs/pull/14056 cc @ahsonkhan.

[ahsonkhan]

Given this issue is about documentation, and we already have a doc published that covers most of the scenarios, moving this to 5.0.
https://docs.microsoft.com/en-us/dotnet/standard/datetime/system-text-json-support

There is just a bit of work left before we can close this issue, which involves closing on the location of the sample:
https://github.com/dotnet/samples/pull/1418
And update the doc accordingly:
https://github.com/dotnet/docs/pull/14056

@layomia - please work with the docs team to close on the pending PRs.

[layomia]

Closing, following the merging of https://github.com/dotnet/samples/pull/1418 and https://github.com/dotnet/docs/pull/14056.