Samouczek: tworzenie aplikacji internetowej ASP.NET za pomocą usługi Azure Cosmos DB for NoSQL

  • Artykuł

DOTYCZY: NoSQL

Zestaw Azure SDK dla platformy .NET umożliwia wykonywanie zapytań dotyczących danych w kontenerze interfejsu API for NoSQL przy użyciu linQ w języku C# lub ciągu zapytania SQL. W tym samouczku przedstawiono proces aktualizowania istniejącej aplikacji internetowej ASP.NET, która używa danych zastępczych do wykonywania zapytań z interfejsu API.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

  • Tworzenie i wypełnianie bazy danych i kontenera przy użyciu interfejsu API dla noSQL
  • Tworzenie aplikacji internetowej ASP.NET na podstawie szablonu
  • Wykonywanie zapytań dotyczących danych z kontenera interfejsu API for NoSQL przy użyciu zestawu Azure SDK dla platformy .NET

Wymagania wstępne

Tworzenie interfejsu API dla zasobów NoSQL

Najpierw utworzysz bazę danych i kontener w istniejącym interfejsie API dla konta NoSQL. Następnie wypełnisz to konto danymi przy użyciu cosmicworks narzędzia dotnet.

  1. Przejdź do istniejącego konta interfejsu API dla noSQL w witrynie Azure Portal.

  2. W menu zasobów wybierz pozycję Klucze.

    Zrzut ekranu przedstawiający stronę interfejsu API dla konta NoSQL. Opcja Klucze jest wyróżniona w menu zasobów.

  3. Na stronie Klucze sprawdź i zarejestruj wartość pola PODSTAWOWE PARAMETRY POŁĄCZENIA*. Ta wartość będzie używana w całym samouczku.

    Zrzut ekranu przedstawiający stronę Klucze z wyróżnionymi polami URI, Klucz podstawowy i Ciąg Połączenie ion podstawowy.

  4. W menu zasobów wybierz pozycję Eksplorator danych.

    Zrzut ekranu przedstawiający opcję Eksplorator danych wyróżnioną w menu zasobów.

  5. Na stronie Eksplorator danych wybierz opcję Nowy kontener na pasku poleceń.

    Zrzut ekranu przedstawiający opcję Nowy kontener na pasku poleceń Eksplorator danych.

  6. W oknie dialogowym Nowy kontener utwórz nowy kontener z następującymi ustawieniami:

    Ustawienie Wartość
    Identyfikator bazy danych cosmicworks
    Typ przepływności bazy danych Ręczne
    Ilość przepływności bazy danych 1000
    Identyfikator kontenera products
    Klucz partycji /category/name

    Zrzut ekranu przedstawiający okno dialogowe Nowy kontener w Eksploratorze danych z różnymi wartościami w każdym polu.

    Ważne

    W tym samouczku najpierw przeskalujemy bazę danych do 1000 RU/s w udostępnionej przepływności, aby zmaksymalizować wydajność migracji danych. Po zakończeniu migracji danych przeskalujemy w dół do 400 RU/s aprowizowanej przepływności.

  7. Wybierz przycisk OK , aby utworzyć bazę danych i kontener.

  8. Otwórz terminal, aby uruchomić polecenia w celu wypełnienia kontenera danymi.

    Napiwek

    Opcjonalnie możesz użyć usługi Azure Cloud Shell tutaj.

  9. Zainstaluj narzędzie dotnet w wersji 2cosmicworks z narzędzia NuGet.

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

  10. cosmicworks Użyj narzędzia , aby wypełnić interfejs API dla konta NoSQL przykładowymi danymi produktu przy użyciu wartości identyfikatora URI i KLUCZA PODSTAWOWEgo zarejestrowanych wcześniej w tym laboratorium. Te zarejestrowane wartości będą używane odpowiednio dla endpoint parametrów i key .

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

  11. Obserwuj dane wyjściowe z narzędzia wiersza polecenia. Powinien on dodać do kontenera 1759 elementów. Przykładowe dane wyjściowe są obcięte w celu zwięzłości.

    ── 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. Wróć do strony Eksplorator danych dla swojego konta.

  13. W sekcji Dane rozwiń cosmicworks węzeł bazy danych, a następnie wybierz pozycję Skaluj.

    Zrzut ekranu przedstawiający opcję Skalowanie w węźle bazy danych.

  14. Zmniejsz przepływność z 1000 do 400.

    Zrzut ekranu przedstawiający ustawienia przepływności bazy danych ograniczone do 400 RU/s.

  15. Na pasku poleceń wybierz pozycję Zapisz.

    Zrzut ekranu przedstawiający opcję Zapisz na pasku poleceń Eksploratora danych.

  16. W sekcji Dane rozwiń węzeł kontenera products i wybierz go.

    Zrzut ekranu przedstawiający rozwinięty węzeł kontenera w węźle bazy danych.

  17. Na pasku poleceń wybierz pozycję Nowe zapytanie SQL.

    Zrzut ekranu przedstawiający opcję Nowe zapytanie SQL na pasku poleceń eksploratora danych.

  18. W edytorze zapytań dodaj ten ciąg zapytania SQL.

    SELECT
  p.sku,
  p.price
