Compartilhar via

Desenvolver localmente usando o emulador do Azure Cosmos DB

  • Artigo

Um caso de uso comum para o emulador é servir como um banco de dados de desenvolvimento enquanto você está criando seus aplicativos. Usar o emulador para desenvolvimento pode ajudá-lo a aprender características de criação e modelagem de dados para um banco de dados como o Azure Cosmos DB sem incorrer em custos de serviço. Além disso, usar o emulador como parte de um fluxo de trabalho de automação pode garantir que você possa executar o mesmo conjunto de testes de integração. Você pode garantir que os mesmos testes sejam executados localmente em seu computador de desenvolvimento e remotamente em um trabalho de integração contínua.

Pré-requisitos

Instalar o emulador

Há várias variações do emulador e cada variação tem um processo de instalação relativamente sem atrito.

Para começar, obtenha a variante do Linux da imagem de contêiner do MCR (Registro de Contêiner da Microsoft).

  1. Efetuar pull da imagem de contêiner mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator do Linux do registro de contêiner para o host local do Docker.

    docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. Verifique se a imagem do emulador está disponível no host Docker local.

    docker images

Para começar, obtenha a variante do Linux da imagem de contêiner do MCR (Registro de Contêiner da Microsoft).

  1. Efetuar pull da imagem de contêiner mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator do Linux usando a marca mongodb do registro de contêiner para o host local do Docker.

    docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

  2. Verifique se a imagem do emulador está disponível no host Docker local.

    docker images

A variante de contêiner do Docker (Linux ou Windows) do emulador não dá suporte à API para Apache Cassandra, À API para Apache Gremlin ou à API para Tabela.

Iniciar o emulador

Depois de baixado, inicie o emulador com a API especificada habilitada.

A variante de contêiner do Docker do emulador não dá suporte à API para Apache Cassandra.

A variante de contêiner do Docker do emulador não dá suporte à API para Apache Gremlin.

A variante de contêiner do Docker do emulador não dá suporte à API para Tabela.

  1. Execute um novo contêiner usando a imagem de contêiner e a seguinte configuração:

    Descrição
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Opcional) Especifique o número de partições a serem usadas.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Opcional) Habilite a persistência de dados entre execuções do emulador.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Opcional) Substitua o endereço IP padrão do emulador.

    Para sistemas Linux, use:

    docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --name linux-emulator \
    --detach \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

    Para sistemas Windows, use:

    $parameters = @(
    "--publish", "8081:8081"
    "--publish", "10250-10255:10250-10255"
    "--name", "windows-emulator"
    "--detach"
)
docker run @parameters mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. Navegue até https://localhost:8081/_explorer/index.html para acessar o data explorer.

  1. Execute um novo contêiner usando a imagem de contêiner e a seguinte configuração:

    Descrição
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT Especifique a versão do ponto de extremidade do MongoDB a ser usada. Os pontos de extremidade com suporte incluem: 3.2, 3.6ou 4.0.
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Opcional) Especifique o número de partições a serem usadas.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Opcional) Habilite a persistência de dados entre execuções do emulador.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Opcional) Substitua o endereço IP padrão do emulador.

    Para sistemas Linux, use:

    docker run \
    --publish 8081:8081 \
    --publish 10250:10250 \
    --env AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT=4.0 \
    --name linux-emulator \
    --detach \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

    Para sistemas Windows, use:

    $parameters = @(
    "--publish", "8081:8081"
    "--publish", "10250:10250"
    "--env", "AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT=4.0"
    "--name", "windows-emulator"
    "--detach"
)
docker run @parameters mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

  2. Navegue até https://localhost:8081/_explorer/index.html para acessar o data explorer.

Importar o certificado TLS/SSL do emulador

Importe o certificado TLS/SSL do emulador para usar o emulador com seu SDK de desenvolvedor preferencial sem desabilitar o TLS/SSL no cliente.

A variante de contêiner do Docker (Linux ou Windows) do emulador não dá suporte à API para Apache Cassandra, À API para Apache Gremlin ou à API para Tabela.

