Tutoriel : Développement d’une application web ASP.NET avec Azure Cosmos DB for NoSQL

Article
04/09/2024

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 cosmicworksl’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`

Capture d’écran de la boîte de dialogue Nouveau conteneur dans Data Explorer, comportant différentes valeurs dans chaque champ

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 cosmicworksl’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 les endpoint paramètres et key 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 nomTag-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 et RetrieveAllProductsAsync 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 et Microsoft.Azure.Cosmos.Linq.
```
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Linq;
```
Dans la classe CosmosService, ajoutez un nouveau private readonly membre de type CosmosClient 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 CosmosClientclasse 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 type Container nommée container. Définissez l’accesseur get pour renvoyer la base de données et cosmicworks le products conteneur.
```
private Container container
{
    get => _client.GetDatabase("cosmicworks").GetContainer("products");
}
```
Créez une méthode asynchrone nommée RetrieveAllProductsAsync qui retourne un IEnumerable<Product>.
```
public async Task<IEnumerable<Product>> RetrieveAllProductsAsync()
{ }
```
Pour les étapes suivantes, ajoutez ce code dans la méthode RetrieveAllProductsAsync.
1. Utilisez la GetItemLinqQueryable<> méthode générique pour obtenir un objet de type IQueryable<> que vous pouvez utiliser pour construire une requête LINQ (Language integrated query). Stockez cet objet dans une variable nommée queryable.
```
var queryable = container.GetItemLinqQueryable<Product>();
```
2. Construisez une requête LINQ à l’aide des méthodes d’extension Where et OrderByDescending . Utilisez la méthode d’extension ToFeedIterator 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ée feed. 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();
```
3. Créez une variable nommée results à l’aide du type générique List<> .
```
List<Product> results = new();
```
4. Créez une boucle while qui itère jusqu’à ce que la propriété HasMoreResults de la variable feed renvoie false. Cette boucle garantit que vous parcourez toutes les pages de résultats côté serveur.
```
while (feed.HasMoreResults)
{ }
```
5. Dans la boucle while, appelez de manière asynchrone la ReadNextAsyncméthode de la feedvariable et stockez le résultat dans une variable nomméeresponse.
```
while (feed.HasMoreResults)
{
    var response = await feed.ReadNextAsync();
}
```
6. 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);
    }
}
```
7. Retournez la liste results comme sortie de la méthode RetrieveAllProductsAsync.
```
return results;
```
Créez une méthode asynchrone nommée RetrieveActiveProductsAsync qui retourne un IEnumerable<Product>.
```
public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync()
{ }
```
Pour les étapes suivantes, ajoutez ce code dans la méthode RetrieveActiveProductsAsync.
1. 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)
""";
```
2. Créez une variable QueryDefinition nommée query et transmettant la chaîne sql comme seul paramètre de requête. Utilisez également la méthode Fluid WithParameter pour appliquer la valeur de red au paramètre @tagFilter.
```
var query = new QueryDefinition(
    query: sql
)
    .WithParameter("@tagFilter", "red");
```
3. Utilisez la méthode générique GetItemQueryIterator<> et la variable query 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ée feed. 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
);
```
4. 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éthode RetrieveActiveProductsAsync.
```
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.

Bien démarrer avec Azure Cosmos DB for NoSQL et .NET