Início Rápido: Criar um aplicativo de console .NET para gerenciar dados nos recursos da API do SQL do Azure Cosmos DBQuickstart: Build a .NET console app to manage Azure Cosmos DB SQL API resources

Introdução à biblioteca de clientes da API do SQL do Azure Cosmos DB para .NET.Get started with the Azure Cosmos DB SQL API client library for .NET. Siga as etapas neste documento para instalar o pacote .NET, criar um aplicativo e experimentar o código de exemplo para operações CRUD básicas nos dados armazenados no Azure Cosmos DB.Follow the steps in this doc to install the .NET package, build an app, and try out the example code for basic CRUD operations on the data stored in Azure Cosmos DB.

O Azure Cosmos DB é o serviço de banco de dados multimodelo distribuído globalmente da Microsoft.Azure Cosmos DB is Microsoft’s globally distributed multi-model database service. É possível usar o Azure Cosmos DB para criar e consultar rapidamente chaves/valores, documentos e bancos de dados de grafos.You can use Azure Cosmos DB to quickly create and query key/value, document, and graph databases. Use a biblioteca de clientes da API do SQL do Azure Cosmos DB para .NET para:Use the Azure Cosmos DB SQL API client library for .NET to:

  • Criar um banco de dados e um contêiner do Azure CosmosCreate an Azure Cosmos database and a container
  • Adicionar dados de exemplo ao contêinerAdd sample data to the container
  • Consultar os dadosQuery the data
  • Excluir o banco de dadosDelete the database

Documentação de referência da API | Código-fonte da biblioteca | Pacote (NuGet)API reference documentation | Library source code | Package (NuGet)

Pré-requisitosPrerequisites

ConfigurandoSetting up

Esta seção orienta a criação de uma conta do Azure Cosmos e a configuração de um projeto que usa a biblioteca de cliente da API do SQL do Azure Cosmos DB para .NET a fim de gerenciar recursos.This section walks you through creating an Azure Cosmos account and setting up a project that uses Azure Cosmos DB SQL API client library for .NET to manage resources. O código de exemplo descrito neste artigo cria o banco de dados FamilyDatabase e os membros da família (cada membro da família é um item) dentro desse banco de dados.The example code described in this article creates a FamilyDatabase database and family members (each family member is an item) within that database. Cada membro da família tem propriedades como Id, FamilyName, FirstName, LastName, Parents, Children, Address,.Each family member has properties such as Id, FamilyName, FirstName, LastName, Parents, Children, Address,. A propriedade LastName é usada como a chave de partição para o contêiner.The LastName property is used as the partition key for the container.

Criar uma conta do Azure CosmosCreate an Azure Cosmos account

O código a seguir criará uma conta do Azure Cosmos com consistência de sessão.The following code will create an Azure Cosmos account with session consistency. A conta é replicada no South Central US e no North Central US.The account is replicated in South Central US and North Central US. Selecione o botão Experimentar e cole o código para executá-lo no Azure Cloud Shell.Select the Try It button and paste the code to run it in the Azure cloud shell.


# Set variables for the new SQL API account, database, and container
resourceGroupName='myResourceGroup'
location='southcentralus'
accountName='mysqlapicosmosdb' 
databaseName='FamilyDatabase'
containerName='FamilyContainer'

# Create a resource group
az group create \
    --name $resourceGroupName \
    --location $location

# Create a SQL API Cosmos DB account with session consistency and multi-master enabled
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --kind GlobalDocumentDB \
    --locations regionName="South Central US" failoverPriority=0 --locations regionName="North Central US" failoverPriority=1 \
    --default-consistency-level "Session" \
    --enable-multiple-write-locations true

Criar um novo aplicativo .NETCreate a new .NET app

Crie um novo aplicativo .NET em seu IDE ou editor preferido.Create a new .NET application in your preferred editor or IDE. Em uma janela de console, execute o novo comando dotnet a seguir para criar um novo aplicativo com o nome todo.In a console window, run the following dotnet new command to create a new app with the name todo.