O certificado do emulador está disponível no caminho _explorer/emulator.pem no contêiner em execução. Use curl para baixar o certificado do contêiner em execução no computador local.

  1. Obtenha o certificado do contêiner em execução.

    Para sistemas Linux, use:

    curl --insecure https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt

    Para sistemas Windows, use:

    $parameters = @{
    Uri = 'https://localhost:8081/_explorer/emulator.pem'
    Method = 'GET'
    OutFile = 'emulatorcert.crt'
    SkipCertificateCheck = $True
}
Invoke-WebRequest @parameters

  2. Gere novamente o pacote de certificados usando o comando apropriado para seu sistema operacional.

    Para sistemas Linux baseados em Debian (por exemplo, Ubuntu), use:

    sudo update-ca-certificates

    Para sistemas Linux baseados em Red Hat (por exemplo, CentOS, Fedora), use:

    sudo update-ca-trust

    Para sistemas Windows, use:

    certutil -f -addstore "Root" ~/emulatorcert.crt

    Para obter instruções mais detalhadas, consulte a documentação específica do seu sistema operacional.

O certificado do emulador está disponível no caminho /_explorer/emulator.pem no contêiner em execução.

  1. Baixe o certificado do contêiner em execução para sua máquina local.

    Para sistemas Linux, use:

    curl --insecure https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt

    Para sistemas Windows, use:

    $parameters = @{
    Uri = 'https://localhost:8081/_explorer/emulator.pem'
    Method = 'GET'
    OutFile = 'emulatorcert.crt'
    SkipCertificateCheck = $True
}
Invoke-WebRequest @parameters

    Observação

    Talvez seja necessário alterar o host (ou endereço IP) e o número da porta se tiver modificado esses valores anteriormente.

  2. Instale o certificado de acordo com o processo normalmente usado para seu sistema operacional. Por exemplo, no Linux, você copiaria o certificado para o caminho /usr/local/share/ca-certificates/.

    Para sistemas Linux, use:

    cp ~/emulatorcert.crt /usr/local/share/ca-certificates/

    Para sistemas Windows, use:

    $parameters = @{
    FilePath = 'emulatorcert.crt'
    CertStoreLocation = 'Cert:\CurrentUser\Root'
}
Import-Certificate @parameters

  3. Para sistemas Linux, gere novamente o pacote de certificados usando o comando apropriado para sua distribuição Linux.

    Para sistemas Linux baseados em Debian (por exemplo, Ubuntu), use:

    sudo update-ca-certificates

    Para sistemas Linux baseados em Red Hat (por exemplo, CentOS, Fedora), use:

    sudo update-ca-trust

    Para obter instruções mais detalhadas, consulte a documentação específica do seu sistema operacional.

Conectar-se ao emulador do SDK

Cada SDK inclui uma classe de cliente normalmente usada para conectar o SDK à sua conta do Azure Cosmos DB. Usando as credenciais do emulador, você pode conectar o SDK à instância do emulador.

Use o SDK do .NET da API do Azure Cosmos DB para NoSQL para se conectar ao emulador de um aplicativo .NET.

  1. Comece em uma pasta vazia.

  2. Criar um aplicativo de console .NET

    dotnet new console

  3. Adicione o pacote Microsoft.Azure.Cosmos do NuGet.

    dotnet add package Microsoft.Azure.Cosmos

  4. Abra o arquivo Program.cs.

  5. Exclua qualquer conteúdo existente dentro do arquivo.

  6. Adicionar um bloco using para o namespace Microsoft.Azure.Cosmos.

    using Microsoft.Azure.Cosmos;

  7. Crie uma nova instância do CosmosClient usando as credenciais do emulador.

    using CosmosClient client = new(
    accountEndpoint: "https://localhost:8081/",
    authKeyOrResourceToken: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
);

  8. Crie um novo banco de dados e um contêiner usando CreateDatabaseIfNotExistsAsync e CreateContainerIfNotExistsAsync.

    Database database = await client.CreateDatabaseIfNotExistsAsync(
    id: "cosmicworks",
    throughput: 400
);

Container container = await database.CreateContainerIfNotExistsAsync(
    id: "products",
    partitionKeyPath: "/id"
);

  9. Crie um novo item no contêiner usando UpsertItemAsync.

    var item = new
{
    id = "68719518371",
    name = "Kiama classic surfboard"
};

await container.UpsertItemAsync(item);

  10. Execute o aplicativo .NET.

    dotnet run

    Aviso

    Se você receber um erro SSL, talvez seja necessário desabilitar o TLS/SSL para seu aplicativo. Isso geralmente ocorre se você estiver desenvolvendo em seu computador local, usando o emulador do Azure Cosmos DB em um contêiner e não tiver importado o certificado SSL do contêiner. Para resolve isso, configure as opções do cliente para desabilitar a validação de TLS/SSL antes de criar o cliente:

    CosmosClientOptions options = new ()
{
    HttpClientFactory = () => new HttpClient(new HttpClientHandler()
    {
        ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
    }),
    ConnectionMode = ConnectionMode.Gateway,
};

