Tutorial: Desenvolver um aplicativo de console .NET com o Azure Cosmos DB para NoSQL

Artigo
12/27/2023

APLICA-SE A: NoSQL

.NET

O SDK do Azure para .NET permite adicionar dados a uma API para contêiner NoSQL, operações individuais assíncronas ou um lote transacional. Este tutorial percorrerá o processo de criação de um novo aplicativo de console .NET que adiciona vários itens a um contêiner.

Neste tutorial, irá aprender a:

Criar um banco de dados usando a API para NoSQL
Criar um aplicativo de console .NET e adicionar o SDK do Azure para .NET
Adicionar itens individuais a uma API para contêiner NoSQL
Recuperar itens eficientes de uma API para contêiner NoSQL
Criar uma transação com alterações em lote para o contêiner API for NoSQL

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, crie um banco de dados vazio na API existente para a conta NoSQL. Você criará um contêiner usando o SDK do Azure para .NET mais tarde.

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 dos campos URI e CHAVE PRIMÁRIA. Esses valores serão usados ao longo do tutorial.
No menu de recursos, selecione Data Explorer.
Na página Data Explorer, selecione a opção Novo Banco de Dados na barra de comandos.
Na caixa de diálogo Novo banco de dados, crie um novo contêiner com as seguintes configurações:

valor

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 400
Selecione OK para criar o banco de dados.

	valor
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	`400`

Criar aplicativo de console .NET

Agora, você criará um novo aplicativo de console .NET e importará o SDK do Azure para .NET usando a Microsoft.Azure.Cosmos biblioteca do NuGet.

Abra um terminal em um diretório vazio.
Criar um novo aplicativo de console usando o console modelo interno
```
dotnet new console --langVersion preview
```
Adicione a versão 3.31.1-preview do Microsoft.Azure.Cosmos pacote do NuGet.
```
dotnet add package Microsoft.Azure.Cosmos --version 3.31.1-preview
```
Além disso, adicione a versão de pré-lançamento do System.CommandLine pacote do NuGet.
```
dotnet add package System.CommandLine --prerelease
```
Além disso, adicione o Humanizer pacote do NuGet.
```
dotnet add package Humanizer
```
Crie o projeto de aplicativo de console.
```
dotnet build
```
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 .cs programa e abra-o. Exclua todo o código existente no arquivo.

Adicione esse código ao arquivo para usar a biblioteca System.CommandLine para analisar a linha de comando para duas cadeias de caracteres passadas pelas --first opções e --last .

using System.CommandLine;

var command = new RootCommand();

var nameOption = new Option<string>("--name") { IsRequired = true };
var emailOption = new Option<string>("--email");
var stateOption = new Option<string>("--state") { IsRequired = true };
var countryOption = new Option<string>("--country") { IsRequired = true };

command.AddOption(nameOption);
command.AddOption(emailOption);
command.AddOption(stateOption);
command.AddOption(countryOption);

command.SetHandler(
    handle: CosmosHandler.ManageCustomerAsync, 
    nameOption, 
    emailOption,
    stateOption,
    countryOption
);

await command.InvokeAsync(args);

Nota

Para este tutorial, não é totalmente importante que você entenda como o analisador de linha de comando funciona. O analisador tem quatro opções que podem ser especificadas quando o aplicativo está em execução. Três das opções são necessárias, pois serão usadas para construir os campos ID e chave de partição.

Neste ponto, o projeto não será compilado, pois você ainda não definiu o método estático CosmosHandler.ManageCustomerAsync .
Salve o arquivo .cs programa.

Adicionar itens a um contêiner usando o SDK

Em seguida, você usará operações individuais para adicionar itens ao contêiner API for NoSQL. Nesta seção, você definirá o CosmosHandler.ManageCustomerAsync método.

Crie um novo arquivo CosmosHandler.cs .
No arquivo CosmosHandler.cs, adicione uma nova diretiva using para os Humanizer namespaces e Microsoft.Azure.Cosmos .
```
using Humanizer;
using Microsoft.Azure.Cosmos;
```
Crie uma nova classe estática chamada CosmosHandler.
```
public static class CosmosHandler
{ }
```

Apenas para validar este aplicativo vai funcionar, crie uma breve implementação do método estático ManageCustomerAsync para imprimir a entrada de linha de comando.