dotnet new console --langVersion 7.1 -n todo

Altere o diretório para a pasta do aplicativo recém-criado.Change your directory to the newly created app folder. É possível criar o aplicativo com:You can build the application with:

cd todo
dotnet build

A saída esperada da compilação deve ser algo como:The expected output from the build should look something like this:

  Restore completed in 100.37 ms for C:\Users\user1\Downloads\CosmosDB_Samples\todo\todo.csproj.
  todo -> C:\Users\user1\Downloads\CosmosDB_Samples\todo\bin\Debug\netcoreapp2.2\todo.dll
  todo -> C:\Users\user1\Downloads\CosmosDB_Samples\todo\bin\Debug\netcoreapp2.2\todo.Views.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:34.17

Instalar pacote Azure Cosmos DBInstall the Azure Cosmos DB package

Ainda no diretório do aplicativo, instale a biblioteca de clientes do Azure Cosmos DB para .NET Core usando o comando para adicionar pacote do dotnet.While still in the application directory, install the Azure Cosmos DB client library for .NET Core by using the dotnet add package command.

dotnet add package Microsoft.Azure.Cosmos

Copiar suas credenciais da conta do Azure Cosmos no portal do AzureCopy your Azure Cosmos account credentials from the Azure portal

O aplicativo de exemplo precisa autenticar sua conta do Azure Cosmos.The sample application needs to authenticate to your Azure Cosmos account. Para autenticar, você deve passar as credenciais da conta do Azure Cosmos para o aplicativo.To authenticate, you should pass the Azure Cosmos account credentials to the application. Obtenha suas credenciais da conta do Azure Cosmos seguindo estas etapas:Get your Azure Cosmos account credentials by following these steps:

  1. Entre no Portal do Azure.Sign in to the Azure portal.

  2. Navegue até a conta do Azure Cosmos.Navigate to your Azure Cosmos account.

  3. Abra o painel Chaves e copie o URI e a CHAVE PRIMÁRIA da sua conta.Open the Keys pane and copy the URI and PRIMARY KEY of your account. Você adicionará os valores do URI e das chaves em uma variável de ambiente da próxima etapa.You will add the URI and keys values to an environment variable in the next step.

Definir as variáveis de ambienteSet the environment variables

Depois de copiar o URI e a CHAVE PRIMÁRIA da sua conta, salve-os em uma nova variável de ambiente no computador local que executa o aplicativo.After you have copied the URI and PRIMARY KEY of your account, save them to a new environment variable on the local machine running the application. Para definir a variável de ambiente, abra uma janela de console e execute o comando a seguir.To set the environment variable, open a console window, and run the following command. Certifique-se de substituir os valores <Your_Azure_Cosmos_account_URI> e <Your_Azure_Cosmos_account_PRIMARY_KEY>.Make sure to replace <Your_Azure_Cosmos_account_URI> and <Your_Azure_Cosmos_account_PRIMARY_KEY> values.

WindowsWindows

setx EndpointUrl "<Your_Azure_Cosmos_account_URI>"
setx PrimaryKey "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

LinuxLinux

export EndpointUrl "<Your_Azure_Cosmos_account_URI>"
export PrimaryKey "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

MacOSMacOS

export EndpointUrl "<Your_Azure_Cosmos_account_URI>"
export PrimaryKey "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

Modelo de objetoObject model

Antes de começar a criar o aplicativo, vamos examinar a hierarquia de recursos no Azure Cosmos DB e o modelo de objeto usado para criar e acessar esses recursos.Before you start building the application, let's look into the hierarchy of resources in Azure Cosmos DB and the object model used to create and access these resources. O Azure Cosmos DB cria recursos na seguinte ordem:The Azure Cosmos DB creates resources in the following order:

  • Conta do Azure CosmosAzure Cosmos account
  • Bancos de dadosDatabases
  • ContêineresContainers
  • ItensItems

