Inicio rápido: Azure Cosmos DB for MongoDB para .NET con el controlador de MongoDB

SE APLICA A: MongoDB

Comience a utilizar MongoDB para crear bases de datos, colecciones y documentos dentro de un recurso de Azure Cosmos DB. Siga estos pasos para instalar el paquete y probar el código de ejemplo para realizar tareas básicas.

Nota:

Los fragmentos de código de ejemplo están disponibles en GitHub como un proyecto de .NET.

Documentación de referencia de la API para MongoDB | Paquete de MongoDB (NuGet)

Requisitos previos

Comprobación de requisitos previos

  • En una ventana de terminal o de comandos, ejecute dotnet --list-sdks para comprobar que .NET 6.x es una de las versiones disponibles.
  • Ejecute az --version (CLI de Azure) o Get-Module -ListAvailable AzureRM (Azure PowerShell) para comprobar que tiene instaladas las herramientas adecuadas de la línea de comandos de Azure.

Instalación

En esta sección, se muestran los pasos a seguir para crear una cuenta de Azure Cosmos DB y configurar un proyecto que use paquetes NuGet de MongoDB.

Creación de una cuenta de Azure Cosmos DB

En este inicio rápido se creará una única cuenta de Azure Cosmos DB mediante la API para MongoDB.

  1. Cree variables de shell para accountName, resourceGroupName y location.

    # Variable for resource group name
    resourceGroupName="msdocs-cosmos-quickstart-rg"
    location="westus"
    
    # Variable for account name with a randomnly generated suffix
    let suffix=$RANDOM*$RANDOM
    accountName="msdocs-$suffix"
    
  2. Si aún no lo ha hecho, inicie sesión en la CLI de Azure con el comando az login.

  3. Use el comando az group create para crear un nuevo grupo de recursos en la suscripción.

    az group create \
        --name $resourceGroupName \
        --location $location
    
  4. Use el comando az cosmosdb create para crear una nueva cuenta de Azure Cosmos DB for MongoDB con la configuración predeterminada.

    az cosmosdb create \
        --resource-group $resourceGroupName \
        --name $accountName \
        --locations regionName=$location
        --kind MongoDB
    

Obtención de la cadena de conexión de MongoDB

  1. Busque la cadena de conexión de API para MongoDB en la lista de cadenas de conexión para la cuenta con el comando az cosmosdb keys list.

    az cosmosdb keys list --type connection-strings \
        --resource-group $resourceGroupName \
        --name $accountName 
    
  2. Anote los valores de PRIMARY KEY. Necesitará estas credenciales más adelante.

Crear una nueva aplicación .NET

Cree una nueva aplicación de .NET en una carpeta vacía con su terminal preferido. Use dotnet new console para crear una nueva aplicación de consola.

dotnet new console -o <app-name>

Instalación del paquete NuGet.

Agregue el paquete NuGet MongoDB.Driver al nuevo proyecto de .NET. Use el comando dotnet add package especificando el nombre del paquete de NuGet.

dotnet add package MongoDb.Driver

Configuración de las variables de entorno

Para usar los valores de la CADENA DE CONEXIÓN en el código, establezca este valor en el entorno local que ejecuta la aplicación. Para establecer la variable de entorno, use el terminal preferido para ejecutar los siguientes comandos:

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

Modelo de objetos

Antes de empezar a compilar la aplicación, consulte la jerarquía de recursos en Azure Cosmos DB. Azure Cosmos DB tiene un modelo de objetos específico que se usa para crear los recursos y acceder a ellos. Azure Cosmos DB crea recursos en una jerarquía que consta de cuentas, bases de datos, colecciones y documentos.

Diagrama de la jerarquía de Azure Cosmos DB que incluye cuentas, bases de datos, colecciones y documentos.

Diagrama jerárquico que muestra una cuenta de Azure Cosmos DB en la parte superior. La cuenta tiene dos nodos de base de datos secundarios. Uno de los nodos de base de datos incluye dos nodos de colección secundarios. El otro de los nodos de base de datos incluye un único nodo de colección secundario. Ese único nodo de colección tiene tres nodos de documento secundarios.

