Verwenden einer Azure Cosmos DB-Dokumentdatenbank in Xamarin.Forms

Das Beispiel herunterladen

Eine Azure Cosmos DB-Dokumentdatenbank ist eine NoSQL-Datenbank, die zugriff auf JSON-Dokumente mit geringer Latenz ermöglicht und einen schnellen, hochverfügbaren, skalierbaren Datenbankdienst für Anwendungen bietet, die eine nahtlose Skalierung und globale Replikation erfordern. In diesem Artikel wird erläutert, wie Sie die .NET Standard-Clientbibliothek von Azure Cosmos DB verwenden, um eine Azure Cosmos DB-Dokumentdatenbank in eine Xamarin.Forms Anwendung zu integrieren.

Microsoft Azure Cosmos DB-Video

Ein Azure Cosmos DB-Dokumentdatenbankkonto kann mithilfe eines Azure-Abonnements bereitgestellt werden. Jedes Datenbankkonto kann über null oder mehr Datenbanken verfügen. Eine Dokumentdatenbank in Azure Cosmos DB ist ein logischer Container für Dokumentsammlungen und -benutzer.

Eine Azure Cosmos DB-Dokumentdatenbank kann null oder mehr Dokumentsammlungen enthalten. Jede Dokumentsammlung kann eine andere Leistungsstufe aufweisen, sodass für Sammlungen, auf die häufig zugegriffen wird, mehr Durchsatz und weniger Durchsatz für Sammlungen, auf die selten zugegriffen wird, angegeben werden kann.

Jede Dokumentsammlung besteht aus null oder mehr JSON-Dokumenten. Dokumente in einer Sammlung sind schemafrei und müssen daher nicht dieselbe Struktur oder Felder verwenden. Wenn Dokumente zu einer Dokumentsammlung hinzugefügt werden, indiziert Azure Cosmos DB sie automatisch, und sie können abgefragt werden.

Zu Entwicklungszwecken kann eine Dokumentdatenbank auch über einen Emulator genutzt werden. Mithilfe des Emulators können Anwendungen lokal entwickelt und getestet werden, ohne ein Azure-Abonnement zu erstellen oder Kosten zu verursachen. Weitere Informationen zum Emulator finden Sie unter Entwickeln lokal mit dem Azure Cosmos DB-Emulator.

In diesem Artikel und der begleitenden Beispielanwendung wird eine Todo-Listenanwendung veranschaulicht, bei der die Aufgaben in einer Azure Cosmos DB-Dokumentdatenbank gespeichert werden. Weitere Informationen zur Beispielanwendung finden Sie unter Grundlegendes zum Beispiel.

Weitere Informationen zu Azure Cosmos DB finden Sie in der Azure Cosmos DB-Dokumentation.

Hinweis

Wenn Sie kein Azure-Abonnement besitzen, erstellen Sie ein kostenloses Konto, bevor Sie beginnen.

Einrichten

Der Prozess zum Integrieren einer Azure Cosmos DB-Dokumentdatenbank in eine Xamarin.Forms Anwendung sieht wie folgt aus:

1. Erstellung eines Azure Cosmos DB-Kontos. Weitere Informationen finden Sie unter Erstellen eines Azure Cosmos DB-Kontos.
2. Fügen Sie den Plattformprojekten in Xamarin.Forms der Projektmappe das NuGet-Paket der Azure Cosmos DB .NET Standard-Clientbibliothek hinzu.
3. Fügen Sie using Anweisungen für die Microsoft.Azure.DocumentsNamespaces , Microsoft.Azure.Documents.Clientund Microsoft.Azure.Documents.Linq zu Klassen hinzu, die auf das Azure Cosmos DB-Konto zugreifen.

Nachdem Sie diese Schritte ausgeführt haben, kann die Azure Cosmos DB .NET Standard-Clientbibliothek verwendet werden, um Anforderungen für die Dokumentdatenbank zu konfigurieren und auszuführen.

Hinweis

Die .NET Standard-Clientbibliothek von Azure Cosmos DB kann nur in Plattformprojekten und nicht in einem PCL-Projekt (Portable Class Library) installiert werden. Daher ist die Beispielanwendung ein Shared Access Project (SAP), um Codeduplizierung zu vermeiden. Die DependencyService -Klasse kann jedoch in einem PCL-Projekt zum Aufrufen von Azure Cosmos DB .NET Standard-Clientbibliothekscode verwendet werden, der in plattformspezifischen Projekten enthalten ist.

Verwenden des Azure Cosmos DB-Kontos

Der DocumentClient Typ kapselt den Endpunkt, die Anmeldeinformationen und die Verbindungsrichtlinie, die für den Zugriff auf das Azure Cosmos DB-Konto verwendet werden, und wird zum Konfigurieren und Ausführen von Anforderungen für das Konto verwendet. Im folgenden Codebeispiel wird veranschaulicht, wie Sie eine instance dieser Klasse erstellen:

DocumentClient client = new DocumentClient(new Uri(Constants.EndpointUri), Constants.PrimaryKey);

