Adicionar o Azure Cosmos DB ao seu aplicativo usando os Serviços Conectados do Visual Studio

Com o Visual Studio, você pode conectar qualquer um dos seguintes itens ao Azure Cosmos DB usando o recurso Serviços Conectados:

• Aplicativo de console do .NET Framework
• ASP.NET Modelo-Visão-Controlador (MVC) (estrutura .NET)
• ASP.NET Core
• .NET Core (incluindo aplicativo de console, WPF, Windows Forms, biblioteca de classes)
• Função de trabalho do .NET Core
• Funções do Azure
• Aplicativo da Plataforma Universal do Windows
• Xamarin
• Cordova

A funcionalidade do serviço conectado adiciona todas as referências necessárias e o código de conexão ao seu projeto, bem como modifica os arquivos de configuração adequadamente.

Pré-requisitos

• Visual Studio com a carga de trabalho do Azure instalada.
• Um projeto de um dos tipos com suporte
• Uma conta do Azure. Se você não tiver uma conta do Azure, ative seus benefícios do Azure para assinantes do Visual Studio ou inscreva-se para uma avaliação gratuita.

Conectar-se ao Azure Cosmos DB usando os Serviços Conectados

Observação

Para projetos .NET Framework, a interface do usuário dos Serviços Conectados é um pouco diferente. Para ver as diferenças, compare com a versão do Visual Studio 2019 desta página.

1. Abra o projeto no Visual Studio.

2. No Gerenciador de Soluções, clique com o botão direito do mouse no nó serviço Conectados e, no menu de contexto, selecione Adicionar para abrir o menu de serviços disponíveis.

   

   Se você não vir o nó Serviços conectados, escolha Projeto>Serviços conectados>Adicionar.

3. Escolha Azure Cosmos DB. A página Conectar-se à dependência é exibida. Você deve ver duas opções, uma para um emulador local, Emulador do Azure Cosmos DB no contêiner (Local) e outra para se conectar ao serviço do Azure Cosmos DB ativo. Você pode reduzir o custo e simplificar o desenvolvimento antecipado começando com o emulador local. Você pode migrar para o serviço ativo posteriormente repetindo essas etapas e escolhendo a outra opção.

   

   Se você optar por usar o Emulador do Azure Cosmos DB, clique em Avançar para ver a tela Resumo das alterações, que mostra como seu projeto está sendo modificado. Uma referência de pacote NuGet é adicionada ao seu projeto e o código de conexão do emulador local é adicionado ao seu projeto. Depois de clicar em Concluir na última tela, o contêiner do emulador será criado; você verá o status do download da imagem na janela de saída.

   Para se conectar ao serviço do Azure, prossiga para a próxima etapa ou, se ainda não estiver conectado, entre em sua conta do Azure antes de continuar. Se não tiver uma conta do Azure, você poderá assinar uma versão de avaliação gratuita.

4. Na tela do Azure Cosmos DB, selecione um Azure Cosmos DB existente e selecione Avançar.

   Se precisar criar um banco de dados, passe para a próxima etapa. Caso contrário, passe à etapa 7.

   

5. Para criar um Azure Cosmos DB:

   1. Selecione Criar um novo Azure Cosmos DB na parte inferior da tela.

   2. Preencha a tela Azure Cosmos DB: criar novo e selecione Criar.

      

   3. Quando a caixa de diálogo Configurar o Azure Cosmos DB é exibida, o novo banco de dados aparece na lista. Selecione o novo banco de dados na lista e selecione Avançar.

6. Insira um nome de cadeia de conexão e escolha se deseja que a cadeia de conexão seja armazenada em um arquivo de segredos local ou no Azure Key Vault.

   

   A cadeia de conexão é adicionada como um segredo e disponibilizada na configuração do aplicativo. Em aplicativos ASP.NET Core, você pode acessar essa cadeia de conexão usando a propriedade Configuration no objeto WebApplicationBuild.

7. A tela Resumo das alterações mostra todas as modificações que serão feitas no projeto se você concluir o processo. Se as alterações parecerem corretas, escolha Concluir.

   

8. No Gerenciador de Soluções, clique duas vezes no nó Serviços Conectados para abrir a guia Serviços Conectados. A conexão é exibida na seção Dependências de Serviço:

   

   Se você clicar nos três pontos ao lado da dependência adicionada, poderá ver várias opções, como Conectar para reabrir o assistente e alterar a conexão. Você também pode clicar nos três pontos no canto superior direito da janela para ver as opções para iniciar dependências locais, alterar as configurações e muito mais.

9. Por padrão, o limite de memória no contêiner é definido como 2G, mas normalmente, mais memória é necessária para executar o Azure Cosmos DB. Para corrigir isso, navegue até a pasta .vs/sd/<GUID>/local na pasta da solução. No Windows Explorer, talvez seja necessário habilitar arquivos ocultos para ver a pasta .vs. Localize e abra o arquivo cosmosdb1.docker-compose.yml. Defina um limite de memória 4G ou superior.

   mem_limit = 4G
   

   Para reiniciar o contêiner com a nova configuração, na seção Dependências de Serviço da guia Serviços Conectados, clique nos três pontos e escolha Iniciar dependências locais.

Observação

O emulador local do Cosmos DB pode fazer referência a uma imagem base que usa uma licença temporária para o Azure Cosmos DB. Se o contêiner não iniciar, verifique a guia Logs na janela Contêineres* para o contêiner do Azure Cosmos DB. Se ela mencionar um problema de expiração PAL, você precisará obter a imagem base mais recente para o contêiner local. Execute o seguinte comando no prompt do console: docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest. A licença é atualizada periodicamente e, quando expira, a atualização para o contêiner mais recente deve resolver o problema. Você pode exibir e informar problemas para o emulador do Azure Cosmos DB no Repositório GitHub do emulador do Azure Cosmos DB.

Próximas etapas

Saiba como armazenar segredos com segurança seguindo o Armazenamento seguro de segredos do aplicativo em desenvolvimento no ASP.NET Core. Em particular, para ler a cadeia de conexão do repositório de segredos, você poderá adicionar código como em Ler o segredo por meio da API de configuração. O código pode ter esta aparência, em que builder é uma instância do WebApplicationBuild que aparece em Program.cs em modelos de projeto ASP.NET Core:

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    connectionString: builder.Configuration["CosmosDBConnectionString"]
);

O CosmosClient fornece acesso à funcionalidade do Azure Cosmos DB por meio de vários métodos. Depois de ter uma instância do CosmosClient, você pode criar um banco de dados NoSQL seguindo este guia: Criar um banco de dados no Azure Cosmos DB for NoSQL usando o .NET.

Conteúdo relacionado

• Página do produto Azure Cosmos DB
• Documentação do Azure Cosmos DB
• Injeção de dependência no ASP.NET Core