Erstellen einer .NET-Konsolen-App mit Azure DocumentDB

In diesem Handbuch wird veranschaulicht, wie Sie eine .NET-Konsolenanwendung erstellen, um eine Verbindung mit einem Azure DocumentDB-Cluster herzustellen. Sie richten Ihre Entwicklungsumgebung ein, verwenden die Azure.Identity Bibliothek aus dem Azure SDK für .NET, um sich zu authentifizieren und mit der Datenbank zu interagieren, um Dokumente zu erstellen, abzufragen und zu aktualisieren.

Voraussetzungen

Ein Azure-Abonnement
- Wenn Sie nicht über ein Azure-Abonnement verfügen, erstellen Sie ein kostenloses Konto

Ein vorhandener Azure DocumentDB-Cluster
- Wenn Sie keinen Cluster haben, erstellen Sie einen neuen Cluster.

Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter "Erste Schritte mit Azure Cloud Shell".
Wenn Sie CLI-Referenzbefehle lieber lokal ausführen möchten, installieren Sie die Azure CLI. Wenn Sie mit Windows oder macOS arbeiten, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.
- Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Um den Authentifizierungsprozess abzuschließen, führen Sie die schritte aus, die in Ihrem Terminal angezeigt werden. Weitere Anmeldeoptionen finden Sie unter Authentifizieren bei Azure mithilfe der Azure CLI.
- Wenn Sie dazu aufgefordert werden, installieren Sie die Azure CLI-Erweiterung bei der ersten Verwendung. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden und Verwalten von Erweiterungen mit der Azure CLI.
- Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um auf die neueste Version zu aktualisieren.

Microsoft Entra-Authentifizierung ist für den Cluster konfiguriert, wobei Ihrer Identität die root Rolle zugewiesen wurde.
- Um die Microsoft Entra-Authentifizierung zu aktivieren, lesen Sie das Konfigurationshandbuch.
Neueste Version von .NET.

Abrufen von Metadaten zu Microsoft Entra-Mandanten

Zum Abrufen eines Zugriffstokens mithilfe der TokenCredential Klasse in Azure.Identitybenötigen Sie den eindeutigen Bezeichner für den Microsoft Entra-Mandanten. Verwenden Sie in diesem Erforderlichen Schritt die Azure CLI, um den tenantId Wert abzurufen und aufzuzeichnen.

Rufen Sie die Details für das aktuell angemeldete Azure-Abonnement mithilfe von az account show ab.
```
az account show
```

Der Befehl gibt eine JSON-Antwort mit verschiedenen Feldern aus.

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

Notieren Sie den Wert der tenantId Eigenschaft. Diese Eigenschaft ist der eindeutige Bezeichner für Ihren Microsoft Entra-Mandanten und wird manchmal als Mandanten-ID bezeichnet. Sie verwenden diesen Wert in den Schritten in einem nachfolgenden Abschnitt.

Konfigurieren der Konsolenanwendung

Erstellen Sie als Nächstes ein neues Konsolenanwendungsprojekt, und importieren Sie die erforderlichen Bibliotheken, um sich bei Ihrem Cluster zu authentifizieren.

Erstellen Sie in einem leeren Verzeichnis eine neue .NET-Konsolenanwendung.
```
dotnet new console
```
Importieren Sie das Azure.Identity Paket aus NuGet.
```
dotnet add package Azure.Identity
```
Importieren Sie als Nächstes das MongoDB.Driver Paket.
```
dotnet add package MongoDB.Driver
```
Erstellen des .NET-Projekts
```
dotnet build
```

Herstellen einer Verbindung mit dem Cluster

Verwenden Sie nun die Azure.Identity Bibliothek, um ein TokenCredential zu erhalten, das Sie verwenden können, um sich mit Ihrem Cluster zu verbinden. Der offizielle MongoDB-Treiber verfügt über eine spezielle Schnittstelle, die implementiert werden muss, um Token von Microsoft Entra für die Verwendung beim Herstellen einer Verbindung mit dem Cluster abzurufen.

Fügen Sie in der Datei Program.cs die Verwendung von Blöcken für die Namespaces Azure.Identity und MongoDB.Driver hinzu.
```
using Azure.Identity;
using MongoDB.Driver;
```

Erstellen Sie eine neue Klasse in einer separaten Datei, die alle erforderlichen Member der MongoDB.Driver.Authentication.Oidc.IOidcCallback Schnittstelle implementiert.

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

Tipp

Zu Veranschaulichungszwecken wird diese Klasse benannt AzureIdentityTokenHandler. Sie können diese Klasse beliebig benennen. Der Rest dieses Handbuchs geht davon aus, dass die Klasse benannt AzureIdentityTokenHandlerist.

