Zelfstudie: Een ASP.NET-webtoepassing ontwikkelen met Azure Cosmos DB for NoSQL

Artikel
04/10/2024

VAN TOEPASSING OP: NoSQL

Met de Azure SDK voor .NET kunt u query's uitvoeren op gegevens in een API voor NoSQL-container met behulp van LINQ in C# of een SQL-queryreeks. In deze zelfstudie wordt stapsgewijs uitgelegd hoe u een bestaande ASP.NET-webtoepassing bijwerkt waarin tijdelijke aanduidingsgegevens worden gebruikt om in plaats daarvan een query uit te voeren vanuit de API.

In deze zelfstudie leert u het volgende:

Een database en container maken en vullen met behulp van API voor NoSQL
Een ASP.NET-webtoepassing maken op basis van een sjabloon
Query's uitvoeren op gegevens uit de API voor NoSQL-container met behulp van de Azure SDK voor .NET

Vereisten

Een bestaand Azure Cosmos DB for NoSQL-account.
- Als u een bestaand Azure-abonnement hebt, maakt u een nieuw account.
- Geen Azure-abonnement? U kunt Azure Cosmos DB gratis proberen zonder dat er een creditcard is vereist.
Visual Studio Code
.NET 6 (LTS) of hoger
Ervaring met het schrijven van C#-toepassingen.

API maken voor NoSQL-resources

Eerst maakt u een database en container in de bestaande API voor NoSQL-account. Vervolgens vult u dit account met gegevens met behulp van het cosmicworks dotnet-hulpprogramma.

Navigeer naar uw bestaande API voor NoSQL-account in Azure Portal.
Selecteer Sleutels in het resourcemenu.
Bekijk en noteer de waarde van het veld PRIMARY CONNECTION STRING* op de pagina Sleutels. Deze waarde wordt in de hele zelfstudie gebruikt.
Selecteer Data Explorer in het resourcemenu.
Selecteer op de pagina Data Explorer de optie Nieuwe container in de opdrachtbalk.
Maak in het dialoogvenster Nieuwe container een nieuwe container met de volgende instellingen:

Instelling Weergegeven als

Database-id cosmicworks

Type databasedoorvoer Handmatig

Hoeveelheid databasedoorvoer 1000

Container-id products

Partitiesleutel /category/name

Belangrijk

In deze zelfstudie schalen we de database eerst op tot 1000 RU/s in gedeelde doorvoer om de prestaties voor de gegevensmigratie te maximaliseren. Zodra de gegevensmigratie is voltooid, schalen we omlaag naar 400 RU/s van ingerichte doorvoer.
Selecteer OK om de database en container te maken.
Open een terminal om opdrachten uit te voeren om de container met gegevens te vullen.

Tip

U kunt eventueel de Azure Cloud Shell hier gebruiken.
Installeer v2 van het cosmicworks dotnet-hulpprogramma vanuit NuGet.
```
dotnet tool install --global cosmicworks  --version 2.*
```
Gebruik het cosmicworks hulpprogramma om uw API voor NoSQL-account te vullen met voorbeeldproductgegevens met behulp van de waarden URI en PRIMAIRE SLEUTEL die u eerder in dit lab hebt genoteerd. Deze vastgelegde waarden worden respectievelijk gebruikt voor de endpoint en key parameters.
```
cosmicworks \
    --number-of-products 1759 \
    --number-of-employees 0 \
    --disable-hierarchical-partition-keys \
    --connection-string <nosql-connection-string>
```

Instelling	Weergegeven als
Database-id	`cosmicworks`
Type databasedoorvoer	Handmatig
Hoeveelheid databasedoorvoer	`1000`
Container-id	`products`
Partitiesleutel	`/category/name`

Bekijk de uitvoer van het opdrachtregelprogramma. Er moeten 1759 items aan de container worden toegevoegd. De voorbeelduitvoer die is opgenomen, wordt afgekapt voor kortheid.

