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 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 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 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, PRIMÁRNÍ KLÍČ a PRIMÁRNÍ PŘIPOJOVACÍ ŘETĚZEC*. Tyto hodnoty se použijí 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ř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í
    Velikost propustnosti 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 na 4 000 RU/s ve sdílené propustnosti, abychom maximalizovali výkon migrace dat. Po dokončení migrace dat se vertikálně snížit 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ěžnouverzi cosmicworks nástroje dotnet z NuGetu.

    dotnet tool install --global cosmicworks  --prerelease
    
  10. Pomocí nástroje cosmicworks naplňte účet rozhraní API pro NoSQL ukázkovými daty o produktech pomocí hodnot URI a PRIMÁRNÍ KLÍČ , které jste si poznamenali dříve v tomto cvičení. Tyto zaznamenané hodnoty se použijí pro endpoint parametry a key v uvedeném pořadí.

    cosmicworks \
        --datasets product \
        --endpoint <uri> \
        --key <primary-key>
    
  11. Sledujte výstup nástroje příkazového řádku. Do kontejneru by se mělo přidat více než 200 položek. Zahrnutý příklad výstupu je zkrácen pro stručnost.

    ...
    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álování v uzlu databáze

  14. Snižte propustnost z 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 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ů 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 sledujte 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ý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 viděli 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 pro stručnost.

    ...
    {
    "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 webovou aplikaci ASP.NET pomocí ukázkové šablony projektu. Potom 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.

  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. Pomocí nově nainstalované dotnet new cosmosdbnosql-webapp šablony vytvořte nový projekt webové aplikace.

    dotnet new cosmosdbnosql-webapp
    
  4. Sestavte a spusťte projekt webové aplikace.

    dotnet run
    
  5. Sledujte výstup příkazu spuštění. 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. 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

    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 se v rozhraní nezobrazí 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í 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 rozhraní API pro 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 k 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. Do 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 CosmosClient třídu .

    public CosmosClient()
    { }
    
  7. V konstruktoru vytvořte novou instanci CosmosClient třídy, která předává řetězcový parametr s hodnotou PRIMARY CONNECTION STRING , kterou jste si předtím poznamenali v testovacím prostředí. Uložte tuto novou instanci do člena _client .

    public CosmosClient()
    { 
        _client = new CosmosClient(
            connectionString: "<primary-connection-string>"
        );
    }
    
  8. Zpět ve třídě CosmosClient vytvořte novou private vlastnost typu Container s názvem container. Nastavte objekt get accessor tak, aby vracel cosmicworks databázi a products kontejner.

    private Container container
    {
        get => _client.GetDatabase("cosmicworks").GetContainer("products");
    }
    
  9. Vytvořte novou asynchronní metodu IEnumerable<Product>s názvem RetrieveAllProductsAsync , která vrací .

    public async Task<IEnumerable<Product>> RetrieveAllProductsAsync()
    { }
    
  10. Pro další kroky přidejte tento kód v rámci RetrieveAllProductsAsync metody .

    1. GetItemLinqQueryable<> Pomocí obecné metody získáte objekt typuIQueryable<>, který můžete použít k vytvoření jazykově integrovaného dotazu (LINQ). 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žte ho do proměnné s názvem feed. Celý tento výraz zabalte do příkazu using, aby se iterátor později vyhodil.

      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 projdete všechny stránky výsledků na straně serveru.

      while (feed.HasMoreResults)
      { }
      
    5. V rámci smyčky while asynchronně volejte metodu ReadNextAsyncfeed 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á 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 IEnumerable<Product>s názvem RetrieveActiveProductsAsync , která vrací .

    public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync()
    { }
    
  12. Pro další kroky přidejte tento kód v rámci RetrieveActiveProductsAsync metody .

    1. Vytvořte nový řetězec s názvem s názvem sql s dotazem 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á 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 vyhodil.

      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 zdrojový kód zkontrolovat s ukázkovým kódem na GitHubu.

Ověření konečné aplikace

Nakonec aplikaci spustíte s povoleným opětovným načítáním za provozu . Spuštění aplikace 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 watch
    

    Poznámka

    dotnet watch Je zde povolená, takže pokud zjistíte chybu, můžete kód rychle změnit.

  2. Výstup příkazu run 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. Prohlédněte si 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, databázi cosmicworks a pak vyberete Odstranit.

Další kroky

Teď, když jste vytvořili svoji první webovou aplikaci .NET pomocí Služby Azure Cosmos DB, můžete se ponořit hlouběji do sady SDK a importovat další data, provádět složité dotazy a spravovat prostředky Azure Cosmos DB for NoSQL.