FROM products p
WHERE p.price < 2000
ORDER BY p.price DESC

  19. Wybierz pozycję Wykonaj zapytanie , aby uruchomić zapytanie i obserwować wyniki.

    Zrzut ekranu przedstawiający opcję Wykonaj zapytanie na pasku poleceń Eksploratora danych.

  20. Wyniki powinny być tablicą z podziałem na strony wszystkich elementów w kontenerze z wartością price mniejszą niż 2000 posortowaną od najwyższej ceny do najniższej. W przypadku zwięzłości w tym miejscu znajduje się podzbiór danych wyjściowych.

    [
  {
    "sku": "BK-R79Y-48",
    "price": 1700.99
  },
  ...
  {
    "sku": "FR-M94B-46",
    "price": 1349.6
  },
...

  21. Zastąp zawartość edytora zapytań tym zapytaniem, a następnie ponownie wybierz pozycję Wykonaj zapytanie , aby obserwować wyniki.

    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. Wyniki powinny być mniejszą tablicą elementów filtrowanych tak, aby zawierały tylko elementy zawierające co najmniej jeden tag z wartością Tag-32nazwy . Ponownie podzbiór danych wyjściowych jest uwzględniony w tym miejscu w celu zwięzłości.

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

Tworzenie aplikacji internetowej ASP.NET

Teraz utworzysz nową aplikację internetową ASP.NET przy użyciu przykładowego szablonu projektu. Następnie zapoznasz się z kodem źródłowym i uruchomisz przykład, aby zapoznać się z aplikacją przed dodaniem łączności usługi Azure Cosmos DB przy użyciu zestawu Azure SDK dla platformy .NET.

Ważne

Ten samouczek w sposób przezroczysty ściąga pakiety z pakietu NuGet. Możesz użyć dotnet nuget list source polecenia , aby zweryfikować źródła pakietów. Jeśli nie masz pakietu NuGet jako źródła pakietów, użyj polecenia dotnet nuget add source , aby zainstalować lokację jako źródło.

  1. Otwórz terminal w pustym katalogu.

  2. Zainstaluj pakiet szablonu cosmicworks.template.web projektu z pakietu NuGet.

    dotnet new install cosmicworks.template.web

  3. Utwórz nowy projekt aplikacji internetowej przy użyciu nowo zainstalowanego dotnet new cosmosdbnosql-webapp szablonu.

    dotnet new cosmosdbnosql-webapp

  4. Skompiluj i uruchom projekt aplikacji internetowej.

    dotnet run

  5. Zwróć uwagę na dane wyjściowe polecenia run. Dane wyjściowe powinny zawierać listę portów i adresów URL, na których działa aplikacja.

    ...
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. Otwórz nową przeglądarkę i przejdź do uruchomionej aplikacji internetowej. Obserwuj wszystkie trzy strony uruchomionej aplikacji.

    Zrzut ekranu przedstawiający przykładową aplikację internetową uruchomioną z danymi zastępczymi.

  7. Zatrzymaj uruchomioną aplikację, przerywając uruchomiony proces.

    Napiwek

    Aby zatrzymać uruchomiony proces, użyj kombinacji klawiszy Ctrl+C. Alternatywnie możesz zamknąć i ponownie otworzyć terminal.

  8. Otwórz program Visual Studio Code przy użyciu bieżącego folderu projektu jako obszaru roboczego.

    Napiwek

    Możesz uruchomić polecenie code . w terminalu, aby otworzyć program Visual Studio Code i automatycznie otworzyć katalog roboczy jako bieżący obszar roboczy.

  9. Przejdź do pliku Services/ICosmosService.cs i otwórz go. RetrieveActiveProductsAsync Obserwuj implementacje metod domyślnych i RetrieveAllProductsAsync . Te metody tworzą statyczną listę produktów do użycia podczas pierwszego uruchamiania projektu. Tutaj podano obcięty przykład jednej 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. Przejdź do pliku Services/CosmosService.cs i otwórz go. Obserwuj bieżącą implementację klasy CosmosService . Ta klasa implementuje interfejs ICosmosService , ale nie zastępuje żadnych metod. W tym kontekście klasa będzie używać implementacji interfejsu domyślnego do momentu zastąpienia implementacji w interfejsie.

    public class CosmosService : ICosmosService
{ }

  11. Na koniec przejdź do i otwórz pliki Models/Product.cs i Models/Category.cs . Obserwuj typy rekordów zdefiniowane w każdym pliku. Te typy będą używane w zapytaniach w tym samouczku.

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

    public record Category(
    string name
);

Wykonywanie zapytań dotyczących danych przy użyciu zestawu SDK platformy .NET

Następnie dodasz zestaw Azure SDK dla platformy .NET do tego przykładowego projektu i użyjesz biblioteki do wykonywania zapytań o dane z kontenera interfejsu API for NoSQL.

  1. Wróć do terminalu Microsoft.Azure.Cosmos , dodaj pakiet z narzędzia NuGet.

    dotnet add package Microsoft.Azure.Cosmos

  2. Skompiluj projekt.

    dotnet build

  3. Wróć do programu Visual Studio Code, przejdź ponownie do pliku Services/CosmosService.cs .

  4. Dodaj nową dyrektywę using dla Microsoft.Azure.Cosmos przestrzeni nazw i Microsoft.Azure.Cosmos.Linq .

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

  5. W klasie CosmosService dodaj nowy private readonly element członkowski typu CosmosClient o nazwie _client.

    private readonly CosmosClient _client;

  6. Utwórz nowy pusty konstruktor dla CosmosService klasy .

    public CosmosService()
{ }

  7. W konstruktorze utwórz nowe wystąpienie CosmosClient klasy przekazującej parametr ciągu z wartością PRIMARY CONNECTION STRING wcześniej zarejestrowaną w laboratorium. Zapisz to nowe wystąpienie w elemencie _client członkowskim.

    public CosmosService()
{ 
    _client = new CosmosClient(
        connectionString: "<primary-connection-string>"
    );
}

  8. Z powrotem w klasie CosmosService utwórz nową private właściwość typu Container o nazwie container. Ustaw metodę pobierania, aby zwrócić cosmicworks bazę danych i products kontener.

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

  9. Utwórz nową metodę asynchroniczną o nazwie RetrieveAllProductsAsync , która zwraca IEnumerable<Product>wartość .

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

  10. Aby wykonać następne kroki, dodaj ten kod w metodzie RetrieveAllProductsAsync .

    1. GetItemLinqQueryable<> Użyj metody ogólnej, aby uzyskać obiekt typuIQueryable<>, którego można użyć do konstruowania zapytania zintegrowanego z językiem (LINQ). Zapisz ten obiekt w zmiennej o nazwie queryable.

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

    2. Konstruowanie zapytania LINQ przy użyciu Where metod i OrderByDescending . ToFeedIterator Użyj metody rozszerzenia, aby utworzyć iterator w celu pobrania danych z usługi Azure Cosmos DB i zapisania iteratora w zmiennej o nazwie feed. Zawijaj to całe wyrażenie w instrukcji using, aby później usunąć iterator.

      using FeedIterator<Product> feed = queryable
    .Where(p => p.price < 2000m)
    .OrderByDescending(p => p.price)
    .ToFeedIterator();

    3. Utwórz nową zmienną o nazwie results przy użyciu typu ogólnego List<> .

      List<Product> results = new();

    4. Utwórz pętlę while , która będzie iterować, dopóki HasMoreResults właściwość zmiennej feed nie zwróci wartości false. Ta pętla zapewnia pętlę przez wszystkie strony wyników po stronie serwera.

      while (feed.HasMoreResults)
{ }

    5. W pętli while asynchronicznie wywołaj ReadNextAsync metodę feed zmiennej i zapisz wynik w zmiennej o nazwie response.

      while (feed.HasMoreResults)
{
    var response = await feed.ReadNextAsync();
}

    6. Nadal w pętli while użyj pętli foreach , aby przejść przez każdy element w odpowiedzi i dodać je do results listy.

      while (feed.HasMoreResults)
{
    var response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        results.Add(item);
    }
}

    7. results Zwróć listę jako dane wyjściowe RetrieveAllProductsAsync metody .

      return results;

  11. Utwórz nową metodę asynchroniczną o nazwie RetrieveActiveProductsAsync , która zwraca IEnumerable<Product>wartość .

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

  12. Aby wykonać następne kroki, dodaj ten kod w metodzie RetrieveActiveProductsAsync .

    1. Utwórz nowy ciąg o nazwie sql z zapytaniem SQL, aby pobrać wiele pól, w których filtr (@tagFilter) jest stosowany do tablicy tagów każdego elementu.

      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. Utwórz nową QueryDefinition zmienną o nazwie query przekazującą sql ciąg jako jedyny parametr zapytania. Ponadto użyj metody fluid, WithParameter aby zastosować wartość red do parametru @tagFilter .

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

    3. GetItemQueryIterator<> Użyj metody ogólnej i zmiennejquery, aby utworzyć iterator, który pobiera dane z usługi Azure Cosmos DB. Zapisz iterator w zmiennej o nazwie feed. Zawijaj to całe wyrażenie w instrukcji using, aby później usunąć iterator.

      using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);

    4. Użyj pętli czasowej, aby iterować wiele stron wyników i przechowywać wartość w ogólnych List<> nazwach wyników. Zwróć wyniki jako dane wyjściowe 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. Zapisz plik Usługi/CosmosClient.cs.

    Napiwek

    Jeśli nie masz pewności, że kod jest poprawny, możesz sprawdzić kod źródłowy pod kątem przykładowego kodu w witrynie GitHub.

