Partilhar via


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

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

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.

Abrir no GitHub Codespaces

Abrir no contêiner de desenvolvimento

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.

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

  2. 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
    
  3. Use azd init para inicializar o projeto.

    azd init --template cosmos-db-mongodb-dotnet-quickstart
    

    Nota

    Este guia de início rápido usa o repositório GitHub azure-samples/cosmos-db-mongodb-dotnet-quickstart . A CLI do Desenvolvedor do Azure clonará automaticamente esse projeto para sua máquina se ela ainda não estiver lá.

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

  5. Implante a conta do Azure Cosmos DB usando azd upo . Os modelos 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 a conclusão do processo de provisionamento. 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 o 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 cliente

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

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

    cd ./src/web
    
  2. Se ainda não estiver instalado, instale o pacote usando dotnet add packageo MongoDb.Driver .

    dotnet add package MongoDb.Driver
    
  3. 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.

Diagrama hierárquico mostrando uma conta do Azure Cosmos DB na parte superior. A conta tem dois fragmentos de banco de dados filho. Um dos fragmentos de banco de dados inclui dois fragmentos de coleção filho. O outro fragmento de banco de dados inclui um único fragmento de coleção filho. Esse único fragmento de coleção tem três fragmentos de doc filho.

Você usa as seguintes classes 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 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 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.

Exemplos de código

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 pela CLI do Desenvolvedor do Azure 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 retorna 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 cria uma nova coleção se ela ainda não existir e retorna 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