Samouczek: tworzenie aplikacji internetowej ASP.NET za pomocą usługi Azure Cosmos DB for NoSQL
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
- Istniejące konto usługi Azure Cosmos DB for NoSQL.
- Jeśli masz istniejącą subskrypcję platformy Azure, utwórz nowe konto.
- Brak subskrypcji platformy Azure? Możesz wypróbować usługę Azure Cosmos DB bezpłatnie bez konieczności korzystania z karty kredytowej.
- Visual Studio Code
- .NET 6 (LTS) lub nowszy
- Doświadczenie w pisaniu aplikacji w języku C#.
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.
Przejdź do istniejącego konta interfejsu API dla noSQL w witrynie Azure Portal.
W menu zasobów wybierz pozycję Klucze.
Na stronie Klucze sprawdź i zarejestruj wartość pola PODSTAWOWE PARAMETRY POŁĄCZENIA*. Ta wartość będzie używana w całym samouczku.
W menu zasobów wybierz pozycję Eksplorator danych.
Na stronie Eksplorator danych wybierz opcję Nowy kontener na pasku poleceń.
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
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.
Wybierz przycisk OK , aby utworzyć bazę danych i kontener.
Otwórz terminal, aby uruchomić polecenia w celu wypełnienia kontenera danymi.
Napiwek
Opcjonalnie możesz użyć usługi Azure Cloud Shell tutaj.
Zainstaluj narzędzie dotnet w wersji 2
cosmicworks
z narzędzia NuGet.dotnet tool install --global cosmicworks --version 2.*
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 dlaendpoint
parametrów ikey
.cosmicworks \ --number-of-products 1759 \ --number-of-employees 0 \ --disable-hierarchical-partition-keys \ --connection-string <nosql-connection-string>
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
Wróć do strony Eksplorator danych dla swojego konta.
W sekcji Dane rozwiń
cosmicworks
węzeł bazy danych, a następnie wybierz pozycję Skaluj.Zmniejsz przepływność z 1000 do 400.
Na pasku poleceń wybierz pozycję Zapisz.
W sekcji Dane rozwiń węzeł kontenera products i wybierz go.
Na pasku poleceń wybierz pozycję Nowe zapytanie SQL.
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
Wybierz pozycję Wykonaj zapytanie , aby uruchomić zapytanie i obserwować wyniki.
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 }, ...
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)
Wyniki powinny być mniejszą tablicą elementów filtrowanych tak, aby zawierały tylko elementy zawierające co najmniej jeden tag z wartością
Tag-32
nazwy . 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.
Otwórz terminal w pustym katalogu.
Zainstaluj pakiet szablonu
cosmicworks.template.web
projektu z pakietu NuGet.dotnet new install cosmicworks.template.web
Utwórz nowy projekt aplikacji internetowej przy użyciu nowo zainstalowanego
dotnet new cosmosdbnosql-webapp
szablonu.dotnet new cosmosdbnosql-webapp
Skompiluj i uruchom projekt aplikacji internetowej.
dotnet run
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 ...
Otwórz nową przeglądarkę i przejdź do uruchomionej aplikacji internetowej. Obserwuj wszystkie trzy strony uruchomionej aplikacji.
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.
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.Przejdź do pliku Services/ICosmosService.cs i otwórz go.
RetrieveActiveProductsAsync
Obserwuj implementacje metod domyślnych iRetrieveAllProductsAsync
. 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), ... }; }
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 { }
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.
Wróć do terminalu
Microsoft.Azure.Cosmos
, dodaj pakiet z narzędzia NuGet.dotnet add package Microsoft.Azure.Cosmos
Skompiluj projekt.
dotnet build
Wróć do programu Visual Studio Code, przejdź ponownie do pliku Services/CosmosService.cs .
Dodaj nową dyrektywę using dla
Microsoft.Azure.Cosmos
przestrzeni nazw iMicrosoft.Azure.Cosmos.Linq
.using Microsoft.Azure.Cosmos; using Microsoft.Azure.Cosmos.Linq;
W klasie CosmosService dodaj nowy
private readonly
element członkowski typuCosmosClient
o nazwie_client
.private readonly CosmosClient _client;
Utwórz nowy pusty konstruktor dla
CosmosService
klasy .public CosmosService() { }
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>" ); }
Z powrotem w klasie CosmosService utwórz nową
private
właściwość typuContainer
o nazwiecontainer
. Ustaw metodę pobierania, aby zwrócićcosmicworks
bazę danych iproducts
kontener.private Container container { get => _client.GetDatabase("cosmicworks").GetContainer("products"); }
Utwórz nową metodę asynchroniczną o nazwie
RetrieveAllProductsAsync
, która zwracaIEnumerable<Product>
wartość .public async Task<IEnumerable<Product>> RetrieveAllProductsAsync() { }
Aby wykonać następne kroki, dodaj ten kod w metodzie
RetrieveAllProductsAsync
.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 nazwiequeryable
.var queryable = container.GetItemLinqQueryable<Product>();
Konstruowanie zapytania LINQ przy użyciu
Where
metod iOrderByDescending
.ToFeedIterator
Użyj metody rozszerzenia, aby utworzyć iterator w celu pobrania danych z usługi Azure Cosmos DB i zapisania iteratora w zmiennej o nazwiefeed
. 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();
Utwórz nową zmienną o nazwie
results
przy użyciu typu ogólnegoList<>
.List<Product> results = new();
Utwórz pętlę while , która będzie iterować, dopóki
HasMoreResults
właściwość zmiennejfeed
nie zwróci wartości false. Ta pętla zapewnia pętlę przez wszystkie strony wyników po stronie serwera.while (feed.HasMoreResults) { }
W pętli while asynchronicznie wywołaj
ReadNextAsync
metodęfeed
zmiennej i zapisz wynik w zmiennej o nazwieresponse
.while (feed.HasMoreResults) { var response = await feed.ReadNextAsync(); }
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); } }
results
Zwróć listę jako dane wyjścioweRetrieveAllProductsAsync
metody .return results;
Utwórz nową metodę asynchroniczną o nazwie
RetrieveActiveProductsAsync
, która zwracaIEnumerable<Product>
wartość .public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync() { }
Aby wykonać następne kroki, dodaj ten kod w metodzie
RetrieveActiveProductsAsync
.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) """;
Utwórz nową
QueryDefinition
zmienną o nazwiequery
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");
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 nazwiefeed
. Zawijaj to całe wyrażenie w instrukcji using, aby później usunąć iterator.using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>( queryDefinition: query );
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ścioweRetrieveActiveProductsAsync
metody .List<Product> results = new(); while (feed.HasMoreResults) { FeedResponse<Product> response = await feed.ReadNextAsync(); foreach (Product item in response) { results.Add(item); } } return results;
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.
Ponownie w terminalu uruchom aplikację.
dotnet run
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.