Início Rápido: Usar o Azure DocumentDB com o driver do MongoDB para C#

Neste início rápido, você criará um aplicativo básico do Azure DocumentDB usando C#. O Azure DocumentDB é um armazenamento de dados NoSQL que permite que os aplicativos armazenem documentos na nuvem e os acessem usando drivers oficiais do MongoDB. Este guia mostra como criar documentos e executar tarefas básicas em seu cluster do Azure DocumentDB usando C#.

Referência de API | Código-fonte | Pacote (NuGet)

Pré-requisitos

• Uma assinatura do Azure

  • Se você não tiver uma assinatura do Azure, crie uma conta gratuita

• .NET 10.0 ou posterior

Criar um cluster do Azure DocumentDB

Para começar, primeiro você precisa criar um cluster do Azure DocumentDB, que serve como base para armazenar e gerenciar seus dados NoSQL.

1. Entre no portal do Azure (https://portal.azure.com).

2. No menu do portal do Azure ou na Home page, selecione Criar um recurso.

3. Na página Novo , pesquise e selecione o Azure DocumentDB.

   

4. Na página Criar cluster do Azure DocumentDB e na seção Configurações básicas, selecione a opção Configurar na seção Camada Cluster.

   

5. Na página Dimensionar , configure essas opções e, em seguida, selecione Salvar para persistir suas alterações na camada de cluster.

   	Value
   Nível do cluster	M30 tier, 2 vCore, 8-GiB RAM
   Armazenamento por fragmento	128 GiB

   

6. De volta à seção Noções básicas , configure as seguintes opções:

   	Value
   Subscription	Selecione sua Assinatura do Azure.
   Grupo de recursos	Crie um novo grupo de recursos ou escolha um grupo de recursos existente
   Nome do cluster	Forneça um nome global exclusivo
   Localidade	Escolha uma região do Azure compatível com sua assinatura
   Versão do MongoDB	Selecione 8.0
   Nome de usuário do administrador	Criar um nome de usuário para acessar o cluster como administrador de usuário
   Senha	Usar uma senha exclusiva associada ao nome de usuário

   

   Dica

   Registre os valores usados para nome de usuário e senha. Esses valores são usados posteriormente neste guia. Para obter mais informações sobre valores válidos, consulte as limitações do cluster.

7. Selecione Avançar: Rede.

8. Na seção Regras de Firewall na guia Rede , configure estas opções:

   	Value
   Método de conectividade	Public access
   Permitir acesso público de serviços e recursos do Azure dentro do Azure para esse cluster	Habilitado

9. Adicione uma regra de firewall para o dispositivo cliente atual para conceder acesso ao cluster selecionando + Adicionar endereço IP do cliente atual.

   

   Dica

   Em muitos ambientes corporativos, os endereços IP do computador do desenvolvedor ficam ocultos devido a uma VPN ou outras configurações de rede corporativa. Nesses casos, você pode permitir temporariamente o acesso a todos os endereços IP adicionando o 0.0.0.0 - 255.255.255.255 intervalo de endereços IP como uma regra de firewall. Use essa regra de firewall apenas temporariamente como parte do teste de conexão e do desenvolvimento.

10. Selecione Examinar + criar.

11. Examine as configurações fornecidas e selecione Criar. São necessários alguns minutos para criar o cluster. Aguarde a conclusão da implantação do recurso.

12. Por fim, selecione Ir para o recurso para navegar até o cluster do Azure DocumentDB no portal.

Obter credenciais do cluster

Obtenha as credenciais que você usa para se conectar ao cluster.

1. Na página do cluster, selecione a opção Cadeias de conexão no menu de recursos.

2. Na seção Cadeias de conexão , copie ou registre o valor do campo Cadeia de conexão .

Inicializar o projeto

Crie um novo projeto de aplicativo de console do .NET em seu diretório atual.

1. Inicie em um diretório vazio.

2. Abra um terminal no diretório atual.

3. Crie um novo aplicativo de console do .NET.

   dotnet new console
   

4. Construa o projeto para garantir que foi criado com êxito.

   dotnet build
   

Instalar a biblioteca de clientes

A biblioteca de clientes está disponível por meio do NuGet, como o pacote MongoDB.Driver.

1. Instale o driver .NET do MongoDB usando o gerenciador de pacotes NuGet.

   dotnet add package MongoDB.Driver
   

2. Abra e examine o arquivo azure-documentdb-dotnet-quickstart.csproj para validar se a referência do pacote existe.

3. Importe os namespaces necessários para o código do aplicativo:

   using System;
   using System.Collections.Generic;
   using System.Threading.Tasks;
   using MongoDB.Bson;
   using MongoDB.Bson.Serialization.Attributes;
   using MongoDB.Driver;
   

Modelo de objeto

Exemplos de código

• Autenticar o cliente
• Consiga uma coleção
• Criar um documento
• Recuperar um documento
• Consultar documentos

O código neste aplicativo se conecta a um banco de dados nomeado adventureworks e a uma coleção chamada products. A products coleção contém detalhes como nome, categoria, quantidade, um identificador exclusivo e um sinalizador de venda para cada produto. Os exemplos de código aqui executam as operações mais comuns ao trabalhar com uma coleção.

Autenticar o cliente

Primeiro, conecte-se ao cliente usando uma cadeia de conexão básica.

1. Crie o método principal e configure a cadeia de conexão. Substitua <your-cluster-name>, <your-username>e <your-password> com suas informações reais do cluster.

   class Program
   {
       static async Task Main(string[] args)
       {
           // Connection string for Azure DocumentDB cluster
           string connectionString = "mongodb+srv://<your-username>:<your-password>@<your-cluster-name>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000";
   
           // Create MongoDB client settings
           var settings = MongoClientSettings.FromConnectionString(connectionString);
   

2. Crie o cliente MongoDB e verifique a conexão.

           // Create a new client and connect to the server
           var client = new MongoClient(settings);
   
           // Ping the server to verify connection
           var database = client.GetDatabase("admin");
           var pingCommand = new BsonDocument("ping", 1);
           await database.RunCommandAsync<BsonDocument>(pingCommand);
   
           Console.WriteLine("Successfully connected and pinged Azure DocumentDB");
   

Adquirir uma coleção

Agora, obtenha seu banco de dados e coleção. Se o banco de dados e a coleção ainda não existirem, use o driver para criá-lo automaticamente.

1. Obtenha uma referência ao banco de dados.

           // Get database reference
           var adventureWorksDatabase = client.GetDatabase("adventureworks");
           Console.WriteLine($"Connected to database: {adventureWorksDatabase.DatabaseNamespace.DatabaseName}");
   

2. Obtenha uma referência à coleção no banco de dados.

           // Get collection reference
           var productsCollection = adventureWorksDatabase.GetCollection<Product>("products");
           Console.WriteLine($"Connected to collection: products");
   

Criar um documento

Em seguida, crie alguns documentos novos em sua coleção. Insira ou atualize os documentos para garantir que eles substituam qualquer documento existente se já houver um com o mesmo identificador exclusivo.

1. Defina uma classe Product e crie documentos de produto de exemplo.

           // Create sample products
           var products = new List<Product>
           {
               new Product
               {
                   Id = "00000000-0000-0000-0000-000000004018",
                   Name = "Windry Mittens",
                   Category = "apparel-accessories-gloves-and-mittens",
                   Quantity = 121,
                   Price = 35.00m,
                   Sale = false
               },
               new Product
               {
                   Id = "00000000-0000-0000-0000-000000004318",
                   Name = "Niborio Tent",
                   Category = "gear-camp-tents",
                   Quantity = 140,
                   Price = 420.00m,
                   Sale = true
               }
           };
   

2. Insira os documentos usando operações upsert.

           // Insert documents with upsert
           foreach (var product in products)
           {
               var filter = Builders<Product>.Filter.Eq(p => p.Id, product.Id);
               var options = new ReplaceOptions { IsUpsert = true };
   
               await productsCollection.ReplaceOneAsync(filter, product, options);
               Console.WriteLine($"Upserted product: {product.Name}");
           }
   

3. Adicione a definição da classe Product no final do arquivo Program.cs.

   public class Product
   {
       [BsonId]
       [BsonElement("_id")]
       public string Id { get; set; }
   
       [BsonElement("name")]
       public string Name { get; set; }
   
       [BsonElement("category")]
       public string Category { get; set; }
   
       [BsonElement("quantity")]
       public int Quantity { get; set; }
   
       [BsonElement("price")]
       public decimal Price { get; set; }
   
       [BsonElement("sale")]
       public bool Sale { get; set; }
   }
   

Recuperar um documento

Em seguida, execute uma operação de leitura de ponto para recuperar um documento específico de sua coleção.

1. Defina o filtro para localizar um documento específico por ID.

           // Retrieve a specific document by ID
           var filter = Builders<Product>.Filter.Eq(p => p.Id, "00000000-0000-0000-0000-000000004018");
   

2. Execute a consulta e recupere o resultado.

           var retrievedProduct = await productsCollection.Find(filter).FirstOrDefaultAsync();
   
           if (retrievedProduct != null)
           {
               Console.WriteLine($"Retrieved product: {retrievedProduct.Name} - ${retrievedProduct.Price}");
           }
           else
           {
               Console.WriteLine("Product not found");
           }
   

Consultar documentos

Por fim, consulte vários documentos usando a Linguagem de Consulta do MongoDB (MQL).

1. Defina uma consulta para localizar documentos que correspondam a critérios específicos.

           // Query for products on sale
           var saleFilter = Builders<Product>.Filter.Eq(p => p.Sale, true);
           var saleProducts = await productsCollection.Find(saleFilter).ToListAsync();
   

2. Percorra os resultados para exibir os documentos correspondentes.

           Console.WriteLine("Products on sale:");
           foreach (var product in saleProducts)
           {
               Console.WriteLine($"- {product.Name}: ${product.Price:F2} (Category: {product.Category})");
           }
       }
   }
   

Explorar seus dados usando o Visual Studio Code

Use a extensão do DocumentDB no Visual Studio Code para executar operações de banco de dados principais, incluindo consulta, inserção, atualização e exclusão de dados.

1. Abra o Visual Studio Code.

2. Navegue até a visualização de Extensões e pesquise o termo DocumentDB. Localize a extensão DocumentDB for VS Code.

3. Selecione o botão Instalar para a extensão. Aguarde a conclusão da instalação. Recarregue o Visual Studio Code, se for solicitado.

4. Navegue até a extensão do DocumentDB selecionando o ícone correspondente na Barra de Atividades.

5. No painel Conexões do DocumentDB , selecione + Nova Conexão....

6. Na caixa de diálogo, selecione Descoberta de Serviço e, em seguida , Azure DocumentDB – Descoberta de Serviço do Azure.

7. Selecione sua assinatura do Azure e seu cluster do Azure DocumentDB recém-criado.

   Dica

   Em muitos ambientes corporativos, os endereços IP do computador do desenvolvedor ficam ocultos devido a uma VPN ou outras configurações de rede corporativa. Nesses casos, você pode permitir temporariamente o acesso a todos os endereços IP adicionando o 0.0.0.0 - 255.255.255.255 intervalo de endereços IP como uma regra de firewall. Use essa regra de firewall apenas temporariamente como parte do teste de conexão e do desenvolvimento. Para obter mais informações, consulte configurar o firewall.

8. De volta ao painel Conexões do DocumentDB, expanda o nó do seu cluster e navegue até os nós de documento e coleção existentes.

9. Abra o menu de contexto da coleção e, em seguida, selecione > Novo DocumentDB Scrapbook.

10. Insira os seguintes comandos MQL (Linguagem de Consulta do MongoDB) e selecione Executar Tudo. Observe a saída dos comandos.

    db.products.find({
      price: { $gt: 200 },
      sale: true
    })
    .sort({ price: -1 })
    .limit(3)
    

Limpar os recursos

Quando terminar de usar o cluster do Azure DocumentDB, você poderá excluir os recursos do Azure criados para não incorrer em mais encargos.

1. Na barra de pesquisa do portal do Azure, procure e selecione Grupos de recursos.

   

2. Na lista, selecione o grupo de recursos criado neste início rápido.

   

3. Na página Grupo de recursos, selecione Excluir grupo de recursos.

4. Na caixa de diálogo de confirmação de exclusão, insira o nome do grupo de recursos para confirmar que você pretende excluí-lo. Por fim, selecione Excluir para excluir permanentemente o grupo de recursos.

   

Conteúdo relacionado

• O que é o Azure DocumentDB?