Primeros pasos con DocumentDB y .NET

Uno de los servicios de bases de datos no relacionales de los que dispone Azure es DocumentDB. Es una base de datos que contiene una serie de colecciones que almacenan documentos en formato JSON.

Si alguien no conoce todavía qué es DocumentDB y para qué sirve, este artículo cubre la información principal del servicio y las bases de datos no relacionales.

En este artículo vamos a ver cómo integrar el servicio con un proyecto .NET, utilizando el SDK que tenemos a disposición de la plataforma aunque también hay disponibles SDKs de JavaScript, Node.js o Python.

Para aprender a crear bases de datos, rellenarlas con documentos y realizar consultas para obtenerlos vamos a basarnos en el siguiente caso. Imaginemos que participamos en varios eventos en los que repartimos diversos premios y queremos tener control del stock que nos queda en cada evento.

Crear el servicio

En primer lugar, hay que crear el servicio DocumentDB. Desde el portal de Azure se creará un nuevo servicio de bases de datos DocumentDB.

1

 

2

 

Una vez creado el servicio se pueden encontrar las claves y el Azure Endpoint del servicio en la sección de Keys. 3

Conectar DocumentDB a un proyecto .NET

Ahora que DocumentDB está activo en Azure, hay que crear un proyecto de consola C#(.NET) desde Visual Studio.

4
A continuación hay que instalar el paquete Nuget de Microsoft.Azure.DocumentDB (desde el Nuget Packet Manager)  para poder trabajar cómodamente con el servicio de Azure desde el proyecto.

 

5

 

Una vez descargado el paquete Nuget se crea un cliente con el que acceder al DocumentDB. Pega el siguiente código en tu solución con los datos de tu servicio. Si ejecutas el programa y aparece el mensaje de prueba finalizada, significará que la conexión ha sido exitosa.

 

 class Program
    {
        private const string EndpointUrl = "INTRODUCE AQUI TU ENDPOINT";
        private const string PrimaryKey = "INTRODUCE AQUI TU CLAVE";
        private DocumentClient client;

        static void Main(string[] args)
        {
           try
            {
                Program p = new Program();
                p.EjecutarTareasAsync().Wait();
            }
            catch (DocumentClientException de)
            {
                Exception baseException = de.GetBaseException();
                Console.WriteLine("Error {0}: {1}, Mensaje: {2}", de.StatusCode, de.Message, baseException.Message);
            }
            catch (Exception e)
            {
                Exception baseException = e.GetBaseException();
                Console.WriteLine("Error: {0}, Mensaje: {1}", e.Message, baseException.Message);
            }
            finally
            {
                Console.WriteLine("Prueba finalizada, pulse cualquier tecla para continuar.");
                Console.ReadKey();
            }
        }
       private async Task EjecutarTareasAsync()
       {
           client = new DocumentClient(new Uri(EndpointUrl), PrimaryKey);
       }
   }

 

Crear bases de datos, colecciones y documentos

Dentro de nuestro DocumentDB podemos tener diversas bases de datos con sus respectivas colecciones de documentos. En este caso hay que crear la base de datos “PremiosDB”, y una colección de datos “Eventos” en la que se guardarán los documentos para los distintos eventos en los que se repartan premios.

Añade las siguientes líneas a la función "EjecutarTareasAsync", debajo de la creación del cliente, para comprobar si existe la base de datos “PremiosDB” y la colección “Eventos”. En caso de que no existan, se crearán.

 await client.CreateDatabaseIfNotExistsAsync(new Database { Id = "PremiosDB" });
await client.CreateDocumentCollectionIfNotExistsAsync(UriFactory.CreateDatabaseUri("PremiosDB"), new DocumentCollection { Id = "Eventos" });

Si ejecutas de nuevo el programa, se creará la base de datos dentro del servicio y la colección correspondiente. El siguiente paso es popular esa colección y para ello hay que definir una clase Evento, que será el formato de documento que se guardará en la colección del DocumentDB.

