Självstudie: Utveckla en ASP.NET webbapp med Azure Cosmos DB för NoSQL

GÄLLER FÖR: NoSQL

Med Azure SDK för .NET kan du fråga efter data i en API för NoSQL-container med LINQ i C# eller en SQL-frågesträng. Den här självstudien går igenom processen med att uppdatera en befintlig ASP.NET webbapp som använder platshållardata för att i stället fråga från API:et.

I den här guiden får du lära dig att:

  • Skapa och fylla i en databas och container med API för NoSQL
  • Skapa en ASP.NET webbapp från en mall
  • Fråga efter data från API:et för NoSQL-containern med hjälp av Azure SDK för .NET

Förutsättningar

Skapa API för NoSQL-resurser

Först skapar du en databas och container i det befintliga API:et för NoSQL-kontot. Sedan fyller du i det här kontot med data med hjälp av cosmicworks dotnet-verktyget.

  1. Gå till ditt befintliga API för NoSQL-konto i Azure Portal.

  2. I resursmenyn väljer du Nycklar.

    Skärmbild av en API för NoSQL-kontosida. Alternativet Nycklar är markerat på resursmenyn.

  3. På sidan Nycklar observerar och registrerar du värdet för fälten URI, PRIMÄR NYCKEL och PRIMÄR ANSLUTNINGSSTRÄNG*. Dessa värden kommer att användas under hela självstudien.

    Skärmbild av sidan Nycklar med fälten URI, Primär nyckel och Primär anslutningssträng markerade.

  4. I resursmenyn väljer du Data Explorer.

    Skärmbild av alternativet Data Explorer markerat på resursmenyn.

  5. På sidan Data Explorer väljer du alternativet Ny container i kommandofältet.

    Skärmbild av alternativet Ny container i kommandofältet Data Explorer.

  6. I dialogrutan Ny container skapar du en ny container med följande inställningar:

    Inställning Värde
    Databas-ID cosmicworks
    Databasdataflödestyp Manuell
    Databasdataflödesmängd 4000
    Container-ID products
    Partitionsnyckel /categoryId

    Skärmbild av dialogrutan Ny container i Data Explorer med olika värden i varje fält.

    Viktigt

    I den här självstudien skalar vi först databasen upp till 4 000 RU/s i delat dataflöde för att maximera prestanda för datamigreringen. När datamigreringen är klar skalar vi ned till 400 RU/s för etablerat dataflöde.

  7. Välj OK för att skapa databasen och containern.

  8. Öppna en terminal för att köra kommandon för att fylla containern med data.

    Tips

    Du kan också använda Azure Cloud Shell här.

  9. Installera en förhandsversionav cosmicworks dotnet-verktyget från NuGet.

    dotnet tool install --global cosmicworks  --prerelease
    
  10. Använd verktyget cosmicworks för att fylla i ditt API för NoSQL-konto med exempelproduktdata med hjälp av de URI- och PRIMÄRNYCKEL-värden som du registrerade tidigare i den här labbuppgiften. Dessa registrerade värden kommer att användas för parametrarna endpoint och key .

    cosmicworks \
        --datasets product \
        --endpoint <uri> \
        --key <primary-key>
    
  11. Observera utdata från kommandoradsverktyget. Den bör lägga till fler än 200 objekt i containern. Exempelutdata som ingår trunkeras för korthet.

    ...
    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. Gå tillbaka till sidan Data Explorer för ditt konto.

  13. I avsnittet Data expanderar du databasnoden cosmicworks och väljer sedan Skala.

    Skärmbild av alternativet Skala i databasnoden.

  14. Minska dataflödet från 4 000 till 400.

    Skärmbild av dataflödesinställningarna för databasen minskade till 400 RU/s.

  15. I kommandofältet väljer du Spara.

    Skärmbild av alternativet Spara i kommandofältet Data Explorer.

  16. I avsnittet Data expanderar och väljer du produktcontainernoden.

    Skärmbild av den expanderade containernoden i databasnoden.

  17. I kommandofältet väljer du Ny SQL-fråga.

    Skärmbild av alternativet Ny SQL-fråga i kommandofältet Data Explorer.

  18. Lägg till den här SQL-frågesträngen i frågeredigeraren.

    SELECT
      p.sku,
      p.price
    FROM products p
    WHERE p.price < 2000
    ORDER BY p.price DESC
    
  19. Välj Kör fråga för att köra frågan och observera resultatet.

    Skärmbild av alternativet Kör fråga i kommandofältet Data Explorer.

  20. Resultatet bör vara en sidnumrerad matris med alla objekt i containern med ett price värde som är mindre än 2 000 sorterade från högsta pris till lägsta. För korthet inkluderas en delmängd av utdata här.

    [
      {
        "sku": "BK-R79Y-48",
        "price": 1700.99
      },
      ...
      {
        "sku": "FR-M94B-46",
        "price": 1349.6
      },
    ...
    
  21. Ersätt innehållet i frågeredigeraren med den här frågan och välj sedan Kör fråga igen för att se resultatet.

    SELECT
      p.name,
      p.categoryName,
      p.tags
    FROM products p
    JOIN t IN p.tags
    WHERE t.name = "Tag-32"
    
  22. Resultatet bör vara en mindre matris med objekt som filtreras för att endast innehålla objekt som innehåller minst en tagg med namnvärdetTag-32. Återigen ingår en delmängd av utdata här för korthet.

    ...
    {
    "name": "ML Mountain Frame - Black, 44",
    "categoryName": "Components, Mountain Frames",
    "tags": [
        {
        "id": "18AC309F-F81C-4234-A752-5DDD2BEAEE83",
        "name": "Tag-32"
        }
    ]
    },
    ...
    

Skapa ASP.NET webbapp

Nu ska du skapa en ny ASP.NET webbapp med hjälp av en exempelprojektmall. Sedan utforskar du källkoden och kör exemplet för att bekanta dig med programmet innan du lägger till Azure Cosmos DB-anslutning med Azure SDK för .NET.

Viktigt

Den här självstudien hämtar transparent paket från NuGet. Du kan använda dotnet nuget list source för att verifiera dina paketkällor. Om du inte har NuGet som paketkälla använder dotnet nuget add source du för att installera platsen som källa.

  1. Öppna en terminal i en tom katalog.

  2. Installera projektmallspaketet cosmicworks.template.web från NuGet.

    dotnet new install cosmicworks.template.web
    
  3. Skapa ett nytt webbprogramprojekt med den nyligen installerade dotnet new cosmosdbnosql-webapp mallen.

    dotnet new cosmosdbnosql-webapp
    
  4. Skapa och kör webbprogramprojektet.

    dotnet run
    
  5. Observera utdata från körningskommandot. Utdata bör innehålla en lista över portar och URL:er där programmet körs.

    ...
    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. Öppna en ny webbläsare och gå till webbprogrammet som körs. Observera alla tre sidorna i det program som körs.

    Skärmbild av exempelwebbprogrammet som körs med platshållardata.

  7. Stoppa det program som körs genom att avsluta den pågående processen.

    Tips

    Använd Ctrl+C-kommandot för att stoppa en pågående process. Du kan också stänga och öppna terminalen igen.

  8. Öppna Visual Studio Code med den aktuella projektmappen som arbetsyta.

    Tips

    Du kan köra code . i terminalen för att öppna Visual Studio Code och automatiskt öppna arbetskatalogen som den aktuella arbetsytan.

  9. Gå till och öppna filen Services/ICosmosService.cs . Observera implementeringarna och RetrieveActiveProductsAsyncRetrieveAllProductsAsync standardmetoden. De här metoderna skapar en statisk lista över produkter som ska användas när projektet körs för första gången. Ett trunkerat exempel på en av metoderna finns här.

    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. Gå till och öppna filen Services/CosmosService.cs . Observera den aktuella implementeringen av CosmosService-klassen . Den här klassen implementerar ICosmosService-gränssnittet men åsidosätter inga metoder. I det här sammanhanget använder klassen standardgränssnittsimplementeringen tills en åsidosättning av implementeringen anges i gränssnittet.

    public class CosmosService : ICosmosService
    { }
    
  11. Gå slutligen till och öppna filen Models/Product.cs . Observera posttypen som definierats i den här filen. Den här typen används i frågor i den här självstudien.

    public record Product(
        string id,
        string categoryId,
        string categoryName,
        string sku,
        string name,
        string description,
        decimal price
    );
    

Fråga efter data med hjälp av .NET SDK

Därefter lägger du till Azure SDK för .NET i det här exempelprojektet och använder biblioteket för att fråga efter data från API:et för NoSQL-containern.

  1. Lägg till paketet från NuGet i terminalen Microsoft.Azure.Cosmos .

    dotnet add package Microsoft.Azure.Cosmos
    
  2. Bygga projektet.

    dotnet build
    
  3. Gå tillbaka till filen Services/CosmosService.cs i Visual Studio Code.

  4. Lägg till ett nytt användningsdirektiv för Microsoft.Azure.Cosmos namnrymderna och Microsoft.Azure.Cosmos.Linq .

    using Microsoft.Azure.Cosmos;
    using Microsoft.Azure.Cosmos.Linq;
    
  5. I klassen CosmosService lägger du till en ny private readonly medlem av typen CosmosClient_client.

    private readonly CosmosClient _client;
    
  6. Skapa en ny tom konstruktor för CosmosService klassen.

    public CosmosService()
    { }
    
  7. I konstruktorn skapar du en ny instans av CosmosClient klassen som skickar in en strängparameter med värdet PRIMARY CONNECTION STRING som du tidigare registrerade i labbet. Lagra den här nya instansen _client i medlemmen.

    public CosmosService()
    { 
        _client = new CosmosClient(
            connectionString: "<primary-connection-string>"
        );
    }
    
  8. Tillbaka i CosmosService-klassen skapar du en ny private egenskap av typen Containercontainer. Ange att get-accessorn ska returnera cosmicworks databasen och products containern.

    private Container container
    {
        get => _client.GetDatabase("cosmicworks").GetContainer("products");
    }
    
  9. Skapa en ny asynkron metod med namnet RetrieveAllProductsAsync som returnerar en IEnumerable<Product>.

    public async Task<IEnumerable<Product>> RetrieveAllProductsAsync()
    { }
    
  10. Lägg till den här koden i metoden för RetrieveAllProductsAsync nästa steg.

    1. Använd den GetItemLinqQueryable<> allmänna metoden för att hämta ett objekt av typen IQueryable<> som du kan använda för att skapa en språkintegrerad fråga (LINQ). Lagra objektet i en variabel med namnet queryable.

      var queryable = container.GetItemLinqQueryable<Product>();
      
    2. Skapa en LINQ-fråga med hjälp av tilläggsmetoderna Where och OrderByDescending . ToFeedIterator Använd tilläggsmetoden för att skapa en iterator för att hämta data från Azure Cosmos DB och lagra iteratorn i en variabel med namnet feed. Omslut hela uttrycket i en using-instruktion för att ta bort iteratorn senare.

      using FeedIterator<Product> feed = queryable
          .Where(p => p.price < 2000m)
          .OrderByDescending(p => p.price)
          .ToFeedIterator();
      
    3. Skapa en ny variabel med namnet results med den allmänna List<> typen.

      List<Product> results = new();
      
    4. Skapa en while-loop som itererar tills HasMoreResults egenskapen för variabeln feed returnerar false. Den här loopen ser till att du loopar igenom alla sidor med resultat på serversidan.

      while (feed.HasMoreResults)
      { }
      
    5. I while-loopen anropar ReadNextAsync du asynkront metoden för variabeln feed och lagrar resultatet i en variabel med namnet .response

      while (feed.HasMoreResults)
      {
          var response = await feed.ReadNextAsync();
      }
      
    6. I while-loopen använder du en foreach-loop för att gå igenom varje objekt i svaret och lägga till dem i results listan.

      while (feed.HasMoreResults)
      {
          var response = await feed.ReadNextAsync();
          foreach (Product item in response)
          {
              results.Add(item);
          }
      }
      
    7. Returnera listan results som utdata för RetrieveAllProductsAsync metoden.

      return results;
      
  11. Skapa en ny asynkron metod med namnet RetrieveActiveProductsAsync som returnerar en IEnumerable<Product>.

    public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync()
    { }
    
  12. Lägg till den här koden i metoden för RetrieveActiveProductsAsync nästa steg.

    1. Skapa en ny sträng med namnet sql med en SQL-fråga för att hämta flera fält där ett filter (@tagFilter) tillämpas på taggar för varje objekt.

      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. Skapa en ny QueryDefinition variabel med namnet query som skickar strängen sql som den enda frågeparametern. WithParameter Använd även fluidmetoden för att tillämpa värdet Tag-75 på parametern@tagFilter.

      var query = new QueryDefinition(
          query: sql
      )
          .WithParameter("@tagFilter", "Tag-75");
      
    3. Använd den GetItemQueryIterator<> allmänna metoden och variabeln query för att skapa en iterator som hämtar data från Azure Cosmos DB. Lagra iteratorn i en variabel med namnet feed. Omslut hela uttrycket i en using-instruktion för att ta bort iteratorn senare.

      using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
          queryDefinition: query
      );
      
    4. Använd en while-loop för att iterera genom flera sidor med resultat och lagra värdet i ett allmänt List<> namngivet resultat. Returnera resultatet som utdata för RetrieveActiveProductsAsync metoden.

      List<Product> results = new();
      
      while (feed.HasMoreResults)
      {
          FeedResponse<Product> response = await feed.ReadNextAsync();
          foreach (Product item in response)
          {
              results.Add(item);
          }
      }
      
      return results;
      
  13. Spara filen Services/CosmosClient.cs .

    Tips

    Om du är osäker på om koden är korrekt kan du kontrollera källkoden mot exempelkoden på GitHub.

Verifiera det slutliga programmet

Slutligen kör du programmet med frekventa omladdningar aktiverade. Om du kör programmet verifieras att koden kan komma åt data från API:et för NoSQL.

  1. Kör programmet i terminalen.

    dotnet run
    
  2. Utdata från körningskommandot bör innehålla en lista över portar och URL:er där programmet körs. Öppna en ny webbläsare och gå till webbprogrammet som körs. Observera alla tre sidorna i det program som körs. Varje sida bör nu innehålla livedata från Azure Cosmos DB.

Rensa resurser

Ta bort databasen som används i den här självstudien när den inte längre behövs. Det gör du genom att gå till kontosidan, välja Data Explorer, välja cosmicworks databasen och sedan ta bort.

Nästa steg

Nu när du har skapat ditt första .NET-webbprogram med Azure Cosmos DB kan du nu fördjupa dig i SDK:n för att importera mer data, utföra komplexa frågor och hantera Azure Cosmos DB för NoSQL-resurser.