Kurz: Vývoj ASP.NET webové aplikace s využitím služby Azure Cosmos DB for NoSQL

Článek
01/26/2023
9 min ke čtení

PLATÍ PRO: NoSQL

Sada Azure SDK pro .NET umožňuje dotazovat data v kontejneru rozhraní API pro NoSQL pomocí LINQ v jazyce C# nebo řetězce dotazu SQL. Tento kurz vás provede procesem aktualizace existující ASP.NET webové aplikace, která místo dotazování z rozhraní API používá zástupná data.

V tomto kurzu se naučíte:

Vytvoření a naplnění databáze a kontejneru pomocí rozhraní API pro NoSQL
Vytvoření webové aplikace ASP.NET ze šablony
Dotazování dat z kontejneru rozhraní API pro NoSQL pomocí sady Azure SDK pro .NET

Požadavky

Existující účet Azure Cosmos DB for NoSQL
- Pokud máte existující předplatné Azure, vytvořte nový účet.
- Nemáte předplatné Azure? Službu Azure Cosmos DB můžete vyzkoušet zdarma bez nutnosti platební karty.
Visual Studio Code
.NET 6 (LTS) nebo novější
Zkušenosti s psaním aplikací v C#.

Vytvoření rozhraní API pro prostředky NoSQL

Nejprve vytvoříte databázi a kontejner v existujícím účtu rozhraní API pro NoSQL. Tento účet pak naplníte daty pomocí cosmicworks nástroje dotnet.

V Azure Portal přejděte ke stávajícímu účtu rozhraní API pro NoSQL.
V nabídce prostředků vyberte Klíče.
Na stránce Klíče sledujte a zaznamenejte hodnoty polí URI, PRIMARY KEY a PRIMARY CONNECTION STRING*. Tyto hodnoty se budou používat v celém kurzu.
V nabídce prostředků vyberte Data Explorer.
Na stránce Data Explorer vyberte na panelu příkazů možnost Nový kontejner.
V dialogovém okně Nový kontejner vytvořte nový kontejner s následujícím nastavením:

Nastavení Hodnota

ID databáze cosmicworks

Typ propustnosti databáze Ruční

Propustnost databáze 4000

ID kontejneru products

Klíč oddílu /categoryId

Důležité

V tomto kurzu nejprve škálujeme databázi až na 4 000 RU/s ve sdílené propustnosti, abychom maximalizovali výkon migrace dat. Po dokončení migrace dat vertikálně snížíme kapacitu na 400 RU/s zřízené propustnosti.
Výběrem OK vytvořte databázi a kontejner.
Otevřete terminál a spusťte příkazy pro naplnění kontejneru daty.

Tip

Volitelně můžete použít azure Cloud Shell tady.
Nainstalujte předběžnou verzicosmicworks nástroje dotnet z NuGetu.
```
dotnet tool install --global cosmicworks  --prerelease
```
Pomocí tohoto cosmicworks nástroje naplňte účet rozhraní API pro NoSQL ukázkovými daty o produktech pomocí hodnot URI a PRIMARY KEY , které jste si poznamenali dříve v tomto cvičení. Tyto zaznamenané hodnoty se použijí pro endpoint parametry a key .
```
cosmicworks \
    --datasets product \
    --endpoint <uri> \
    --key <primary-key>
```

Nastavení	Hodnota
ID databáze	`cosmicworks`
Typ propustnosti databáze	Ruční
Propustnost databáze	`4000`
ID kontejneru	`products`
Klíč oddílu	`/categoryId`

Podívejte se na výstup z nástroje příkazového řádku. Do kontejneru by se mělo přidat více než 200 položek. Ukázkový výstup je kvůli stručnosti zkrácený.

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

Vraťte se na stránku Data Explorer vašeho účtu.
V části Data rozbalte cosmicworks uzel databáze a pak vyberte Škálovat.
Snižte propustnost ze 4 000 na 400.
Na panelu příkazů vyberte Uložit.
V části Data rozbalte a vyberte uzel kontejneru produktů .
Na panelu příkazů vyberte Nový dotaz SQL.

V editoru dotazů přidejte tento řetězec dotazu SQL.

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

Výběrem možnosti Execute Query (Spustit dotaz ) spusťte dotaz a prohlédněte si výsledky.
Výsledky by měly být stránkované pole všech položek v kontejneru s price hodnotou, která je menší než 2 000 seřazená od nejvyšší ceny po nejnižší. Pro stručnost je zde zahrnuta podmnožina výstupu.
```
[
  {
    "sku": "BK-R79Y-48",
    "price": 1700.99
  },
  ...
  {
    "sku": "FR-M94B-46",
    "price": 1349.6
  },
...
```
Nahraďte obsah editoru dotazů tímto dotazem a pak znovu vyberte Execute Query (Spustit dotaz ) a prohlédněte si výsledky.
```
SELECT
  p.name,
  p.categoryName,
  p.tags
FROM products p
JOIN t IN p.tags
WHERE t.name = "Tag-32"
```
Výsledky by měly být menší pole položek vyfiltrovaných tak, aby obsahovaly pouze položky, které obsahují alespoň jednu značku s hodnotou Tag-32názvu . Opět je zde zahrnuta podmnožina výstupu, aby byla stručná.
```
...
{
"name": "ML Mountain Frame - Black, 44",
"categoryName": "Components, Mountain Frames",
"tags": [
    {
    "id": "18AC309F-F81C-4234-A752-5DDD2BEAEE83",
    "name": "Tag-32"
    }
]
},
...
```

