Hinzufügen von Azure Cosmos DB zu Ihrer App mithilfe des Visual Studio-Features „Verbundene Dienste“

Mit Visual Studio können Sie über das Feature Verbundene Dienste eine Verbindung zwischen Azure Cosmos DB und jedem der folgenden Elemente herstellen:

• .NET Framework-Konsolen-App
• ASP.NET Model-View-Controller (MVC) (.NET Framework)
• ASP.NET Core
• .NET Core (einschließlich Konsolen-App, WPF, Windows Forms, Klassenbibliothek)
• .NET Core-Workerrolle
• Azure-Funktionen
• App für Universelle Windows-Plattform
• Xamarin
• Cordova

Mit der Funktion für verbundene Dienste werden die benötigten Verweise und der Verbindungscode zu Ihrem Projekt hinzugefügt und Ihre Konfigurationsdateien entsprechend geändert.

Voraussetzungen

• Visual Studio mit installierter Azure-Workload
• Ein Projekt eines unterstützten Typs
• Ein Azure-Konto. Wenn Sie nicht über ein Azure-Konto verfügen, aktivieren Sie Ihre Azure-Nutzen für Visual Studio-Abonnenten oder registrieren Sie sich für eine kostenlose Testversion.

Herstellen einer Verbindung mit Azure Cosmos DB über das Feature „Verbundene Dienste“

Hinweis

Bei .NET Framework-Projekten unterscheidet sich die Benutzeroberfläche von Verbundene Dienste geringfügig. Um die Unterschiede zu sehen, vergleichen Sie sie mit der Visual Studio 2019-Version dieser Seite.

1. Öffnen Sie Ihr Projekt in Visual Studio.

2. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Knoten Verbundene Dienste, und wählen Sie im Kontextmenü Hinzufügen aus, um das Menü verfügbarer Dienste zu öffnen.

   

   Wenn der Knoten Verbundene Dienste nicht angezeigt wird, wählen Sie Projekt>Verbundene Dienste>Hinzufügen aus.

3. Wählen Sie Azure Cosmos DB aus. Die Seite Mit Abhängigkeit verbinden wird angezeigt. Es sollten zwei Optionen angezeigt werden: eine für einen lokalen Emulator, Azure Cosmos DB-Emulator im Container (lokal), und eine für die Verbindung mit dem aktiven Azure Cosmos DB-Dienst. Sie können die Kosten senken und die frühe Entwicklung vereinfachen, indem Sie mit dem lokalen Emulator beginnen. Sie können später zum Livedienst migrieren, indem Sie diese Schritte wiederholen und die andere Option auswählen.

   

   Wenn Sie den Azure Cosmos DB-Emulator verwenden möchten, klicken Sie auf Weiter, um den Bildschirm Zusammenfassung der Änderungen anzuzeigen, der zeigt, wie Ihr Projekt geändert wird. Ihrem Projekt werden ein NuGet-Paketverweis und der Verbindungscode für den lokalen Emulator hinzugefügt. Sobald Sie auf dem letzten Bildschirm auf Fertig stellen geklickt haben, wird der Container für den Emulator erstellt. Im Ausgabefenster wird der Status des Bilddownloads angezeigt.

   Wenn Sie eine Verbindung mit dem Azure-Dienst herstellen möchten, fahren Sie mit dem nächsten Schritt fort, oder melden Sie sich bei Ihrem Azure-Konto an, bevor Sie fortfahren, falls Sie noch nicht angemeldet sind. Wenn Sie nicht über ein Azure-Konto verfügen, können Sie sich für eine kostenlose Testversionregistrieren.

4. Wählen Sie auf dem Bildschirm Azure Cosmos DB eine vorhandene Azure Cosmos DB-Instanz und dann Weiter aus.

   Wenn Sie eine neue Datenbank erstellen müssen, fahren Sie mit dem nächsten Schritt fort. Andernfalls fahren Sie mit Schritt 7 fort.

   

5. So erstellen Sie eine Azure Cosmos DB-Instanz

   1. Wählen Sie unten auf dem Bildschirm Neue Azure Cosmos DB-Instanz erstellen aus.

   2. Füllen Sie den Bildschirm Azure Cosmos DB: Neu erstellen aus, und wählen Sie Erstellen aus.

      

   3. Wenn das Dialogfeld Azure Cosmos DB konfigurieren angezeigt wird, wird die neue Datenbank in der Liste angezeigt. Wählen Sie die neue Datenbank in der Liste und dann Weiter aus.

