Introdução ao Azure Cosmos DB for MongoDB usando o .NET

Artigo
08/15/2024

APLICA-SE AO: MongoDB

Este artigo mostra como se conectar ao Azure Cosmos DB for MongoDB usando o .NET Core e os pacotes NuGet relevantes. Depois de conectar-se, será possível executar operações em bancos de dados, coleções e documentos.

Observação

Os snippets de código de exemplo estão disponíveis no GitHub como um projeto .NET Core.

Documentação de referência da API for MongoDB | Pacote do MongoDB (NuGet)

Pré-requisitos

Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
.NET 6.0
Interface de linha de comando do Azure (CLI) ou Azure PowerShell
Recurso do Azure Cosmos DB for MongoDB

Criar um aplicativo .NET Core

Crie um aplicativo .NET Core em uma pasta vazia usando seu terminal de preferência. Para este cenário, você usará um aplicativo de console. Use o comando dotnet new para criar e nomear o aplicativo de console.
```
dotnet new console -o app
```
Adicione o pacote NuGet do MongoDB ao projeto do console. Use o dotnet add package comando que especifica o nome do pacote NuGet.
```
dotnet add package MongoDB.Driver
```
Para executar o aplicativo, use um terminal para navegar até o diretório do aplicativo e execute o aplicativo.
```
dotnet run
```

Conectar-se ao Azure Cosmos DB for MongoDB com o driver nativo do MongoDB

Para conectar-se ao Azure Cosmos DB com o driver nativo do MongoDB, crie uma instância da classe MongoClient. Essa classe é o ponto de partida para executar todas as operações em bancos de dados MongoDB. O construtor mais comum para MongoClient aceita uma cadeia de conexão, que pode ser recuperada seguindo estas etapas:

Obter nome do recurso

Crie uma variável de shell para resourceGroupName.

# Variable for resource group name
resourceGroupName="msdocs-cosmos"

Use o comando az cosmosdb list para recuperar o nome da primeira conta do Azure Cosmos DB em seu grupo de recursos e armazená-lo na variável de shell accountName.

# Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

Crie uma variável de shell para RESOURCE_GROUP_NAME.

# Variable for resource group name
$RESOURCE_GROUP_NAME = "msdocs-cosmos"

Use o cmdlet Get-AzCosmosDBAccountKey para recuperar o nome da primeira conta do Azure Cosmos DB em seu grupo de recursos e armazená-lo na variável de shell accountName.
```
# Get the name of the first Azure Cosmos DB account in your resource group
$ACCOUNT_NAME = (Get-AzCosmosDBAccount -ResourceGroupName $RESOURCE_GROUP_NAME)[0].Name
```

Recuperar sua cadeia de conexão

Localize a cadeia de conexão da API do MongoDB na lista de cadeias de conexão da conta com o comando az cosmosdb keys list.
```
az cosmosdb keys list --type connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName 
```
Copie os valores de PRIMARY KEY. Você usará essas credenciais mais tarde.

Localize CONNECTION STRING na lista de cadeias de conexão e chaves da conta com o cmdlet Get-AzCosmosDBAccountKey.

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    Type = "ConnectionStrings"
}    
Get-AzCosmosDBAccountKey @parameters |
    Select-Object -Property "Primary MongoDB Connection String"

Copie o valor de CONNECTION STRING. Você usará essas credenciais mais tarde.

Dica

Para este guia, é recomendável usar o nome do grupo de recursos msdocs-cosmos.

Entre no portal do Azure.
Navegue até a página da conta do Azure Cosmos DB for MongoDB existente.
Na página da conta do Azure Cosmos DB for MongoDB, selecione a opção do menu de navegação Cadeia de conexão.
Copie o valor do campo PRIMARY CONNECTION STRING. Você usa esse valor em uma etapa posterior.

Configurar variáveis de ambiente

Para usar os valores de CONNECTION STRING no código, defina esse valor no ambiente local que executa o aplicativo. Para definir a variável de ambiente, use seu terminal preferido para executar os seguintes comandos:

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

export COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

Um arquivo .env é uma maneira padrão de armazenar variáveis de ambiente em um projeto. Crie um arquivo .env na raiz do projeto. Adicione as linhas abaixo ao arquivo .env :

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

Criar MongoClient com cadeia de conexão

Defina uma nova instância da classe MongoClient usando o construtor e a variável de cadeia de conexão que você definiu anteriormente.

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

var settings = client.Settings;

Console.WriteLine(settings.Server.Host);

Usar classes do cliente do MongoDB com a API do Azure Cosmos DB para MongoDB

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 de banco de dados do Azure Cosmos DB, incluindo contas, bancos de dados, coleções e documentos.

Cada tipo de recurso é representado por uma ou mais classes C# associadas. Aqui está uma lista das classes mais comuns:

Classe	Descrição
`MongoClient`	Esta classe fornece a representação lógica do lado do cliente da camada da API para MongoDB no Azure Cosmos DB. Esse objeto do cliente é usado para configurar e executar solicitações no serviço.
`MongoDatabase`	Essa classe é uma referência a um banco de dados que pode, ou não, existir no serviço ainda. O banco de dados é validado ou criado no lado do servidor quando você tenta executar 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.

Os guias a seguir mostram como usar cada uma dessas classes para compilar o aplicativo e gerenciar dados.

Guia:

Confira também

Próximas etapas

Agora que você se conectou a uma conta da API para MongoDB, use o próximo guia para criar e gerenciar bancos de dados.

Criar um banco de dados no Azure Cosmos DB for MongoDB usando o .NET

Compartilhar via