Руководство. Разработка веб-приложения ASP.NET с помощью Azure Cosmos DB для NoSQL
ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL
Пакет SDK Azure для .NET позволяет запрашивать данные в контейнере API для NoSQL с помощью LINQ в C# или строки запроса SQL. В этом руководстве описывается процесс обновления существующего веб-приложения ASP.NET, использующего заполнители для запроса из API.
В этом руководстве описано следующее:
- Создание и заполнение базы данных и контейнера с помощью API для NoSQL
- Создание веб-приложения ASP.NET на основе шаблона
- Запрос данных из контейнера API для NoSQL с помощью пакета SDK Azure для .NET
Необходимые компоненты
- Существующая учетная запись Azure Cosmos DB для NoSQL.
- Если у вас есть подписка Azure, создайте новую учетную запись.
- Нет подписки Azure? Вы можете попробовать Azure Cosmos DB бесплатно без кредитной карты.
- Visual Studio Code
- .NET 6 (LTS) или более поздней версии
- Опыт написания приложений C#.
Создание ресурсов API для NoSQL
Сначала вы создадите базу данных и контейнер в существующей учетной записи API для NoSQL. Затем вы заполните эту учетную запись данными cosmicworks
с помощью средства dotnet.
Перейдите к существующей учетной записи API для NoSQL в портал Azure.
В меню ресурсов выберите "Ключи".
На странице "Ключи" просмотрите и запишите значение поля PRIMARY CONNECTION STRING* . Это значение будет использоваться во всем руководстве.
В меню ресурсов выберите Обозреватель данных.
На странице обозревателя данных выберите параметр "Создать контейнер" на панели команд.
В диалоговом окне создания контейнера создайте новый контейнер со следующими параметрами:
Параметр Значение Идентификатор базы данных cosmicworks
Тип пропускной способности базы данных Вручную Объем пропускной способности базы данных 1000
Идентификатор контейнера products
Ключ секции /category/name
Внимание
В этом руководстве мы сначала масштабируем базу данных до 1000 ЕЗ/с в общей пропускной способности, чтобы повысить производительность миграции данных. После завершения миграции данных мы масштабируем до 400 ЕЗ/с подготовленной пропускной способности.
Нажмите кнопку "ОК ", чтобы создать базу данных и контейнер.
Откройте терминал для выполнения команд, чтобы заполнить контейнер данными.
Совет
Вы также можете использовать Azure Cloud Shell здесь.
Установите версию
cosmicworks
2 средства dotnet из NuGet.dotnet tool install --global cosmicworks --version 2.*
cosmicworks
Используйте средство для заполнения учетной записи API для NoSQL с примерами данных продукта с помощью URI и значений PRIMARY KEY, записанных ранее в этой лаборатории. Эти записанные значения будут использоваться дляendpoint
параметров иkey
параметров соответственно.cosmicworks \ --number-of-products 1759 \ --number-of-employees 0 \ --disable-hierarchical-partition-keys \ --connection-string <nosql-connection-string>
Просмотрите выходные данные из средства командной строки. Он должен добавить в контейнер 1759 элементов. Пример выходных данных, включенных, усечен для краткости.
── 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
Вернитесь на страницу обозревателя данных для учетной записи.
В разделе "Данные" разверните
cosmicworks
узел базы данных и выберите "Масштаб".Уменьшите пропускную способность от 1000 до 400.
В командной строке выберите Сохранить.
В разделе "Данные" разверните узел контейнера продуктов и выберите его.
На панели команд выберите новый SQL-запрос.
В редакторе запросов добавьте эту строку запроса SQL.
SELECT p.sku, p.price FROM products p WHERE p.price < 2000 ORDER BY p.price DESC
Выберите "Выполнить запрос" , чтобы запустить запрос и просмотреть результаты.
Результаты должны быть массивом с разбивкой на страницы всех элементов в контейнере со
price
значением, которое меньше 2000 отсортировано от максимальной цены до наименьшей. Для краткости ниже приведено подмножество выходных данных.[ { "sku": "BK-R79Y-48", "price": 1700.99 }, ... { "sku": "FR-M94B-46", "price": 1349.6 }, ...
Замените содержимое редактора запросов этим запросом, а затем снова нажмите кнопку "Выполнить запрос ", чтобы просмотреть результаты.
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)
Результаты должны быть меньшим массивом элементов, отфильтрованных только для хранения элементов, которые включают по крайней мере один тег со значением
Tag-32
имени. Опять же, подмножество выходных данных включается здесь для краткости.[ ... { "name": "HL Touring Frame - Yellow, 60", "category": "Components", "subcategory": "Touring Frames", "tags": [ "Components", "Touring Frames", "Yellow", "60" ] }, ... ]
Создание веб-приложения ASP.NET
Теперь вы создадите новое веб-приложение ASP.NET с помощью примера шаблона проекта. Затем вы изучите исходный код и запустите пример, чтобы ознакомиться с приложением перед добавлением подключения Azure Cosmos DB с помощью пакета SDK Azure для .NET.
Внимание
В этом руководстве прозрачно извлекает пакеты из NuGet. Вы можете использовать dotnet nuget list source
для проверки источников пакетов. Если у вас нет NuGet в качестве источника пакета, используйте dotnet nuget add source
для установки сайта в качестве источника.
Откройте терминал в пустом каталоге.
cosmicworks.template.web
Установите пакет шаблона проекта из NuGet.dotnet new install cosmicworks.template.web
Создайте проект веб-приложения с помощью только что установленного
dotnet new cosmosdbnosql-webapp
шаблона.dotnet new cosmosdbnosql-webapp
Создайте и запустите проект веб-приложения.
dotnet run
Просмотрите выходные данные команды выполнения. Выходные данные должны содержать список портов и URL-адресов, в которых выполняется приложение.
... 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 ...
Откройте новый браузер и перейдите к работающему веб-приложению. Просмотрите все три страницы запущенного приложения.
Остановите запущенное приложение, завершив выполняемый процесс.
Совет
Чтобы остановить выполняющийся процесс, используйте команду CTRL+C. Кроме того, можно закрыть и повторно открыть терминал.
Откройте Visual Studio Code, используя текущую папку проекта в качестве рабочей области.
Совет
Вы можете запустить
code .
терминал, чтобы открыть Visual Studio Code и автоматически открыть рабочий каталог в качестве текущей рабочей области.Перейдите к файлу Services/ICosmosService.cs и откройте его. Обратите внимание на
RetrieveActiveProductsAsync
реализацию методов по умолчанию.RetrieveAllProductsAsync
Эти методы создают статический список продуктов, используемых при первом запуске проекта. Здесь приведен усеченный пример одного из методов.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), ... }; }
Перейдите к файлу Services/CosmosService.cs и откройте его. Обратите внимание на текущую реализацию класса CosmosService . Этот класс реализует интерфейс ICosmosService , но не переопределяет никакие методы. В этом контексте класс будет использовать реализацию интерфейса по умолчанию, пока не будет предоставлено переопределение реализации в интерфейсе.
public class CosmosService : ICosmosService { }
Наконец, перейдите к файлам Models/Product.cs и Models/Category.cs. Просмотрите типы записей, определенные в каждом файле. Эти типы будут использоваться в запросах на протяжении всего этого руководства.
public record Product( string id, Category category, string sku, string name, string description, decimal price );
public record Category( string name );
Запрос данных с помощью пакета SDK для .NET
Затем вы добавите пакет SDK Azure для .NET в этот пример проекта и используйте библиотеку для запроса данных из контейнера API для NoSQL.
Вернитесь в терминал, добавьте
Microsoft.Azure.Cosmos
пакет из NuGet.dotnet add package Microsoft.Azure.Cosmos
Выполните сборку проекта.
dotnet build
Вернитесь в Visual Studio Code, снова перейдите к файлу Services/CosmosService.cs .
Добавьте новую директиву using для
Microsoft.Azure.Cosmos
пространств имен иMicrosoft.Azure.Cosmos.Linq
пространств имен.using Microsoft.Azure.Cosmos; using Microsoft.Azure.Cosmos.Linq;
В классе CosmosService добавьте новый
private readonly
член типаCosmosClient
с именем_client
.private readonly CosmosClient _client;
Создайте пустой конструктор для
CosmosService
класса.public CosmosService() { }
В конструкторе создайте новый экземпляр
CosmosClient
класса, передавающего строковый параметр с значением PRIMARY CONNECTION STRING , которое вы ранее записали в лаборатории. Сохраните этот новый экземпляр в члене_client
.public CosmosService() { _client = new CosmosClient( connectionString: "<primary-connection-string>" ); }
Вернитесь в класс CosmosService , создайте новое
private
свойство типаContainer
с именемcontainer
. Задайте метод доступа для возвратаcosmicworks
базы данных иproducts
контейнера.private Container container { get => _client.GetDatabase("cosmicworks").GetContainer("products"); }
Создайте асинхронный метод с именем
RetrieveAllProductsAsync
, который возвращаетIEnumerable<Product>
.public async Task<IEnumerable<Product>> RetrieveAllProductsAsync() { }
Чтобы выполнить следующие действия, добавьте этот код в
RetrieveAllProductsAsync
метод.Используйте универсальный
GetItemLinqQueryable<>
метод, чтобы получить объект типаIQueryable<>
, который можно использовать для создания запроса, интегрированного с языком (LINQ). Храните этот объект в переменной с именемqueryable
.var queryable = container.GetItemLinqQueryable<Product>();
Создайте запрос LINQ с помощью
Where
методов расширения иOrderByDescending
методов расширения.ToFeedIterator
Используйте метод расширения для создания итератора для получения данных из Azure Cosmos DB и хранения итератора в переменной с именемfeed
. Обтекайте все это выражение в инструкции using, чтобы удалить итератор позже.using FeedIterator<Product> feed = queryable .Where(p => p.price < 2000m) .OrderByDescending(p => p.price) .ToFeedIterator();
Создайте переменную с именем
results
универсальногоList<>
типа.List<Product> results = new();
Создайте цикл времени, который будет итерировать, пока
HasMoreResults
свойство переменнойfeed
не возвращает значение false. Этот цикл гарантирует, что вы выполняете цикл по всем страницам результатов на стороне сервера.while (feed.HasMoreResults) { }
В цикле в то время асинхронно вызовите
ReadNextAsync
метод переменнойfeed
и сохраните результат в переменной с именемresponse
.while (feed.HasMoreResults) { var response = await feed.ReadNextAsync(); }
По-прежнему в течение цикла используйте цикл foreach для прохождения каждого элемента в ответе и добавления их в
results
список.while (feed.HasMoreResults) { var response = await feed.ReadNextAsync(); foreach (Product item in response) { results.Add(item); } }
results
Возвращает список в качестве выходныхRetrieveAllProductsAsync
данных метода.return results;
Создайте асинхронный метод с именем
RetrieveActiveProductsAsync
, который возвращаетIEnumerable<Product>
.public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync() { }
Чтобы выполнить следующие действия, добавьте этот код в
RetrieveActiveProductsAsync
метод.Создайте новую строку с именем
sql
SQL-запроса, чтобы получить несколько полей, в которых фильтр (@tagFilter
) применяется к массиву тегов каждого элемента.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) """;
Создайте новую
QueryDefinition
переменную с именемquery
, передаваемую в строку вsql
качестве единственного параметра запроса. Кроме того, используйтеWithParameter
метод жидкости для применения значенияred
к параметру@tagFilter
.var query = new QueryDefinition( query: sql ) .WithParameter("@tagFilter", "red");
Используйте универсальный
GetItemQueryIterator<>
метод и переменную для создания итератораquery
, который получает данные из Azure Cosmos DB. Храните итератор в переменной с именемfeed
. Обтекайте все это выражение в инструкции using, чтобы удалить итератор позже.using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>( queryDefinition: query );
Используйте цикл времени для итерации нескольких страниц результатов и хранения значения в универсальных именованных
List<>
результатах. Возвращает результаты в виде выходныхRetrieveActiveProductsAsync
данных метода.List<Product> results = new(); while (feed.HasMoreResults) { FeedResponse<Product> response = await feed.ReadNextAsync(); foreach (Product item in response) { results.Add(item); } } return results;
Сохраните файл Services/CosmosClient.cs .
Совет
Если вы не уверены, что ваш код правильный, вы можете проверить исходный код на основе примера кода на GitHub.
Проверка окончательного приложения
Наконец, вы запустите приложение с включенной горячей перезагрузкой . Запуск приложения проверяет, может ли ваш код получить доступ к данным из API для NoSQL.
Вернитесь в терминал, запустите приложение.
dotnet run
Выходные данные команды выполнения должны содержать список портов и URL-адресов, в которых выполняется приложение. Откройте новый браузер и перейдите к работающему веб-приложению. Просмотрите все три страницы запущенного приложения. Теперь каждая страница должна содержать динамические данные из Azure Cosmos DB.
Очистка ресурсов
При отсутствии необходимости удалите базу данных, используемую в этом руководстве. Для этого перейдите на страницу учетной записи, выберите обозреватель данных, выберите cosmicworks
базу данных и нажмите кнопку "Удалить".
Следующие шаги
Теперь, когда вы создали первое веб-приложение .NET с помощью Azure Cosmos DB, теперь вы можете ознакомиться с пакетом SDK для импорта дополнительных данных, выполнения сложных запросов и управления ресурсами Azure Cosmos DB для NoSQL.