Vytvoření webové aplikace ASP.NET

Teď vytvoříte novou ASP.NET webovou aplikaci pomocí ukázkové šablony projektu. Potom prozkoumáte zdrojový kód a spustíte ukázku, abyste se seznámili s aplikací, než přidáte možnosti připojení ke službě Azure Cosmos DB pomocí sady Azure SDK pro .NET.

Důležité

Tento kurz transparentně načítá balíčky z NuGetu. K ověření zdrojů balíčků můžete použít příkaz dotnet nuget list source . Pokud jako zdroj balíčku nemáte NuGet, nainstalujte lokalitu jako zdroj pomocí příkazu dotnet nuget add source .

Otevřete terminál v prázdném adresáři.
cosmicworks.template.web Nainstalujte balíček šablony projektu z NuGetu.
```
dotnet new install cosmicworks.template.web
```
Vytvořte nový projekt webové aplikace pomocí nově nainstalované dotnet new cosmosdbnosql-webapp šablony.
```
dotnet new cosmosdbnosql-webapp
```
Sestavte a spusťte projekt webové aplikace.
```
dotnet run
```

Prohlédněte si výstup příkazu run. Výstup by měl obsahovat seznam portů a adres URL, na kterých je aplikace spuštěná.

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

Otevřete nový prohlížeč a přejděte do spuštěné webové aplikace. Prohlédněte si všechny tři stránky spuštěné aplikace.
Zastavte spuštěnou aplikaci ukončením spuštěného procesu.

Tip

Pomocí příkazu Ctrl+C zastavte spuštěný proces. Případně můžete terminál zavřít a znovu otevřít.
Otevřete Visual Studio Code a jako pracovní prostor použijte složku aktuálního projektu.

Tip

Spuštěním příkazu v terminálu můžete code . otevřít Visual Studio Code a automaticky otevřít pracovní adresář jako aktuální pracovní prostor.

Přejděte do souboru Services/ICosmosService.cs a otevřete ho. RetrieveActiveProductsAsync Sledujte implementace výchozích metod a RetrieveAllProductsAsync . Tyto metody vytvoří statický seznam produktů, které se mají použít při prvním spuštění projektu. Zde je uveden zkrácený příklad jedné z metod.

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

Přejděte do souboru Services/CosmosService.cs a otevřete ho. Sledujte aktuální implementaci třídy CosmosService . Tato třída implementuje rozhraní ICosmosService , ale nepřepíše žádné metody. V tomto kontextu bude třída používat výchozí implementaci rozhraní, dokud je v rozhraní k dispozici přepsání implementace.
```
public class CosmosService : ICosmosService
{ }
```
Nakonec přejděte na soubor Models/Product.cs a otevřete ho. Sledujte typ záznamu definovaný v tomto souboru. Tento typ se bude používat v dotazech v průběhu tohoto kurzu.
```
public record Product(
    string id,
    string categoryId,
    string categoryName,
    string sku,
    string name,
    string description,
    decimal price
);
```

Dotazování na data pomocí sady .NET SDK

Dále do tohoto ukázkového projektu přidáte sadu Azure SDK pro .NET a použijete knihovnu k dotazování dat z kontejneru rozhraní API for NoSQL.