Wechseln Sie zurück zum Editor für die Program.cs Datei.
Erstellen Sie eine Zeichenfolgenvariable mit dem Namen Des vorhandenen Clusters. Verwenden Sie dann diese Variable, um mithilfe von MongoUrl eine neue Instanz vom Typ MongoUrl.Create zu erstellen.
```
string clusterName = "<azure-documentdb-cluster-name>";

MongoUrl url = MongoUrl.Create($"mongodb+srv://{clusterName}.global.mongocluster.cosmos.azure.com/");
```
Konfigurieren Sie eine neue MongoSettings-Instanz mithilfe der in den vorherigen Schritten erstellten MongoUrl-Konfiguration und der Standardkonfiguration gemäß den Best Practices für Azure DocumentDB.
```
MongoClientSettings settings = MongoClientSettings.FromUrl(url);

settings.UseTls = true;
settings.RetryWrites = false;
settings.MaxConnectionIdleTime = TimeSpan.FromMinutes(2);
```
Erstellen Sie neue Anmeldeinformationen vom Typ DefaultAzureCredential.
```
DefaultAzureCredential credential = new();
```
Tipp

Sie können hier beliebige Anmeldeinformationen des Typs TokenCredential verwenden. DefaultAzureCredential ist die reibungsloseste Option für frühe Entwicklungsszenarien.
Erstellen Sie eine neue Instanz Ihrer Klasse, die IOidcCallback implementiert, und konfigurieren Sie sie mit der Mandanten-ID, die Sie sich weiter oben in diesem Leitfaden notiert haben.
```
string tenantId = "<microsoft-entra-tenant-id>";

AzureIdentityTokenHandler tokenHandler = new(credential, tenantId);
```
Konfigurieren Sie die Anmeldeinformationen für Ihre Einstellungen mithilfe von MongoCredential.CreateOidcCredential, und übergeben Sie die Rückrufimplementierung des benutzerdefinierten Handlers.
```
settings.Credential = MongoCredential.CreateOidcCredential(tokenHandler);
```

Fixieren Sie die Einstellungen, und erstellen Sie dann eine neue Instanz von MongoClient.

settings.Freeze();

MongoClient client = new(settings);

Console.WriteLine("Client created");

Ausführen gängiger Vorgänge

Verwenden Sie schließlich die offizielle Bibliothek, um allgemeine Aufgaben mit Datenbanken, Sammlungen und Dokumenten auszuführen. Hier verwenden Sie die gleichen Klassen und Methoden, mit denen Sie mit MongoDB oder DocumentDB interagieren würden, um Ihre Sammlungen und Elemente zu verwalten.

Stellen Sie Ihre Dokumente dar, indem Sie einen benutzerdefinierten Datensatztyp in einer eigenen Datei erstellen.
```
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    decimal price,
    bool clearance
);
```
Tipp

Zu Veranschaulichungszwecken wird diese Struktur benannt Product. Der Rest dieses Handbuchs geht davon aus, dass Sie diese Struktur bereits definiert haben.
Kehren Sie zurück zur Program.cs Datei zurück.

Rufen Sie mithilfe von MongoClient.GetDatabase einen Zeiger auf Ihre Datenbank ab.

string databaseName = "<database-name>";

IMongoDatabase database = client.GetDatabase(databaseName);

Console.WriteLine("Database pointer created");

Verwenden Sie dann den Datenbankzeiger, um mithilfe von IMongoDatabase.GetCollection<> einen Zeiger auf Ihre Auflistung abzurufen.

string collectionName = "<collection-name>";

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

Console.WriteLine("Collection pointer created");

Erstellen Sie mithilfe der -Methode zwei Dokumente, und führen Sie ein IMongoCollection<>.ReplaceOneAsync durch.

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

Lesen sie ein einzelnes Dokument aus der Sammlung mithilfe IMongoCollection<>.Find und IFindFluent<,>.SingleAsync. Verwenden Sie einen Filter, um das dokument anzugeben, das Sie suchen möchten.
```
Product document = await collection.Find(
    doc => doc.id == "cccccccc-2222-3333-4444-dddddddddddd"
).SingleAsync();

Console.WriteLine($"Found document:\t{document.name}");
```
Fragen Sie alle Dokumente ab, die einem Filter mit derselben Find Methode entsprechen. Verwenden Sie einen Filter, um eine bestimmte Eigenschaft (z. B. category) und einen bestimmten Wert (z. B. gear-surf-surfboards) zu definieren. Aufzählen der Ergebnisse mithilfe von 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}");
}
```

Löschen Sie ein bestimmtes Dokument aus der Auflistung mithilfe IMongoCollection<>.DeleteOneAsync und eines Filters.

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

Console.WriteLine($"Deleted document");

Speichern Sie alle Codedateien im Projekt.
Ausführen des Projekts mit dotnet run
```
dotnet run
```

Untersuchen Sie die Ausgabe der ausgeführten Anwendung.

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

War diese Seite hilfreich?

Last updated on 2025-11-19