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

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. V Azure Portal přejděte ke stávajícímu účtu rozhraní API pro 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 zaznamenejte hodnoty polí URI, PRIMARY KEY a PRIMARY CONNECTION STRING*. Tyto hodnoty se budou používat v celém kurzu.

    Snímek obrazovky se stránkou Klíče se zvýrazněnými poli URI, Primární klíč a Primární připojovací řetězec

  4. V nabídce prostředků vyberte Data Explorer.

    Snímek obrazovky se zvýrazněnou možností Data Explorer v nabídce prostředků

  5. Na stránce Data Explorer vyberte na panelu příkazů možnost Nový kontejner.

    Snímek obrazovky s možností Nový kontejner na panelu příkazů Data Explorer

  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í
    Propustnost databáze 4000
    ID kontejneru products
    Klíč oddílu /categoryId

    Snímek obrazovky s dialogovým oknem Nový kontejner v Data Explorer s různými hodnotami v každém poli

    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.

  7. Výběrem OK vytvořte databázi a kontejner.

  8. Otevřete terminál a spusťte příkazy pro naplnění kontejneru daty.

    Tip

    Volitelně můžete použít azure Cloud Shell tady.

  9. Nainstalujte předběžnou verzicosmicworks nástroje dotnet z NuGetu.

    dotnet tool install --global cosmicworks  --prerelease
    
  10. 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>
    
  11. 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
    
  12. Vraťte se na stránku Data Explorer vašeho účtu.

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

    Snímek obrazovky s možností Škálovat v rámci uzlu databáze

  14. Snižte propustnost ze 4 000 na 400.

    Snímek obrazovky s nastavením propustnosti pro databázi sníženou na 400 RU/s

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

    Snímek obrazovky s možností Uložit na panelu příkazů Data Explorer

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

    Snímek obrazovky s rozbaleným uzlem kontejneru v 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ů Data Explorer

  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 možnosti Execute Query (Spustit dotaz ) spusťte dotaz a prohlédněte si výsledky.

    Snímek obrazovky s možností Spustit dotaz na panelu příkazů Data Explorer

  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á 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 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"
    
  22. 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 .

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

    Snímek obrazovky s ukázkovou webovou aplikací spuštěnou 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 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.

  9. 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)
        };
    }
    
  10. 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
    { }
    
  11. 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.

  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. V editoru Visual Studio Code znovu přejděte do souboru Services/CosmosService.cs .

  4. 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;
    
  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 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>"
        );
    }
    
  8. 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");
    }
    
  9. Vytvořte novou asynchronní metodu s názvem RetrieveAllProductsAsync , která vrátí 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 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;
      
  11. Vytvořte novou asynchronní metodu s názvem RetrieveActiveProductsAsync , která vrátí 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 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;
      
  13. 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.

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