DOCSP-49078: Extended JSON (#619)

Author: mcmorisi

source/data-formats/extended-json.txt

@@ -8,4 +8,84 @@ Extended JSON
    :local:
    :backlinks: none
    :depth: 2
-   :class: singlecol
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+ 
+.. meta::
+   :keywords: code examples, bson, relaxed, canonical, legacy
+
+.. sharedinclude:: dbx/extended-json.rst
+
+   .. replacement:: driver-specific-text-relaxed
+
+      The {+driver-short+} uses Relaxed mode by default.
+
+
+Read Extended JSON
+------------------
+
+You can read an Extended JSON documents into a {+language+} object by using the
+``BsonSerializer.Deserialize<T>()`` method. The following example reads an
+Extended JSON document into a ``BsonDocument`` object:
+
+.. io-code-block::
+
+   .. input:: /includes/fundamentals/code-examples/ExtendedJson.cs
+      :language: csharp
+      :start-after: start-read-ejson
+      :end-before: end-read-ejson
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      { "_id" : { "$oid" : "573a1391f29313caabcd9637" }, "createdAt" : { "$date" : "1970-01-19T12:51:39.609Z" }, "numViews" : 36520312 }
+
+Write Extended JSON
+-------------------
+
+You can write an Extended JSON string by calling the ``ToJson()`` method on a
+``BsonDocument`` object or custom class. You must specify a ``JsonWriterSettings`` object
+with the ``OutputMode`` property set to the desired Extended JSON format as a parameter.
+
+Consider the following custom class:
+
+.. literalinclude:: /includes/fundamentals/code-examples/ExtendedJson.cs
+   :language: csharp
+   :start-after: start-custom-class
+   :end-before: end-custom-class
+
+The following example outputs an instance of ``MyDocument`` in
+Extended JSON format by specifying the ``CanonicalExtendedJson`` value as an ``OutputMode``
+property:
+
+.. io-code-block::
+
+   .. input:: /includes/fundamentals/code-examples/ExtendedJson.cs
+      :language: csharp
+      :start-after: start-write-ejson
+      :end-before: end-write-ejson
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      { "_id" : { "$oid" : "68094769744af81f368ff1c1" }, "CreatedAt" : { "$date" : { "$numberLong" : "1745438569994" } }, "NumViews" : { "$numberLong" : "1234567890" } }
+
+API Documentation
+-----------------
+
+To learn more about the methods and classes used on this page, see the following API
+documentation:
+
+- `BsonDocument <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonDocument.html>`__
+- `BsonSerializer <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.BsonSerializer.html>`__
+- `ToJson() <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonExtensionMethods.ToJson.html>`__
+- `JsonWriter <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.IO.JsonWriter.html>`__
+- `JsonReader <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.IO.JsonReader.html>`__
+- `JsonWriterSettings <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.IO.JsonWriterSettings.html>`__
+- `JsonReaderSettings <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.IO.JsonReaderSettings.html>`__
+- `JsonOutputMode <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.IO.JsonOutputMode.html>`__

source/includes/fundamentals/code-examples/ExtendedJson.cs

@@ -0,0 +1,42 @@
+using MongoDB.Bson;
+using MongoDB.Bson.IO;
+using MongoDB.Bson.Serialization;
+
+public class ExtendedJson
+{
+    public static void Main(string[] args)
+    {
+        {
+            // start-read-ejson
+            var ejson = "{\n\"_id\": { \"$oid\": \"573a1391f29313caabcd9637\" },\n  \"createdAt\": { \"$date\": { \"$numberLong\": \"1601499609\" }},\n\"numViews\": { \"$numberLong\": \"36520312\" }\n}\n\n";
+            
+            var document = BsonSerializer.Deserialize<BsonDocument>(ejson);
+            Console.WriteLine(document.ToJson());
+            // end-read-ejson
+        }
+
+        {
+            // start-write-ejson
+            var document = new MyDocument();
+            document.Id = ObjectId.GenerateNewId();
+            document.CreatedAt = DateTime.UtcNow;
+            document.NumViews = 1234567890;
+            
+            var json = document.ToJson(new JsonWriterSettings
+            {
+                OutputMode = JsonOutputMode.CanonicalExtendedJson
+            });
+            Console.WriteLine(json);
+            // end-write-ejson
+        }
+    }
+}
+
+// start-custom-class
+public class MyDocument
+{
+    public ObjectId Id { get; set; }
+    public DateTime CreatedAt { get; set; }
+    public long NumViews { get; set; }
+}
+// end-custom-class