Kurz: Vývoj webové aplikace ASP.NET pomocí služby Azure Cosmos DB for NoSQL
PLATÍ PRO: NoSQL
Sada Azure SDK pro .NET umožňuje dotazovat data v kontejneru API for NoSQL pomocí LINQ v jazyce C# nebo řetězce dotazu SQL. Tento kurz vás provede procesem aktualizace existující webové aplikace ASP.NET, která místo toho používá zástupná data k dotazování z rozhraní API.
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 API for 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.
- Žádné 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 jazyce 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.
Na webu Azure Portal přejděte ke svému stávajícímu účtu API for NoSQL.
V nabídce prostředků vyberte Klíče.
Na stránce Klíče sledujte a poznamenejte hodnotu pole PRIMARY CONNECTION STRING*. Tato hodnota se použije v průběhu kurzu.
V nabídce prostředků vyberte Průzkumník dat.
Na stránce Průzkumník dat 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í Velikost propustnosti databáze 1000
ID kontejneru products
Klíč oddílu /category/name
Důležité
V tomto kurzu nejprve škálujeme databázi na 1 000 RU/s ve sdílené propustnosti, abychom maximalizovali výkon migrace dat. Po dokončení migrace dat se vertikálně navyšujeme na 400 RU/s zřízené propustnosti.
Vyberte OK a vytvořte databázi a kontejner.
Otevřete terminál pro spuštění příkazů pro naplnění kontejneru daty.
Tip
Tady můžete volitelně použít Azure Cloud Shell.
Nainstalujte nástroj dotnet z NuGetu
cosmicworks
v2.dotnet tool install --global cosmicworks --version 2.*
cosmicworks
Tento nástroj použijte k naplnění účtu ROZHRANÍ API pro NoSQL ukázkovými daty produktů pomocí hodnot URI a PRIMÁRNÍHO KLÍČE, které jste si poznamenali dříve v tomto cvičení. Tyto zaznamenané hodnoty se použijí proendpoint
parametry akey
parametry.cosmicworks \ --number-of-products 1759 \ --number-of-employees 0 \ --disable-hierarchical-partition-keys \ --connection-string <nosql-connection-string>
Sledujte výstup nástroje příkazového řádku. Do kontejneru by se mělo přidat 1759 položek. Ukázkový výstup je zkrácen pro stručnost.
── 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
Vraťte se na stránku Průzkumníka dat pro váš účet.
V části Data rozbalte
cosmicworks
uzel databáze a pak vyberte Škálovat.Snižte propustnost z 1 000 až na 400.
Na panelu příkazů vyberte Uložit.
V části Data rozbalte uzel kontejneru produktů a vyberte ho.
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 příkazu 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ých 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 Spustit dotaz , abyste mohli sledovat výsledky.
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)
Výsledky by měly být menší pole položek filtrovaný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 pro stručnost.[ ... { "name": "HL Touring Frame - Yellow, 60", "category": "Components", "subcategory": "Touring Frames", "tags": [ "Components", "Touring Frames", "Yellow", "60" ] }, ... ]
Vytvoření webové aplikace ASP.NET
Teď vytvoříte novou ASP.NET webovou aplikaci pomocí ukázkové šablony projektu. Pak prozkoumáte zdrojový kód a spustíte ukázku, abyste se seznámili s aplikací před přidáním 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. Můžete použít dotnet nuget list source
k ověření zdrojů balíčků. Pokud nemáte NuGet jako zdroj balíčku, použijte dotnet nuget add source
k instalaci lokality jako zdroj.
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, ve 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. Sledujte 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 pomocí aktuální složky projektu jako pracovního prostoru.
Tip
V terminálu můžete spustit
code .
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 aRetrieveAllProductsAsync
výchozí metody. Tyto metody vytvoří statický seznam produktů, které se mají použít při prvním spuštění projektu. Tady 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", 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), ... }; }
Přejděte na soubor 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 třída použije výchozí implementaci rozhraní, dokud není v rozhraní k dispozici přepsání implementace.
public class CosmosService : ICosmosService { }
Nakonec přejděte k souborům Models/Product.cs a Models/Category.cs a otevřete je. Sledujte typy záznamů definované v jednotlivých souborech. Tyto typy se použijí v dotazech v tomto kurzu.
public record Product( string id, Category category, string sku, string name, string description, decimal price );
public record Category( string name );
Dotazování dat 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 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
Zpět v editoru Visual Studio Code přejděte znovu do souboru Services/CosmosService.cs .
Přidejte novou direktivu using pro obory
Microsoft.Azure.Cosmos
názvů aMicrosoft.Azure.Cosmos.Linq
obory názvů.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, která předává 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 přístupový objekt get 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á vrací hodnotuIEnumerable<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 integrovaného jazyka (LINQ). Uložte tento objekt do proměnné s názvemqueryable
.var queryable = container.GetItemLinqQueryable<Product>();
Vytvořte dotaz LINQ pomocí
Where
metod rozšíření aOrderByDescending
metod.ToFeedIterator
Pomocí metody rozšíření 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
. Zabalte tento celý výraz 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 procházíte všechny stránky výsledků na straně serveru.while (feed.HasMoreResults) { }
Ve smyčce while asynchronně volejte
ReadNextAsync
metodufeed
proměnné a uložte výsledek 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á prochází 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á vrací hodnotuIEnumerable<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
sql
dotazu 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.name, p.category, p.sku, p.description, p.price FROM products p JOIN tag IN p.tags WHERE STRINGEQUALS(tag, @tagFilter, true) """;
Vytvořte novou
QueryDefinition
proměnnou s názvemquery
předávajícísql
řetězec jako jediný parametr dotazu. Použijte také metoduWithParameter
tekutiny k použití hodnotyred
parametru@tagFilter
.var query = new QueryDefinition( query: sql ) .WithParameter("@tagFilter", "red");
GetItemQueryIterator<>
Použijte obecnou metodu a proměnnou k vytvoření iterátoruquery
, který získává data ze služby Azure Cosmos DB. Uložte iterátor do proměnné s názvemfeed
. Zabalte tento celý výraz 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 iterujte více stránek výsledků a uložte hodnotu do obecných
List<>
pojmenovaných výsledků. 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 Služby/CosmosClient.cs.
Tip
Pokud si nejste jistí, že je váš kód správný, můžete zdrojový kód zkontrolovat 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 ověříte, že váš kód má přístup 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, ve 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 Průzkumník dat, 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, teď se můžete hlouběji ponořit do sady SDK a importovat další data, provádět složité dotazy a spravovat prostředky Azure Cosmos DB for NoSQL.
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro