Guia de início rápido: Azure Cosmos DB para MongoDB para .NET com o driver MongoDB

Artigo
03/28/2024

APLICA-SE A: MongoDB

Comece a usar o MongoDB para criar bancos de dados, coleções e documentos em seu recurso do Azure Cosmos DB. Siga estas etapas para implantar uma solução mínima em seu ambiente usando a CLI do Azure Developer.

Documentação | de referência da API para MongoDB Pacotes do pacote MongoDB (NuGet) /Microsoft.Azure.Cosmos) | CLI do desenvolvedor do Azure

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
Conta do GitHub

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
CLI do desenvolvedor do Azure
Área de trabalho do Docker

Configuração

Implante o contêiner de desenvolvimento deste projeto em seu ambiente. Em seguida, use a CLI do Desenvolvedor do Azure (azd) para criar uma conta do Azure Cosmos DB para MongoDB e implantar um aplicativo de exemplo em contêiner. O aplicativo de exemplo usa a biblioteca de cliente para gerenciar, criar, ler e consultar dados de exemplo.

Importante

As contas do GitHub incluem um direito de armazenamento e horas essenciais sem nenhum custo. Para obter mais informações, consulte armazenamento incluído e horas principais para contas do GitHub.

Abra um terminal no diretório raiz do projeto.
Autentique-se na CLI do Desenvolvedor do Azure usando azd auth logino . Siga as etapas especificadas pela ferramenta para autenticar na CLI usando suas credenciais preferidas do Azure.
```
azd auth login
```
Use azd init para inicializar o projeto.
```
azd init
```
Durante a inicialização, configure um nome de ambiente exclusivo.

Gorjeta

O nome do ambiente também será usado como o nome do grupo de recursos de destino. Para este guia de início rápido, considere usar msdocs-cosmos-db-o .
Implante a conta do Azure Cosmos DB usando azd upo . Os modelos Bicep também implantam um aplicativo Web de exemplo.
```
azd up
```
Durante o processo de provisionamento, selecione sua assinatura e o local desejado. Aguarde a conclusão do processo de provisionamento. O processo pode levar aproximadamente cinco minutos.

Depois que o provisionamento dos recursos do Azure for concluído, uma URL para o aplicativo Web em execução será incluída na saída.

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 o URL no console para navegar até seu aplicativo Web no navegador. Observe a saída do aplicativo em execução.

Instalar a biblioteca de cliente

A biblioteca do cliente está disponível através do NuGet, como o Microsoft.Azure.Cosmos pacote.

Abra um terminal e navegue até a /src/web pasta.
```
cd ./src/web
```
Se ainda não estiver instalado, instale o pacote usando dotnet add packageo MongoDb.Driver .
```
dotnet add package MongoDb.Driver
```
Além disso, instale o Azure.Identity pacote se ainda não estiver instalado.
```
dotnet add package Azure.Identity
```

Modelo de objeto

Antes de começar a criar o aplicativo, vamos examinar a hierarquia de recursos no Azure Cosmos DB. O Azure Cosmos DB tem um modelo de objeto específico usado para criar e acessar recursos. O Azure Cosmos DB cria recursos em uma hierarquia que consiste em contas, bancos de dados, coleções e documentos.

Diagrama da hierarquia do Azure Cosmos DB, incluindo contas, bancos de dados, coleções e documentos.

Você usará as seguintes classes do MongoDB para interagir com esses recursos:

MongoClient - Esta classe fornece uma representação lógica do lado do cliente para a camada API for MongoDB no Azure Cosmos DB. O objeto cliente é usado para configurar e executar solicitações no serviço.
MongoDatabase - Esta classe é uma referência a uma base de dados que pode, ou não, existir no serviço ainda. O banco de dados é validado no lado do servidor quando você tenta acessá-lo ou executar uma operação em relação a ele.
Collection - Esta classe é uma referência a uma coleção que também pode não existir no serviço ainda. A coleção é validada no lado do servidor quando você tenta trabalhar com ela.

O código de exemplo demonstrado neste artigo cria um banco de dados nomeado adventureworks com uma coleção chamada products. A products coleção foi projetada para conter detalhes do produto, como nome, categoria, quantidade e um indicador de venda. Cada produto também contém um identificador exclusivo.

Autenticar o cliente

No diretório do projeto, abra o arquivo Program.cs . No editor, adicione uma diretiva using para MongoDB.Driver.

using MongoDB.Driver;

Defina uma nova instância da classe usando o construtor e Environment.GetEnvironmentVariable leia a cadeia de MongoClient conexão definida anteriormente.

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

Criar uma base de dados

Use o MongoClient.GetDatabase método para criar um novo banco de dados se ele ainda não existir. Esse método retornará uma referência ao banco de dados existente ou recém-criado.

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

Criar uma coleção

O MongoDatabase.GetCollection criará uma nova coleção se ela ainda não existir e retornará uma referência à coleção.

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

Criar um item

A maneira mais fácil de criar um novo item em uma coleção é criar uma classe C# ou tipo de registro com todos os membros que você deseja serializar em JSON. Neste exemplo, o registro C# tem um identificador exclusivo, um campo de categoria para a chave de partição e campos extras de nome, quantidade e venda.

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

Crie um item na coleção usando o Product registro chamando 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
));

Obter um item

No Azure Cosmos DB, você pode recuperar itens compondo consultas usando Linq. No SDK, chame IMongoCollection.FindAsync<> e passe uma expressão C# para filtrar os 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);

Itens de consulta

Depois de inserir um item, você pode executar uma consulta para obter todos os itens que correspondem a um filtro específico tratando a coleção como um IQueryablearquivo . Este exemplo usa uma expressão para filtrar produtos por categoria. Depois que a chamada for AsQueryable feita, chame MongoQueryable.Where para recuperar um conjunto de itens 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);
}

Executar o código

Este aplicativo cria um banco de dados e uma coleção da API MongoDb do Azure Cosmos DB. Em seguida, o exemplo cria um item e, em seguida, lê exatamente o mesmo item de volta. Finalmente, o exemplo cria um segundo item e, em seguida, executa uma consulta que deve retornar vários itens. Com cada etapa, o exemplo envia metadados para o console sobre as etapas executadas.

Para executar o aplicativo, use um terminal para navegar até o diretório do aplicativo e executar o aplicativo.

dotnet run

A saída do aplicativo deve ser semelhante a este exemplo:

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

Clean up resources (Limpar recursos)

Quando não precisar mais da conta do Azure Cosmos DB para MongoDB, você poderá excluir o grupo de recursos correspondente.

Use o az group delete comando para excluir o grupo de recursos.

az group delete --name $resourceGroupName

Use o Remove-AzResourceGroup cmdlet para excluir o grupo de recursos.

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