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

Artículo
03/29/2024

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 implementar una solución mínima en su entorno mediante la Azure Developer CLI.

Documentación de referencia de la API para MongoDB | Paquete MongoDB (NuGet) packages/Microsoft.Azure.Cosmos) | Azure Developer CLI

Requisitos previos

Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
Cuenta de GitHub

Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
CLI de desarrollo de Azure
Docker Desktop

Instalación

Implemente el contenedor de desarrollo de este proyecto en su entorno. A continuación, use Azure Developer CLI (azd) para crear una cuenta de Azure Cosmos DB for MongoDB e implementar una aplicación de ejemplo en contenedor. La aplicación de ejemplo usa la biblioteca cliente para administrar, crear, leer y consultar datos de ejemplo.

Importante

Las cuentas de GitHub incluyen un derecho de almacenamiento y horas de núcleo sin costo alguno. Para obtener más información, consulte el almacenamiento y las horas de núcleo incluidas para las cuentas de GitHub.

Abra un terminal en el directorio raíz del proyecto.
Autentíquese en Azure Developer CLI mediante azd auth login. Siga los pasos especificados por la herramienta para autenticarse en la CLI mediante sus credenciales de Azure preferidas.
```
azd auth login
```
Ejecute azd init para inicializar el proyecto.
```
azd init
```
Durante la inicialización, configure un nombre de entorno único.

Sugerencia

El nombre del entorno también se usará como nombre del grupo de recursos de destino. Para este inicio rápido, considere la posibilidad de usar msdocs-cosmos-db-.
Implemente la cuenta de Azure Cosmos DB mediante azd up. Las plantillas de Bicep también implementan una aplicación web de muestra.
```
azd up
```
Durante el proceso de aprovisionamiento, seleccione la suscripción y la ubicación deseada. Espere a que se complete el proceso de aprovisionamiento. El proceso puede tardar aproximadamente cinco minutos.

Una vez realizado el aprovisionamiento de los recursos de Azure, se incluye una dirección URL a la aplicación web en ejecución en la salida.

Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

Use la dirección URL de la consola para ir a la aplicación web en el explorador. Observe la salida de la aplicación en ejecución.

Instalación de la biblioteca cliente

La biblioteca cliente está disponible a través de NuGet, como paquete Microsoft.Azure.Cosmos.

Abra un terminal y vaya a la carpeta /src/web.
```
cd ./src/web
```
Si aún no está instalado, instale el paquete MongoDb.Driver mediante dotnet add package.
```
dotnet add package MongoDb.Driver
```
Además, instale el paquete Azure.Identity si aún no está instalado.
```
dotnet add package Azure.Identity
```

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.

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.

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 MongoDB, puede eliminar el grupo de recursos correspondiente.

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

az group delete --name $resourceGroupName

Use el cmdlet Remove-AzResourceGroup para eliminar el grupo de recursos.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters