Utiliser une base de données de documents Azure Cosmos DB dans Xamarin.Forms

  • Article

Une base de données de documents Azure Cosmos DB est une base de données NoSQL qui fournit un accès à faible latence aux documents JSON, offrant un service de base de données rapide, hautement disponible et évolutif pour les applications qui nécessitent une mise à l’échelle transparente et une réplication globale. Cet article explique comment utiliser la bibliothèque cliente .NET Standard Azure Cosmos DB pour intégrer une base de données de documents Azure Cosmos DB dans une Xamarin.Forms application.

Vidéo Microsoft Azure Cosmos DB

Un compte de base de données de documents Azure Cosmos DB peut être provisionné à l’aide d’un abonnement Azure. Chaque compte de base de données peut avoir zéro ou plusieurs bases de données. Une base de données de documents dans Azure Cosmos DB est un conteneur logique pour les collections de documents et les utilisateurs.

Une base de données de documents Azure Cosmos DB peut contenir zéro ou plusieurs collections de documents. Chaque collection de documents peut avoir un niveau de performances différent, ce qui permet de spécifier davantage de débit pour les collections fréquemment sollicitées et moins de débit pour les collections rarement sollicitées.

Chaque collection de documents se compose de zéro ou plusieurs documents JSON. Les documents d’une collection sont sans schéma et n’ont donc pas besoin de partager la même structure ou les mêmes champs. À mesure que des documents sont ajoutés à une collection de documents, Azure Cosmos DB les indexe automatiquement et ils deviennent disponibles pour être interrogés.

À des fins de développement, une base de données de documents peut également être consommée via un émulateur. À l’aide de l’émulateur, les applications peuvent être développées et testées localement, sans créer d’abonnement Azure ou entraîner des coûts. Pour plus d’informations sur l’émulateur, consultez Développement localement avec l’émulateur Azure Cosmos DB.

Cet article, ainsi que l’exemple d’application associé, illustre une application de liste todo où les tâches sont stockées dans une base de données de documents Azure Cosmos DB. Pour plus d’informations sur l’exemple d’application, consultez Présentation de l’exemple.

Pour plus d’informations sur Azure Cosmos DB, consultez la documentation Azure Cosmos DB.

Remarque

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

Programme d’installation

Le processus d’intégration d’une base de données de documents Azure Cosmos DB dans une Xamarin.Forms application est le suivant :

  1. Créez un compte Azure Cosmos DB. Pour plus d’informations, consultez Créer un compte Azure Cosmos DB.
  2. Ajoutez le package NuGet de la bibliothèque cliente Azure Cosmos DB .NET Standard aux projets de plateforme de la Xamarin.Forms solution.
  3. Ajoutez des using directives pour les espaces Microsoft.Azure.Documents.Clientde noms et Microsoft.Azure.Documents.Linq les Microsoft.Azure.Documentsespaces de noms aux classes qui accèderont au compte Azure Cosmos DB.

Une fois ces étapes effectuées, la bibliothèque cliente .NET Standard d’Azure Cosmos DB peut être utilisée pour configurer et exécuter des requêtes sur la base de données de documents.

Remarque

La bibliothèque cliente .NET Standard d’Azure Cosmos DB ne peut être installée que dans des projets de plateforme, et non dans un projet PCL (Portable Class Library). Par conséquent, l’exemple d’application est un projet d’accès partagé (SAP) pour éviter la duplication de code. Toutefois, la DependencyService classe peut être utilisée dans un projet PCL pour appeler le code de bibliothèque cliente .NET Standard d’Azure Cosmos DB contenu dans des projets spécifiques à la plateforme.

Consommation du compte Azure Cosmos DB

Le DocumentClient type encapsule le point de terminaison, les informations d’identification et la stratégie de connexion utilisés pour accéder au compte Azure Cosmos DB et est utilisé pour configurer et exécuter des demandes sur le compte. L’exemple de code suivant montre comment créer une instance de cette classe :

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

L’URI azure Cosmos DB et la clé primaire doivent être fournis au DocumentClient constructeur. Ceux-ci peuvent être obtenus à partir du portail Azure. Pour plus d’informations, consultez Connecter à un compte Azure Cosmos DB.

Création d’une base de données

Une base de données de documents est un conteneur logique pour les collections de documents et les utilisateurs, et peut être créée dans le portail Azure, ou par programmation à l’aide de la DocumentClient.CreateDatabaseIfNotExistsAsync méthode :

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

La CreateDatabaseIfNotExistsAsync méthode spécifie un Database objet en tant qu’argument, avec l’objet Database spécifiant le nom de la base de données comme Id propriété. La CreateDatabaseIfNotExistsAsync méthode crée la base de données s’il n’existe pas ou retourne la base de données s’il existe déjà. Toutefois, l’exemple d’application ignore toutes les données retournées par la CreateDatabaseIfNotExistsAsync méthode.

Remarque

La CreateDatabaseIfNotExistsAsync méthode retourne un Task<ResourceResponse<Database>> objet et le code d’état de la réponse peut être case activée pour déterminer si une base de données a été créée ou si une base de données existante a été retournée.

Création d’une collection de documents

Une collection de documents est un conteneur pour les documents JSON et peut être créée dans le portail Azure, ou par programmation à l’aide de la DocumentClient.CreateDocumentCollectionIfNotExistsAsync méthode :

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

