CSHARP-1480: Reference documentation for sync API.

Author: rstam

Docs/reference/content/examples/exporting_json.md

@@ -13,7 +13,7 @@ title = "Exporting JSON"
 
 The .NET BSON library supports writing JSON documents with the [`JsonWriter`]({{< apiref "T_MongoDB_Bson_IO_JsonWriter" >}}) class. 
 
-The program below will export all documents from a collection to a file with one document per line. 
+The programs below will export all documents from a collection to a file with one document per line. There are two versions of the program, one using the synchronous API and the other using the asynchronous API.
 
 Given the collection's contents:
 
@@ -25,7 +25,37 @@ Given the collection's contents:
 { "_id" : ObjectId("551330712dfd32ffd580e326"), "x" : 4.0 }
 ```
 
-And the program:
+And the synchronous version of the program:
+
+```csharp
+using MongoDB.Bson;
+using MongoDB.Bson.IO;
+using MongoDB.Bson.Serialization;
+using MongoDB.Driver;
+
+// ...
+
+string outputFileName; // initialize to the output file
+IMongoCollection<BsonDocument> collection; // initialize to the collection to read from
+
+using (var streamWriter = new StreamWriter(outputFileName))
+{
+    var cursor = collection.Find(new BsonDocument()).ToCursor();
+    foreach (var document in cursor.ToEnumerable())
+    {
+        using (var stringWriter = new StringWriter())
+        using (var jsonWriter = new JsonWriter(stringWriter))
+        {
+            var context = BsonSerializationContext.CreateRoot(jsonWriter);
+            collection.DocumentSerializer.Serialize(context, document);
+            var line = stringWriter.ToString();
+            streamWriter.WriteLine(line);
+        }
+    }
+}
+```
+
+Or the asynchronous version of the program:
 
 ```csharp
 using MongoDB.Bson;

Docs/reference/content/examples/importing_json.md

@@ -13,7 +13,7 @@ title = "Importing JSON"
 
 The .NET BSON library supports reading JSON documents with the [`JsonReader`]({{< apiref "T_MongoDB_Bson_IO_JsonReader" >}}) class. 
 
-The program below will import all documents from a file with one document per line into the collection.
+The programs below will import all documents from a file with one document per line into the collection. There are two versions of the program, one using the synchronous API and the other using the asynchronous API.
 
 Given the input file's contents:
 
@@ -24,7 +24,35 @@ Given the input file's contents:
 { "_id" : ObjectId("551330712dfd32ffd580e326"), "x" : 4.0 }
 ```
 
-And the program:
+And the synchronous version of the program::
+
+```csharp
+using MongoDB.Bson;
+using MongoDB.Bson.IO;
+using MongoDB.Bson.Serialization;
+using MongoDB.Driver;
+
+// ...
+
+string inputFileName; // initialize to the input file
+IMongoCollection<BsonDocument> collection; // initialize to the collection to write to.
+
+using (var streamReader = new StreamReader(inputFileName))
+{
+    string line;
+    while ((line = streamReader.ReadLine()) != null)
+    {
+        using (var jsonReader = new JsonReader(line))
+        {
+            var context = BsonDeserializationContext.CreateRoot(jsonReader);
+            var document = collection.DocumentSerializer.Deserialize(context);
+            collection.InsertOne(document);
+        }
+    }
+}
+```
+
+Or the asynchronous version of the program:
 
 ```csharp
 using MongoDB.Bson;

Docs/reference/content/examples/tailable_cursor.md

@@ -13,15 +13,58 @@ title = "Using a Tailable Cursor"
 
 MongoDB offers the option to watch a [capped collection]({{< docsref "manual/core/capped-collections/" >}}) for changes using a [tailable cursor]({{< docsref "manual/tutorial/create-tailable-cursor/" >}}).
 
-The code below "tails" the capped collection and outputs documents to the console as they are added. The method also handles the possibility of a dead cursor by tracking the field `insertDate`. New documents are added with increasing values of `insertDate`.
+The code below "tails" a capped collection and outputs documents to the console as they are added. The method also handles the possibility of a dead cursor by tracking the field `insertDate`. New documents are added with increasing values of `insertDate`.
 
 {{% note %}}Even though we are using [`BsonDocument`]({{< apiref "T_MongoDB_Bson_BsonDocument" >}}) below, it is possible to use an application defined class by replacing the [`BsonDocument`]({{< apiref "T_MongoDB_Bson_BsonDocument" >}}) references with that of your application defined class.{{% /note %}}
 
+This version of the code uses the synchronous API to tail the capped collection:
+
+```csharp
+private static void TailCollection(IMongoCollection<BsonDocument> collection)
+{
+    // Set lastInsertDate to the smallest value possible
+    BsonValue lastInsertDate = BsonMinKey.Value;
+    
+    var options = new FindOptions<BsonDocument> 
+    { 
+        // Our cursor is a tailable cursor and informs the server to await
+        CursorType = CursorType.TailableAwait
+    };
+    
+    // Initially, we don't have a filter. An empty BsonDocument matches everything.
+    BsonDocument filter = new BsonDocument();
+    
+    // NOTE: This loops forever. It would be prudent to provide some form of 
+    // an escape condition based on your needs; e.g. the user presses a key.
+    while (true)
+    {
+        // Start the cursor and wait for the initial response
+        using (var cursor = collection.FindSync(filter, options))
+        {
+            foreach (var document in cursor.ToEnumerable())
+            {
+                // Set the last value we saw 
+                lastInsertDate = document["insertDate"];
+                
+                // Write the document to the console.
+                Console.WriteLine(document.ToString());
+            }
+        }
+
+        // The tailable cursor died so loop through and restart it
+        // Now, we want documents that are strictly greater than the last value we saw
+        filter = new BsonDocument("$gt", new BsonDocument("insertDate", lastInsertDate));
+    }
+}
+```
+
+This version of the code uses the asynchronous API to tail the capped collection:
+
 ```csharp
 private static async Task TailCollectionAsync(IMongoCollection<BsonDocument> collection)
 {
-    // Set lastValue to the smallest value possible
-    BsonValue lastValue = BsonMinKey.Value;
+    // Set lastInsertDate to the smallest value possible
+    BsonValue lastInsertDate = BsonMinKey.Value;
 
     var options = new FindOptions<BsonDocument> 
     { 
@@ -43,7 +86,7 @@ private static async Task TailCollectionAsync(IMongoCollection<BsonDocument> col
             await cursor.ForEachAsync(document =>
             {
                 // Set the last value we saw 
-                lastValue = document["insertDate"];
+                lastInsertDate = document["insertDate"];
 
                 // Write the document to the console.
                 await Console.WriteLineAsync(document.ToString());
@@ -52,10 +95,10 @@ private static async Task TailCollectionAsync(IMongoCollection<BsonDocument> col
 
         // The tailable cursor died so loop through and restart it
         // Now, we want documents that are strictly greater than the last value we saw
-        filter = new BsonDocument("$gt", new BsonDocument("insertDate", lastId));
+        filter = new BsonDocument("$gt", new BsonDocument("insertDate", lastInsertDate));
     }
 }
 ```
 
 {{% note %}}If multiple documents might have the exact same insert date, then using the above logic might cause you to miss some documents in the event that the cursor gets restarted. To solve this,
-you could track all the documents you've seen by their identifiers for the same `lastValue` and ignore them in the callback. In addition, you would need to change the `$gt` condition to `$gte`{{% /note %}}.
+you could track all the documents you've seen by their identifiers for the same `lastInsertDate` and ignore them when restarting the tailable cursor. In addition, you would need to change the `$gt` condition to `$gte`{{% /note %}}.

Docs/reference/content/examples/user_management.md

@@ -11,7 +11,7 @@ title = "Managing Users"
 
 ## How to Manage Users
 