using CosmosClient client = new(
  ...,
  ...,
  clientOptions: options
);

Dica

Consulte o guia do desenvolvedor do .NET para obter mais operações que você pode executar usando o SDK do .NET.

Use o driver .NET do MongoDB para se conectar ao emulador de um aplicativo .NET.

  1. Comece em uma pasta vazia.

  2. Criar um aplicativo de console .NET

    dotnet new console

  3. Adicione o pacote MongoDB.Driver do NuGet.

    dotnet add package MongoDB.Driver

  4. Abra o arquivo Program.cs.

  5. Exclua qualquer conteúdo existente dentro do arquivo.

  6. Adicionar um bloco using para o namespace MongoDB.Driver.

    using MongoDB.Driver;

  7. Crie uma nova instância do MongoClient usando as credenciais do emulador.

    var client = new MongoClient(
    "mongodb://localhost:C2y6yDjf5%2FR%2Bob0N8A7Cgv30VRDJIWEHLM%2B4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw%2FJw%3D%3D@localhost:10255/admin?ssl=true&retrywrites=false"
);

  8. Obtenha o banco de dados e o contêiner usando GetDatabase e GetCollection<>.

    var database = client.GetDatabase("cosmicworks");

var collection = database.GetCollection<dynamic>("products");

  9. Crie um novo item no XXX usando InsertOneAsync.

    var item = new
{
    name = "Kiama classic surfboard"
};

await collection.InsertOneAsync(item);

  10. Execute o aplicativo .NET.

    dotnet run

Use o driver .NET do Apache Cassandra para se conectar ao emulador de um aplicativo .NET.

  1. Comece em uma pasta vazia.

  2. Criar um aplicativo de console .NET

    dotnet new console

  3. Adicione o pacote CassandraCSharpDriver do NuGet.

    dotnet add package CassandraCSharpDriver

  4. Abra o arquivo Program.cs.

  5. Exclua qualquer conteúdo existente dentro do arquivo.

  6. Adicionar um bloco using para o namespace Cassandra.

    using Cassandra;

  7. Crie uma nova instância do Cluster usando as credenciais do emulador. Crie uma nova sessão usando Connect.

    var options = new SSLOptions(
    sslProtocol: System.Security.Authentication.SslProtocols.Tls12,
    checkCertificateRevocation: true,
    remoteCertValidationCallback: (_, _, _, policyErrors) => policyErrors == System.Net.Security.SslPolicyErrors.None);

using var cluster = Cluster.Builder()
    .WithCredentials(
        username: "localhost",
        password: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
    )
    .WithPort(
        port: 10350
    )
    .AddContactPoint(
        address: "localhost"
    )
    .WithSSL(
        sslOptions: options
    )
    .Build();

using var session = cluster.Connect();

  8. Crie um novo banco de dados e um contêiner usando PrepareAsync e ExecuteAsync.

    var createKeyspace = await session.PrepareAsync("CREATE KEYSPACE IF NOT EXISTS cosmicworks WITH replication = {'class':'basicclass', 'replication_factor': 1};");
await session.ExecuteAsync(createKeyspace.Bind());

var createTable = await session.PrepareAsync("CREATE TABLE IF NOT EXISTS cosmicworks.products (id text PRIMARY KEY, name text)");
await session.ExecuteAsync(createTable.Bind());

  9. Crie um novo item na tabela usando ExecuteAsync. Use Bind para atribuir propriedades ao item.

    var item = new
{
    id = "68719518371",
    name = "Kiama classic surfboard"
};

var createItem = await session.PrepareAsync("INSERT INTO cosmicworks.products (id, name) VALUES (?, ?)");

var createItemStatement = createItem.Bind(item.id, item.name);

await session.ExecuteAsync(createItemStatement);

  10. Execute o aplicativo .NET.

    dotnet run

Importante

Antes de começar, a API para Apache Gremlin exige que você crie seus recursos no emulador. Crie um banco de dados chamado db1 e um contêiner chamado coll1. As configurações de taxa de transferência são irrelevantes para este guia e podem ser definidas da forma mais baixa que desejar.

