Creare un'app console .NET con Azure Cosmos DB per MongoDB vCore

2025-05-20
Si applica a: ✅ MongoDB (vCore)

Questa guida illustra come creare un'applicazione console .NET per connettersi a un cluster vCore di Azure Cosmos DB per MongoDB. È possibile configurare l'ambiente di sviluppo, usare la Azure.Identity libreria di Azure SDK per .NET per eseguire l'autenticazione e interagire con il database per creare, eseguire query e aggiornare i documenti.

Prerequisiti

Un cluster esistente di Azure Cosmos DB per MongoDB (vCore).

Versione più recente dell'interfaccia della riga di comando di Azure in Azure Cloud Shell.
- Se si preferisce eseguire i comandi CLI di riferimento in locale, accedere all'interfaccia della riga di comando di Azure usando il comando az login.

Autenticazione di Microsoft Entra configurata per il cluster con il ruolo dbOwner assegnato alla tua identità.
- Per abilitare l'autenticazione di Microsoft Entra, vedere la guida alla configurazione.
Versione più recente di .NET.

Recuperare i metadati del tenant di Microsoft Entra

Per recuperare un token di accesso usando la TokenCredential classe in Azure.Identity, è necessario l'identificatore univoco per il tenant di Microsoft Entra. In questo passaggio dei prerequisiti, utilizzare l'Azure CLI per recuperare e registrare il valore tenantId.

Ottenere i dettagli per la sottoscrizione di Azure attualmente registrata usando az account show.
```
az account show
```

Il comando restituisce una risposta JSON contenente vari campi.

{
  "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"
  }
}

Registrare il valore della tenantId proprietà . Questa proprietà è l'identificatore univoco per il tenant di Microsoft Entra e a volte viene definito ID tenant. Questo valore viene usato nei passaggi all'interno di una sezione successiva.

Configurare l'applicazione console

Creare quindi un nuovo progetto di applicazione console e importare le librerie necessarie per l'autenticazione nel cluster.

In una directory vuota creare una nuova applicazione console .NET.
```
dotnet new console
```
Importare il Azure.Identity pacchetto da NuGet.
```
dotnet add package Azure.Identity
```
Importare quindi il MongoDB.Driver pacchetto.
```
dotnet add package MongoDB.Driver
```
Compilare il progetto .NET
```
dotnet build
```

Connettersi al cluster

Ora, utilizza la libreria Azure.Identity per ottenere un TokenCredential da utilizzare per connetterti al cluster. Il driver Ufficiale di MongoDB ha un'interfaccia speciale che deve essere implementata per ottenere i token da Microsoft Entra per l'uso durante la connessione al cluster.

Nel file Program.cs, aggiungere blocchi using per questi namespace: Azure.Identity e MongoDB.Driver.
```
using Azure.Identity;
using MongoDB.Driver;
```

Creare una nuova classe in un file separato che implementa tutti i membri necessari dell'interfaccia MongoDB.Driver.Authentication.Oidc.IOidcCallback .

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);
    }
}

Suggerimento

Ai fini illustrativi, questa classe è denominata AzureIdentityTokenHandler. È possibile assegnare a questa classe qualsiasi nome desiderato. Nella parte restante di questa guida si presuppone che la classe sia denominata AzureIdentityTokenHandler.

Tornare all'editor per il file Program.cs .

Creare una variabile stringa con il nome del cluster esistente. Usare quindi tale variabile per creare una nuova istanza di tipo MongoUrl usando MongoUrl.Create

string clusterName = "<azure-cosmos-db-mongodb-vcore-cluster-name>";

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

Configurare una nuova MongoSettings istanza usando il MongoUrl creato nei passaggi precedenti e la configurazione della procedura consigliata standard per Azure Cosmos DB per MongoDB vCore.
```
MongoClientSettings settings = MongoClientSettings.FromUrl(url);

settings.UseTls = true;
settings.RetryWrites = false;
settings.MaxConnectionIdleTime = TimeSpan.FromMinutes(2);
```
Creare una nuova credenziale di tipo DefaultAzureCredential.
```
DefaultAzureCredential credential = new();
```
Suggerimento

Qui è possibile usare qualsiasi credenziale di tipo TokenCredential . DefaultAzureCredential è l'opzione più semplice per gli scenari di sviluppo iniziali.
Creare una nuova istanza della classe che implementa IOidcCallback e configurarla con l'ID tenant registrato in precedenza in questa guida.
```
string tenantId = "<microsoft-entra-tenant-id>";

AzureIdentityTokenHandler tokenHandler = new(credential, tenantId);
```
Configura la credenziale per le tue impostazioni usando MongoCredential.CreateOidcCredential e passando l'implementazione del callback del gestore personalizzato.
```
settings.Credential = MongoCredential.CreateOidcCredential(tokenHandler);
```

Bloccare le impostazioni e quindi creare una nuova istanza di MongoClient.

settings.Freeze();

MongoClient client = new(settings);

Console.WriteLine("Client created");

Eseguire operazioni comuni

Infine, usare la libreria ufficiale per eseguire attività comuni con database, raccolte e documenti. In questo caso si usano le stesse classi e metodi usati per interagire con MongoDB o DocumentDB per gestire le raccolte e gli elementi.

Rappresentare i documenti creando un tipo di record personalizzato nel proprio file.
```
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    decimal price,
    bool clearance
);
```
Suggerimento

A scopo illustrativo, questo struct è denominato Product. Nella parte restante di questa guida si presuppone che questo struct sia già definito.
Tornare al file di Program.cs .

Ottieni un puntatore al tuo database usando MongoClient.GetDatabase.

string databaseName = "<database-name>";

IMongoDatabase database = client.GetDatabase(databaseName);

Console.WriteLine("Database pointer created");

Quindi, utilizza il puntatore del database per ottenere un puntatore alla tua raccolta usando IMongoDatabase.GetCollection<>.

string collectionName = "<collection-name>";

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

Console.WriteLine("Collection pointer created");

Creare ed effettuare un upsert di due documenti utilizzando il metodo .

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

Leggere un singolo documento dalla raccolta usando IMongoCollection<>.Find e IFindFluent<,>.SingleAsync. Usare un filtro per specificare il documento specifico da trovare.

Product document = await collection.Find(
    doc => doc.id == "cccccccc-2222-3333-4444-dddddddddddd"
).SingleAsync();

Console.WriteLine($"Found document:\t{document.name}");

Eseguire una query per tutti i documenti che corrispondono a un filtro usando lo stesso Find metodo. Usare un filtro per definire una proprietà specifica ( ad esempio category) e un valore specifico (ad esempio gear-surf-surfboards). Enumerare i risultati 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}");
}
```

Eliminare un documento specifico dalla raccolta utilizzando IMongoCollection<>.DeleteOneAsync e un filtro.

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

Console.WriteLine($"Deleted document");

Salvare tutti i file di codice nel progetto.
Eseguire il progetto usando dotnet run
```
dotnet run
```

Osservare l'output dell'applicazione in esecuzione.

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

Condividi tramite

Creare un'app console .NET con Azure Cosmos DB per MongoDB vCore

Prerequisiti

Recuperare i metadati del tenant di Microsoft Entra

Configurare l'applicazione console

Connettersi al cluster

Eseguire operazioni comuni

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive