Kurz: Vývoj ASP.NET webové aplikace s využitím služby Azure Cosmos DB for NoSQL
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 verzi
cosmicworks
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í proendpoint
parametry akey
.cosmicworks \ --datasets product \ --endpoint <uri> \ --key <primary-key>
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-32
ná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 aRetrieveAllProductsAsync
. 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ů aMicrosoft.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 typuCosmosClient
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 typuContainer
s názvemcontainer
. Nastavte get accessor pro vrácenícosmicworks
databáze aproducts
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.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ázvemqueryable
.var queryable = container.GetItemLinqQueryable<Product>();
Vytvořte dotaz LINQ pomocí rozšiřujících
Where
metod aOrderByDescending
.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ázvemfeed
. 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();
Vytvořte novou proměnnou s názvem
results
pomocí obecnéhoList<>
typu.List<Product> results = new();
Vytvořte smyčku While , která bude iterovat, dokud
HasMoreResults
vlastnostfeed
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) { }
Ve smyčce While asynchronně volejte
ReadNextAsync
metodufeed
proměnné a výsledek uložíte do proměnné s názvemresponse
.while (feed.HasMoreResults) { var response = await feed.ReadNextAsync(); }
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); } }
results
Vrátí seznam jako výstupRetrieveAllProductsAsync
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.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 """;
Vytvořte novou
QueryDefinition
proměnnou s názvemquery
předánísql
řetězce jako jediného parametru dotazu. K použití hodnotyTag-75
parametruWithParameter
použijte také metodu@tagFilter
fluid.var query = new QueryDefinition( query: sql ) .WithParameter("@tagFilter", "Tag-75");
GetItemQueryIterator<>
Pomocí obecné metody aquery
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ázvemfeed
. 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 );
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ýstupRetrieveActiveProductsAsync
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.