public static async Task ManageCustomerAsync(string name, string email, string state, string country)
{
    await Console.Out.WriteLineAsync($"Hello {name} of {state}, {country}!");
}

Salve o arquivo CosmosHandler.cs .

De volta ao terminal, execute o aplicativo.

dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

A saída do comando deve ser uma saudação divertida.
```
Hello Mica Pereira of Washington, United States!
```
Retorne ao arquivo CosmosHandler.cs .
Dentro da classe estática CosmosHandler , adicione um novo private static readonly membro do tipo CosmosClient chamado _client.
```
private static readonly CosmosClient _client;
```
Crie um novo construtor estático para a CosmosHandler classe.
```
static CosmosHandler()
{ }
```
Dentro do construtor, crie uma nova instância da classe passando em dois parâmetros de cadeia de CosmosClient caracteres com os valores URI e PRIMARY KEY que você registrou anteriormente no laboratório. Armazene essa nova instância no _client membro.
```
static CosmosHandler()
{
    _client = new CosmosClient(
        accountEndpoint: "<uri>", 
        authKeyOrResourceToken: "<primary-key>"
    );
}
```
De volta à classe estática CosmosHandler , crie um novo método assíncrono chamado GetContainerAsync que retorna um Containerarquivo .
```
private static async Task<Container> GetContainer()
{ }
```
Para as próximas etapas, adicione esse código dentro do GetContainerAsync método.
1. Obtenha o banco de dados e armazene-o cosmicworks em uma variável chamada database.
```
Database database = _client.GetDatabase("cosmicworks");
```
2. Crie um novo genérico List<> de valores dentro de uma lista de caminhos de chave de string partição hierárquica e armazene-o em uma variável chamada keyPaths.
```
List<string> keyPaths = new()
{
    "/address/country",
    "/address/state"
};
```
3. Crie uma nova ContainerProperties variável com o nome do contêiner (customers) e a lista de caminhos de chave de partição.
```
ContainerProperties properties = new(
    id: "customers",
    partitionKeyPaths: keyPaths
);
```
4. Use o CreateContainerIfNotExistsAsync método para fornecer as propriedades do contêiner e recuperá-lo. Esse método irá, de acordo com o nome, criar assincronamente o contêiner se ele ainda não existir no banco de dados. Retornar o resultado como a saída do GetContainerAsync método.
```
return await database.CreateContainerIfNotExistsAsync(
    containerProperties: properties
);
```
Exclua todo o código dentro do ManageCustomerAsync método.
Para as próximas etapas, adicione esse código dentro do ManageCustomerAsync método.
1. Chame o método de forma assíncrona e armazene GetContainerAsync o resultado em uma variável chamada container.
```
Container container = await GetContainerAsync();
```
2. Crie uma nova variável chamada id que usa o método do Humanizer para transformar o Kebaberize parâmetro do namemétodo.
```
string id = name.Kebaberize();
```
  Nota
  
  O Kebaberize método substituirá todos os espaços por hífenes e converterá o texto para minúsculas.
3. Crie um novo item digitado anônimo usando os nameparâmetros , statee método e country a id variável. Armazene o item como uma variável chamada customer.
```
var customer = new {
    id = id,
    name = name,
    address = new {
        state = state,
        country = country
    }
};
```
4. Use o método assíncrono CreateItemAsync do contêiner para criar um novo item no contêiner e atribuir os metadados de resposta HTTP a uma variável chamada response.
```
var response = await container.CreateItemAsync(customer);
```
5. Escreva os response valores das StatusCode variáveis e RequestCharge propriedades no console. Escreva também o valor da id variável.
```
Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");
```
Salve o arquivo CosmosHandler.cs .

De volta ao terminal, execute o aplicativo novamente.

dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

A saída do comando deve incluir um status e uma taxa de solicitação para a operação.
```
[Created]       mica-pereira    7.05 RUs
```
Nota

A taxa do seu pedido pode variar.

Execute o aplicativo mais uma vez.

dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

Desta vez, o programa deve falhar. Se percorrer a mensagem de erro, verá que a falha ocorreu devido a um conflito no identificador exclusivo dos itens.

