Compartir vía

Inicio rápido: Uso de Azure DocumentDB con el controlador mongoDB para C#

En este inicio rápido, creará una aplicación básica de Azure DocumentDB mediante C#. Azure DocumentDB es un almacén de datos NoSQL que permite a las aplicaciones almacenar documentos en la nube y acceder a ellos mediante controladores oficiales de MongoDB. En esta guía se muestra cómo crear documentos y realizar tareas básicas en el clúster de Azure DocumentDB mediante C#.

Referencia de | APICódigo fuente | Paquete (NuGet)

Prerrequisitos

  • Una suscripción de Azure

  • .NET 10.0 o posterior

Creación de un clúster de Azure DocumentDB

Para empezar, primero debe crear un clúster de Azure DocumentDB, que sirve como base para almacenar y administrar los datos NoSQL.

  1. Inicie sesión en Azure Portal (https://portal.azure.com).

  2. En el menú de Azure Portal o en la página principal, seleccione Crear un recurso.

  3. En la página Nuevo , busque y seleccione Azure DocumentDB.

    Captura de pantalla que muestra la búsqueda de Azure DocumentDB.

  4. En la página Crear clúster de Azure DocumentDB y, en la sección Aspectos básicos , seleccione la opción Configurar en la sección Nivel de clúster.

    Captura de pantalla que muestra la opción Configurar clúster.

  5. En la página Escala , configure estas opciones y seleccione Guardar para conservar los cambios en el nivel de clúster.

    Importancia
    Nivel de clúster M30 tier, 2 vCore, 8-GiB RAM
    Almacenamiento por partición 128 GiB

    Captura de pantalla de las opciones de configuración para el proceso y el almacenamiento de un nuevo clúster de Azure DocumentDB.

  6. De nuevo en la sección Aspectos básicos , configure las siguientes opciones:

    Importancia
    Subscription Seleccione su suscripción a Azure.
    Grupo de recursos Cree un grupo de recursos nuevo o seleccione uno existente
    Nombre del clúster Proporcione un nombre único global.
    Ubicación Seleccione una región de Azure compatible para su suscripción
    Versión de MongoDB Seleccionar 8.0
    Nombre de usuario de administrador Creación de un nombre de usuario para acceder al clúster como administrador de usuarios
    Contraseña Uso de una contraseña única asociada al nombre de usuario

    Captura de pantalla que muestra los parámetros del clúster.

    Sugerencia

    Registre los valores que usa para el nombre de usuario y la contraseña. Estos valores se usan más adelante en esta guía. Para más información sobre los valores válidos, consulte Limitaciones del clúster.

  7. Seleccione Siguiente: Redes.

  8. En la sección Reglas de firewall de la pestaña Redes , configure estas opciones:

    Importancia
    Método de conectividad Public access
    Permitir el acceso público desde servicios y recursos de Azure a este clúster Enabled

  9. Agregue una regla de firewall para el dispositivo cliente actual para conceder acceso al clúster seleccionando + Agregar dirección IP del cliente actual.

    Captura de pantalla que muestra las configuraciones de red.

    Sugerencia

    En muchos entornos corporativos, las direcciones IP de la máquina del desarrollador se ocultan debido a una VPN u otra configuración de red corporativa. En estos casos, puede permitir temporalmente el acceso a todas las direcciones IP agregando el 0.0.0.0 - 255.255.255.255 intervalo de direcciones IP como regla de firewall. Use esta regla de firewall solo temporalmente como parte de las pruebas de conexión y el desarrollo.

  10. Selecciona Revisar + crear.

  11. Revise la configuración que proporcione y, a continuación, seleccione Crear. La operación de creación del clúster tarda unos minutos. Espere a que se complete la implementación de recursos.

  12. Por último, seleccione Ir al recurso para ir al clúster de Azure DocumentDB en el portal.

Captura de pantalla que muestra las opciones de recursos goto.

Obtener credenciales del clúster

Obtenga las credenciales que usa para conectarse al clúster.

  1. En la página del clúster, seleccione la opción Cadenas de conexión en el menú de recursos.

  2. En la sección Cadenas de conexión , copie o registre el valor del campo Cadena de conexión .

Captura de pantalla que muestra la opción cadenas de conexión.

Importante

La cadena de conexión del portal no incluye el valor de contraseña. Debe reemplazar el marcador de posición <password> por los datos de acceso que introdujo al crear el clúster o ingresar la contraseña de manera interactiva.

Inicialización del proyecto

Cree un nuevo proyecto de aplicación de consola de .NET en el directorio actual.

  1. Inicie en un directorio vacío.

  2. Abra un terminal en el directorio actual.

  3. Cree una nueva aplicación de consola de .NET.

    dotnet new console

  4. Compile el proyecto para asegurarse de que se creó correctamente.

    dotnet build

Instalación de la biblioteca cliente

La biblioteca cliente está disponible a través de NuGet, como paquete MongoDB.Driver.

  1. Instale el controlador .NET de MongoDB mediante el administrador de paquetes NuGet.

    dotnet add package MongoDB.Driver

  2. Abra y revise el archivo azure-documentdb-dotnet-quickstart.csproj para validar que existe la referencia del paquete.

  3. Importe los espacios de nombres necesarios en el código de la aplicación:

    using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
using MongoDB.Driver;

Modelo de objetos

Nombre Description
MongoClient Tipo que se usa para conectarse a MongoDB.
IMongoDatabase Representa una base de datos en el clúster.
IMongoCollection<T> Representa una colección dentro de una base de datos del clúster.

Ejemplos de código

El código de esta aplicación se conecta a una base de datos denominada adventureworks y a una colección denominada products. La products colección contiene detalles como el nombre, la categoría, la cantidad, un identificador único y una marca de venta para cada producto. Los ejemplos de código aquí realizan las operaciones más comunes al trabajar con una colección.

Autenticar el cliente

En primer lugar, conéctese al cliente mediante una cadena de conexión básica.

  1. Cree el método principal y configure la cadena de conexión. Reemplace <your-cluster-name>, <your-username>, y <your-password> con su información real del clúster.

    class Program
{
    static async Task Main(string[] args)
    {
        // Connection string for Azure DocumentDB cluster
        string connectionString = "mongodb+srv://<your-username>:<your-password>@<your-cluster-name>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000";

        // Create MongoDB client settings
        var settings = MongoClientSettings.FromConnectionString(connectionString);

  2. Cree el cliente de MongoDB y compruebe la conexión.

            // Create a new client and connect to the server
        var client = new MongoClient(settings);

        // Ping the server to verify connection
        var database = client.GetDatabase("admin");
        var pingCommand = new BsonDocument("ping", 1);
        await database.RunCommandAsync<BsonDocument>(pingCommand);

        Console.WriteLine("Successfully connected and pinged Azure DocumentDB");

Consigue una colección

Ahora, consigue base de datos y colección. Si la base de datos y la colección aún no existen, use el controlador para crearla automáticamente.

  1. Obtenga una referencia a la base de datos.

            // Get database reference
        var adventureWorksDatabase = client.GetDatabase("adventureworks");
        Console.WriteLine($"Connected to database: {adventureWorksDatabase.DatabaseNamespace.DatabaseName}");

  2. Obtenga una referencia a la colección dentro de la base de datos.

            // Get collection reference
        var productsCollection = adventureWorksDatabase.GetCollection<Product>("products");
        Console.WriteLine($"Connected to collection: products");

Creación de un documento

A continuación, cree un par de documentos nuevos dentro de la colección. Inserte o actualice los documentos para asegurarse de que reemplacen cualquier documento existente si ya existen con el mismo identificador único.

  1. Defina una clase Product y cree documentos de producto de ejemplo.

            // Create sample products
        var products = new List<Product>
        {
            new Product
            {
                Id = "00000000-0000-0000-0000-000000004018",
                Name = "Windry Mittens",
                Category = "apparel-accessories-gloves-and-mittens",
                Quantity = 121,
                Price = 35.00m,
                Sale = false
            },
            new Product
            {
                Id = "00000000-0000-0000-0000-000000004318",
                Name = "Niborio Tent",
                Category = "gear-camp-tents",
                Quantity = 140,
                Price = 420.00m,
                Sale = true
            }
        };

  2. Inserte los documentos mediante operaciones upsert.

            // Insert documents with upsert
        foreach (var product in products)
        {
            var filter = Builders<Product>.Filter.Eq(p => p.Id, product.Id);
            var options = new ReplaceOptions { IsUpsert = true };

            await productsCollection.ReplaceOneAsync(filter, product, options);
            Console.WriteLine($"Upserted product: {product.Name}");
        }

  3. Agregue la definición de clase Product al final del archivo Program.cs.

    public class Product
{
    [BsonId]
    [BsonElement("_id")]
    public string Id { get; set; }

    [BsonElement("name")]
    public string Name { get; set; }

    [BsonElement("category")]
    public string Category { get; set; }

    [BsonElement("quantity")]
    public int Quantity { get; set; }

    [BsonElement("price")]
    public decimal Price { get; set; }

    [BsonElement("sale")]
    public bool Sale { get; set; }
}

Recuperar un documento

A continuación, realice una operación de lectura puntual para recuperar un documento específico de la colección.

  1. Defina el filtro para buscar un documento específico por identificador.

            // Retrieve a specific document by ID
        var filter = Builders<Product>.Filter.Eq(p => p.Id, "00000000-0000-0000-0000-000000004018");

  2. Ejecute la consulta y recupere el resultado.

            var retrievedProduct = await productsCollection.Find(filter).FirstOrDefaultAsync();

        if (retrievedProduct != null)
        {
            Console.WriteLine($"Retrieved product: {retrievedProduct.Name} - ${retrievedProduct.Price}");
        }
        else
        {
            Console.WriteLine("Product not found");
        }

Consulta de documentos

Por último, consulte varios documentos mediante el lenguaje de consulta mongoDB (MQL).

  1. Defina una consulta para buscar documentos que coincidan con criterios específicos.

            // Query for products on sale
        var saleFilter = Builders<Product>.Filter.Eq(p => p.Sale, true);
        var saleProducts = await productsCollection.Find(saleFilter).ToListAsync();

  2. Recorra en iteración los resultados para mostrar los documentos coincidentes.

            Console.WriteLine("Products on sale:");
        foreach (var product in saleProducts)
        {
            Console.WriteLine($"- {product.Name}: ${product.Price:F2} (Category: {product.Category})");
        }
    }
}

Exploración de los datos mediante Visual Studio Code

Use la extensión DocumentDB en Visual Studio Code para realizar operaciones básicas de base de datos, como consultar, insertar, actualizar y eliminar datos.

  1. Abra Visual Studio Code.

  2. Vaya a la vista Extensiones y busque el término DocumentDB. Busque la extensión DocumentDB para VS Code .

  3. Seleccione el botón Instalar de la extensión. Espere a que termine la instalación. Vuelva a cargar Visual Studio Code si se le solicita.

  4. Vaya a la extensión DocumentDB seleccionando el icono correspondiente en la barra de actividad.

  5. En el panel Conexiones de DocumentDB , seleccione + Nueva conexión....

  6. En el cuadro de diálogo, seleccione Detección de servicios y, a continuación, Azure DocumentDB - Azure Service Discovery.

  7. Seleccione la suscripción de Azure y el clúster de Azure DocumentDB recién creado.

    Sugerencia

    En muchos entornos corporativos, las direcciones IP de la máquina del desarrollador se ocultan debido a una VPN u otra configuración de red corporativa. En estos casos, puede permitir temporalmente el acceso a todas las direcciones IP agregando el 0.0.0.0 - 255.255.255.255 intervalo de direcciones IP como regla de firewall. Use esta regla de firewall solo temporalmente como parte de las pruebas de conexión y el desarrollo. Para más información, consulte Configuración del firewall.

  8. De nuevo en el panel Conexiones de DocumentDB , expanda el nodo del clúster y vaya a los nodos de documento y colección existentes.

  9. Abra el menú contextual de la colección y luego seleccione >.

  10. Escriba los siguientes comandos del lenguaje de consulta de MongoDB (MQL) y, a continuación, seleccione Ejecutar todo. Observa la salida de los comandos.

    db.products.find({
  price: { $gt: 200 },
  sale: true
})
.sort({ price: -1 })
.limit(3)

Limpieza de recursos

Cuando haya terminado con el clúster de Azure DocumentDB, puede eliminar los recursos de Azure que creó para que no incurra en más cargos.

  1. En la barra de búsqueda de Azure Portal, busque y seleccione Grupos de recursos.

    Captura de pantalla que muestra la opción para buscar grupos de recursos.

  2. En la lista, seleccione el grupo de recursos que usó para este inicio rápido.

    Captura de pantalla que muestra el grupo de recursos.

  3. En la página del grupo de recursos, seleccione Eliminar grupo de recursos.

  4. En el cuadro de diálogo de confirmación de eliminación, escriba el nombre del grupo de recursos para confirmar que desea eliminarlo. Por último, seleccione Eliminar para eliminar de forma permanente el grupo de recursos.

    Captura de pantalla que muestra el botón de confirmación para eliminar el grupo de recursos.

Contenido relacionado

  • Last updated on