Tutorial: Desenvolver um aplicativo Web ASP.NET com o Azure Cosmos DB para NoSQL
APLICA-SE A: NoSQL
O SDK do Azure para .NET permite que você consulte dados em um contêiner de API para NoSQL usando LINQ em C# ou uma cadeia de caracteres de consulta SQL. Este tutorial percorrerá o processo de atualização de um aplicativo Web ASP.NET existente que usa dados de espaço reservado para consultar a partir da API.
Neste tutorial, irá aprender a:
- Criar e preencher um banco de dados e contêiner usando a API para NoSQL
- Criar um aplicativo Web ASP.NET a partir de um modelo
- Consultar dados do contêiner API para NoSQL usando o SDK do Azure para .NET
Pré-requisitos
- Uma conta existente do Azure Cosmos DB para NoSQL.
- Se você tiver uma assinatura existente do Azure, crie uma nova conta.
- Não há assinatura do Azure? Você pode experimentar o Azure Cosmos DB gratuitamente sem necessidade de cartão de crédito.
- Visual Studio Code
- .NET 6 (LTS) ou posterior
- Experiência na escrita de aplicativos em C#.
Criar API para recursos NoSQL
Primeiro, você criará um banco de dados e um contêiner na API existente para a conta NoSQL. Em seguida, você preencherá essa conta com dados usando a cosmicworks
ferramenta dotnet.
Navegue até sua conta existente da API para NoSQL no portal do Azure.
No menu de recursos, selecione Chaves.
Na página Chaves, observe e registre o valor do campo CADEIA DE CONEXÃO PRIMÁRIA*. Esse valor será usado durante todo o tutorial.
No menu de recursos, selecione Data Explorer.
Na página Data Explorer, selecione a opção Novo Contêiner na barra de comandos.
Na caixa de diálogo Novo contêiner, crie um novo contêiner com as seguintes configurações:
Definição Value ID da base de dados cosmicworks
Tipo de taxa de transferência do banco de dados Manual Valor da taxa de transferência do banco de dados 1000
ID do contentor products
Chave de partição /category/name
Importante
Neste tutorial, primeiro dimensionaremos o banco de dados até 1.000 RU/s em taxa de transferência compartilhada para maximizar o desempenho da migração de dados. Quando a migração de dados estiver concluída, reduziremos para 400 RU/s de taxa de transferência provisionada.
Selecione OK para criar o banco de dados e o contêiner.
Abra um terminal para executar comandos para preencher o contêiner com dados.
Gorjeta
Opcionalmente, você pode usar o Azure Cloud Shell aqui.
Instale a v2 da
cosmicworks
ferramenta dotnet do NuGet.dotnet tool install --global cosmicworks --version 2.*
Use a
cosmicworks
ferramenta para preencher sua conta API para NoSQL com dados de produto de exemplo usando os valores de URI e CHAVE PRIMÁRIA que você registrou anteriormente neste laboratório. Esses valores registados serão utilizados para osendpoint
parâmetros ekey
respectivamente.cosmicworks \ --number-of-products 1759 \ --number-of-employees 0 \ --disable-hierarchical-partition-keys \ --connection-string <nosql-connection-string>
Observe a saída da ferramenta de linha de comando. Deve adicionar 1759 itens ao recipiente. A saída de exemplo incluída é truncada para brevidade.
── 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
Regresse à página Data Explorer da sua conta.
Na seção Dados, expanda o nó do
cosmicworks
banco de dados e selecione Dimensionar.Reduza a taxa de transferência de 1.000 para 400.
Na barra de comandos, selecione Salvar.
Na seção Dados, expanda e selecione o nó do contêiner de produtos.
Na barra de comandos, selecione Nova consulta SQL.
No editor de consultas, adicione esta cadeia de caracteres de consulta SQL.
SELECT p.sku, p.price FROM products p WHERE p.price < 2000 ORDER BY p.price DESC
Selecione Executar consulta para executar a consulta e observar os resultados.
Os resultados devem ser uma matriz paginada de todos os itens no contêiner com um
price
valor inferior a 2.000 classificados do preço mais alto para o mais baixo. Por uma questão de brevidade, um subconjunto da saída está incluído aqui.[ { "sku": "BK-R79Y-48", "price": 1700.99 }, ... { "sku": "FR-M94B-46", "price": 1349.6 }, ...
Substitua o conteúdo do editor de consultas por esta consulta e, em seguida, selecione Executar consulta novamente para observar os resultados.
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)
Os resultados devem ser uma matriz menor de itens filtrados para conter apenas itens que incluam pelo menos uma tag com um valor de nome de
Tag-32
. Novamente, um subconjunto da saída é incluído aqui para brevidade.[ ... { "name": "HL Touring Frame - Yellow, 60", "category": "Components", "subcategory": "Touring Frames", "tags": [ "Components", "Touring Frames", "Yellow", "60" ] }, ... ]
Criar ASP.NET aplicação Web
Agora, você criará um novo aplicativo Web ASP.NET usando um modelo de projeto de exemplo. Em seguida, você explorará o código-fonte e executará o exemplo para se familiarizar com o aplicativo antes de adicionar a conectividade do Azure Cosmos DB usando o SDK do Azure para .NET.
Importante
Este tutorial extrai pacotes do NuGet de forma transparente. Você pode usar dotnet nuget list source
para verificar as fontes do pacote. Se você não tiver o NuGet como fonte de pacote, use dotnet nuget add source
para instalar o site como fonte.
Abra um terminal em um diretório vazio.
Instale o
cosmicworks.template.web
pacote de modelo de projeto do NuGet.dotnet new install cosmicworks.template.web
Crie um novo projeto de aplicativo Web usando o modelo recém-instalado
dotnet new cosmosdbnosql-webapp
.dotnet new cosmosdbnosql-webapp
Crie e execute o projeto de aplicação Web.
dotnet run
Observe a saída do comando run. A saída deve incluir uma lista de portas e URLs onde o aplicativo está sendo executado.
... 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 ...
Abra um novo navegador e navegue até o aplicativo Web em execução. Observe todas as três páginas do aplicativo em execução.
Pare o aplicativo em execução encerrando o processo em execução.
Gorjeta
Use o comando Ctrl+C para interromper um processo em execução. Em alternativa, pode fechar e reabrir o terminal.
Abra o Visual Studio Code usando a pasta de projeto atual como o espaço de trabalho.
Gorjeta
Você pode executar
code .
no terminal para abrir o Visual Studio Code e abrir automaticamente o diretório de trabalho como o espaço de trabalho atual.Navegue até o arquivo Serviços/ICosmosService.cs e abra-o. Observe as implementações do método e
RetrieveAllProductsAsync
padrãoRetrieveActiveProductsAsync
. Esses métodos criam uma lista estática de produtos para usar ao executar o projeto pela primeira vez. Um exemplo truncado de um dos métodos é fornecido aqui.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), ... }; }
Navegue até o arquivo Serviços/CosmosService.cs e abra-os. Observe a implementação atual da classe CosmosService . Essa classe implementa a interface ICosmosService, mas não substitui nenhum método. Nesse contexto, a classe usará a implementação de interface padrão até que uma substituição da implementação seja fornecida na interface.
public class CosmosService : ICosmosService { }
Finalmente, navegue e abra os arquivos Modelos/Product.cs e Modelos/Category.cs . Observe os tipos de registro definidos em cada arquivo. Esses tipos serão usados em consultas ao longo deste tutorial.
public record Product( string id, Category category, string sku, string name, string description, decimal price );
public record Category( string name );
Consultar dados usando o SDK do .NET
Em seguida, você adicionará o SDK do Azure para .NET a este projeto de exemplo e usará a biblioteca para consultar dados do contêiner API for NoSQL.
De volta ao terminal, adicione o
Microsoft.Azure.Cosmos
pacote do NuGet.dotnet add package Microsoft.Azure.Cosmos
Compilar o projeto.
dotnet build
De volta ao Visual Studio Code, navegue novamente até o arquivo Services/CosmosService.cs .
Adicione uma nova diretiva using para os
Microsoft.Azure.Cosmos
namespaces eMicrosoft.Azure.Cosmos.Linq
.using Microsoft.Azure.Cosmos; using Microsoft.Azure.Cosmos.Linq;
Dentro da classe CosmosService , adicione um novo
private readonly
membro do tipoCosmosClient
chamado_client
.private readonly CosmosClient _client;
Crie um novo construtor vazio para a
CosmosService
classe.public CosmosService() { }
Dentro do construtor, crie uma nova instância da
CosmosClient
classe passando em um parâmetro string com o valor PRIMARY CONNECTION STRING que você registrou anteriormente no laboratório. Armazene essa nova instância no_client
membro.public CosmosService() { _client = new CosmosClient( connectionString: "<primary-connection-string>" ); }
De volta à classe CosmosService , crie uma nova
private
propriedade do tipoContainer
chamadacontainer
. Defina o get accessor para retornar o banco de dados eproducts
ocosmicworks
contêiner.private Container container { get => _client.GetDatabase("cosmicworks").GetContainer("products"); }
Crie um novo método assíncrono chamado
RetrieveAllProductsAsync
que retorna umIEnumerable<Product>
arquivo .public async Task<IEnumerable<Product>> RetrieveAllProductsAsync() { }
Para as próximas etapas, adicione esse código dentro do
RetrieveAllProductsAsync
método.Use o
GetItemLinqQueryable<>
método genérico para obter um objeto do tipoIQueryable<>
que você pode usar para construir uma consulta integrada à linguagem (LINQ). Armazene esse objeto em uma variável chamadaqueryable
.var queryable = container.GetItemLinqQueryable<Product>();
Construa uma consulta LINQ usando os
Where
métodos eOrderByDescending
extension. Use oToFeedIterator
método extension para criar um iterador para obter dados do Azure Cosmos DB e armazenar o iterador em uma variável chamadafeed
. Envolva toda essa expressão em uma instrução using para descartar o iterador mais tarde.using FeedIterator<Product> feed = queryable .Where(p => p.price < 2000m) .OrderByDescending(p => p.price) .ToFeedIterator();
Crie uma nova variável chamada
results
usando o tipo genéricoList<>
.List<Product> results = new();
Crie um loop while que irá iterar até que a
HasMoreResults
feed
propriedade da variável retorne false. Esse loop garantirá que você percorra todas as páginas de resultados do lado do servidor.while (feed.HasMoreResults) { }
Dentro do loop while, chame assincronamente o
feed
ReadNextAsync
método da variável e armazene o resultado em uma variável chamadaresponse
.while (feed.HasMoreResults) { var response = await feed.ReadNextAsync(); }
Ainda dentro do loop while , use um loop foreach para percorrer cada item na resposta e adicioná-los à
results
lista.while (feed.HasMoreResults) { var response = await feed.ReadNextAsync(); foreach (Product item in response) { results.Add(item); } }
Retornar a
results
lista como a saída doRetrieveAllProductsAsync
método.return results;
Crie um novo método assíncrono chamado
RetrieveActiveProductsAsync
que retorna umIEnumerable<Product>
arquivo .public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync() { }
Para as próximas etapas, adicione esse código dentro do
RetrieveActiveProductsAsync
método.Crie uma nova cadeia de caracteres nomeada
sql
com uma consulta SQL para recuperar vários campos onde um filtro (@tagFilter
) é aplicado à matriz de tags de cada item.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) """;
Crie uma nova
QueryDefinition
variável chamadaquery
passando nasql
cadeia de caracteres como o único parâmetro de consulta. Além disso, use oWithParameter
método fluido para aplicar o valorred
ao@tagFilter
parâmetro.var query = new QueryDefinition( query: sql ) .WithParameter("@tagFilter", "red");
Use o
GetItemQueryIterator<>
método genérico e aquery
variável para criar um iterador que obtém dados do Azure Cosmos DB. Armazene o iterador em uma variável chamadafeed
. Envolva toda essa expressão em uma instrução using para descartar o iterador mais tarde.using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>( queryDefinition: query );
Use um loop while para iterar através de várias páginas de resultados e armazenar o valor em um genérico
List<>
nomeado resultados. Retorne os resultados como a saída doRetrieveActiveProductsAsync
método.List<Product> results = new(); while (feed.HasMoreResults) { FeedResponse<Product> response = await feed.ReadNextAsync(); foreach (Product item in response) { results.Add(item); } } return results;
Salve o arquivo Serviços/CosmosClient.cs .
Gorjeta
Se você não tiver certeza de que seu código está correto, você pode verificar seu código-fonte em relação ao código de exemplo no GitHub.
Validar a candidatura final
Finalmente, você executará o aplicativo com recarregamentos quentes ativados . A execução do aplicativo validará que seu código pode acessar dados da API para NoSQL.
De volta ao terminal, execute o aplicativo.
dotnet run
A saída do comando run deve incluir uma lista de portas e URLs onde o aplicativo está sendo executado. Abra um novo navegador e navegue até o aplicativo Web em execução. Observe todas as três páginas do aplicativo em execução. Cada página agora deve incluir dados dinâmicos do Azure Cosmos DB.
Clean up resources (Limpar recursos)
Quando não for mais necessário, exclua o banco de dados usado neste tutorial. Para fazer isso, navegue até a página da conta, selecione Data Explorer, selecione o cosmicworks
banco de dados e selecione Excluir.
Próximos passos
Agora que você criou seu primeiro aplicativo Web .NET usando o Azure Cosmos DB, agora pode se aprofundar no SDK para importar mais dados, executar consultas complexas e gerenciar seus recursos do Azure Cosmos DB para NoSQL.