Unhandled exception: Microsoft.Azure.Cosmos.CosmosException : Response status code does not indicate success: Conflict (409);Reason: (
    Errors : [
      "Resource with specified id or name already exists."
    ]
);

Recuperar um item usando o SDK

Agora que você criou seu primeiro item no contêiner, pode usar o mesmo SDK para recuperar o item. Aqui, você consultará e apontará a leitura do item para comparar a diferença no consumo da unidade de solicitação (RU).

Retorne ou abra o arquivo CosmosHandler.cs .

Exclua todas as linhas de código do método, ManageCustomerAsync exceto as duas primeiras linhas.

public static async Task ManageCustomerAsync(string name, string email, string state, string country)
{
    Container container = await GetContainerAsync();

    string id = name.Kebaberize();
}

Para as próximas etapas, adicione esse código dentro do ManageCustomerAsync método.
1. Use o método assíncrono CreateItemAsync do contêiner para criar um novo item no contêiner e atribuir os metadados de resposta HTTP a uma variável chamada response.
```
var response = await container.CreateItemAsync(customer);
```
2. Crie uma nova cadeia de caracteres nomeada sql com uma consulta SQL para recuperar itens em que um filtro (@id) corresponde.
```
string sql = """
SELECT
    *
FROM customers c
WHERE c.id = @id
""";
```
3. Crie uma nova QueryDefinition variável chamada query passando na sql cadeia de caracteres como o único parâmetro de consulta. Além disso, use o WithParameter método fluido para aplicar o valor da variável id ao @id parâmetro.
```
var query = new QueryDefinition(
    query: sql
)
    .WithParameter("@id", id);
```
4. Use o GetItemQueryIterator<> método genérico e a query variável para criar um iterador que obtém dados do Azure Cosmos DB. Armazene o iterador em uma variável chamada feed. Envolva toda essa expressão em uma instrução using para descartar o iterador mais tarde.
```
using var feed = container.GetItemQueryIterator<dynamic>(
    queryDefinition: query
);
```
5. Chame assincronamente o feed método da variável e armazene ReadNextAsync o resultado em uma variável chamada response.
```
var response = await feed.ReadNextAsync();
```
6. Escreva os response valores das StatusCode variáveis e RequestCharge propriedades no console. Escreva também o valor da id variável.
```
Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");
```
Salve o arquivo CosmosHandler.cs .
De volta ao terminal, execute o aplicativo para ler o único item usando uma consulta SQL.
```
dotnet run -- --name 'Mica Pereira'
```
A saída do comando deve indicar que a consulta exigiu várias RUs.
```
[OK]    mica-pereira    2.82 RUs
```

De volta ao arquivo CosmosHandler.cs , exclua todas as linhas de código do método novamente, exceto as ManageCustomerAsync duas primeiras linhas.

public static async Task ManageCustomerAsync(string name, string email, string state, string country)
{
    Container container = await GetContainerAsync();

    string id = name.Kebaberize();
}

Para as próximas etapas, adicione esse código dentro do ManageCustomerAsync método.
1. Crie uma nova instância de adicionando os state parâmetros e country como um valor de chave de partição de PartitionKeyBuilder várias partes.
```
var partitionKey = new PartitionKeyBuilder()
    .Add(country)
    .Add(state)
    .Build();
```
2. Use o método do contêiner para apontar a leitura do item do ReadItemAsync<> contêiner usando as id variáveis e partitionKey . Salve o resultado em uma variável chamada response.
```
var response = await container.ReadItemAsync<dynamic>(
    id: id, 
    partitionKey: partitionKey
);
```
3. Escreva os response valores das StatusCode variáveis e RequestCharge propriedades no console. Escreva também o valor da id variável.
```
Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RU");
```
Salve o arquivo CosmosHandler.cs novamente.

De volta ao terminal, execute o aplicativo mais uma vez para ler o item único.

dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

A saída do comando deve indicar que a consulta exigia uma única RU.
```
[OK]    mica-pereira    1 RUs
```

Criar uma transação usando o SDK

Finalmente, você pegará o item que criou, lerá esse item e criará um item relacionado diferente como parte de uma única transação usando o SDK do Azure para .NET.

Retorne ou abra o arquivo CosmosHandler.cs .

Exclua essas linhas de código do ManageCustomerAsync método.

var response = await container.ReadItemAsync<dynamic>(
    id: id, 
    partitionKey: partitionKey
);

Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");

Para as próximas etapas, adicione esse novo código dentro do ManageCustomerAsync método.
1. Crie um novo item digitado anônimo usando os nameparâmetros , statee método e country a id variável. Armazene o item como uma variável chamada customerCart. Este item representará um carrinho de compras em tempo real para o cliente que está vazio no momento.
```
var customerCart = new {
    id = $"{Guid.NewGuid()}",
    customerId = id,
    items = new string[] {},
    address = new {
        state = state,
        country = country
    }
};
```
2. Crie outro novo item digitado anônimo usando os nameparâmetros , statee método e country a id variável. Armazene o item como uma variável chamada customerCart. Este item representará informações de envio e contato para o cliente.
```
var customerContactInfo = new {
    id = $"{id}-contact",
    customerId = id,
    email = email,
    location = $"{state}, {country}",
    address = new {
        state = state,
        country = country
    }
};
```
3. Crie um novo lote usando o método do CreateTransactionalBatch contêiner passando a partitionKey variável. Armazene o lote em uma variável chamada batch. Use métodos fluentes para executar as seguintes ações:
  
  Método Parâmetro
  
  ReadItem id variável string
  
  CreateItem customerCart variável de tipo anónimo
  
  CreateItem customerContactInfo variável de tipo anónimo
```
var batch = container.CreateTransactionalBatch(partitionKey)
    .ReadItem(id)
    .CreateItem(customerCart)
    .CreateItem(customerContactInfo);
```
4. Use o método do ExecuteAsync lote para iniciar a transação. Salve o resultado em uma variável chamada response.
```
using var response = await batch.ExecuteAsync();
```
5. Escreva os response valores das StatusCode variáveis e RequestCharge propriedades no console. Escreva também o valor da id variável.
```
Console.WriteLine($"[{response.StatusCode}]\t{response.RequestCharge} RUs");
```
Salve o arquivo CosmosHandler.cs novamente.

Método	Parâmetro
`ReadItem`	`id` variável string
`CreateItem`	`customerCart` variável de tipo anónimo
`CreateItem`	`customerContactInfo` variável de tipo anónimo

De volta ao terminal, execute o aplicativo mais uma vez para ler o item único.

dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

A saída do comando deve mostrar as unidades de solicitação usadas para toda a transação.
```
[OK]    16.05 RUs
```
Nota

A taxa do seu pedido pode variar.

Validar os dados finais no Data Explorer

Para concluir as coisas, você usará o Data Explorer no portal do Azure para exibir os dados e o contêiner criados neste tutorial.

Navegue até sua conta existente da API para NoSQL no portal do Azure.
No menu de recursos, selecione Data Explorer.
Na página Data Explorer, expanda o banco de dados e selecione o customerscosmicworks contêiner.
Na barra de comandos, selecione Nova consulta SQL.
No editor de consultas, observe essa cadeia de caracteres de consulta SQL.
```
SELECT * FROM c
```
Selecione Executar consulta para executar a consulta e observar os resultados.

Os resultados devem incluir uma matriz JSON com três itens criados neste tutorial. Observe que todos os itens têm o mesmo valor de chave de partição hierárquica, mas campos de ID exclusivos. A saída de exemplo incluída é truncada para brevidade.

[
  {
    "id": "mica-pereira",
    "name": "Mica Pereira",
    "address": {
      "state": "Washington",
      "country": "United States"
    },
    ...
  },
  {
    "id": "33d03318-6302-4559-b5c0-f3cc643b2f38",
    "customerId": "mica-pereira",
    "items": [],
    "address": {
      "state": "Washington",
      "country": "United States"
    },
    ...
  },
  {
    "id": "mica-pereira-contact",
    "customerId": "mica-pereira",
    "email": null,
    "location": "Washington, United States",
    "address": {
      "state": "Washington",
      "country": "United States"
    },
    ...
  }
]

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 de console .NET usando o Azure Cosmos DB, tente o próximo tutorial onde você atualizará um aplicativo Web existente para usar dados do Azure Cosmos DB.

Tutorial: Desenvolver um aplicativo Web ASP.NET com o Azure Cosmos DB para NoSQL

Partilhar via