Weryfikowanie ostatecznej aplikacji

Na koniec uruchomisz aplikację z włączonymi przeładowywaniem na gorąco. Uruchomienie aplikacji zweryfikuje, że kod może uzyskiwać dostęp do danych z interfejsu API for NoSQL.

  1. Ponownie w terminalu uruchom aplikację.

    dotnet run

  2. Dane wyjściowe polecenia run powinny zawierać listę portów i adresów URL, na których działa aplikacja. Otwórz nową przeglądarkę i przejdź do uruchomionej aplikacji internetowej. Obserwuj wszystkie trzy strony uruchomionej aplikacji. Każda strona powinna teraz zawierać dane na żywo z usługi Azure Cosmos DB.

Czyszczenie zasobów

Gdy baza danych używana w tym samouczku nie będzie już potrzebna, usuń bazę danych. W tym celu przejdź do strony konta, wybierz pozycję Eksplorator danych, wybierz cosmicworks bazę danych, a następnie wybierz pozycję Usuń.

Następne kroki

Po utworzeniu pierwszej aplikacji internetowej platformy .NET przy użyciu usługi Azure Cosmos DB możesz teraz dokładniej zapoznać się z zestawem SDK, aby zaimportować więcej danych, wykonać złożone zapytania i zarządzać zasobami usługi Azure Cosmos DB for NoSQL.

Rozpoczynanie pracy z usługą Azure Cosmos DB dla baz danych NoSQL i platformy .NET