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

Artikel
03/06/2023
10 minuten om te lezen

VAN TOEPASSING OP: NoSQL

Met de Azure SDK voor .NET kunt u query's uitvoeren op gegevens in een API for NoSQL-container met behulp van LINQ in C# of een SQL-queryreeks. Deze zelfstudie doorloopt het proces voor het bijwerken van een bestaande ASP.NET webtoepassing die gebruikmaakt van tijdelijke aanduidingen voor gegevens om in plaats daarvan query's uit de API uit te voeren.

In deze zelfstudie leert u het volgende:

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

Vereisten

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

API voor NoSQL-resources maken

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

Navigeer naar uw bestaande API voor NoSQL-account in de Azure Portal.
Selecteer Sleutels in het resourcemenu.
Bekijk op de pagina Sleutels de waarde van de velden URI, PRIMAIRE SLEUTEL en PRIMAIRE VERBINDINGSREEKS* en noteer deze. Deze waarden worden 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 Waarde

Database-id cosmicworks

Type databasedoorvoer Handmatig

Hoeveelheid databasedoorvoer 4000

Container-id products

Partitiesleutel /categoryId

Belangrijk

In deze zelfstudie schalen we de database eerst naar 4000 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 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 een voorlopige versie van het cosmicworksdotnet-hulpprogrammavanuit NuGet.
```
dotnet tool install --global cosmicworks  --prerelease
```
Gebruik het cosmicworks hulpprogramma om uw API voor NoSQL-account te vullen met voorbeeldproductgegevens met behulp van de URI - en PRIMARY KEY-waarden die u eerder in dit lab hebt vastgelegd. Deze vastgelegde waarden worden respectievelijk gebruikt voor de endpoint parameters en key .
```
cosmicworks \
    --datasets product \
    --endpoint <uri> \
    --key <primary-key>
```

Instelling	Waarde
Database-id	`cosmicworks`
Type databasedoorvoer	Handmatig
Hoeveelheid databasedoorvoer	`4000`
Container-id	`products`
Partitiesleutel	`/categoryId`

Bekijk de uitvoer van het opdrachtregelprogramma. Er moeten meer dan 200 items aan de container worden toegevoegd. De opgenomen voorbeelduitvoer wordt kortheidshalve afgekapt.

...
Revision:       v4
Datasets:
        product

Database:       [cosmicworks]   Status: Created
Container:      [products]      Status: Ready

product Items Count:    295
Entity: [9363838B-2D13-48E8-986D-C9625BE5AB26]  Container:products      Status: RanToCompletion
...
Container:      [product]       Status: Populated

Ga terug naar de pagina Data Explorer voor uw account.
Vouw in de sectie Gegevens het cosmicworks databaseknooppunt uit en selecteer vervolgens Schalen.
Verlaag de doorvoer van 4000 naar 400.
Selecteer Opslaan in de opdrachtbalk.
Vouw in de sectie Gegevens het containerknooppunt producten uit en selecteer deze.
Selecteer nieuwe SQL-query in de opdrachtbalk.

Voeg in de queryeditor deze SQL-queryreeks toe.

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 de resultaten te bekijken.
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 naar laagste. Kortheidshalve 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 query-editor door deze query en selecteer vervolgens opnieuw Query uitvoeren om de resultaten te bekijken.
```
SELECT
  p.name,
  p.categoryName,
  p.tags
FROM products p
JOIN t IN p.tags
WHERE t.name = "Tag-32"
```
De resultaten moeten een kleinere matrix met items zijn die zijn gefilterd om alleen items te bevatten die ten minste één tag met een naamwaarde van Tag-32bevatten. Nogmaals, hier is ter beknoptheid een subset van de uitvoer opgenomen.
```
...
{
"name": "ML Mountain Frame - Black, 44",
"categoryName": "Components, Mountain Frames",
"tags": [
    {
    "id": "18AC309F-F81C-4234-A752-5DDD2BEAEE83",
    "name": "Tag-32"
    }
]
},
...
```

ASP.NET webtoepassing maken