-While MongoDB supports many user management commands, the driver does not have any helpers for them because users are generally managed from the [MongoDB shell]({{< docsref "reference/mongo-shell/" >}}). However, it is still possible to manage users from the driver by using the [`IMongoDatabase.RunCommandAsync`]({{< apiref "M_MongoDB_Driver_IMongoDatabase_RunCommandAsync__1" >}}) method.
+While MongoDB supports many user management commands, the driver does not have any helpers for them because users are generally managed from the [MongoDB shell]({{< docsref "reference/mongo-shell/" >}}). However, it is still possible to manage users from the driver by using the [`RunCommand`]({{< apiref "M_MongoDB_Driver_IMongoDatabase_RunCommand__1" >}}) or [`RunCommandAsync`]({{< apiref "M_MongoDB_Driver_IMongoDatabase_RunCommandAsync__1" >}}) methods.
 
 
 ## Listing Users
@@ -24,7 +24,12 @@ var db = client.GetDatabase("products");
 
 // construct the usersInfo command
 var command = new BsonDocument("usersInfo", 1);
-
+```
+```csharp
+// Run the command. If it fails, an exception will be thrown.
+var result = db.RunCommand<BsonDocument>(command);
+```
+```csharp
 // Run the command. If it fails, an exception will be thrown.
 var result = await db.RunCommandAsync<BsonDocument>(command);
 ```
@@ -51,22 +56,27 @@ var command = new BsonDocument
     { "pwd", "cleartext password" },
     { "customData", new BsonDocument("employeeId", 12345) },
     { "roles", new BsonArray
-               {
-                   new BsonDocument
-                   {
-                       { "role", "clusterAdmin" },
-                       { "db", "admin" }   
-                   },
-                   new BsonDocument
-                   {
-                       { "role", "readAnyDatabase" },
-                       { "db", "admin" }   
-                   },
-                   "readWrite"
-               }},
+        {
+            new BsonDocument
+            {
+                { "role", "clusterAdmin" },
+                { "db", "admin" }   
+            },
+            new BsonDocument
+            {
+                { "role", "readAnyDatabase" },
+                { "db", "admin" }   
+            },
+            "readWrite"
+        }},
     { "writeConcern", writeConcern.ToBsonDocument() }
 };
-
+```
+```csharp
+// Run the command. If it fails, an exception will be thrown.
+db.RunCommand<BsonDocument>(command);
+```
+```csharp
 // Run the command. If it fails, an exception will be thrown.
 await db.RunCommandAsync<BsonDocument>(command);
 ```
@@ -85,15 +95,20 @@ var command = new BsonDocument
     { "updateUser", "appClient01" },
     { "customData", new BsonDocument("employeeId", "0x3039") },
     { "roles", new BsonArray
-               {
-                   new BsonDocument
-                   {
-                       { "role", "read" },
-                       { "db", "assets" }   
-                   },
-               }}
+        {
+            new BsonDocument
+            {
+                { "role", "read" },
+                { "db", "assets" }   
+            },
+        }}
 };
-
+```
+```csharp
+// Run the command. If it fails, an exception will be thrown.
+db.RunCommand<BsonDocument>(command);
+```
+```csharp
 // Run the command. If it fails, an exception will be thrown.
 await db.RunCommandAsync<BsonDocument>(command);
 ```
@@ -107,10 +122,17 @@ The following example uses the [`dropUser`]({{< docsref "reference/command/dropU
 var db = client.GetDatabase("products");
 
 // Construct the dropUser command.
-var command = @"{ dropUser: ""accountAdmin01"",
-                  writeConcern: { w: ""majority"", wtimeout: 5000 }
-                }";
-
+var command = 
+    @"{
+        dropUser: ""accountAdmin01"",
+        writeConcern: { w: ""majority"", wtimeout: 5000 }
+    }";
+```
+```csharp
+// Run the command. If it fails, an exception will be thrown.
+db.RunCommand<BsonDocument>(command);
+```
+```csharp
 // Run the command. If it fails, an exception will be thrown.
 await db.RunCommandAsync<BsonDocument>(command);
 ```