Der Azure Cosmos DB-URI und der Primärschlüssel müssen dem DocumentClient Konstruktor bereitgestellt werden. Diese können über das Azure-Portal abgerufen werden. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit einem Azure Cosmos DB-Konto.

Erstellen einer Datenbank

Eine Dokumentdatenbank ist ein logischer Container für Dokumentsammlungen und -benutzer und kann im Azure-Portal oder programmgesteuert mit der DocumentClient.CreateDatabaseIfNotExistsAsync -Methode erstellt werden:

public async Task CreateDatabase(string databaseName)
{
  ...
  await client.CreateDatabaseIfNotExistsAsync(new Database
  {
    Id = databaseName
  });
  ...
}

Die CreateDatabaseIfNotExistsAsync -Methode gibt ein Database -Objekt als Argument an, wobei das Database -Objekt den Datenbanknamen als Id Eigenschaft angibt. Die CreateDatabaseIfNotExistsAsync -Methode erstellt die Datenbank, wenn sie nicht vorhanden ist, oder gibt die Datenbank zurück, wenn sie bereits vorhanden ist. Die Beispielanwendung ignoriert jedoch alle von der CreateDatabaseIfNotExistsAsync -Methode zurückgegebenen Daten.

Hinweis

Die CreateDatabaseIfNotExistsAsync -Methode gibt ein Task<ResourceResponse<Database>> -Objekt zurück, und der status Code der Antwort kann überprüft werden, um zu bestimmen, ob eine Datenbank erstellt oder eine vorhandene Datenbank zurückgegeben wurde.

Erstellen einer Dokumentsammlung

Eine Dokumentsammlung ist ein Container für JSON-Dokumente und kann im Azure-Portal oder programmgesteuert mit der DocumentClient.CreateDocumentCollectionIfNotExistsAsync -Methode erstellt werden:

public async Task CreateDocumentCollection(string databaseName, string collectionName)
{
  ...
  // Create collection with 400 RU/s
  await client.CreateDocumentCollectionIfNotExistsAsync(
    UriFactory.CreateDatabaseUri(databaseName),
    new DocumentCollection
    {
      Id = collectionName
    },
    new RequestOptions
    {
      OfferThroughput = 400
    });
  ...
}

Für die CreateDocumentCollectionIfNotExistsAsync Methode sind zwei obligatorische Argumente erforderlich: ein Datenbankname, der als Uriangegeben ist, und ein DocumentCollection -Objekt. Das DocumentCollection -Objekt stellt eine Dokumentauflistung dar, deren Name mit der Id -Eigenschaft angegeben wird. Die CreateDocumentCollectionIfNotExistsAsync -Methode erstellt die Dokumentauflistung, falls sie nicht vorhanden ist, oder gibt die Dokumentauflistung zurück, sofern sie bereits vorhanden ist. Die Beispielanwendung ignoriert jedoch alle von der CreateDocumentCollectionIfNotExistsAsync -Methode zurückgegebenen Daten.

Hinweis

Die CreateDocumentCollectionIfNotExistsAsync -Methode gibt ein Task<ResourceResponse<DocumentCollection>> -Objekt zurück, und der status Code der Antwort kann überprüft werden, um zu bestimmen, ob eine Dokumentsammlung erstellt oder eine vorhandene Dokumentsammlung zurückgegeben wurde.

Optional kann die CreateDocumentCollectionIfNotExistsAsync Methode auch ein RequestOptions -Objekt angeben, das Optionen kapselt, die für Anforderungen angegeben werden können, die an das Azure Cosmos DB-Konto ausgegeben werden. Die RequestOptions.OfferThroughput -Eigenschaft wird verwendet, um die Leistungsstufe der Dokumentsammlung zu definieren, und in der Beispielanwendung wird auf 400 Anforderungseinheiten pro Sekunde festgelegt. Dieser Wert sollte erhöht oder verringert werden, je nachdem, ob häufig oder selten auf die Sammlung zugegriffen wird.

Wichtig

Beachten Sie, dass die CreateDocumentCollectionIfNotExistsAsync -Methode eine neue Sammlung mit einem reservierten Durchsatz erstellt, was Sich auf die Preise auswirkt.

Abrufen von Dokumenten in der Dokumentsammlung

Der Inhalt einer Dokumentsammlung kann durch Erstellen und Ausführen einer Dokumentabfrage abgerufen werden. Eine Dokumentabfrage wird mit der DocumentClient.CreateDocumentQuery -Methode erstellt:

public async Task<List<TodoItem>> GetTodoItemsAsync()
{
  ...
  var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
            .AsDocumentQuery();
  while (query.HasMoreResults)
  {
    Items.AddRange(await query.ExecuteNextAsync<TodoItem>());
  }
  ...
}

Diese Abfrage ruft asynchron alle Dokumente aus der angegebenen Auflistung ab und platziert die Dokumente zur Anzeige in einer List<TodoItem> Sammlung.

