Docs Menu
Docs Home
/ / /
C#/.NET
/

BSON Operations

On this page

  • Overview
  • BSON Data Format
  • Create a BSON Document
  • Change a BSON Document
  • Write BSON to a File
  • Read BSON from a File
  • API Documentation

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, 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"
}

To build 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"}
};

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");

Note

For a full list of methods in the BsonDocument class, see the API Documentation.

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. Each data type has a dedicated Write* method that you should use.

  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"
}

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();
}

Warning

If you call ReadName() twice in a row without reading a value, the driver will throw an InvalidOperationException.

Tip

The BsonBinaryReader and BsonBinaryWriter constructors accept any System.IO.Stream object. This means that you can read or write any location that can be accessed by a stream.

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

Back

LINQ