Criar um aplicativo de console do .NET com o Azure DocumentDB

Este guia demonstra como criar um aplicativo de console do .NET para se conectar a um cluster do Azure DocumentDB. Configure seu ambiente de desenvolvimento, use a Azure.Identity biblioteca do SDK do Azure para .NET para autenticação e interaja 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 existente do Azure DocumentDB
- Se você não tiver um cluster, crie um novo cluster

Utilize o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Introdução ao Azure Cloud Shell.
Se você preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se você estiver executando no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira 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 as etapas exibidas em seu terminal. Para obter outras opções de entrada, consulte Autenticar no Azure usando a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar e gerenciar extensões com a CLI do Azure.
- Execute o comando az version para localizar 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 sua identidade concedida à função root.
- Para habilitar a autenticação do Microsoft Entra, examine o guia de configuração.
Versão mais recente do .NET.

Recuperar metadados do locatário do Microsoft Entra

Para recuperar um token de acesso usando a classe TokenCredential em Azure.Identity, você precisa do identificador exclusivo do locatário 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 atualmente conectada 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"
  }
}

Registre o valor da propriedade tenantId. Essa propriedade é o identificador exclusivo do locatário do Microsoft Entra e, às vezes, é conhecida como a ID do locatário. Use esse valor em etapas em 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 do .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
```

Conectar-se ao cluster

Agora, use a biblioteca Azure.Identity para obter uma TokenCredential a ser usada para conectar-se ao 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 blocos de uso para esses Azure.Identity e MongoDB.Driver namespaces.
```
using Azure.Identity;
using MongoDB.Driver;
```

Crie uma nova classe em um arquivo separado que implemente 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);
    }
}

Dica

Para fins ilustrativos, essa classe é denominada AzureIdentityTokenHandler. Você pode nomear essa classe como quiser. O restante deste guia pressupõe que a classe seja nomeada 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 o MongoUrl criado nas etapas anteriores e a configuração de prática recomendada padrão 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();
```
Dica

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

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

Congele as configurações e, em seguida, crie uma nova instância de MongoClient.

settings.Freeze();

MongoClient client = new(settings);

Console.WriteLine("Client created");

Executar operações comuns

Por fim, 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 MongoDB ou DocumentDB 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
);
```
Dica

Para fins ilustrativos, esse struct é nomeado Product. O restante deste guia pressupõe que você já tenha esse struct definido.
Volte para o arquivo Program.cs .

Obtenha um ponteiro para o 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 a coleção usando IMongoDatabase.GetCollection<>.

string collectionName = "<collection-name>";

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

Console.WriteLine("Collection pointer created");

Crie e insira 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}");

Ler 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}");
```
Consulte 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). Enumerar 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.
Executar 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

Comentários

Esta página foi útil?

Last updated on 2025-11-19