Tutoriel : Développement d’une application web ASP.NET avec Azure Cosmos DB for NoSQL
S’APPLIQUE À : NoSQL
Le Kit de développement logiciel (SDK) Azure pour .NET vous permet d’interroger des données dans un conteneur API pour NoSQL à l’aide de LINQ en C# ou d’une chaîne de requête SQL. Ce tutoriel décrit le processus de mise à jour d’une application web ASP.NET existante qui utilise des données d’espace réservé pour interroger à la place à partir de l’API.
Dans ce tutoriel, vous apprenez à effectuer les opérations suivantes :
- Créez et remplissez une base de données et un conteneur à l’aide de l’API pour NoSQL.
- Créez une application web ASP.NET à partir d’un modèle.
- Interrogez des données à partir du conteneur API pour NoSQL à l’aide du Kit de développement logiciel (SDK) Azure pour .NET.
Prérequis
- Un compte Azure Cosmos DB for NoSQL déjà créé :
- Si vous disposez d’un abonnement Azure, créez un compte.
- Vous ne possédez pas d’abonnement Azure ? Vous pouvez essayer Azure Cosmos DB gratuitement sans carte de crédit.
- Visual Studio Code
- .NET version 6 (LTS) ou plus récente
- Expérience dans l’écriture d’applications C#
Création de ressources API for NoSQL
Tout d’abord, vous allez créer une base de données et un conteneur dans le compte d’API pour NoSQL existant. Vous remplirez ensuite ce compte avec des données à l’aide de cosmicworks
l’outil dotnet.
Accédez à votre compte API for NoSQL sur le Portail Azure.
Dans le menu des ressources, sélectionnez Clés.
Dans la page Clés, observez et enregistrez la valeur du champ CHAÎNE DE CONNEXION PRIMAIRE*. Ces valeurs seront utilisées tout au long du didacticiel.
Dans le menu de la ressource, sélectionnez Explorateur de données.
Sur la page Data Explorer, sélectionnez l’option Nouveau conteneur dans la barre de commandes.
Dans la boîte de dialogue Nouveau conteneur, créez un conteneur en indiquant les paramètres suivants :
Paramètre Valeur ID de base de données cosmicworks
Type de débit de la base de données Manuel Valeur du débit de la base de données 1000
ID de conteneur products
Clé de partition /category/name
Important
Dans ce didacticiel, nous allons d’abord mettre à l’échelle la base de données jusqu’à 1000 RU/s en débit partagé afin d’optimiser le niveau de performance de la migration des données. Une fois la migration des données terminée, nous effectuerons un scale-down à 400 RU/s de débit provisionné.
Sélectionnez OK pour créer la base de données et le conteneur.
Ouvrez un terminal pour exécuter des commandes afin de remplir le conteneur avec des données.
Conseil
Vous pouvez également utiliser Azure Cloud Shell ici.
Installez v2 de l’outil dotnet
cosmicworks
depuis NuGet.dotnet tool install --global cosmicworks --version 2.*
Utilisez
cosmicworks
l’outil pour remplir votre compte API pour NoSQL avec des exemples de données de produit à l’aide des valeurs d’URI et DE CLÉ PRIMAIRE que vous avez enregistrées précédemment dans ce labo. Ces valeurs enregistrées seront utilisées pour lesendpoint
paramètres etkey
respectivement.cosmicworks \ --number-of-products 1759 \ --number-of-employees 0 \ --disable-hierarchical-partition-keys \ --connection-string <nosql-connection-string>
Observez la sortie de l’outil de ligne de commande. Ceci doit ajouter 1759 éléments au conteneur. L’exemple de sortie inclus est tronqué par souci de concision.
── Parsing connection string ──────────────────────────────────────────────────────────────── ╭─Connection string──────────────────────────────────────────────────────────────────────────╮ │ AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>; │ ╰────────────────────────────────────────────────────────────────────────────────────────────╯ ── Populating data ────────────────────────────────────────────────────────────────────────── ╭─Products configuration─────────────────────────────────────────────────────────────────────╮ │ Database cosmicworks │ │ Container products │ │ Count 1,759 │ ╰────────────────────────────────────────────────────────────────────────────────────────────╯ ... [SEED] 00000000-0000-0000-0000-000000005951 | Road-650 Black, 60 - Bikes [SEED] 00000000-0000-0000-0000-000000005950 | Mountain-100 Silver, 42 - Bikes [SEED] 00000000-0000-0000-0000-000000005949 | Men's Bib-Shorts, L - Clothing [SEED] 00000000-0000-0000-0000-000000005948 | ML Mountain Front Wheel - Components [SEED] 00000000-0000-0000-0000-000000005947 | Mountain-500 Silver, 42 - Bikes
Revenez à la page Data Explorer de votre compte.
Dans la section Données , développez le
cosmicworks
nœud de base de données, puis sélectionnez Mettre à l’échelle.Réduisez le débit de 1000 à 400.
Dans la barre de commandes, sélectionnez Enregistrer.
Dans la section Données, développez et sélectionnez le nœud conteneur des produits .
Dans la barre de commandes, sélectionnez Nouvelle requête SQL.
Dans l’éditeur de requête, ajoutez cette chaîne de requête SQL.
SELECT p.sku, p.price FROM products p WHERE p.price < 2000 ORDER BY p.price DESC
Sélectionnez Exécuter la requête pour exécuter la requête, puis observez les résultats.
Les résultats doivent être un tableau paginé de tous les éléments du conteneur avec une
price
valeur inférieure à 2 000 triée du prix le plus élevé au plus bas. Par souci de concision, un sous-ensemble de la sortie est inclus ici.[ { "sku": "BK-R79Y-48", "price": 1700.99 }, ... { "sku": "FR-M94B-46", "price": 1349.6 }, ...
Remplacez le contenu de l’éditeur de requête par cette requête, puis sélectionnez à nouveau Exécuter la requête pour observer les résultats.
SELECT p.name, p.category.name AS category, p.category.subCategory.name AS subcategory, p.tags FROM products p JOIN tag IN p.tags WHERE STRINGEQUALS(tag, "yellow", true)
Les résultats doivent être un tableau plus petit d’éléments filtrés pour contenir uniquement des éléments qui incluent au moins une balise avec la valeur de nom
Tag-32
. Encore une fois, un sous-ensemble de la sortie est inclus ici pour des raisons de brièveté.[ ... { "name": "HL Touring Frame - Yellow, 60", "category": "Components", "subcategory": "Touring Frames", "tags": [ "Components", "Touring Frames", "Yellow", "60" ] }, ... ]
Création d’une application web ASP.NET
Maintenant, vous allez créer une application web ASP.NET à l’aide d’un exemple de modèle de projet. Vous explorerez ensuite le code source et exécuterez l’exemple pour vous familiariser avec l’application avant d’ajouter la connectivité Azure Cosmos DB à l’aide du SDK Azure pour .NET.
Important
Ce tutoriel extrait en toute transparence les packages de NuGet. Vous pouvez utiliser dotnet nuget list source
pour vérifier les sources de vos packages. Si vous n’avez pas NuGet en tant que source de package, utilisez dotnet nuget add source
pour installer le site en tant que source.
Ouvrez un terminal dans un répertoire vide.
Installez le package de modèle de projet
cosmicworks.template.web
à partir de NuGet.dotnet new install cosmicworks.template.web
Créez un projet d’application web à l’aide du modèle nouvellement installé
dotnet new cosmosdbnosql-webapp
.dotnet new cosmosdbnosql-webapp
Construisez et exécutez le projet d’application web.
dotnet run
Observez la sortie de la commande run. La sortie devrait inclure une liste de ports et d’URL où l’application est exécutée.
... info: Microsoft.Hosting.Lifetime[14] Now listening on: http://localhost:5000 info: Microsoft.Hosting.Lifetime[14] Now listening on: https://localhost:5001 info: Microsoft.Hosting.Lifetime[0] Application started. Press Ctrl+C to shut down. info: Microsoft.Hosting.Lifetime[0] Hosting environment: Production ...
Ouvrez un nouveau navigateur et naviguez vers l’application web en cours d’exécution. Observez les trois pages de l’application en cours d’exécution.
Arrêtez l’exécution de l’application en mettant fin au processus en cours d’exécution.
Conseil
Utilisez la commande Ctrl+C pour arrêter un processus en cours d’exécution. Vous pouvez également fermer et rouvrir le terminal.
Ouvrez Visual Studio Code en utilisant le dossier de projet actuel comme espace de travail.
Conseil
Vous pouvez exécuter
code .
dans le terminal pour lancer Visual Studio Code et ouvrir automatiquement le répertoire de travail comme espace de travail actif.Naviguez vers et ouvrez le fichier Services/ICosmosService.cs. Observez les implémentations de
RetrieveActiveProductsAsync
méthode etRetrieveAllProductsAsync
par défaut. Ces méthodes créent une liste statique de produits à utiliser lors de la première exécution du projet. Un exemple tronqué de l’une des méthodes est fourni ici.public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync() { await Task.Delay(1); return new List<Product>() { new Product(id: "baaa4d2d-5ebe-45fb-9a5c-d06876f408e0", category: new Category(name: "Components, Road Frames"), sku: "FR-R72R-60", name: """ML Road Frame - Red, 60""", description: """The product called "ML Road Frame - Red, 60".""", price: 594.83000000000004m), new Product(id: "bd43543e-024c-4cda-a852-e29202310214", category: new Category(name: "Components, Forks"), sku: "FK-5136", name: """ML Fork""", description: """The product called "ML Fork".""", price: 175.49000000000001m), ... }; }
Naviguez vers et ouvrez le fichier Services/CosmosService.cs. Observez l’implémentation actuelle de la classe CosmosService . Cette classe implémente l’interface ICosmosService , mais ne remplace aucune méthode. Dans ce contexte, la classe utilise l’implémentation d’interface par défaut jusqu’à ce qu’un remplacement de l’implémentation soit fourni dans l’interface.
public class CosmosService : ICosmosService { }
Enfin, accédez aux fichiers Models/Product.cs et Models/Category.cs et ouvrez-les. Observez les types d’enregistrements définis dans chaque fichier. Ces types seront utilisés dans les requêtes tout au long de ce didacticiel.
public record Product( string id, Category category, string sku, string name, string description, decimal price );
public record Category( string name );
Interrogez les données à l’aide du SDK .NET.
Ensuite, vous allez ajouter le SDK Azure pour .NET à cet exemple de projet et utiliser la bibliothèque pour interroger les données du conteneur API for NoSQL.
De retour dans le terminal, ajoutez le package
Microsoft.Azure.Cosmos
à partir de NuGet.dotnet add package Microsoft.Azure.Cosmos
Créez le projet.
dotnet build
De retour dans Visual Studio Code, accédez à nouveau au fichier Services/CosmosService.cs .
Ajoutez une nouvelle directive using pour les espaces de noms
Microsoft.Azure.Cosmos
etMicrosoft.Azure.Cosmos.Linq
.using Microsoft.Azure.Cosmos; using Microsoft.Azure.Cosmos.Linq;
Dans la classe CosmosService, ajoutez un nouveau
private readonly
membre de typeCosmosClient
nommé_client
.private readonly CosmosClient _client;
Créez un constructeur vide pour la classe
CosmosService
.public CosmosService() { }
Dans le constructeur, créez une nouvelle instance de la
CosmosClient
classe en passant dans un paramètre de chaîne avec la valeur de la CHAÎNE DE CONNEXION PRIMAIRE que vous avez précédemment enregistrée dans le laboratoire. Stockez cette nouvelle instance dans le membre_client
.public CosmosService() { _client = new CosmosClient( connectionString: "<primary-connection-string>" ); }
De retour dans la classe CosmosService, créez une
private
propriété de typeContainer
nomméecontainer
. Définissez l’accesseur get pour renvoyer la base de données etcosmicworks
leproducts
conteneur.private Container container { get => _client.GetDatabase("cosmicworks").GetContainer("products"); }
Créez une méthode asynchrone nommée
RetrieveAllProductsAsync
qui retourne unIEnumerable<Product>
.public async Task<IEnumerable<Product>> RetrieveAllProductsAsync() { }
Pour les étapes suivantes, ajoutez ce code dans la méthode
RetrieveAllProductsAsync
.Utilisez la
GetItemLinqQueryable<>
méthode générique pour obtenir un objet de typeIQueryable<>
que vous pouvez utiliser pour construire une requête LINQ (Language integrated query). Stockez cet objet dans une variable nomméequeryable
.var queryable = container.GetItemLinqQueryable<Product>();
Construisez une requête LINQ à l’aide des méthodes d’extension
Where
etOrderByDescending
. Utilisez la méthode d’extensionToFeedIterator
pour créer un itérateur afin d’obtenir des données à partir d’Azure Cosmos DB et de stocker l’itérateur dans une variable nomméefeed
. Encapsulez l’expression entière dans une instruction using pour pouvoir supprimer l’itérateur ultérieurement.using FeedIterator<Product> feed = queryable .Where(p => p.price < 2000m) .OrderByDescending(p => p.price) .ToFeedIterator();
Créez une variable nommée
results
à l’aide du type génériqueList<>
.List<Product> results = new();
Créez une boucle while qui itère jusqu’à ce que la propriété
HasMoreResults
de la variablefeed
renvoie false. Cette boucle garantit que vous parcourez toutes les pages de résultats côté serveur.while (feed.HasMoreResults) { }
Dans la boucle while, appelez de manière asynchrone la
ReadNextAsync
méthode de lafeed
variable et stockez le résultat dans une variable nomméeresponse
.while (feed.HasMoreResults) { var response = await feed.ReadNextAsync(); }
Toujours dans la boucle while , utilisez une boucle pour chaque pour parcourir chaque élément de la réponse et les ajouter à la
results
liste.while (feed.HasMoreResults) { var response = await feed.ReadNextAsync(); foreach (Product item in response) { results.Add(item); } }
Retournez la liste
results
comme sortie de la méthodeRetrieveAllProductsAsync
.return results;
Créez une méthode asynchrone nommée
RetrieveActiveProductsAsync
qui retourne unIEnumerable<Product>
.public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync() { }
Pour les étapes suivantes, ajoutez ce code dans la méthode
RetrieveActiveProductsAsync
.Créez une chaîne nommée
sql
avec une requête SQL pour récupérer plusieurs champs où un filtre (@tagFilter
) est appliqué à un tableau de balises de chaque élément.string sql = """ SELECT p.id, p.name, p.category, p.sku, p.description, p.price FROM products p JOIN tag IN p.tags WHERE STRINGEQUALS(tag, @tagFilter, true) """;
Créez une variable
QueryDefinition
nomméequery
et transmettant la chaînesql
comme seul paramètre de requête. Utilisez également la méthode FluidWithParameter
pour appliquer la valeur dered
au paramètre@tagFilter
.var query = new QueryDefinition( query: sql ) .WithParameter("@tagFilter", "red");
Utilisez la méthode générique
GetItemQueryIterator<>
et la variablequery
pour créer un itérateur qui récupère des données à partir d’Azure Cosmos DB. Stockez l’itérateur dans une variable nomméefeed
. Encapsulez l’expression entière dans une instruction using pour pouvoir supprimer l’itérateur ultérieurement.using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>( queryDefinition: query );
Utilisez une boucle while pour itérer plusieurs pages de résultats et stocker la valeur dans
List<>
un résultat nommé générique. Retournez le résultat en sortie de la méthodeRetrieveActiveProductsAsync
.List<Product> results = new(); while (feed.HasMoreResults) { FeedResponse<Product> response = await feed.ReadNextAsync(); foreach (Product item in response) { results.Add(item); } } return results;
Enregistrez le fichier Services/CosmosClient.cs.
Conseil
Si vous n’êtes pas sûr que votre code est correct, vous pouvez vérifier votre code source par rapport à l’exemple de code sur GitHub.
Validez l’application finale.
Enfin, vous allez exécuter l’application avec les rechargements à chaud activés. L’exécution de l’application valide que votre code peut accéder aux données de l’API pour NoSQL.
De retour dans le terminal, exécutez l’application.
dotnet run
La sortie de la commande d’exécution devrait inclure une liste de ports et d’URL où l’application est exécutée. Ouvrez un nouveau navigateur et naviguez vers l’application web en cours d’exécution. Observez les trois pages de l’application en cours d’exécution. Chaque page doit maintenant inclure des données actives d’Azure Cosmos DB.
Nettoyer les ressources
Quand vous n’en avez plus besoin, supprimez les bases de données utilisées dans ce tutoriel. Pour ce faire, accédez à la page du compte, sélectionnez Data Explorer, la base de données cosmicworks
, puis Supprimer.
Étapes suivantes
Maintenant que vous avez créé votre première application web .NET à l’aide d’Azure Cosmos DB, vous pouvez désormais approfondir le Kit de développement logiciel (SDK) pour importer davantage de données, effectuer des requêtes complexes et gérer vos ressources Azure Cosmos DB for NoSQL.