Guia de Início Rápido: Azure Cosmos DB for MongoDB para .NET com o driver do MongoDB

  • Artigo

APLICA-SE AO: MongoDB

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

Documentação de referência da API para MongoDB | Pacote MongoDB (NuGet) pacotes/Microsoft.Azure.Cosmos) | Azure Developer CLI

Pré-requisitos

Configurando

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

Abrir em GitHub Codespaces

Abrir no Contêiner de Desenvolvimento

Importante

As contas do GitHub incluem um direito a horas de armazenamento e núcleo sem nenhum custo. Para obter mais informações, confira Horas de armazenamento e núcleo incluídas nas contas do GitHub.

  1. Abra um terminal no diretório raiz do projeto.

  2. Autentique-se no Azure Developer CLI usando azd auth login. Siga as etapas especificadas pela ferramenta para se autenticar na CLI usando suas credenciais preferenciais do Azure.

    azd auth login

  3. Execute azd init para inicializar o projeto.

    azd init

  4. Durante a inicialização, configure um nome de ambiente exclusivo.

    Dica

    O nome do ambiente também será usado como o nome do grupo de recursos de destino. Neste início rápido, considere o uso de msdocs-cosmos-db.

  5. Implante a conta do Azure Cosmos DB usando azd up. Os modelos do Bicep também implantam um aplicativo Web de exemplo.

    azd up

  6. Durante o processo de provisionamento, selecione sua assinatura e o local desejado. Aguarde o processo de provisionamento ser concluído. O processo pode levar aproximadamente cinco minutos.

  7. 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.

  8. Use a URL no console para navegar até seu aplicativo Web no navegador. Observe a saída do aplicativo em execução.

    Captura de tela do aplicativo Web em execução.

Instalar a biblioteca de clientes

A biblioteca de clientes está disponível por meio do NuGet, como o pacote Microsoft.Azure.Cosmos.

  1. Abra um terminal e vá até a pasta /src/web.

    cd ./src/web

  2. Se o pacote MongoDb.Driver ainda não estiver instalado, instale-o usando dotnet add package.

    dotnet add package MongoDb.Driver

  3. Instale também o pacote Azure.Identity, caso ainda não esteja 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 que é usado para criar e acessar recursos. Ele cria recursos em uma hierarquia que consiste em contas, bancos de dados, contêineres 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 a representação lógica do lado do cliente da camada da API do MongoDB no Azure Cosmos DB. Esse objeto do cliente é usado para configurar e executar solicitações no serviço.
  • MongoDatabase - Esta classe é uma referência a um banco 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 executa uma operação nele.
  • 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.

Exemplos de código

O código de exemplo demonstrado neste artigo cria um banco de dados chamado adventureworks com uma coleção chamada products. A coleção products 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 de uso para MongoDB.Driver.

using MongoDB.Driver;

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

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

Criar um banco de dados

Use o MongoClient.GetDatabasemétodo para criar um novo banco de dados se ele ainda não existir. Este 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 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 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 um nome extra, quantidade e campos de venda .

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

Crie um item na coleção usando o registro Product 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 redigindo 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 IQueryable. Este exemplo usa uma expressão para filtrar produtos por categoria. Após a chamada para AsQueryable ser 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

Esse aplicativo cria um banco de dados e uma coleção da API do MongoDB do Azure Cosmos DB. O exemplo cria um item e lê exatamente o mesmo item de volta. Por fim, o exemplo cria um segundo item e executa uma consulta que deve retornar vários itens. A cada etapa, o exemplo gera metadados para o console sobre as etapas executadas.

Para executar o aplicativo, use um terminal para navegar até o diretório do aplicativo e execute 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

Limpar os recursos

Quando a conta do Azure Cosmos DB for MongoDB não for mais necessária, exclua o grupo de recursos correspondente a ela.

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

az group delete --name $resourceGroupName