Crea una nueva clase Evento en tu solución y añade las siguientes líneas.

 public class Evento
    {
        [JsonProperty(PropertyName = "id")]
        public string Id{ get; set; }

        [JsonProperty(PropertyName = "camisetas")]
        public int Camisetas { get; set; }

        [JsonProperty(PropertyName = "mochilas")]
        public int Mochilas { get; set; }

        [JsonProperty(PropertyName = "tazas")]
        public int Tazas { get; set; }
    }

Volviendo a la clase Program, crea una función que sirva para crear documentos dentro de la colección. Añade la siguiente función a tu código.

 private async Task CreateEventoDocument(string databaseName, string collectionName, Evento evento)
        {
            try
            {
                await this.client.ReadDocumentAsync(UriFactory.CreateDocumentUri(databaseName, collectionName, evento.Nombre));
                Console.WriteLine("Encontrado evento {0}", evento.Nombre);
                Console.WriteLine("Pulsa cualquier tecla para continuar ...");
            }
            catch (DocumentClientException de)
            {
                if (de.StatusCode == HttpStatusCode.NotFound)
                {
                    await this.client.CreateDocumentAsync(UriFactory.CreateDocumentCollectionUri(databaseName, collectionName), evento);
                    Console.WriteLine("Evento {0} creado", evento.Nombre);
                    Console.WriteLine("Pulsa cualquier tecla para continuar ...");
                }
                else
                {
                    throw;
                }
            }
        }

 

Ahora dispones de una función con la que podrás crear nuevos documentos en DocumentDB pasándole la base de datos, la colección y el documento a subir. Si no existe un documento con el mismo Id, lo creará.

 

Añadir nuevos documentos

Crea un nuevo objeto Evento para subir a la colección de documentos. Añade las siguientes líneas a la función "EjecutarTareasAsync".

 Evento evento1 = new Evento{
                    Id = "Evento1",
                    Camisetas = 30,
                    Mochilas = 10,
                    Tazas = 15
                };

await p.CreateEventoDocument("PremiosDB", "Eventos", evento1);

Ejecuta de nuevo el programa para subir el evento a la colección de documentos. Una vez finalizado, en Azure quedarán registrados los nuevos datos. En la sección Collections->Document Explorer aparecerá la nueva colección y el nuevo documento generado.

6 7

Obtener los documentos

Vamos a crear la función correspondiente para obtener nuestros documentos de eventos de la colección de eventos.

 private void ObtenerEventos(string databaseName, string collectionName) {
            FeedOptions queryOptions = new FeedOptions { MaxItemCount = -1 };

            // Buscar documentos en la colección
            IQueryable<Evento> eventosQuery = client.CreateDocumentQuery<Evento>(
            UriFactory.CreateDocumentCollectionUri(databaseName, collectionName), queryOptions);

            // Mostrar resultados
            foreach (Evento evento in eventosQuery)
            {
                Console.WriteLine("\t {0}", evento.Id);
                Console.WriteLine("\t --------------------------");
                Console.WriteLine("\t Tazas -> {0}", evento.Tazas);
                Console.WriteLine("\t Mochilas -> {0}", evento.Mochilas);
                Console.WriteLine("\t Camisetas -> {0}", evento.Camisetas);
                Console.WriteLine("\t --------------------------");
            }
        }

Ahora que tenemos nuestra función para crear premios vamos a implementarla en nuestra función de tareas a ejecutar.

 ObtenerEventos("PremiosDB", "Eventos");

Si ejecutas el código aparecerán los eventos que hayas registrado en la colección de DocumentDB con los datos del stock.

8

Ahora que sabes como crear un servicio DocumentDB, crear bases de datos y obtener los datos que las componen, puedes integrar el servicio en tus proyectos .NET.

 

Daniel Mitchell

Technical Evangelist Intern

@danymitb