── 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

Ga terug naar de Data Explorer-pagina voor uw account.
Vouw in de sectie Gegevens het cosmicworks databaseknooppunt uit en selecteer Vervolgens Schalen.
Verminder de doorvoer van 1000 tot 400.
Selecteer Opslaan op de opdrachtbalk.
Vouw in de sectie Gegevens het containerknooppunt producten uit en selecteer het.
Selecteer nieuwe SQL-query in de opdrachtbalk.

Voeg deze SQL-queryreeks toe in de queryeditor.

SELECT
  p.sku,
  p.price
FROM products p
WHERE p.price < 2000
ORDER BY p.price DESC

Selecteer Query uitvoeren om de query uit te voeren en bekijk de resultaten.
De resultaten moeten een gepagineerde matrix zijn van alle items in de container met een price waarde die kleiner is dan 2000 gesorteerd van hoogste prijs tot laagste waarde. Ter beknoptheid wordt hier een subset van de uitvoer opgenomen.
```
[
  {
    "sku": "BK-R79Y-48",
    "price": 1700.99
  },
  ...
  {
    "sku": "FR-M94B-46",
    "price": 1349.6
  },
...
```

Vervang de inhoud van de queryeditor door deze query en selecteer Query uitvoeren opnieuw om de resultaten te bekijken.

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)

De resultaten moeten een kleinere matrix van items zijn die zijn gefilterd om alleen items te bevatten die ten minste één tag bevatten met een naamwaarde van Tag-32. Nogmaals, hier wordt een subset van de uitvoer opgenomen voor beknoptheid.
```
[
  ...
  {
    "name": "HL Touring Frame - Yellow, 60",
    "category": "Components",
    "subcategory": "Touring Frames",
    "tags": [
      "Components",
      "Touring Frames",
      "Yellow",
      "60"
    ]
  },
  ...
]
```

Een ASP.NET-webtoepassing maken

Nu maakt u een nieuwe ASP.NET-webtoepassing met behulp van een voorbeeldprojectsjabloon. Vervolgens verkent u de broncode en voert u het voorbeeld uit om kennis te maken met de toepassing voordat u Azure Cosmos DB-connectiviteit toevoegt met behulp van de Azure SDK voor .NET.

Belangrijk

In deze zelfstudie worden pakketten transparant opgehaald uit NuGet. U kunt uw dotnet nuget list source pakketbronnen controleren. Als u NuGet niet als pakketbron hebt, gebruikt dotnet nuget add source u deze om de site als bron te installeren.

Open een terminal in een lege map.
Installeer het cosmicworks.template.web projectsjabloonpakket vanuit NuGet.
```
dotnet new install cosmicworks.template.web
```
Maak een nieuw webtoepassingsproject met behulp van de zojuist geïnstalleerde dotnet new cosmosdbnosql-webapp sjabloon.
```
dotnet new cosmosdbnosql-webapp
```
Bouw het webtoepassingsproject en voer het uit.
```
dotnet run
```

Bekijk de uitvoer van de run-opdracht. De uitvoer moet een lijst met poorten en URL's bevatten waar de toepassing wordt uitgevoerd.

...
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
...

Open een nieuwe browser en navigeer naar de actieve webtoepassing. Bekijk alle drie de pagina's van de actieve toepassing.
Stop de actieve toepassing door het actieve proces te beëindigen.

Tip

Gebruik de Ctrl C-opdracht + om een actief proces te stoppen. U kunt de terminal ook sluiten en opnieuw openen.
Open Visual Studio Code met behulp van de huidige projectmap als werkruimte.

Tip

U kunt in de terminal uitvoeren code . om Visual Studio Code te openen en de werkmap automatisch te openen als de huidige werkruimte.

Ga naar het bestand Services/ICosmosService.cs en open het. Bekijk de RetrieveActiveProductsAsync en RetrieveAllProductsAsync standaardmethode-implementaties. Met deze methoden maakt u een statische lijst met producten die u voor het eerst wilt gebruiken bij het uitvoeren van het project. Hier vindt u een afgekapt voorbeeld van een van de methoden.

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