La CreateDocumentCollectionIfNotExistsAsync méthode nécessite deux arguments obligatoires : un nom de base de données spécifié en tant qu’objet Uriet un DocumentCollection objet. L’objet DocumentCollection représente une collection de documents dont le nom est spécifié avec la Id propriété. La CreateDocumentCollectionIfNotExistsAsync méthode crée la collection de documents s’il n’existe pas ou retourne la collection de documents s’il existe déjà. Toutefois, l’exemple d’application ignore toutes les données retournées par la CreateDocumentCollectionIfNotExistsAsync méthode.

Remarque

La CreateDocumentCollectionIfNotExistsAsync méthode retourne un Task<ResourceResponse<DocumentCollection>> objet et le code d’état de la réponse peut être case activée pour déterminer si une collection de documents a été créée ou si une collection de documents existante a été retournée.

Si vous le souhaitez, la CreateDocumentCollectionIfNotExistsAsync méthode peut également spécifier un RequestOptions objet, qui encapsule les options qui peuvent être spécifiées pour les demandes émises sur le compte Azure Cosmos DB. La RequestOptions.OfferThroughput propriété est utilisée pour définir le niveau de performances de la collection de documents et, dans l’exemple d’application, est définie sur 400 unités de requête par seconde. Cette valeur doit être augmentée ou réduite selon que la collection sera fréquemment ou rarement sollicitée.

Important

Notez que la CreateDocumentCollectionIfNotExistsAsync méthode crée une collection avec un débit réservé, ce qui a des implications sur les tarifs.

Récupération de documents de collection de documents

Le contenu d’une collection de documents peut être récupéré en créant et en exécutant une requête de document. Une requête de document est créée avec la DocumentClient.CreateDocumentQuery méthode :

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

Cette requête récupère de façon asynchrone tous les documents de la collection spécifiée et place les documents dans une List<TodoItem> collection à afficher.

La CreateDocumentQuery<T> méthode spécifie un Uri argument qui représente la collection qui doit être interrogée pour les documents. Dans cet exemple, la collectionLink variable est un champ de niveau classe qui spécifie celui Uri qui représente la collection de documents à partir de laquelle récupérer des documents :

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

La CreateDocumentQuery<T> méthode crée une requête qui est exécutée de manière synchrone et retourne un IQueryable<T> objet. Toutefois, la AsDocumentQuery méthode convertit l’objet IQueryable<T> en objet IDocumentQuery<T> qui peut être exécuté de manière asynchrone. La requête asynchrone est exécutée avec la IDocumentQuery<T>.ExecuteNextAsync méthode, qui récupère la page suivante des résultats de la base de données de documents, avec la IDocumentQuery<T>.HasMoreResults propriété indiquant s’il existe des résultats supplémentaires à retourner à partir de la requête.

Les documents peuvent être filtrés côte à côte en incluant une Where clause dans la requête, qui applique un prédicat de filtrage à la requête sur la collection de documents :

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

Cette requête récupère tous les documents de la collection dont Done la propriété est égale à false.

Insertion d’un document dans une collection de documents

Les documents sont du contenu JSON défini par l’utilisateur et peuvent être insérés dans une collection de documents avec la DocumentClient.CreateDocumentAsync méthode :

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

La CreateDocumentAsync méthode spécifie un Uri argument qui représente la collection dans laquelle le document doit être inséré et un object argument qui représente le document à insérer.

Remplacement d’un document dans une collection de documents

Les documents peuvent être remplacés dans une collection de documents par la DocumentClient.ReplaceDocumentAsync méthode :

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

La ReplaceDocumentAsync méthode spécifie un Uri argument qui représente le document dans la collection qui doit être remplacé et un object argument qui représente les données de document mises à jour.

Suppression d’un document d’une collection de documents

Un document peut être supprimé d’une collection de documents avec la DocumentClient.DeleteDocumentAsync méthode :

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

La DeleteDocumentAsync méthode spécifie un Uri argument qui représente le document dans la collection qui doit être supprimé.

Suppression d’une collection de documents

Une collection de documents peut être supprimée d’une base de données avec la DocumentClient.DeleteDocumentCollectionAsync méthode :

await client.DeleteDocumentCollectionAsync(collectionLink);

La DeleteDocumentCollectionAsync méthode spécifie un Uri argument qui représente la collection de documents à supprimer. Notez que l’appel de cette méthode supprime également les documents stockés dans la collection.

Suppression d’une base de données

Une base de données peut être supprimée d’un compte de base de données Azure Cosmos DB avec la DocumentClient.DeleteDatabaesAsync méthode :

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

La DeleteDatabaseAsync méthode spécifie un Uri argument qui représente la base de données à supprimer. Notez que l’appel de cette méthode supprime également les collections de documents stockées dans la base de données et les documents stockés dans les collections de documents.

Résumé

Cet article explique comment utiliser la bibliothèque cliente .NET Standard Azure Cosmos DB pour intégrer une base de données de documents Azure Cosmos DB dans une Xamarin.Forms application. Une base de données de documents Azure Cosmos DB est une base de données NoSQL qui fournit un accès à faible latence aux documents JSON, offrant un service de base de données rapide, hautement disponible et évolutif pour les applications qui nécessitent une mise à l’échelle transparente et une réplication globale.