Constrói uma aplicação de consola .NET com Azure DocumentDB

Este guia demonstra como construir uma aplicação de consola .NET para se ligar a um cluster Azure DocumentDB. Você configura seu ambiente de desenvolvimento, usa a Azure.Identity biblioteca do SDK do Azure para .NET para autenticar e interage com o banco de dados para criar, consultar e atualizar documentos.

Pré-requisitos

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

Um cluster do Azure DocumentDB existente
- Se não tiver um cluster, crie um novo cluster

Utilize o ambiente Bash no Azure Cloud Shell. Para mais informações, veja Get started with Azure Cloud Shell.
Se preferir executar comandos de referência da CLI localmente, instale o CLI do Azure. Se estiver a usar Windows ou macOS, considere executar o Azure CLI num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.
- Se você estiver usando uma instalação local, entre na CLI do Azure usando o comando az login . Para concluir o processo de autenticação, siga os passos exibidos no seu terminal. Para outras opções de entrada, consulte Autenticar no Azure usando a CLI do Azure.
- Quando solicitado, instale a extensão do Azure CLI na primeira utilização. Para obter mais informações sobre extensões, consulte Usar e gerenciar extensões com a CLI do Azure.
- Execute az version para descobrir a versão e as bibliotecas dependentes que estão instaladas. Para atualizar para a versão mais recente, execute az upgrade.

Autenticação do Microsoft Entra configurada para o cluster com o papel atribuído à sua identidade root.
- Para habilitar a autenticação do Microsoft Entra, consulte o guia de configuração.
Versão mais recente do .NET.

Recuperar metadados do inquilino do Microsoft Entra

Para recuperar um token de acesso usando a classe TokenCredential em Azure.Identity, precisa-se do identificador exclusivo para o inquilino do Microsoft Entra. Nesta etapa de pré-requisito, use a CLI do Azure para recuperar e registrar o tenantId valor.

Obtenha os detalhes da assinatura do Azure onde a sessão está iniciada usando az account show.
```
az account show
```

O comando gera uma resposta JSON contendo vários campos.

{
  "environmentName": "AzureCloud",
  "homeTenantId": "eeeeffff-4444-aaaa-5555-bbbb6666cccc",
  "id": "dddd3d3d-ee4e-ff5f-aa6a-bbbbbb7b7b7b",
  "isDefault": true,
  "managedByTenants": [],
  "name": "example-azure-subscription",
  "state": "Enabled",
  "tenantId": "eeeeffff-4444-aaaa-5555-bbbb6666cccc",
  "user": {
    "cloudShellID": true,
    "name": "kai@adventure-works.com",
    "type": "user"
  }
}

Registe o valor da propriedade tenantId. Essa propriedade é o identificador exclusivo para seu locatário do Microsoft Entra e às vezes é chamada de ID do locatário. Você usa esse valor em etapas dentro de uma seção subsequente.

Configurar seu aplicativo de console

Em seguida, crie um novo projeto de aplicativo de console e importe as bibliotecas necessárias para autenticar no cluster.

Em um diretório vazio, crie um novo aplicativo de console .NET.
```
dotnet new console
```
Importe o Azure.Identity pacote do NuGet.
```
dotnet add package Azure.Identity
```
Em seguida, importe o MongoDB.Driver pacote.
```
dotnet add package MongoDB.Driver
```
Criar o projeto .NET
```
dotnet build
```

Ligar ao cluster

Agora, use a Azure.Identity biblioteca para obter um TokenCredential para usar para se conectar ao seu cluster. O driver oficial do MongoDB tem uma interface especial que deve ser implementada para obter tokens do Microsoft Entra para uso ao se conectar ao cluster.

No arquivo Program.cs, adicione os blocos de ‘using’ para esses namespaces Azure.Identity e MongoDB.Driver.
```
using Azure.Identity;
using MongoDB.Driver;
```

Crie uma nova classe em um arquivo separado que implementa todos os membros necessários da MongoDB.Driver.Authentication.Oidc.IOidcCallback interface.

using Azure.Core;
using MongoDB.Driver.Authentication.Oidc;

internal sealed class AzureIdentityTokenHandler(
    TokenCredential credential,
    string tenantId
) : IOidcCallback
{
    private readonly string[] scopes = ["https://ossrdbms-aad.database.windows.net/.default"];

    public OidcAccessToken GetOidcAccessToken(OidcCallbackParameters parameters, CancellationToken cancellationToken)
    {
        AccessToken token = credential.GetToken(
            new TokenRequestContext(scopes, tenantId: tenantId),
            cancellationToken
        );

        return new OidcAccessToken(token.Token, token.ExpiresOn - DateTimeOffset.UtcNow);
    }

    public async Task<OidcAccessToken> GetOidcAccessTokenAsync(OidcCallbackParameters parameters, CancellationToken cancellationToken)
    {
        AccessToken token = await credential.GetTokenAsync(
            new TokenRequestContext(scopes, parentRequestId: null, tenantId: tenantId),
            cancellationToken
        );

        return new OidcAccessToken(token.Token, token.ExpiresOn - DateTimeOffset.UtcNow);
    }
}

Sugestão

Para fins ilustrativos, esta classe é denominada AzureIdentityTokenHandler. Você pode nomear essa classe como quiser. O resto deste guia assume que a classe é chamada AzureIdentityTokenHandler.

Volte para o editor do arquivo Program.cs .
Crie uma variável de cadeia de caracteres com o nome do cluster existente. Em seguida, use essa variável para criar uma nova instância do tipo MongoUrl usando MongoUrl.Create
```
string clusterName = "<azure-documentdb-cluster-name>";

MongoUrl url = MongoUrl.Create($"mongodb+srv://{clusterName}.global.mongocluster.cosmos.azure.com/");
```

