Verwenden einer Azure Cosmos DB-Dokumentdatenbank in Xamarin.Forms

  • Artikel

Eine Azure Cosmos DB-Dokumentdatenbank ist eine NoSQL-Datenbank, die einen schnellen, hochverwendbaren, skalierbaren Datenbankdienst für Anwendungen bietet, die eine nahtlose Skalierung und globale Replikation erfordern. In diesem Artikel wird erläutert, wie Sie die Azure Cosmos DB .NET Standard-Clientbibliothek 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 mit einem Azure-Abonnement bereitgestellt werden. Jedes Datenbankkonto kann null oder mehr Datenbanken haben. 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 Dokumentauflistung kann eine andere Leistungsstufe aufweisen, sodass mehr Durchsatz für häufig verwendete Auflistungen und weniger Durchsatz für selten aufgerufene Auflistungen angegeben werden kann.

Jede Dokumentsammlung besteht aus null oder mehr JSON-Dokumenten. Dokumente in einer Auflistung sind schemafrei und müssen daher nicht dieselbe Struktur oder Felder gemeinsam nutzen. Wenn Dokumente zu einer Dokumentsammlung hinzugefügt werden, indiziert Azure Cosmos DB sie automatisch und sind verfügbar, um abgefragt zu werden.

Für Entwicklungszwecke 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 kostenaufwendigen zu müssen. Weitere Informationen zum Emulator finden Sie unter Developing lokal with the Azure Cosmos DB Emulator.

In diesem Artikel und der zugehörigen Beispielanwendung wird eine Todo-Listenanwendung veranschaulicht, in 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.

Setup

Der Prozess für die Integration einer Azure Cosmos DB-Dokumentdatenbank in eine Xamarin.Forms Anwendung lautet wie folgt:

  1. Erstellung eines Azure Cosmos DB-Kontos. Weitere Informationen finden Sie unter Erstellen eines Azure Cosmos DB-Kontos.
  2. Fügen Sie das NuGet-Paket der Azure Cosmos DB .NET Standard-Clientbibliothek zu den Plattformprojekten in der Xamarin.Forms Lösung hinzu.
  3. Fügen Sie using Direktiven für die Microsoft.Azure.DocumentsMicrosoft.Azure.Documents.ClientKlassen und Microsoft.Azure.Documents.Linq Namespaces 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 Azure Cosmos DB .NET Standard-Clientbibliothek 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 Codeduplizierungen zu vermeiden. Die Klasse kann jedoch in einem PCL-Projekt verwendet werden, DependencyService um Azure Cosmos DB .NET Standard-Clientbibliothekscode in plattformspezifischen Projekten aufzurufen.

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 wird, und wird verwendet, um Anforderungen für das Konto zu konfigurieren und auszuführen. Im folgenden Codebeispiel wird veranschaulicht, wie eine Instanz dieser Klasse erstellt wird:

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 Verbinden zu 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 mithilfe 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 Statuscode 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 mithilfe 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 ein UriObjekt angegeben ist DocumentCollection . Das DocumentCollection Objekt stellt eine Dokumentauflistung dar, deren Name mit der Id Eigenschaft angegeben wird. Die CreateDocumentCollectionIfNotExistsAsync Methode erstellt die Dokumentauflistung, wenn sie nicht vorhanden ist, oder gibt die Dokumentauflistung zurück, falls 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 Statuscode der Antwort kann überprüft werden, um zu bestimmen, ob eine Dokumentsammlung erstellt wurde oder eine vorhandene Dokumentauflistung 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 für das Azure Cosmos DB-Konto ausgestellt wurden. Die RequestOptions.OfferThroughput Eigenschaft wird verwendet, um die Leistungsstufe der Dokumentsammlung zu definieren und in der Beispielanwendung auf 400 Anforderungseinheiten pro Sekunde festgelegt. Dieser Wert sollte erhöht oder verringert werden, je nachdem, ob die Sammlung häufig oder selten zugegriffen wird.

Wichtig

Beachten Sie, dass die CreateDocumentCollectionIfNotExistsAsync Methode eine neue Auflistung mit einem reservierten Durchsatz erstellt, der Preisauswirkungen hat.

Abrufen von Dokumentensammlungsdokumenten

Der Inhalt einer Dokumentsammlung kann abgerufen werden, indem eine Dokumentabfrage erstellt und ausgeführt wird. Mit der DocumentClient.CreateDocumentQuery Methode wird eine Dokumentabfrage 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 in einer List<TodoItem> Auflistung zur Anzeige.

Die CreateDocumentQuery<T> Methode gibt ein Uri Argument an, das die Auflistung darstellt, die für Dokumente abgefragt werden soll. In diesem Beispiel ist die collectionLink Variable ein Feld auf Klassenebene, das die Uri Dokumentauflistung angibt, 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. AsDocumentQuery Die 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 aus der Abfrage zurückgegeben werden sollen.

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 Auflistung darstellt, das ersetzt werden soll, und ein object Argument, das die aktualisierten Dokumentdaten darstellt.

Löschen eines Dokuments aus einer Dokumentsammlung

Ein Dokument kann aus einer Dokumentsammlung mit der DocumentClient.DeleteDocumentAsync Methode 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 aus einer Datenbank mit der DocumentClient.DeleteDocumentCollectionAsync Methode 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 das Aufrufen dieser Methode auch die in der Auflistung gespeicherten Dokumente löscht.

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 das Aufrufen dieser Methode auch die in der Datenbank gespeicherten Dokumentsammlungen und die in den Dokumentsammlungen gespeicherten Dokumente löscht.

Zusammenfassung

In diesem Artikel wird erläutert, wie Sie die Azure Cosmos DB .NET Standard-Clientbibliothek verwenden, um eine Azure Cosmos DB-Dokumentdatenbank in eine Xamarin.Forms Anwendung zu integrieren. Eine Azure Cosmos DB-Dokumentdatenbank ist eine NoSQL-Datenbank, die einen schnellen, hochverwendbaren, skalierbaren Datenbankdienst für Anwendungen bietet, die eine nahtlose Skalierung und globale Replikation erfordern.