Use o driver .NET do Apache Gremlin para se conectar ao emulador de um aplicativo .NET.

  1. Comece em uma pasta vazia.

  2. Criar um aplicativo de console .NET

    dotnet new console

  3. Adicione o pacote Gremlin.Net do NuGet.

    dotnet add package Gremlin.Net

  4. Abra o arquivo Program.cs.

  5. Exclua qualquer conteúdo existente dentro do arquivo.

  6. Adicionar um bloco using para o namespace Gremlin.Net.Driver.

    using Gremlin.Net.Driver;

  7. Crie uma nova instância do GremlinServer e GremlinClient usando as credenciais do emulador.

    var server = new GremlinServer(
    hostname: "localhost",
    port: 8901,
    username: "/dbs/db1/colls/coll1",
    password: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
);

using var client = new GremlinClient(
    gremlinServer: server,
    messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
);

  8. Limpe o grafo usando SubmitAsync.

    await client.SubmitAsync(
    requestScript: "g.V().drop()"
);

  9. Use SubmitAsync novamente para adicionar um novo item ao grafo com os parâmetros especificados.

    await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', prop_id).property('name', prop_name)",
    bindings: new Dictionary<string, object>
    {
        { "prop_id", "68719518371" },
        { "prop_name", "Kiama classic surfboard" }
    }
);

  10. Execute o aplicativo .NET.

    dotnet run

Use o SDK de Tabelas do Azure para .NET para se conectar ao emulador de um aplicativo .NET.

  1. Comece em uma pasta vazia.

  2. Criar um aplicativo de console .NET

    dotnet new console

  3. Adicione o pacote Azure.Data.Tables do NuGet.

    dotnet add package Azure.Data.Tables

  4. Abra o arquivo Program.cs.

  5. Exclua qualquer conteúdo existente dentro do arquivo.

  6. Adicionar um bloco using para o namespace Azure.Data.Tables.

    using Azure.Data.Tables;

  7. Crie uma nova instância do TableServiceClient usando as credenciais do emulador.

    var serviceClient = new TableServiceClient(
    connectionString: "DefaultEndpointsProtocol=http;AccountName=localhost;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;TableEndpoint=http://localhost:8902/;"
);

  8. Use GetTableClient para criar uma nova instância de TableClient com o nome da tabela. Em seguida, verifique se a tabela existe usando CreateIfNotExistsAsync.

    var client = serviceClient.GetTableClient(
    tableName: "cosmicworksproducts"
);

await client.CreateIfNotExistsAsync();

  9. Crie um novo tipo record para itens.

    public record Product : Azure.Data.Tables.ITableEntity
{
    public required string RowKey { get; set; }

    public required string PartitionKey { get; set; }

    public required string Name { get; init; }

    public Azure.ETag ETag { get; set; }

    public DateTimeOffset? Timestamp { get; set; }
}

  10. Crie um novo item na tabela usando UpsertEntityAsync e o modo Replace.

    var item = new Product
{
    RowKey = "68719518371",
    PartitionKey = "Surfboards",
    Name = "Kiama classic surfboard",
    Timestamp = DateTimeOffset.Now
};

await client.UpsertEntityAsync(
    entity: item,
    mode: TableUpdateMode.Replace
);

  11. Execute o aplicativo .NET.

    dotnet run

Usar o emulador em um fluxo de trabalho de CI GitHub Actions

Para executar uma carga de trabalho de integração contínua que valide automaticamente a sua aplicação, utilize o emulador Azure Cosmos DB com um conjunto de testes da sua estrutura preferida. O emulador do Azure Cosmos DB é pré-instalado na variante windows-latest dos executores hospedados do GitHub Action.

Execute um conjunto de testes usando o driver de teste interno para .NET e uma estrutura de teste, como MSTest, NUnit ou XUnit.

  1. Valide se o conjunto de testes de unidade para seu aplicativo funciona conforme o esperado.

    dotnet test

  2. Crie um novo fluxo de trabalho no repositório GitHub em um arquivo chamado .github/workflows/ci.yml.

  3. Adicione um trabalho ao fluxo de trabalho para iniciar o emulador do Azure Cosmos DB usando o PowerShell e executar o conjunto de testes de unidade.

    name: Continuous Integration
on:
  push:
    branches:
      - main
jobs:
  unit_tests:
    name: Run .NET unit tests
    runs-on: windows-latest
    steps:
      - name: Checkout (GitHub)
        uses: actions/checkout@v3
      - name: Start Azure Cosmos DB emulator
        run: |
          Write-Host "Launching Cosmos DB Emulator"
          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
          Start-CosmosDbEmulator
      - name: Run .NET tests
        run: dotnet test

    Observação

    Inicie o emulador na linha de comando usando vários argumentos ou comandos do PowerShell. Para obter mais informações, consulte argumentos de linha de comando do emulador.

Próxima etapa

Examinar as notas de versão do emulador