Use ToUnixTimeMilliseconds (#46036)

Author: gewarren

docs/standard/datetime/system-text-json-support.md

@@ -22,7 +22,7 @@ The `System.Text.Json` library parses and writes <xref:System.DateTime> and <xre
 
 The <xref:System.Text.Json.JsonSerializer>, <xref:System.Text.Json.Utf8JsonReader>, <xref:System.Text.Json.Utf8JsonWriter>,
 and <xref:System.Text.Json.JsonElement> types parse and write <xref:System.DateTime> and <xref:System.DateTimeOffset>
-text representations according to the extended profile of the ISO 8601-1:2019 format. For example, `2019-07-26T16:59:57-05:00`.
+text representations according to the extended profile of the ISO 8601-1:2019 format, for example, `2019-07-26T16:59:57-05:00`.
 
 <xref:System.DateTime> and <xref:System.DateTimeOffset> data can be serialized with <xref:System.Text.Json.JsonSerializer>:
 
@@ -32,18 +32,16 @@ text representations according to the extended profile of the ISO 8601-1:2019 fo
 
 :::code language="csharp" source="snippets/system-text-json-support/csharp/deserializing-with-jsonserializer-valid/Program.cs":::
 
-With default options, input <xref:System.DateTime> and <xref:System.DateTimeOffset> text representations must conform to the extended ISO 8601-1:2019 profile.
-Attempting to deserialize representations that don't conform to the profile will cause <xref:System.Text.Json.JsonSerializer> to throw a <xref:System.Text.Json.JsonException>:
+With default options, input <xref:System.DateTime> and <xref:System.DateTimeOffset> text representations must conform to the extended ISO 8601-1:2019 profile. If you attempt to deserialize representations that don't conform to the profile, <xref:System.Text.Json.JsonSerializer> throws a <xref:System.Text.Json.JsonException>:
 
 :::code language="csharp" source="snippets/system-text-json-support/csharp/deserializing-with-jsonserializer-error/Program.cs":::
 
-The <xref:System.Text.Json.JsonDocument> provides structured access to the contents of a JSON payload, including <xref:System.DateTime>
-and <xref:System.DateTimeOffset> representations. The following example shows how to calculate the average
+<xref:System.Text.Json.JsonDocument> provides structured access to the contents of a JSON payload, including <xref:System.DateTime> and <xref:System.DateTimeOffset> representations. The following example shows how to calculate the average
 temperature on Mondays from a collection of temperatures:
 
 :::code language="csharp" source="snippets/system-text-json-support/csharp/computing-with-jsondocument-valid/Program.cs":::
 
-Attempting to compute the average temperature given a payload with non-compliant <xref:System.DateTime> representations will cause <xref:System.Text.Json.JsonDocument> to throw a <xref:System.FormatException>:
+If you attempt to compute the average temperature given a payload with non-compliant <xref:System.DateTime> representations, <xref:System.Text.Json.JsonDocument> throws a <xref:System.FormatException>:
 
 :::code language="csharp" source="snippets/system-text-json-support/csharp/computing-with-jsondocument-error/Program.cs":::
 
@@ -55,7 +53,7 @@ The lower level <xref:System.Text.Json.Utf8JsonWriter> writes <xref:System.DateT
 
 :::code language="csharp" source="snippets/system-text-json-support/csharp/reading-with-utf8jsonreader-valid/Program.cs":::
 
-Attempting to read non-compliant formats with <xref:System.Text.Json.Utf8JsonReader> will cause it to throw a <xref:System.FormatException>:
+If you attempt to read non-compliant formats with <xref:System.Text.Json.Utf8JsonReader>, it throws a <xref:System.FormatException>:
 
 :::code language="csharp" source="snippets/system-text-json-support/csharp/reading-with-utf8jsonreader-error/Program.cs":::
 
@@ -67,8 +65,12 @@ Attempting to read non-compliant formats with <xref:System.Text.Json.Utf8JsonRea
 
 ### When using <xref:System.Text.Json.JsonSerializer>
 
-If you want the serializer to perform custom parsing or formatting, you can implement [custom converters](xref:System.Text.Json.Serialization.JsonConverter%601).
-Here are a few examples:
+If you want the serializer to perform custom parsing or formatting, you can implement [custom converters](xref:System.Text.Json.Serialization.JsonConverter%601). The following sections show a few examples:
+
+- [DateTime(Offset).Parse and DateTime(Offset).ToString](#datetimeoffsetparse-and-datetimeoffsettostring)
+- [Utf8Parser and Utf8Formatter](#-and-)
+- [Use DateTime(Offset).Parse as a fallback](#use-datetimeoffsetparse-as-a-fallback)
+- [Use Unix epoch date format](#use-unix-epoch-date-format)
 
 #### DateTime(Offset).Parse and DateTime(Offset).ToString
 
@@ -135,7 +137,7 @@ and then written with the <xref:System.Text.Json.Utf8JsonWriter.WriteStringValue
 ### When using <xref:System.Text.Json.Utf8JsonReader>
 
 If you want to read a custom <xref:System.DateTime> or <xref:System.DateTimeOffset> text representation with <xref:System.Text.Json.Utf8JsonReader>,
-you can get the value of the current JSON token as a <xref:System.String> using <xref:System.Text.Json.Utf8JsonReader.GetString> method, then parse the value using custom logic.
+you can get the value of the current JSON token as a <xref:System.String> using the <xref:System.Text.Json.Utf8JsonReader.GetString> method, then parse the value using custom logic.
 
 The following example shows how a custom <xref:System.DateTimeOffset> text representation can be retrieved using the <xref:System.Text.Json.Utf8JsonReader.GetString> method,
 then parsed using <xref:System.DateTimeOffset.ParseExact(System.String,System.String,System.IFormatProvider)>:
@@ -146,24 +148,23 @@ then parsed using <xref:System.DateTimeOffset.ParseExact(System.String,System.St
 
 ### Date and time components
 
-The extended ISO 8601-1:2019 profile implemented in <xref:System.Text.Json?displayProperty=fullName> defines the following components for
-date and time representations. These components are used to define various supported levels of granularity
+The extended ISO 8601-1:2019 profile implemented in <xref:System.Text.Json?displayProperty=fullName> defines the following components for date and time representations. These components are used to define various supported levels of granularity
 when parsing and formatting <xref:System.DateTime> and <xref:System.DateTimeOffset> representations.
 
-| Component       | Format                      | Description                                                                     |
-|-----------------|-----------------------------|---------------------------------------------------------------------------------|
-| Year            | "yyyy"                      | 0001-9999                                                                       |
-| Month           | "MM"                        | 01-12                                                                           |
-| Day             | "dd"                        | 01-28, 01-29, 01-30, 01-31 based on month/year.                                 |
-| Hour            | "HH"                        | 00-23                                                                           |
-| Minute          | "mm"                        | 00-59                                                                           |
-| Second          | "ss"                        | 00-59                                                                           |
-| Second fraction | "FFFFFFF"                   | Minimum of one digit, maximum of 16 digits.                                     |
-| Time offset     | "K"                         | Either "Z" or "('+'/'-')HH':'mm".                                               |
-| Partial time    | "HH':'mm':'ss[FFFFFFF]"     | Time without UTC offset information.                                            |
-| Full date       | "yyyy'-'MM'-'dd"            | Calendar date.                                                                  |
-| Full time       | "'Partial time'K"           | UTC of day or Local time of day with the time offset between local time and UTC.|
-| Date time       | "'Full date''T''Full time'" | Calendar date and time of day, for example, 2019-07-26T16:59:57-05:00.                  |
+| Component       | Format                  | Description                                     |
+|-----------------|-------------------------|-------------------------------------------------|
+| Year            | "yyyy"                  | 0001-9999                                       |
+| Month           | "MM"                    | 01-12                                           |
+| Day             | "dd"                    | 01-28, 01-29, 01-30, 01-31 based on month/year. |
+| Hour            | "HH"                    | 00-23                                           |
+| Minute          | "mm"                    | 00-59                                           |
+| Second          | "ss"                    | 00-59                                           |
+| Second fraction | "FFFFFFF"               | Minimum of one digit, maximum of 16 digits.     |
+| Time offset     | "K"                     | Either "Z" or "('+'/'-')HH':'mm".               |
+| Partial time    | "HH':'mm':'ss[FFFFFFF]" | Time without UTC offset information.            |
+| Full date       | "yyyy'-'MM'-'dd"        | Calendar date.                                  |
+| Full time       | "'Partial time'K"       | UTC of day or Local time of day with the time offset between local time and UTC.|
+| Date time       | "'Full date''T''Full time'" | Calendar date and time of day, for example, 2019-07-26T16:59:57-05:00. |
 
 ### Support for parsing
 

docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md

@@ -23,8 +23,8 @@ The `System.Text.Json` namespace provides functionality for serializing to and d
 * .NET Framework 4.6.2 and later versions
 * .NET Core 2.0, 2.1, and 2.2
 
->[!TIP]
-> You can use AI assistance to [migrate from `Newtonsoft.Json` with GitHub Copilot](#use-github-copilot-to-migrate).
+> [!TIP]
+> You can use AI assistance to [migrate from `Newtonsoft.Json`](#use-github-copilot-to-migrate).
 
 `System.Text.Json` focuses primarily on performance, security, and standards compliance. It has some key differences in default behavior and doesn't aim to have feature parity with `Newtonsoft.Json`. For some scenarios, `System.Text.Json` currently has no built-in functionality, but there are recommended workarounds. For other scenarios, workarounds are impractical.
 
@@ -380,7 +380,7 @@ Starting in .NET 7, you can use the C# `required` modifier or the <xref:System.T
 * The `DateTimeZoneHandling` setting can be used to serialize all `DateTime` values as UTC dates.
 * The `DateFormatString` setting and `DateTime` converters can be used to customize the format of date strings.
 
-<xref:System.Text.Json?displayProperty=fullName> supports ISO 8601-1:2019, including the RFC 3339 profile. This format is widely adopted, unambiguous, and makes round trips precisely. To use any other format, create a custom converter. For example, the following converters serialize and deserialize JSON that uses Unix epoch format with or without a time zone offset (values such as `/Date(1590863400000-0700)/` or `/Date(1590863400000)/`):
+<xref:System.Text.Json> supports ISO 8601-1:2019, including the RFC 3339 profile. This format is widely adopted, unambiguous, and makes round trips precisely. To use any other format, create a custom converter. For example, the following converters serialize and deserialize JSON that uses Unix epoch format with or without a time zone offset (values such as `/Date(1590863400000-0700)/` or `/Date(1590863400000)/`):
 
 :::code language="csharp" source="snippets/how-to-contd/csharp/CustomConverterUnixEpochDate.cs" id="ConverterOnly":::
 

docs/standard/serialization/system-text-json/snippets/how-to-contd/csharp/CopyOptions.cs

@@ -11,7 +11,7 @@ public class Forecast
 
     public class Program
     {
-        public static void Main()
+        public static void Run()
         {
             Forecast forecast = new()
             {

docs/standard/serialization/system-text-json/snippets/how-to-contd/csharp/CustomConverterHandleNull.cs

@@ -31,7 +31,7 @@ public override void Write(
 
     public class Program
     {
-        public static void Main()
+        public static void Run()
         {
             string json = @"{""x"":1,""y"":2,""Description"":null}";
 

docs/standard/serialization/system-text-json/snippets/how-to-contd/csharp/CustomConverterInferredTypesToObject.cs

@@ -35,7 +35,7 @@ public class WeatherForecast
 
     public class Program
     {
-        public static void Main()
+        public static void Run()
         {
             string jsonString = """
                 {

docs/standard/serialization/system-text-json/snippets/how-to-contd/csharp/CustomConverterPreserveReferences.cs

@@ -101,7 +101,7 @@ class MyReferenceHandler : ReferenceHandler
 
     public class Program
     {
-        public static void Main()
+        public static void Run()
         {
             Employee tyler = new()
             {

docs/standard/serialization/system-text-json/snippets/how-to-contd/csharp/CustomConverterUnixEpochDate.cs

@@ -2,29 +2,50 @@
 using System.Text.Json;
 using System.Text.Json.Serialization;
 using System.Text.RegularExpressions;
+using Newtonsoft.Json;
 
 namespace CustomConverterUnixEpochDate
 {
     class Program
     {
-        public static void Main()
+        public static void STJExample(DateTimeOffset date)
         {
             var forecast = new Forecast()
             {
-                Date = DateTimeOffset.Now,
+                Date = date,
                 TemperatureCelsius = 19,
                 Summary = "warm"
             };
 
             var options = new JsonSerializerOptions();
             options.Converters.Add(new UnixEpochDateTimeOffsetConverter());
-            options.WriteIndented = true;
 
-            string json = JsonSerializer.Serialize(forecast, options);
-            Console.WriteLine(json);
+            string json = System.Text.Json.JsonSerializer.Serialize(forecast, options);
+            Console.WriteLine($"System.Text.Json: {json}");
 
-            Forecast forecastDeserialized = JsonSerializer.Deserialize<Forecast>(json, options)!;
-            Console.WriteLine($"Deserialized date = {forecastDeserialized.Date}");
+            Forecast forecastDeserialized = System.Text.Json.JsonSerializer.Deserialize<Forecast>(json, options)!;
+            Console.WriteLine($"System.Text.Json deserialized date = {forecastDeserialized.Date}");
+        }
+
+        public static void NewtonsoftExample(DateTimeOffset date)
+        {
+            var forecast = new Forecast()
+            {
+                Date = date,
+                TemperatureCelsius = 19,
+                Summary = "warm"
+            };
+
+            var settings = new JsonSerializerSettings
+            {
+                DateFormatHandling = DateFormatHandling.MicrosoftDateFormat,
+            };
+
+            string json = JsonConvert.SerializeObject(forecast, settings);
+            Console.WriteLine($"{Environment.NewLine}Newtonsoft: {json}");
+
+            Forecast forecastDeserialized = JsonConvert.DeserializeObject<Forecast>(json, settings)!;
+            Console.WriteLine($"Newtonsoft deserialized date = {forecastDeserialized.Date}");
         }
     }
 
@@ -36,23 +57,28 @@ public class Forecast
     }
 
     // <ConverterOnly>
-    sealed class UnixEpochDateTimeOffsetConverter : JsonConverter<DateTimeOffset>
+    sealed class UnixEpochDateTimeOffsetConverter : System.Text.Json.Serialization.JsonConverter<DateTimeOffset>
     {
         static readonly DateTimeOffset s_epoch = new(1970, 1, 1, 0, 0, 0, TimeSpan.Zero);
-        static readonly Regex s_regex = new("^/Date\\(([+-]*\\d+)([+-])(\\d{2})(\\d{2})\\)/$", RegexOptions.CultureInvariant);
+        static readonly Regex s_regex = new(
+            "^/Date\\(([+-]*\\d+)([+-])(\\d{2})(\\d{2})\\)/$",
+            RegexOptions.CultureInvariant);
 
-        public override DateTimeOffset Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        public override DateTimeOffset Read(
+            ref Utf8JsonReader reader,
+            Type typeToConvert,
+            JsonSerializerOptions options)
         {
             string formatted = reader.GetString()!;
             Match match = s_regex.Match(formatted);
 
             if (
                     !match.Success
-                    || !long.TryParse(match.Groups[1].Value, System.Globalization.NumberStyles.Integer, CultureInfo.InvariantCulture, out long unixTime)
-                    || !int.TryParse(match.Groups[3].Value, System.Globalization.NumberStyles.Integer, CultureInfo.InvariantCulture, out int hours)
-                    || !int.TryParse(match.Groups[4].Value, System.Globalization.NumberStyles.Integer, CultureInfo.InvariantCulture, out int minutes))
+                    || !long.TryParse(match.Groups[1].Value, NumberStyles.Integer, CultureInfo.InvariantCulture, out long unixTime)
+                    || !int.TryParse(match.Groups[3].Value, NumberStyles.Integer, CultureInfo.InvariantCulture, out int hours)
+                    || !int.TryParse(match.Groups[4].Value, NumberStyles.Integer, CultureInfo.InvariantCulture, out int minutes))
             {
-                throw new JsonException();
+                throw new System.Text.Json.JsonException();
             }
 
             int sign = match.Groups[2].Value[0] == '+' ? 1 : -1;
@@ -61,12 +87,18 @@ public override DateTimeOffset Read(ref Utf8JsonReader reader, Type typeToConver
             return s_epoch.AddMilliseconds(unixTime).ToOffset(utcOffset);
         }
 
-        public override void Write(Utf8JsonWriter writer, DateTimeOffset value, JsonSerializerOptions options)
+        public override void Write(
+            Utf8JsonWriter writer,
+            DateTimeOffset value,
+            JsonSerializerOptions options)
         {
-            long unixTime = Convert.ToInt64((value - s_epoch).TotalMilliseconds);
+            long unixTime = value.ToUnixTimeMilliseconds();
+
             TimeSpan utcOffset = value.Offset;
 
-            string formatted = string.Create(CultureInfo.InvariantCulture, $"/Date({unixTime}{(utcOffset >= TimeSpan.Zero ? "+" : "-")}{utcOffset:hhmm})/");
+            string formatted = string.Create(
+                CultureInfo.InvariantCulture,
+                $"/Date({unixTime}{(utcOffset >= TimeSpan.Zero ? "+" : "-")}{utcOffset:hhmm})/");
 
             writer.WriteStringValue(formatted);
         }