Nu gaat u een nieuwe ASP.NET webtoepassing maken 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 op transparante wijze opgehaald uit NuGet. U kunt gebruiken dotnet nuget list source om uw pakketbronnen te verifiëren. Als u nuGet niet als pakketbron hebt, gebruikt dotnet nuget add source u 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
```
Het webtoepassingsproject bouwen en uitvoeren.
```
dotnet run
```

Bekijk de uitvoer van de run-opdracht. De uitvoer moet een lijst met poorten en URL's bevatten waarop 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 opdracht Ctrl+C 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 uitvoeren code . in de terminal om Visual Studio Code te openen en de werkmap automatisch te openen als de huidige werkruimte.

Navigeer naar het bestand Services/ICosmosService.cs en open het. Bekijk de implementaties van de RetrieveActiveProductsAsync standaardmethode en RetrieveAllProductsAsync . Met deze methoden wordt een statische lijst met producten gemaakt die moeten worden gebruikt bij het voor de eerste keer 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", categoryId: "3E4CEACD-D007-46EB-82D7-31F6141752B2", categoryName: "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: "d5928182-0307-4bf9-8624-316b9720c58c", categoryId: "AA5A82D4-914C-4132-8C08-E7B75DCE3428", categoryName: "Components, Cranksets", sku: "CS-6583", name: """ML Crankset""", description: """The product called "ML Crankset".""", price: 256.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 een onderdrukking van de implementatie wordt opgegeven in de interface.
```
public class CosmosService : ICosmosService
{ }
```
Navigeer ten slotte naar het bestand Models/Product.cs en open het. Bekijk het recordtype dat in dit bestand is gedefinieerd. Dit type wordt in deze zelfstudie gebruikt in query's.
```
public record Product(
    string id,
    string categoryId,
    string categoryName,
    string sku,
    string name,
    string description,
    decimal price
);
```

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 in de terminal het Microsoft.Azure.Cosmos pakket toe vanuit NuGet.
```
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 naamruimten en Microsoft.Azure.Cosmos.Linq .
```
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Linq;
```
Voeg in de klasse CosmosService een nieuw private readonly lid van het type CosmosClient toe met de naam _client.
```
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 hebt vastgelegd in het lab. 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 naam container. 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>retourneert.
```
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 met taal geïntegreerde 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 extensiemethoden en OrderByDescending . 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. Verpak deze hele 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 while-lus die wordt herhaald totdat de HasMoreResults eigenschap van de feed variabele false retourneert. Deze lus zorgt ervoor dat u alle pagina's met resultaten aan de serverzijde doorloopt.
```
while (feed.HasMoreResults)
{ }
```
5. Binnen de while-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 while-lus 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. Retourneer de results lijst als de uitvoer van de RetrieveAllProductsAsync methode.
```
return results;
```
Maak een nieuwe asynchrone methode met de naam RetrieveActiveProductsAsync die een IEnumerable<Product>retourneert.
```
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 waarin een filter (@tagFilter) wordt toegepast op tagsmatrix van elk item.
```
string sql = """
SELECT
    p.id,
    p.categoryId,
    p.categoryName,
    p.sku,
    p.name,
    p.description,
    p.price,
    p.tags
FROM products p
JOIN t IN p.tags
WHERE t.name = @tagFilter
""";
```
2. Maak een nieuwe QueryDefinition variabele met de naam query passing in de sql tekenreeks als de enige queryparameter. Gebruik ook de WithParameter vloeistofmethode om de waarde Tag-75 toe te passen op de @tagFilter parameter .
```
var query = new QueryDefinition(
    query: sql
)
    .WithParameter("@tagFilter", "Tag-75");
```
3. Gebruik de GetItemQueryIterator<> algemene methode en de query variabele om een iterator te maken waarmee gegevens worden opgehaald uit Azure Cosmos DB. Sla de iterator op in een variabele met de naam feed. Verpak deze hele 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 de 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 of uw code juist is, kunt u uw broncode controleren op basis van 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 uit de API voor NoSQL.

Voer de toepassing uit in de terminal.
```
dotnet run
```
De uitvoer van de run-opdracht moet een lijst met poorten en URL's bevatten waarop 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 van Azure Cosmos DB bevatten.

Resources opschonen

Verwijder de database die in deze zelfstudie wordt gebruikt wanneer u deze niet meer nodig hebt. 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 behulp van Azure Cosmos DB, kunt u dieper ingaan op de SDK om meer gegevens te importeren, complexe query's uit te voeren en uw Azure Cosmos DB voor NoSQL-resources te beheren.

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