6. Geben Sie einen Namen für die Verbindungszeichenfolge ein, und wählen Sie aus, ob die Verbindungszeichenfolge in einer lokalen Geheimnisdatei oder in Azure Key Vault gespeichert werden soll.

   

   Die Verbindungszeichenfolge wird als Geheimnis hinzugefügt und in der App-Konfiguration verfügbar gemacht. In ASP.NET Core-Apps können Sie auf diese Verbindungszeichenfolge zugreifen, indem Sie die Configuration-Eigenschaft für das WebApplicationBuild-Objekt verwenden.

7. Auf dem Bildschirm Zusammenfassung der Änderungen werden alle Änderungen angezeigt, die an Ihrem Projekt vorgenommen werden, wenn Sie den Vorgang abschließen. Wenn die Änderungen korrekt sind, wählen Sie Fertig stellen aus.

   

8. Doppelklicken Sie im Projektmappen-Explorer auf den Knoten Verbundene Dienste, um die Registerkarte Verbundene Dienste zu öffnen. Die Verbindung wird im Abschnitt Dienstabhängigkeiten angezeigt:

   

   Wenn Sie auf die drei Punkte neben der von Ihnen hinzugefügten Abhängigkeit klicken, werden verschiedene Optionen angezeigt, z. B. Verbinden, um den Assistenten erneut zu öffnen und die Verbindung zu ändern. Sie können auch oben rechts im Fenster auf die drei Punkte klicken, um Optionen zum Starten lokaler Abhängigkeiten, Ändern von Einstellungen und mehr anzuzeigen.

9. Standardmäßig ist das Speicherlimit im Container auf 2 GB festgelegt, aber normalerweise ist mehr Speicher erforderlich, um Azure Cosmos DB auszuführen. Um dieses Problem zu beheben, navigieren Sie zum Ordner .vs/sd/<GUID>/local unter Ihrem Lösungsordner. In Windows Explorer müssen Sie möglicherweise ausgeblendete Dateien aktivieren, um den Ordner .vs anzuzeigen. Suchen und öffnen Sie die Datei cosmosdb1.docker-compose.yml. Legen Sie das Arbeitsspeicherlimit auf 4G oder höher fest.

   mem_limit = 4G
   

   Um den Container mit der neuen Einstellung neu zu starten, klicken Sie auf der Registerkarte Verbundene Dienste im Abschnitt Dienstabhängigkeiten auf die drei Punkte und wähle Sie Lokale Abhängigkeiten starten.

Hinweis

Der lokale Emulator für Azure Cosmos DB kann auf ein Basis-Image verweisen, das eine temporäre Lizenz für Azure Cosmos DB verwendet. Wenn der Container nicht startet, überprüfen Sie die Registerkarte Logs im Fenster Containers* für den Azure Cosmos DB-Container. Wenn ein Problem mit dem PAL-Ablauf angezeigt wird, müssen Sie für den lokalen Container das neueste Basisimage abrufen. Führen Sie an der Eingabeaufforderung der Konsole den folgenden Befehl aus: docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest. Die Lizenz wird regelmäßig aktualisiert, und wenn sie abläuft, sollte durch die Aktualisierung auf den neuesten Container das Problem behoben werden. Sie können Probleme für den Azure Cosmos DB-Emulator im Azure Cosmos DB-Emulator GitHub Repo einsehen und melden.

Nächste Schritte

Informationen zum sicheren Speichern von Geheimnissen finden Sie unter Sichere Speicherung von App-Geheimnissen in der Entwicklung in ASP.NET Core. Um insbesondere die Verbindungszeichenfolge aus dem Geheimnisspeicher zu lesen, können Sie wie in Lesen des Geheimnisses über die Konfigurations-API beschrieben Code hinzufügen. Der Code könnte wie folgt aussehen, wobei builder eine Instanz von WebApplicationBuild ist, die in Program.cs in ASP.NET Core-Projektvorlagen erscheint:

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    connectionString: builder.Configuration["CosmosDBConnectionString"]
);

Die CosmosClient bietet durch ihre verschiedenen Methoden Zugang zur Azure Cosmos DB-Funktionalität. Sobald Sie eine Instanz von CosmosClient haben, können Sie eine NoSQL-Datenbank erstellen, indem Sie diese Anleitung befolgen: Erstellen einer Datenbank in Azure Cosmos DB for NoSQL mit .NET.

Zugehöriger Inhalt

• Produktseite für Azure Cosmos DB
• Dokumentation zu Azure Cosmos DB
• Abhängigkeitsinjektion in ASP.NET Core