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

  • Artikel

GÄLLER FÖR: NoSQL

Med Azure SDK för .NET kan du köra frågor mot data i ett API för NoSQL-container med LINQ i C# eller en SQL-frågesträng. I den här självstudien går vi igenom processen med att uppdatera ett befintligt ASP.NET webbprogram som använder platshållardata för att i stället fråga från API:et.

I den här självstudien lär du dig att:

  • Skapa och fylla i en databas och container med hjälp av API för NoSQL
  • Skapa ett ASP.NET webbprogram 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-portalen.

  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ältet PRIMÄR ANSLUTNINGSSTRÄNG* . Det här värdet används under hela självstudien.

    Skärmbild av sidan Nycklar med fälten URI, Primärnyckel och Primär Anslut jonsträng markerade.

  4. I resursmenyn väljer du Datautforskaren.

    Skärmbild av alternativet Datautforskaren som är markerat på resursmenyn.

  5. På sidan Datautforskarenväljer du alternativet Ny container i kommandofältet.

    Skärmbild av alternativet Ny container i datautforskarens kommandofält.

  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ödesbelopp 1000
    Container-ID products
    Partitionsnyckel /category/name

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

    Viktigt!

    I den här självstudien skalar vi först databasen upp till 1 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.

    Dricks

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

  9. Installera v2 av cosmicworks dotnet-verktyget från NuGet.

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

  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ÄRNYCKELvärden som du registrerade tidigare i den här labbuppgiften. De registrerade värdena kommer att användas för parametrarna endpoint och key .

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

  11. Observera utdata från kommandoradsverktyget. Den bör lägga till 1 759 objekt i containern. Exempelutdata som ingår trunkeras för korthet.

    ── 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. Gå tillbaka till datautforskarens sida 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 1 000 till 400.

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

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

    Skärmbild av alternativet Spara i datautforskarens kommandofält.

  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 datautforskarens kommandofält.

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

  20. Resultatet ska 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.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. Resultatet bör vara en mindre matris med objekt som filtreras så att de endast innehåller objekt som innehåller minst en tagg med namnvärdet Tag-32. Återigen ingår en delmängd av utdata här för korthet.

    [
  ...
  {
    "name": "HL Touring Frame - Yellow, 60",
    "category": "Components",
    "subcategory": "Touring Frames",
    "tags": [
      "Components",
      "Touring Frames",
      "Yellow",
      "60"
    ]
  },
  ...
]

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 hjälp av 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 du dotnet nuget add source 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 hjälp av 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 programmet 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.

    Dricks

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

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

    Dricks

    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 . RetrieveActiveProductsAsyncRetrieveAllProductsAsync Observera och standardmetodimplementeringar. De här metoderna skapar en statisk lista över produkter som ska användas när du kör projektet 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", 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. Gå till och öppna filen Services/CosmosService.cs . Observera den aktuella implementeringen av klassen CosmosService . 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 filerna Models/Product.cs och Models/Category.cs . Observera de posttyper som definierats i varje fil. Dessa typer kommer att användas i frågor under den här självstudien.

    public record Product(
    string id,
    Category category,
    string sku,
    string name,
    string description,
    decimal price
);

    public record Category(
    string name
);

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 med namnet _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 Klassen CosmosService skapar du en ny private egenskap av typen Container med namnet container. Ställ in get-accessorn för att 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 konstruera 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 generiska 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 säkerställer 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. Använd en foreach-loop i while-loopen 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å taggarnas matris för varje objekt.

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

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

    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.

    Dricks

    Om du är osäker på att 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 programmet 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 Datautforskarencosmicworks, välja 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 gå djupare in i SDK:n för att importera mer data, utföra komplexa frågor och hantera Azure Cosmos DB för NoSQL-resurser.

Kom igång med Azure Cosmos DB för NoSQL och .NET