Introducción a Azure Cosmos DB for MongoDB mediante .NET

SE APLICA A: MongoDB

En este artículo se muestra cómo conectarse para MongoDB de Azure Cosmos DB mediante .NET Core y los paquetes NuGet pertinentes. Una vez conectado, puede realizar operaciones en bases de datos, colecciones y documentos.

Nota

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

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

Requisitos previos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
• .NET 6.0
• Interfaz de la línea de comandos (CLI) de Azure o Azure PowerShell
• Azure Cosmos DB para el recurso de MongoDB

Creación de una aplicación .NET Core

1. Cree una nueva aplicación .NET Core en una carpeta vacía con su terminal preferido. En este escenario, usará una aplicación de consola. Use el comando dotnet new para crear la aplicación de consola y asignarle un nombre.

   dotnet new console -o app
   

2. Agregue el paquete NuGet de MongoDB al proyecto de consola. Use el comando dotnet add package especificando el nombre del paquete de NuGet.

   dotnet add package MongoDB.Driver
   

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

   dotnet run
   

Conexión a MongoDB de Azure Cosmos DB con el controlador nativo de MongoDB

Para conectarse a Azure Cosmos DB con el controlador nativo de MongoDB, cree una instancia de la clase MongoClient. Esta clase es el punto inicial para realizar todas las operaciones en bases de datos de MongoDB. El constructor más común para MongoClient acepta una cadena de conexión, que puede recuperar mediante los pasos siguientes:

Obtención del nombre del recurso

CLI de Azure

1. Cree una variable de shell para resourceGroupName.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos"
   

2. Use el comando az cosmosdb list para recuperar el nombre de la primera cuenta de Azure Cosmos DB del grupo de recursos y almacenarlo en la variable de shell accountName.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

PowerShell

1. Cree una variable de shell para RESOURCE_GROUP_NAME.

   # Variable for resource group name
   $RESOURCE_GROUP_NAME = "msdocs-cosmos"
   

2. Use el cmdlet Get-AzCosmosDBAccountKey para recuperar el nombre de la primera cuenta de Azure Cosmos DB del grupo de recursos y almacenarlo en la variable de shell accountName.

   # Get the name of the first Azure Cosmos DB account in your resource group
   $ACCOUNT_NAME = (Get-AzCosmosDBAccount -ResourceGroupName $RESOURCE_GROUP_NAME)[0].Name
   

Portal

Omita este paso y use la información del portal en el paso siguiente.

Recuperación de la cadena de conexión

CLI de Azure

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.

PowerShell

1. Busque CONNECTION STRING en la lista de claves y cadenas de conexión para la cuenta con el cmdlet Get-AzCosmosDBAccountKey.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary MongoDB Connection String"    
   

2. Registre el valor de CONNECTION STRING. Necesitará estas credenciales más adelante.

Portal

Sugerencia

Para esta guía, se recomienda usar el nombre del grupo de recursos msdocs-cosmos.

1. Inicie sesión en Azure Portal.

2. Vaya a la página de la cuenta de Azure Cosmos DB for MongoDB existente.

3. En la página de la cuenta de Azure Cosmos DB for MongoDB, seleccione la opción de menú de navegación Cadena de conexión.

4. Registre el valor del campo CADENA DE CONEXIÓN PRINCIPAL. Se usará este valor en un paso posterior.

   

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:

Windows

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

Linux/macOS

export COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

.env

Un archivo .env es una manera estándar de almacenar variables de entorno en un proyecto. Cree un archivo .env en el directorio raíz del proyecto. Agregue las líneas siguientes al archivo .env:

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

Creación de MongoClient con cadena de conexión

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

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

var settings = client.Settings;

Console.WriteLine(settings.Server.Host);

Uso de clases de cliente de MongoDB con Azure Cosmos DB para la API para MongoDB

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 jerárquico que muestra una cuenta de Azure Cosmos DB for MongoDB 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.

Cada tipo de recurso se representa mediante una o varias clases de C# asociadas. A continuación, se muestra una lista de las clases más comunes:

Clase	Descripción
MongoClient	Esta clase proporciona una representación lógica del cliente para la capa de 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 o no en el servicio. La base de datos se valida o crea en el lado servidor al intentar realizar una operación en ella.
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.

En las siguientes guías se muestra cómo usar cada una de estas clases para compilar la aplicación y administrar los datos.

Guía:

• Administración de bases de datos
• Administración de recopilaciones
• Administración de documentos
• Uso de consultas para buscar documentos

Consulte también

• Paquete (NuGet)
• Referencia de las API

Pasos siguientes

Ahora que se ha conectado a una cuenta de API para MongoDB, use la siguiente guía para crear y administrar bases de datos.

Creación de una base de datos en API para MongoDB de Azure Cosmos DB mediante .NET