Navigeer naar het bestand Services/CosmosService.cs en open het. Bekijk de huidige implementatie van de CosmosService-klasse . Deze klasse implementeert de ICosmosService-interface , maar overschrijft geen methoden. In deze context gebruikt de klasse de standaardinterface-implementatie totdat er een onderdrukking van de implementatie wordt geboden in de interface.
```
public class CosmosService : ICosmosService
{ }
```
Navigeer ten slotte naar de bestanden Modellen/Product.cs en Modellen/Category.cs . Bekijk de recordtypen die in elk bestand zijn gedefinieerd. Deze typen worden in deze zelfstudie gebruikt in query's.
```
public record Product(
    string id,
    Category category,
    string sku,
    string name,
    string description,
    decimal price
);
```
```
public record Category(
    string name
);
```

Query's uitvoeren op gegevens met behulp van de .NET SDK

Vervolgens voegt u de Azure SDK voor .NET toe aan dit voorbeeldproject en gebruikt u de bibliotheek om query's uit te voeren op gegevens uit de API voor NoSQL-container.

Voeg het Microsoft.Azure.Cosmos pakket vanuit NuGet toe aan de terminal.
```
dotnet add package Microsoft.Azure.Cosmos
```
Maak het project.
```
dotnet build
```
Ga in Visual Studio Code opnieuw naar het bestand Services/CosmosService.cs .
Voeg een nieuwe using-instructie toe voor de Microsoft.Azure.Cosmos en Microsoft.Azure.Cosmos.Linq naamruimten.
```
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Linq;
```
Voeg in de Klasse CosmosService een nieuw private readonly lid van het type CosmosClient met de naam _clienttoe.
```
private readonly CosmosClient _client;
```
Maak een nieuwe lege constructor voor de CosmosService klasse.
```
public CosmosService()
{ }
```
Maak in de constructor een nieuw exemplaar van de CosmosClient klasse die een tekenreeksparameter doorgeeft met de waarde PRIMARY CONNECTION STRING die u eerder in het lab hebt vastgelegd. Sla dit nieuwe exemplaar op in het _client lid.
```
public CosmosService()
{ 
    _client = new CosmosClient(
        connectionString: "<primary-connection-string>"
    );
}
```
Maak in de CosmosService-klasse een nieuwe private eigenschap van het type Container met de naamcontainer. Stel de get-accessor in om de cosmicworks database en products container te retourneren.
```
private Container container
{
    get => _client.GetDatabase("cosmicworks").GetContainer("products");
}
```
Maak een nieuwe asynchrone methode met de naam RetrieveAllProductsAsync die een IEnumerable<Product>.
```
public async Task<IEnumerable<Product>> RetrieveAllProductsAsync()
{ }
```
Voor de volgende stappen voegt u deze code toe binnen de RetrieveAllProductsAsync methode.
1. Gebruik de GetItemLinqQueryable<> algemene methode om een object van het type IQueryable<> op te halen dat u kunt gebruiken om een LANGUAGE-Integrated Query (LINQ) te maken. Sla dat object op in een variabele met de naam queryable.
```
var queryable = container.GetItemLinqQueryable<Product>();
```
2. Maak een LINQ-query met behulp van de Where en OrderByDescending extensiemethoden. Gebruik de ToFeedIterator extensiemethode om een iterator te maken om gegevens op te halen uit Azure Cosmos DB en de iterator op te slaan in een variabele met de naam feed. Verpakt deze volledige expressie in een using-instructie om de iterator later te verwijderen.
```
using FeedIterator<Product> feed = queryable
    .Where(p => p.price < 2000m)
    .OrderByDescending(p => p.price)
    .ToFeedIterator();
```
3. Maak een nieuwe variabele met de naam results met behulp van het algemene List<> type.
```
List<Product> results = new();
```
4. Maak een tijdjelus die wordt herhaald totdat de HasMoreResults eigenschap van de feed variabele onwaar retourneert. Deze lus zorgt ervoor dat u alle pagina's met resultaten aan de serverzijde doorloopt.
```
while (feed.HasMoreResults)
{ }
```
5. Binnen de tijdje-lus roept u asynchroon de ReadNextAsync methode van de feed variabele aan en slaat u het resultaat op in een variabele met de naam response.
```
while (feed.HasMoreResults)
{
    var response = await feed.ReadNextAsync();
}
```
6. Gebruik nog steeds binnen de tijdjelus een foreach-lus om elk item in het antwoord te doorlopen en toe te voegen aan de results lijst.
```
while (feed.HasMoreResults)
{
    var response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        results.Add(item);
    }
}
```
7. Retourneert de results lijst als uitvoer van de RetrieveAllProductsAsync methode.
```
return results;
```
Maak een nieuwe asynchrone methode met de naam RetrieveActiveProductsAsync die een IEnumerable<Product>.
```
public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync()
{ }
```
Voor de volgende stappen voegt u deze code toe binnen de RetrieveActiveProductsAsync methode.
1. Maak een nieuwe tekenreeks met de naam sql met een SQL-query om meerdere velden op te halen waarop een filter (@tagFilter) wordt toegepast op tagsmatrix van elk item.
```
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. Maak een nieuwe QueryDefinition variabele met de naam query doorgeven in de sql tekenreeks als de enige queryparameter. Gebruik ook de WithParameter vloeistofmethode om de waarde red toe te passen op de @tagFilter parameter.
```
var query = new QueryDefinition(
    query: sql
)
    .WithParameter("@tagFilter", "red");
