BSON Operations

Overview

In this guide, you can learn how to create BSON documents, read BSON from a file, and write BSON to a file using the .NET/C# Driver.

BSON Data Format

BSON, or Binary JSON, is the data format that MongoDB uses to organize and store data. This data format includes all JSON data structure types and adds support for types including dates, different size integers, ObjectIds, and binary data. For a complete list of supported types, see the BSON Types server manual page.

The code samples in this guide use the following BSON document as an example:

{
    "address" : {
        "street" : "Pizza St",
        "zipcode" : "10003"
    },
    "coord" : [-73.982419, 41.579505]
    "cuisine" : "Pizza",
    "name" : "Mongo's Pizza"
}

Create a BSON Document

To build a representation of a BSON document in C#, create an instance of the BsonDocument class. The BsonDocument constructor accepts BsonElement arguments that map to the fields and values in the document. Each BsonElement can be either an instance of the BsonElement class or a field-value pair inside curly braces ( {} ).

The following code sample shows how to create a BsonDocument object to represent the example BSON document. Each key-value pair in the BsonDocument object is a BsonElement object.

var newRestaurant = new BsonDocument
{
    { "address", new BsonDocument
        {
            { "street", "Pizza St" },
            { "zipcode", "10003" }
        }
    },
    { "coord", new BsonArray
        {-73.982419, 41.579505 }
    },
    { "cuisine", "Pizza" },
    { "name", "Mongo's Pizza"}
};

Change a BSON Document

The BsonDocument class includes methods that let you change the contents of the BSON document. The following code sample makes three changes to the previous BsonDocument object:

1. Adds a new field, "restaurant_id", with the value "12345"

2. Removes the "cuisine" field

3. Sets the value of the "name" field to "Mongo's Pizza Palace"

var newRestaurant = new BsonDocument
{
    { "address", new BsonDocument
        {
            { "street", "Pizza St" },
            { "zipcode", "10003" }
        }
    },
    { "coord", new BsonArray
        {-73.982419, 41.579505 }
    },
    { "cuisine", "Pizza" },
    { "name", "Mongo's Pizza"}
};
newRestaurant.Add(new BsonElement("restaurant_id", "12345"));
newRestaurant.Remove("cuisine");
newRestaurant.Set("name", "Mongo's Pizza Palace");

Write BSON to a File

You can write BSON to a file using the methods in the BsonBinaryWriter class. To write to a file, perform the following steps:

1. Open a file stream for the file containing BSON data.

2. Create a BsonBinaryWriter using the file stream.

3. For each BSON document and subdocument you want to create, call WriteStartDocument().

4. Within each BSON document and subdocument, call WriteName() to set the field name and the appropriate Write* method to set its value. Use the dedicated Write* method that corresponds to each data type.

5. To start and end arrays, use WriteStartArray() and WriteEndArray().

6. At the end of each document and subdocument, call WriteEndDocument().

The following code sample shows how to write the sample BSON document to myFile.bson:

string outputFileName = "myFile.bson";
using (var stream = File.OpenWrite(outputFileName))
using (var writer = new BsonBinaryWriter(stream))
{
    writer.WriteStartDocument();
    //address
    writer.WriteName("address");
    writer.WriteStartDocument();
    writer.WriteName("street");
    writer.WriteString("Pizza St");
    writer.WriteName("zipcode");
    writer.WriteString("10003");
    writer.WriteEndDocument();
    //coord
    writer.WriteName("coord");
    writer.WriteStartArray();
    writer.WriteDouble(-73.982419);
    writer.WriteDouble(41.579505);
    writer.WriteEndArray();
    //cuisine
    writer.WriteName("cuisine");
    writer.WriteString("Pizza");
    //name
    writer.WriteName("name");
    writer.WriteString("Mongo's Pizza");
    writer.WriteEndDocument();
}

The resulting BSON document looks like the following:

{
    "address" : {
        "street" : "Pizza St",
        "zipcode" : "10003"
    },
    "coord" : [-73.982419, 41.579505]
    "cuisine" : "Pizza",
    "name" : "Mongo's Pizza"
}

Read BSON from a File

To read a BSON document from a file, follow the same steps used for writing a BSON document to a file, with two differences:

• Use BsonBinaryReader instead of BsonBinaryWriter.

• Use Read* methods instead of Write* methods. These methods return field names and values from the BSON document.

The following code sample shows how to read the fields and values from the sample BSON document stored in myFile.bson:

string inputFileName = "myFile.bson";
using (var stream = File.OpenRead(inputFileName))
using (var reader = new BsonBinaryReader(stream))
{
    reader.ReadStartDocument();
    //address
    string addressFieldName = reader.ReadName();
    reader.ReadStartDocument();
    string streetFieldName = reader.ReadName();
    string streetValue = reader.ReadString();
    string zipFieldName = reader.ReadName();
    string zipValue = reader.ReadString();
    reader.ReadEndDocument();
    //coord
    string coordFieldName = reader.ReadName();
    reader.ReadStartArray();
    double coord1 = reader.ReadDouble();
    double coord2 = reader.ReadDouble();
    reader.ReadEndArray();
    //cuisine
    string cuisineFieldName = reader.ReadName();
    string cuisineValue = reader.ReadString();
    //name
    string nameFieldName = reader.ReadName();
    string nameValue = reader.ReadString();
    reader.ReadEndDocument();
}

Read and Write Other Formats

The preceding examples show how to read and write BSON data by using the BsonBinaryReader and BsonBinaryWriter classes. These classes implement the IBsonReader and IBsonWriter interfaces. To read and write data in other formats, the .NET/C# Driver provides the following alternative implementations of the IBsonReader and IBsonWriter interfaces:

• JsonReader and JsonWriter: Read and write JSON data

• BsonDocumentReader and BsonDocumentWriter: Read and write BSON data contained in a BsonDocument object

Because these classes implement the same interfaces, you can call their methods in the same way as the preceding BsonBinaryReader and BsonBinaryWriter examples.

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

• BsonDocument

• BsonElement

• BsonBinaryReader

• BsonBinaryWriter

• IBsonReader

• IBsonWriter