Para saber mais sobre a hierarquia de diferentes entidades, confira o artigo Trabalhando com bancos de dados, contêineres e itens no Azure Cosmos DB.To learn in more about the hierarchy of different entities, see the working with databases, containers, and items in Azure Cosmos DB article. Use as seguintes classes .NET para interagir com esses recursos:You will use the following .NET classes to interact with these resources:

  • CosmosClient – fornece a representação lógica do lado do cliente para o serviço do Azure Cosmos DB.CosmosClient - This class provides a client-side logical representation for the Azure Cosmos DB service. Esse objeto do cliente é usado para configurar e executar solicitações no serviço.The client object is used to configure and execute requests against the service.

  • CreateDatabaseIfNotExistsAsync – esse método cria (se não existir) ou obtém (se já existir) um recurso de banco de dados como uma operação assíncrona.CreateDatabaseIfNotExistsAsync - This method creates (if doesn't exist) or gets (if already exists) a database resource as an asynchronous operation.

  • CreateContainerIfNotExistsAsync – esse método cria (se não existir) ou obtém (se já existir) um contêiner como uma operação assíncrona.CreateContainerIfNotExistsAsync- - This method creates (if it doesn't exist) or gets (if it already exists) a container as an asynchronous operation. Você pode verificar o código de status da resposta para determinar se o contêiner foi criado recentemente (201) ou se um contêiner existente foi retornado (200).You can check the status code from the response to determine whether the container was newly created (201) or an existing container was returned (200).

  • CreateItemAsync – esse método cria um item dentro do contêiner.CreateItemAsync - This method creates an item within the container.

  • GetItemQueryIterator – esse método cria uma consulta para itens em contêiner em um banco de dados do Azure Cosmos usando uma instrução SQL com valores parametrizados.GetItemQueryIterator - This method creates a query for items under a container in an Azure Cosmos database using a SQL statement with parameterized values.

  • DeleteAsync – exclui o banco de dados especificado de sua conta Azure Cosmos.DeleteAsync - Deletes the specified database from your Azure Cosmos account. O método DeleteAsync exclui somente o banco de dados.DeleteAsync method only deletes the database. O descarte da instância Cosmosclient deve ocorrer separadamente (o que é feito no método DeleteDatabaseAndCleanupAsync).Disposing of the Cosmosclient instance should happen separately (which it does in the DeleteDatabaseAndCleanupAsync method.

Exemplos de códigoCode examples

O código de exemplo descrito neste artigo cria um banco de dados de família em Azure Cosmos DB.The sample code described in this article creates a family database in Azure Cosmos DB. O banco de dados da família contém detalhes da família, como nome, endereço, local, pais associados, filhos e animais de estimação.The family database contains family details such as name, address, location, the associated parents, children, and pets. Antes de preencher os dados de sua conta do Azure Cosmos, defina as propriedades de um item da família.Before populating the data to your Azure Cosmos account, define the properties of a family item. Crie uma nova classe chamada Family.cs no nível raiz do seu aplicativo de exemplo e adicione o seguinte código a ela:Create a new class named Family.cs at the root level of your sample application and add the following code to it:

using Newtonsoft.Json;

namespace todo
{
    public class Family
    {
        [JsonProperty(PropertyName = "id")]
        public string Id { get; set; }
        public string LastName { get; set; }
        public Parent[] Parents { get; set; }
        public Child[] Children { get; set; }
        public Address Address { get; set; }
        public bool IsRegistered { get; set; }
        public override string ToString()
        {
            return JsonConvert.SerializeObject(this);
        }
    }

    public class Parent
    {
        public string FamilyName { get; set; }
        public string FirstName { get; set; }
    }

    public class Child
    {
        public string FamilyName { get; set; }
        public string FirstName { get; set; }
        public string Gender { get; set; }
        public int Grade { get; set; }
        public Pet[] Pets { get; set; }
    }

    public class Pet
    {
        public string GivenName { get; set; }
    }

    public class Address
    {
        public string State { get; set; }
        public string County { get; set; }
        public string City { get; set; }
    }
}

Adicionar usando as diretivas e definir o objeto de clienteAdd the using directives & define the client object

No diretório do projeto, abra o arquivo Program.cs em seu editor e adicione o seguinte usando as diretivas na parte superior do seu aplicativo:From the project directory, open the Program.cs file in your editor and add the following using directives at the top of your application:


using System;
using System.Threading.Tasks;
using System.Configuration;
using System.Collections.Generic;
using System.Net;
using Microsoft.Azure.Cosmos;

Para program.cs file, adicione o código para ler as variáveis de ambiente que você definiu na etapa anterior.To the program.cs file, add code to read the environment variables that you have set in the previous step. Defina os objetos CosmosClient, Database e Container.Define the CosmosClient, Database, and the Container objects. Em seguida, adicione o código ao método principal que chama o método GetStartedDemoAsync com o qual você gerencia os recursos da conta do Azure Cosmos.Next add code to the main method that calls the GetStartedDemoAsync method where you manage Azure Cosmos account resources.

namespace todo
{
public class Program
{

    /// The Azure Cosmos DB endpoint for running this GetStarted sample.
    private string EndpointUrl = Environment.GetEnvironmentVariable("EndpointUrl");

    /// The primary key for the Azure DocumentDB account.
    private string PrimaryKey = Environment.GetEnvironmentVariable("PrimaryKey");

    // The Cosmos client instance
    private CosmosClient cosmosClient;

    // The database we will create
    private Database database;

    // The container we will create.
    private Container container;

    // The name of the database and container we will create
    private string databaseId = "FamilyDatabase";
    private string containerId = "FamilyContainer";

    public static async Task Main(string[] args)
    {
       try
       {
           Console.WriteLine("Beginning operations...\n");
           Program p = new Program();
           await p.GetStartedDemoAsync();

        }
        catch (CosmosException de)
        {
           Exception baseException = de.GetBaseException();
           Console.WriteLine("{0} error occurred: {1}", de.StatusCode, de);
        }
        catch (Exception e)
        {
            Console.WriteLine("Error: {0}", e);
        }
        finally
        {
            Console.WriteLine("End of demo, press any key to exit.");
            Console.ReadKey();
        }
    }
}
}

Criar um banco de dadosCreate a database

Defina o método CreateDatabaseAsync dentro da classe program.cs.Define the CreateDatabaseAsync method within the program.cs class. Esse método cria o FamilyDatabase, caso ainda não exista.This method creates the FamilyDatabase if it doesn't already exist.

private async Task CreateDatabaseAsync()
{
    // Create a new database
    this.database = await this.cosmosClient.CreateDatabaseIfNotExistsAsync(databaseId);
    Console.WriteLine("Created Database: {0}\n", this.database.Id);
}

Criar um contêinerCreate a container

Defina o método CreateContainerAsync dentro da classe program.cs.Define the CreateContainerAsync method within the program.cs class. Esse método cria o FamilyContainer, caso ainda não exista.This method creates the FamilyContainer if it doesn't already exist.

/// Create the container if it does not exist. 
/// Specifiy "/LastName" as the partition key since we're storing family information, to ensure good distribution of requests and storage.
private async Task CreateContainerAsync()
{
    // Create a new container
    this.container = await this.database.CreateContainerIfNotExistsAsync(containerId, "/LastName");
    Console.WriteLine("Created Container: {0}\n", this.container.Id);
}

Criar um itemCreate an item

Crie um item de família adicionando o método AddItemsToContainerAsync com o seguinte código:Create a family item by adding the AddItemsToContainerAsync method with the following code:

private async Task AddItemsToContainerAsync()
{
    // Create a family object for the Andersen family
    Family andersenFamily = new Family
    {
        Id = "Andersen.1",
        LastName = "Andersen",
        Parents = new Parent[]
        {
           new Parent { FirstName = "Thomas" },
           new Parent { FirstName = "Mary Kay" }
        },
        Children = new Child[]
        {
           new Child
            {
                FirstName = "Henriette Thaulow",
                Gender = "female",
                Grade = 5,
                Pets = new Pet[]
                {
                    new Pet { GivenName = "Fluffy" }
                }
            }
        },
        Address = new Address { State = "WA", County = "King", City = "Seattle" },
        IsRegistered = false
 };

try
{
    // Read the item to see if it exists. ReadItemAsync will throw an exception if the item does not exist and return status code 404 (Not found).
    ItemResponse<Family> andersenFamilyResponse = await this.container.ReadItemAsync<Family>(andersenFamily.Id, new PartitionKey(andersenFamily.LastName));
    Console.WriteLine("Item in database with id: {0} already exists\n", andersenFamilyResponse.Resource.Id);
}
catch(CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
{
    // Create an item in the container representing the Andersen family. Note we provide the value of the partition key for this item, which is "Andersen"
    ItemResponse<Family> andersenFamilyResponse = await this.container.CreateItemAsync<Family>(andersenFamily, new PartitionKey(andersenFamily.LastName));

    // Note that after creating the item, we can access the body of the item with the Resource property off the ItemResponse. We can also access the RequestCharge property to see the amount of RUs consumed on this request.
    Console.WriteLine("Created item in database with id: {0} Operation consumed {1} RUs.\n", andersenFamilyResponse.Resource.Id, andersenFamilyResponse.RequestCharge);
}

Consultar os itensQuery the items

Depois de inserir um item, você pode executar uma consulta para obter os detalhes da família "Martins".After inserting an item, you can run a query to get the details of "Andersen" family. O código a seguir mostra como executar a consulta usando diretamente a consulta SQL.The following code shows how to execute the query using the SQL query directly. A consulta SQL para obter os detalhes da família "Martins" é: SELECT * FROM c WHERE c.LastName = 'Andersen'.The SQL query to get the "Anderson" family details is: SELECT * FROM c WHERE c.LastName = 'Andersen'. Defina o método QueryItemsAsync dentro da classe program.cs e adicione o seguinte código:Define the QueryItemsAsync method within the program.cs class and add the following code to it:

private async Task QueryItemsAsync()
{
    var sqlQueryText = "SELECT * FROM c WHERE c.LastName = 'Andersen'";

    Console.WriteLine("Running query: {0}\n", sqlQueryText);

    QueryDefinition queryDefinition = new QueryDefinition(sqlQueryText);
    FeedIterator<Family> queryResultSetIterator = this.container.GetItemQueryIterator<Family>(queryDefinition);

    List<Family> families = new List<Family>();

    while (queryResultSetIterator.HasMoreResults)
    {
        FeedResponse<Family> currentResultSet = await queryResultSetIterator.ReadNextAsync();
        foreach (Family family in currentResultSet)
        {
            families.Add(family);
            Console.WriteLine("\tRead {0}\n", family);
        }
    }
}

Excluir o banco de dadosDelete the database

Por fim, você pode excluir o banco de dados adicionando o método DeleteDatabaseAndCleanupAsync com o seguinte código:Finally you can delete the database adding the DeleteDatabaseAndCleanupAsync method with the following code:

private async Task DeleteDatabaseAndCleanupAsync()
{
   DatabaseResponse databaseResourceResponse = await this.database.DeleteAsync();
   // Also valid: await this.cosmosClient.Databases["FamilyDatabase"].DeleteAsync();

   Console.WriteLine("Deleted Database: {0}\n", this.databaseId);

   //Dispose of CosmosClient
    this.cosmosClient.Dispose();
}

Executar as operações CRUDExecute the CRUD operations

Depois de definir todos os métodos necessários, execute-os com o método GetStartedDemoAsync.After you have defined all the required methods, execute them with in the GetStartedDemoAsync method. O método DeleteDatabaseAndCleanupAsync foi retirado do comentário deste código porque você não verá nenhum recurso se esse método for executado.The DeleteDatabaseAndCleanupAsync method commented out in this code because you will not see any resources if that method is executed. Você pode remover os comentários após validar que seus recursos do Azure Cosmos DB foram criados no portal do Azure.You can uncomment it after validating that your Azure Cosmos DB resources were created in the Azure portal.

public async Task GetStartedDemoAsync()
{
    // Create a new instance of the Cosmos Client
    this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
    await this.CreateDatabaseAsync();
    await this.CreateContainerAsync();
    await this.AddItemsToContainerAsync();
    await this.QueryItemsAsync();
    await this.ReplaceFamilyItemAsync();
    await this.DeleteFamilyItemAsync();
    //await this.DeleteDatabaseAndCleanupAsync();
}

Depois de adicionar todos os métodos necessários, salve o arquivo Program.cs.After you add all the required methods, save the Program.cs file.

Executar o códigoRun the code

Em seguida, compile e execute o aplicativo para criar os recursos do Azure Cosmos DB.Next build and run the application to create the Azure Cosmos DB resources. Abra uma nova janela de prompt de comando, não utilize a mesma instância usada para definir as variáveis de ambiente,Make sure to open a new command prompt window, don't use the same instance that you have used to set the environment variables. porque as variáveis de ambiente não estão definidas na janela aberta no momento.Because the environment variables are not set in the current open window. Será necessário abrir um novo prompt de comando para ver as atualizações.You will need to open a new command prompt to see the updates.

dotnet build
dotnet run

A saída a seguir é gerada quando você executa o aplicativo.The following output is generated when you run the application. Você também pode entrar no portal do Azure e validar que os recursos foram criados:You can also sign into the Azure portal and validate that the resources are created:

Created Database: FamilyDatabase

Created Container: FamilyContainer

Created item in database with id: Andersen.1 Operation consumed 11.62 RUs.

Running query: SELECT * FROM c WHERE c.LastName = 'Andersen'

        Read {"id":"Andersen.1","LastName":"Andersen","Parents":[{"FamilyName":null,"FirstName":"Thomas"},{"FamilyName":null,"FirstName":"Mary Kay"}],"Children":[{"FamilyName":null,"FirstName":"Henriette Thaulow","Gender":"female","Grade":5,"Pets":[{"GivenName":"Fluffy"}]}],"Address":{"State":"WA","County":"King","City":"Seattle"},"IsRegistered":false}

End of demo, press any key to exit.

Você pode validar que os dados foram criados entrando no portal do Azure e olhando os itens necessários em sua conta do Azure Cosmos.You can validate that the data is created by signing into the Azure portal and see the required items in your Azure Cosmos account.

Limpar recursosClean up resources

Quando não for mais necessária, você poderá usar o CLI do Azure ou o Azure PowerShell para remover a conta do Azure Cosmos e o grupo de recursos correspondente.When no longer needed, you can use the Azure CLI or Azure PowerShell to remove the Azure Cosmos account and the corresponding resource group. O comando a seguir mostra como excluir o grupo de recursos usando o CLI do Azure:The following command shows how to delete the resource group by using the Azure CLI:

az group delete -g "myResourceGroup" -l "southcentralus"

Próximas etapasNext steps

Neste início rápido, você aprendeu a criar uma conta do Azure Cosmos, como criar um banco de dados e um contêiner usando o .NET Core.In this quickstart, you learned how to create an Azure Cosmos account, create a database and a container using a .NET Core app. Agora você pode importar dados adicionais para sua conta do Azure Cosmos com as instruções no artigo a seguir.You can now import additional data to your Azure Cosmos account with the instructions int the following article.