Zpátky v terminálu přidejte Microsoft.Azure.Cosmos balíček z NuGetu.
```
dotnet add package Microsoft.Azure.Cosmos
```
Sestavte projekt.
```
dotnet build
```
V editoru Visual Studio Code znovu přejděte do souboru Services/CosmosService.cs .
Přidejte novou direktivu Microsoft.Azure.Cosmos using pro obory názvů a Microsoft.Azure.Cosmos.Linq .
```
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Linq;
```
V rámci třídy CosmosService přidejte nového private readonly člena typu CosmosClient s názvem _client.
```
private readonly CosmosClient _client;
```
Vytvořte nový prázdný konstruktor pro CosmosService třídu.
```
public CosmosService()
{ }
```
V konstruktoru vytvořte novou instanci CosmosClient třídy předávající parametr řetězce s hodnotou PRIMARY CONNECTION STRING , kterou jste předtím zaznamenali v testovacím prostředí. Uložte tuto novou instanci do člena _client .
```
public CosmosService()
{ 
    _client = new CosmosClient(
        connectionString: "<primary-connection-string>"
    );
}
```
Zpět ve třídě CosmosService vytvořte novou private vlastnost typu Container s názvem container. Nastavte get accessor pro vrácení cosmicworks databáze a products kontejneru.
```
private Container container
{
    get => _client.GetDatabase("cosmicworks").GetContainer("products");
}
```
Vytvořte novou asynchronní metodu s názvem RetrieveAllProductsAsync , která vrátí IEnumerable<Product>.
```
public async Task<IEnumerable<Product>> RetrieveAllProductsAsync()
{ }
```
Pro další kroky přidejte tento kód do RetrieveAllProductsAsync metody.
1. GetItemLinqQueryable<> Pomocí obecné metody získáte objekt typuIQueryable<>, který můžete použít k vytvoření dotazu LINQ (Language-integrated). Uložte tento objekt do proměnné s názvem queryable.
```
var queryable = container.GetItemLinqQueryable<Product>();
```
2. Vytvořte dotaz LINQ pomocí rozšiřujících Where metod a OrderByDescending . ToFeedIterator Pomocí rozšiřující metody vytvořte iterátor pro získání dat ze služby Azure Cosmos DB a uložení iterátoru do proměnné s názvem feed. Celý tento výraz zabalte do příkazu using, aby se iterátor později vyřadil.
```
using FeedIterator<Product> feed = queryable
    .Where(p => p.price < 2000m)
    .OrderByDescending(p => p.price)
    .ToFeedIterator();
```
3. Vytvořte novou proměnnou s názvem results pomocí obecného List<> typu.
```
List<Product> results = new();
```
4. Vytvořte smyčku While , která bude iterovat, dokud HasMoreResults vlastnost feed proměnné nevrátí hodnotu false. Tato smyčka zajistí, že budete procházet všechny stránky výsledků na straně serveru.
```
while (feed.HasMoreResults)
{ }
```
5. Ve smyčce While asynchronně volejte ReadNextAsync metodu feed proměnné a výsledek uložíte do proměnné s názvem response.
```
while (feed.HasMoreResults)
{
    var response = await feed.ReadNextAsync();
}
```
6. Stále ve smyčce While použijte smyčku foreach , která projde každou položku v odpovědi a přidá je do results seznamu.
```
while (feed.HasMoreResults)
{
    var response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        results.Add(item);
    }
}
```
7. results Vrátí seznam jako výstup RetrieveAllProductsAsync metody.
```
return results;
```
Vytvořte novou asynchronní metodu s názvem RetrieveActiveProductsAsync , která vrátí IEnumerable<Product>.
```
public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync()
{ }
```
Pro další kroky přidejte tento kód do RetrieveActiveProductsAsync metody.
1. Vytvořte nový řetězec s názvem s dotazem sql SQL, který načte více polí, ve kterých se na pole značek každé položky použije filtr (@tagFilter).
```
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. Vytvořte novou QueryDefinition proměnnou s názvem query předání sql řetězce jako jediného parametru dotazu. K použití hodnoty Tag-75 parametru WithParameter použijte také metodu @tagFilter fluid.
```
var query = new QueryDefinition(
    query: sql
)
    .WithParameter("@tagFilter", "Tag-75");
```
3. GetItemQueryIterator<> Pomocí obecné metody a query proměnné vytvořte iterátor, který získává data ze služby Azure Cosmos DB. Uložte iterátor do proměnné s názvem feed. Celý tento výraz zabalte do příkazu using, aby se iterátor později vyřadil.
```
using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);
```
4. Pomocí smyčky While můžete iterovat více stránkami výsledků a uložit hodnotu do obecného List<> pojmenovaného výsledku. Vrátí výsledky jako výstup RetrieveActiveProductsAsync metody.
```
List<Product> results = new();

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

return results;
```
Uložte soubor Services/CosmosClient.cs .

Tip

Pokud si nejste jistí, jestli je váš kód správný, můžete zkontrolovat zdrojový kód s ukázkovým kódem na GitHubu.

Ověření konečné aplikace

Nakonec spustíte aplikaci s povoleným opětovným načítáním za provozu . Spuštěním aplikace se ověří, že váš kód může přistupovat k datům z rozhraní API pro NoSQL.

Zpátky v terminálu spusťte aplikaci.
```
dotnet run
```
Výstup příkazu spuštění by měl obsahovat seznam portů a adres URL, na kterých je aplikace spuštěná. Otevřete nový prohlížeč a přejděte do spuštěné webové aplikace. Sledujte všechny tři stránky spuštěné aplikace. Každá stránka by teď měla obsahovat živá data ze služby Azure Cosmos DB.

Vyčištění prostředků

Pokud už databázi použitou v tomto kurzu nepotřebujete, odstraňte ji. Uděláte to tak, že přejdete na stránku účtu, vyberete Data Explorer, vyberete cosmicworks databázi a pak vyberete Odstranit.

Další kroky

Teď, když jste vytvořili svou první webovou aplikaci .NET pomocí služby Azure Cosmos DB, můžete se teď podrobněji podívat na sadu SDK a importovat další data, provádět složité dotazy a spravovat prostředky Azure Cosmos DB for NoSQL.

Začínáme se službou Azure Cosmos DB for NoSQL a .NET