```
3. Gebruik de GetItemQueryIterator<> algemene methode en de query variabele om een iterator te maken die gegevens ophaalt uit Azure Cosmos DB. Sla de iterator op in een variabele met de naam feed. Verpakt deze volledige expressie in een using-instructie om de iterator later te verwijderen.
```
using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);
```
4. Gebruik een while-lus om meerdere pagina's met resultaten te doorlopen en de waarde op te slaan in een algemene List<> benoemde resultaten. Retourneer de resultaten als uitvoer van de RetrieveActiveProductsAsync methode.
```
List<Product> results = new();

while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        results.Add(item);
    }
}

return results;
```
Sla het bestand Services/CosmosClient.cs op.

Tip

Als u niet zeker weet dat uw code juist is, kunt u de broncode controleren op de voorbeeldcode op GitHub.

De uiteindelijke toepassing valideren

Ten slotte voert u de toepassing uit met hot-reloads ingeschakeld. Als u de toepassing uitvoert, wordt gecontroleerd of uw code toegang heeft tot gegevens vanuit de API voor NoSQL.

Voer de toepassing uit in de terminal.
```
dotnet run
```
De uitvoer van de opdracht uitvoeren moet een lijst met poorten en URL's bevatten waar de toepassing wordt uitgevoerd. Open een nieuwe browser en navigeer naar de actieve webtoepassing. Bekijk alle drie de pagina's van de actieve toepassing. Elke pagina moet nu livegegevens uit Azure Cosmos DB bevatten.

Resources opschonen

Wanneer u deze niet meer nodig hebt, verwijdert u de database die in deze zelfstudie wordt gebruikt. Hiervoor gaat u naar de accountpagina, selecteert u Data Explorer, selecteert u de cosmicworks database en selecteert u Vervolgens Verwijderen.

Volgende stappen

Nu u uw eerste .NET-webtoepassing hebt gemaakt met Azure Cosmos DB, kunt u nu dieper ingaan op de SDK om meer gegevens te importeren, complexe query's uit te voeren en uw Azure Cosmos DB for NoSQL-resources te beheren.

Aan de slag met Azure Cosmos DB voor NoSQL en .NET