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

  • Článek

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

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.

  1. Na webu Azure Portal přejděte ke svému stávajícímu účtu API for NoSQL.

  2. V nabídce prostředků vyberte Klíče.

    Snímek obrazovky se stránkou účtu ROZHRANÍ API pro NoSQL V nabídce prostředků je zvýrazněná možnost Klíče.

  3. Na stránce Klíče sledujte a poznamenejte hodnotu pole PRIMARY CONNECTION STRING*. Tato hodnota se použije v průběhu kurzu.

    Snímek obrazovky se stránkou Klíče se zvýrazněnými poli URI, Primární klíč a Primární Připojení ion String

  4. V nabídce prostředků vyberte Průzkumník dat.

    Snímek obrazovky se zvýrazněnou možností Průzkumník dat v nabídce prostředků

  5. Na stránce Průzkumník dat vyberte na panelu příkazů možnost Nový kontejner.

    Snímek obrazovky s možností Nový kontejner na panelu příkazů Průzkumníka dat

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

    Snímek obrazovky s dialogovým oknem Nový kontejner v Průzkumníku dat s různými hodnotami v jednotlivých polích

    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.

  7. Vyberte OK a vytvořte databázi a kontejner.

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

  9. Nainstalujte nástroj dotnet z NuGetu cosmicworks v2.

    dotnet tool install --global cosmicworks  --version 2.*

  10. 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í pro endpoint parametry a key parametry.

    cosmicworks \
    --number-of-products 1759 \
    --number-of-employees 0 \
    --disable-hierarchical-partition-keys \
    --connection-string <nosql-connection-string>

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

  12. Vraťte se na stránku Průzkumníka dat pro váš účet.

  13. V části Data rozbalte cosmicworks uzel databáze a pak vyberte Škálovat.

    Snímek obrazovky s možností Škálování v databázovém uzlu

  14. Snižte propustnost z 1 000 až na 400.

    Snímek obrazovky s nastavením propustnosti pro databázi, která se snížila na 400 RU/s

  15. Na panelu příkazů vyberte Uložit.

    Snímek obrazovky s možností Uložit na panelu příkazů Průzkumníka dat

  16. V části Data rozbalte uzel kontejneru produktů a vyberte ho.

    Snímek obrazovky s rozbaleným uzlem kontejneru v rámci uzlu databáze

  17. Na panelu příkazů vyberte Nový dotaz SQL.

    Snímek obrazovky s možností Nový dotaz SQL na panelu příkazů Průzkumníka dat

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

  19. Výběrem příkazu Spustit dotaz spusťte dotaz a prohlédněte si výsledky.

    Snímek obrazovky s možností Spustit dotaz na panelu příkazů Průzkumníka dat

  20. 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
  },
...

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

  22. 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-32ná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.

  1. Otevřete terminál v prázdném adresáři.

  2. cosmicworks.template.web Nainstalujte balíček šablony projektu z NuGetu.

    dotnet new install cosmicworks.template.web

  3. Vytvořte nový projekt webové aplikace pomocí nově nainstalované dotnet new cosmosdbnosql-webapp šablony.

    dotnet new cosmosdbnosql-webapp

  4. Sestavte a spusťte projekt webové aplikace.

    dotnet run

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

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

    Snímek obrazovky ukázkové webové aplikace spuštěné se zástupnými daty

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

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

  9. Přejděte do souboru Services/ICosmosService.cs a otevřete ho. RetrieveActiveProductsAsync Sledujte implementace a RetrieveAllProductsAsync 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),
        ...
    };
}

  10. 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
{ }

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

  1. Zpátky v terminálu přidejte Microsoft.Azure.Cosmos balíček z NuGetu.

    dotnet add package Microsoft.Azure.Cosmos

  2. Sestavte projekt.

    dotnet build

  3. Zpět v editoru Visual Studio Code přejděte znovu do souboru Services/CosmosService.cs .

  4. Přidejte novou direktivu using pro obory Microsoft.Azure.Cosmos názvů a Microsoft.Azure.Cosmos.Linq obory názvů.

    using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Linq;

  5. V rámci třídy CosmosService přidejte nového private readonly člena typu CosmosClient s názvem _client.

    private readonly CosmosClient _client;

  6. Vytvořte nový prázdný konstruktor pro CosmosService třídu.

    public CosmosService()
{ }

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

  8. Zpět ve třídě CosmosService vytvořte novou private vlastnost typu Container s názvem container. Nastavte přístupový objekt get pro vrácení cosmicworks databáze a products kontejneru.

    private Container container
{
    get => _client.GetDatabase("cosmicworks").GetContainer("products");
}

  9. Vytvořte novou asynchronní metodu s názvem RetrieveAllProductsAsync , která vrací hodnotu IEnumerable<Product>.

    public async Task<IEnumerable<Product>> RetrieveAllProductsAsync()
{ }

  10. 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 integrovaného jazyka (LINQ). Uložte tento objekt do proměnné s názvem queryable.

      var queryable = container.GetItemLinqQueryable<Product>();

    2. Vytvořte dotaz LINQ pomocí Where metod rozšíření a OrderByDescending 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ázvem feed. 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();

    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 procházíte 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 uložte výsledek 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á 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);
    }
}

    7. results Vrátí seznam jako výstup RetrieveAllProductsAsync metody.

      return results;

  11. Vytvořte novou asynchronní metodu s názvem RetrieveActiveProductsAsync , která vrací hodnotu IEnumerable<Product>.

    public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync()
{ }

  12. Pro další kroky přidejte tento kód do RetrieveActiveProductsAsync metody.

    1. 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)
""";

    2. Vytvořte novou QueryDefinition proměnnou s názvem query předávající sql řetězec jako jediný parametr dotazu. Použijte také metodu WithParameter tekutiny k použití hodnoty red parametru @tagFilter .

      var query = new QueryDefinition(
    query: sql
)
    .WithParameter("@tagFilter", "red");

    3. 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ázvem feed. 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
);

    4. 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ý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;

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

  1. Zpátky v terminálu spusťte aplikaci.

    dotnet run

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

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