Se usaran las siguientes clases de MongoDB para interactuar con estos recursos:

  • MongoClient: Esta clase proporciona una representación lógica del cliente para la capa de la API para MongoDB en Azure Cosmos DB. El objeto de cliente se usa para configurar y ejecutar solicitudes en el servicio.
  • MongoDatabase: esta clase es una referencia a una base de datos que podría existir ya o no en el servicio. La base de datos se valida en el servidor al intentar acceder a ella o hacer alguna una operación.
  • Collection: Esta clase es una referencia a una colección que podría no existir aún en el servicio. La colección se valida en el servidor al intentar utilizarla.

Ejemplos de código

El código de ejemplo mostrado en este artículo crea una base de datos denominada adventureworks, con una colección denominada products. La colección products se ha diseñado para incluir detalles del producto, como el nombre, la categoría, la cantidad y un indicador de venta. Cada producto también contiene un identificador único.

Autenticar el cliente

En el directorio del proyecto, abra el archivo Program.cs. En el editor, agregue una directiva using para MongoDB.Driver.

using MongoDB.Driver;

Defina una nueva instancia de la clase MongoClient mediante el constructor y Environment.GetEnvironmentVariable para leer la cadena de conexión que estableció anteriormente.

// New instance of CosmosClient class
var client = new MongoClient(Environment.GetEnvironmentVariable("MONGO_CONNECTION"));

Crear una base de datos

Use el método MongoClient.GetDatabase para crear una nueva base de datos si aún no existe. Este método devolverá una referencia a la base de datos existente o recién creada.

// Database reference with creation if it does not already exist
var db = client.GetDatabase("adventure");

Creación de una colección

MongoDatabase.GetCollection Creará una nueva colección si aún no existe y devolverá una referencia a la colección.

// Container reference with creation if it does not alredy exist
var _products = db.GetCollection<Product>("products");

Crear un elemento

La manera más fácil de crear un nuevo elemento en una colección es crear una clase o un tipo de registro de C# con todos los miembros que quiere serializar en JSON. En este ejemplo, el registro C# tiene un identificador único, un campo category para la clave de partición y campos name, quantity y sale adicionales.

public record Product(
    string Id,
    string Category,
    string Name,
    int Quantity,
    bool Sale
);

Cree un elemento en la colección mediante el registro Product llamando a IMongoCollection<TDocument>.InsertOne.

// Create new object and upsert (create or replace) to container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Yamba Surfboard", 
    12, 
    false
));

Obtención de un elemento

En Azure Cosmos DB, puede recuperar elementos mediante la redacción de consultas con Linq. En el SDK, llame a IMongoCollection.FindAsync<> y pase una expresión de C# para filtrar los resultados.

// Read a single item from container
var product = (await _products.FindAsync(p => p.Name.Contains("Yamba"))).FirstOrDefault();
Console.WriteLine("Single product:");
Console.WriteLine(product.Name);

Elementos de consulta

Después de insertar un elemento, puede ejecutar una consulta para obtener todos los elementos que coincidan con un filtro específico tratando la colección como un IQueryable. En este ejemplo se usa una expresión para filtrar productos por categoría. Una vez realizada la llamada a AsQueryable, llame a MongoQueryable.Where para recuperar un conjunto de elementos filtrados.

// Read multiple items from container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Sand Surfboard",
    4,
    false
));

var products = _products.AsQueryable().Where(p => p.Category == "gear-surf-surfboards");

Console.WriteLine("Multiple products:");
foreach (var prod in products)
{
    Console.WriteLine(prod.Name);
}

Ejecución del código

Esta aplicación crea una base de datos y una colección de API de MongoDB para Azure Cosmos DB. A continuación, el ejemplo crea un elemento y luego lee el mismo elemento exactamente. Por último, en el ejemplo se crea un segundo elemento y se realiza una consulta que debe devolver varios elementos. Con cada paso, el ejemplo genera metadatos en la consola sobre los pasos que ha realizado.

Para ejecutar la aplicación, use un terminal para ir al directorio de la aplicación y ejecutarla.

dotnet run

La salida de la aplicación debe ser similar a este ejemplo:

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

Limpieza de recursos

Cuando ya no necesite la cuenta de Azure Cosmos DB for NoSQL, puede eliminar el grupo de recursos correspondiente.

Use el comando az group delete para eliminar el grupo de recursos.

az group delete --name $resourceGroupName