Configure uma nova MongoSettings instância usando a MongoUrl criado nos passos prévios e a configuração padrão de boas práticas para o Azure DocumentDB.

MongoClientSettings settings = MongoClientSettings.FromUrl(url);

settings.UseTls = true;
settings.RetryWrites = false;
settings.MaxConnectionIdleTime = TimeSpan.FromMinutes(2);

Crie uma nova credencial do tipo DefaultAzureCredential.
```
DefaultAzureCredential credential = new();
```
Sugestão

Você pode usar qualquer credencial do tipo TokenCredential aqui. DefaultAzureCredential é a opção mais sem atrito para cenários de desenvolvimento inicial.
Crie uma nova instância da classe que implemente IOidcCallback e configure-a com o ID de cliente que registou anteriormente neste guia.
```
string tenantId = "<microsoft-entra-tenant-id>";

AzureIdentityTokenHandler tokenHandler = new(credential, tenantId);
```
Configure a credencial para as suas configurações usando MongoCredential.CreateOidcCredential e passando a implementação personalizada do manipulador de retorno de chamada.
```
settings.Credential = MongoCredential.CreateOidcCredential(tokenHandler);
```

Congele as configurações e crie uma nova instância do MongoClient.

settings.Freeze();

MongoClient client = new(settings);

Console.WriteLine("Client created");

Executar operações comuns

Finalmente, use a biblioteca oficial para executar tarefas comuns com bancos de dados, coleções e documentos. Aqui, você usa as mesmas classes e métodos que usaria para interagir com o MongoDB ou o Banco de Dados de Documentos para gerenciar suas coleções e itens.

Represente seus documentos criando um tipo de registro personalizado em seu próprio arquivo.
```
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    decimal price,
    bool clearance
);
```
Sugestão

Para fins ilustrativos, esta estrutura é denominada Product. O resto deste guia pressupõe que você já tenha essa estrutura definida.
Volte ao arquivo Program.cs .

Obtenha um ponteiro para seu banco de dados usando MongoClient.GetDatabase.

string databaseName = "<database-name>";

IMongoDatabase database = client.GetDatabase(databaseName);

Console.WriteLine("Database pointer created");

Em seguida, use o ponteiro do banco de dados para obter um ponteiro para sua coleção usando IMongoDatabase.GetCollection<>.

string collectionName = "<collection-name>";

IMongoCollection<Product> collection = database.GetCollection<Product>(collectionName);

Console.WriteLine("Collection pointer created");

Crie e atualize dois documentos usando o IMongoCollection<>.ReplaceOneAsync método.

Product classicSurfboard = new(
    id: "bbbbbbbb-1111-2222-3333-cccccccccccc",
    category: "gear-surf-surfboards",
    name: "Kiama Classic Surfboard",
    quantity: 25,
    price: 790.00m,
    clearance: false
);

Product paddleKayak = new(
    id: "cccccccc-2222-3333-4444-dddddddddddd",
    category: "gear-paddle-kayaks",
    name: "Lastovichka Paddle Kayak",
    quantity: 10,
    price: 599.99m,
    clearance: true
);

await collection.ReplaceOneAsync<Product>(
    doc => doc.id == classicSurfboard.id,
    classicSurfboard,
    new ReplaceOptions { IsUpsert = true }
);

Console.WriteLine($"Upserted document:\t{classicSurfboard.id}");

await collection.ReplaceOneAsync<Product>(
    doc => doc.id == paddleKayak.id,
    paddleKayak,
    new ReplaceOptions { IsUpsert = true }
);

Console.WriteLine($"Upserted document:\t{paddleKayak.id}");

Leia um único documento da coleção usando IMongoCollection<>.Find e IFindFluent<,>.SingleAsync. Use um filtro para especificar o documento específico que você gostaria de encontrar.
```
Product document = await collection.Find(
    doc => doc.id == "cccccccc-2222-3333-4444-dddddddddddd"
).SingleAsync();

Console.WriteLine($"Found document:\t{document.name}");
```
Consulta de todos os documentos que correspondem a um filtro usando o mesmo Find método. Use um filtro para definir uma propriedade específica (como category) e um valor específico (como gear-surf-surfboards). Enumere os resultados usando IFindFluent<,>.ToListAsync.
```
List<Product> documents = await collection.Find(
    doc => doc.category == "gear-surf-surfboards"
).ToListAsync();

foreach (Product doc in documents)
{
    Console.WriteLine($"Queried document:\t{doc}");
}
```

Exclua um documento específico da coleção usando IMongoCollection<>.DeleteOneAsync e um filtro.

await collection.DeleteOneAsync(
    doc => doc.id == "bbbbbbbb-1111-2222-3333-cccccccccccc"
);

Console.WriteLine($"Deleted document");

Salve todos os arquivos de código no projeto.
Execute o projeto usando dotnet run
```
dotnet run
```

Observe a saída do aplicativo em execução.

Client created
Database pointer created
Collection pointer created
Upserted document:      bbbbbbbb-1111-2222-3333-cccccccccccc
Upserted document:      cccccccc-2222-3333-4444-dddddddddddd
Found document: Lastovichka Paddle Kayak
Queried document:       Product { id = bbbbbbbb-1111-2222-3333-cccccccccccc, category = gear-surf-surfboards, name = Kiama Classic Surfboard, quantity = 25, price = 790.00, clearance = False }
Deleted document

Feedback

Esta página foi útil?

Last updated on 2025-11-19