Die CreateDocumentQuery<T> -Methode gibt ein Uri Argument an, das die Auflistung darstellt, die nach Dokumenten abgefragt werden soll. In diesem Beispiel ist die collectionLink Variable ein Feld auf Klassenebene, das das Uri angibt, das die Dokumentauflistung darstellt, aus der Dokumente abgerufen werden sollen:

Uri collectionLink = UriFactory.CreateDocumentCollectionUri(Constants.DatabaseName, Constants.CollectionName);

Die CreateDocumentQuery<T> -Methode erstellt eine Abfrage, die synchron ausgeführt wird, und gibt ein IQueryable<T> -Objekt zurück. Die AsDocumentQuery -Methode konvertiert das IQueryable<T> -Objekt jedoch in ein IDocumentQuery<T> Objekt, das asynchron ausgeführt werden kann. Die asynchrone Abfrage wird mit der IDocumentQuery<T>.ExecuteNextAsync -Methode ausgeführt, die die nächste Seite der Ergebnisse aus der Dokumentdatenbank abruft, wobei die IDocumentQuery<T>.HasMoreResults -Eigenschaft angibt, ob zusätzliche Ergebnisse von der Abfrage zurückgegeben werden.

Dokumente können serverseitig gefiltert werden, indem eine Where Klausel in die Abfrage eingeschlossen wird, die ein Filter prädikat auf die Abfrage für die Dokumentsammlung anwendet:

var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
          .Where(f => f.Done != true)
          .AsDocumentQuery();

Diese Abfrage ruft alle Dokumente aus der Auflistung ab, deren Done Eigenschaft gleich falseist.

Einfügen eines Dokuments in eine Dokumentsammlung

Dokumente sind benutzerdefinierte JSON-Inhalte und können mit der DocumentClient.CreateDocumentAsync -Methode in eine Dokumentsammlung eingefügt werden:

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  await client.CreateDocumentAsync(collectionLink, item);
  ...
}

Die CreateDocumentAsync -Methode gibt ein Uri Argument an, das die Auflistung darstellt, in die das Dokument eingefügt werden soll, und ein object Argument, das das einzufügende Dokument darstellt.

Ersetzen eines Dokuments in einer Dokumentsammlung

Dokumente können in einer Dokumentsammlung durch die DocumentClient.ReplaceDocumentAsync -Methode ersetzt werden:

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  await client.ReplaceDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, item.Id), item);
  ...
}

Die ReplaceDocumentAsync -Methode gibt ein Uri Argument an, das das Dokument in der Sammlung darstellt, das ersetzt werden soll, und ein object Argument, das die aktualisierten Dokumentdaten darstellt.

Löschen eines Dokuments aus einer Dokumentsammlung

Ein Dokument kann mit der DocumentClient.DeleteDocumentAsync -Methode aus einer Dokumentsammlung gelöscht werden:

public async Task DeleteTodoItemAsync(string id)
{
  ...
  await client.DeleteDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, id));
  ...
}

Die DeleteDocumentAsync -Methode gibt ein Uri Argument an, das das Dokument in der Auflistung darstellt, das gelöscht werden soll.

Löschen einer Dokumentsammlung

Eine Dokumentsammlung kann mit der DocumentClient.DeleteDocumentCollectionAsync -Methode aus einer Datenbank gelöscht werden:

await client.DeleteDocumentCollectionAsync(collectionLink);

Die DeleteDocumentCollectionAsync -Methode gibt ein Uri Argument an, das die zu löschende Dokumentauflistung darstellt. Beachten Sie, dass beim Aufrufen dieser Methode auch die in der Auflistung gespeicherten Dokumente gelöscht werden.

Löschen einer Datenbank

Eine Datenbank kann mit der DocumentClient.DeleteDatabaesAsync Methode aus einem Azure Cosmos DB-Datenbankkonto gelöscht werden:

await client.DeleteDatabaseAsync(UriFactory.CreateDatabaseUri(Constants.DatabaseName));

Die DeleteDatabaseAsync -Methode gibt ein Uri Argument an, das die zu löschende Datenbank darstellt. Beachten Sie, dass beim Aufrufen dieser Methode auch die in der Datenbank gespeicherten Dokumentsammlungen und die in den Dokumentsammlungen gespeicherten Dokumente gelöscht werden.

Zusammenfassung

In diesem Artikel wurde erläutert, wie Sie die .NET Standard-Clientbibliothek von Azure Cosmos DB verwenden, um eine Azure Cosmos DB-Dokumentdatenbank in eine Xamarin.Forms Anwendung zu integrieren. Eine Azure Cosmos DB-Dokumentdatenbank ist eine NoSQL-Datenbank, die zugriff auf JSON-Dokumente mit geringer Latenz ermöglicht und einen schnellen, hochverfügbaren, skalierbaren Datenbankdienst für Anwendungen bietet, die eine nahtlose Skalierung und globale Replikation erfordern.

Ähnliche Themen

• Todo Azure Cosmos DB (Beispiel)
• Dokumentation für Azure Cosmos DB
• Azure Cosmos DB .NET Standard-Clientbibliothek
• Azure Cosmos DB-API