Operaciones BSON

Overview

En esta guía, podrás aprender a crear documentos BSON, leer BSON desde un archivo y guardar BSON en un archivo utilizando el driver .NET/C#.

Formato de datos BSON

BSON, o JSON binario, es el formato de datos que MongoDB usa para organizar y almacenar datos. Este formato de datos incluye todos los tipos de estructura de datos JSON y añade soporte para tipos como fechas, enteros de diferentes tamaños, ObjectIds y datos binarios. Para ver una lista completa de los tipos compatibles, consulta la BSON Types página del manual del servidor.

Los ejemplos de código en esta guía usan el siguiente documento BSON como ejemplo:

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

Crear un Documento BSON

Para compilar una representación de un documento BSON en C#, crea una instancia del BsonDocument Clase. El constructor BsonDocument acepta argumentos BsonElement que corresponden a los campos y valores del documento. Cada BsonElement puede ser una instancia de la clase BsonElement o un par campo-valor entre llaves ( {} ).

El siguiente ejemplo de código muestra cómo crear un objeto BsonDocument para representar el ejemplo de documento BSON. Cada par clave-valor en el objeto BsonDocument es un objeto BsonElement.

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

Cambiar un documento BSON

La clase BsonDocument incluye métodos que le permiten cambiar el contenido del documento BSON. El siguiente código de muestra realiza tres cambios en el objeto anterior BsonDocument:

1. Agrega un nuevo campo, "restaurant_id", con el valor "12345"

2. Elimina el campo "cuisine"

3. Establece el valor del campo "name" en "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");

Guardar BSON en un archivo

Puede escribir BSON en un archivo utilizando los métodos de la clase BsonBinaryWriter. Para escribir en un archivo, siga estos pasos:

1. Abre un flujo de archivos para el archivo que contiene datos BSON.

2. Cree un BsonBinaryWriter utilizando el flujo de archivos.

3. Para cada documento BSON y subdocumento que quieras crear, llama a WriteStartDocument().

4. Dentro de cada documento BSON y subdocumento, llame a WriteName() para establecer el nombre del campo y al método Write* correspondiente para establecer su valor. Utiliza el método dedicado Write* que corresponde a cada tipo de datos.

5. Para iniciar y finalizar matrices, utilice WriteStartArray() y WriteEndArray().

6. Al final de cada documento y subdocumento, llame a WriteEndDocument().

El siguiente ejemplo de código muestra cómo escribir el documento BSON de muestra en 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();
}

El documento BSON resultante se ve como el siguiente:

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

Leer BSON desde un archivo

Para leer un documento BSON desde un archivo, siga los mismos pasos utilizados para escribir un documento BSON en un archivo, con dos diferencias:

• Utiliza BsonBinaryReader en lugar de BsonBinaryWriter.

• Utiliza los métodos Read* en lugar de los métodos Write*. Estos métodos devuelven nombres de campos y valores del documento BSON.

El siguiente ejemplo de código muestra cómo leer los campos y valores del documento BSON de muestra almacenado en 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();
}

Leer y guardar otros formatos

Los ejemplos precedentes muestran cómo leer y guardar datos BSON utilizando las clases BsonBinaryReader y BsonBinaryWriter. Estas clases implementan las interfaces IBsonReader y IBsonWriter. Para leer y escribir datos en otros formatos, el controlador .NET/C# proporciona las siguientes implementaciones alternativas de las interfaces IBsonReader y IBsonWriter:

• JsonReader y JsonWriter: Leer y escribir datos JSON

• BsonDocumentReader y BsonDocumentWriter: Leer y escribir datos BSON contenidos en un objeto BsonDocument

Dado que estas clases implementan las mismas interfaces, puedes llamar a sus métodos de la misma manera que en los ejemplos BsonBinaryReader y BsonBinaryWriter anteriores.

Documentación de la API

Para aprender más sobre cualquiera de los métodos o tipos analizados en esta guía, consulta la siguiente documentación de API:

• Documento Bson

• BsonElement

• BsonBinaryReader

• BsonBinaryWriter

• Lector de IBson

• IBsonWriter