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 as 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 sua máquina de desenvolvimento e remotamente em um trabalho de integração contínua.

Pré-requisitos

Instalar o emulador

Existem 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 Linux da imagem de contêiner do Microsoft Container Registry (MCR).

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

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

  2. Verifique se a imagem do emulador foi puxada para o host Docker local.

    docker images

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

  1. Puxe a imagem do mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator contêiner Linux usando a mongodb tag do registro do contêiner para o host Docker local.

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

  2. Verifique se a imagem do emulador foi puxada para o host Docker local.

    docker images

A variante de contêiner do Docker (Linux ou Windows) do emulador não suporta a API para Apache Cassandra, API para Apache Gremlin ou API para Table.

Iniciar o emulador

Uma vez baixado, inicie o emulador com a API especificada ativada.

A variante de contêiner do Docker do emulador não suporta a API do Apache Cassandra.

A variante de contêiner do Docker do emulador não suporta a API do Apache Gremlin.

A variante de contêiner do Docker do emulador não suporta a API para Tabela.

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

    Description
    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 as execuções do emulador.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Opcional) Substitua o endereço IP padrão do emulador. 
    docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --interactive \
    --tty \
    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 do contêiner e a seguinte configuração:

    Description
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT Especifique a versão do ponto de extremidade do MongoDB a ser usada. Os pontos de extremidade suportados 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 as execuções do emulador.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Opcional) Substitua o endereço IP padrão do emulador. 
    docker run \
    --publish 8081:8081 \
    --publish 10250:10250 \
    --env AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT=4.0 \
    --interactive \
    --tty \
    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 preferido sem desabilitar o TLS/SSL no cliente.

A variante de contêiner do Docker (Linux ou Windows) do emulador não suporta a API para Apache Cassandra, API para Apache Gremlin ou API para Table.

O certificado para o 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 para sua máquina local.

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

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

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

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

    Nota

    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 o seu sistema operacional. Por exemplo, no Linux você copiaria o certificado para o /usr/local/share/ca-certificates/ caminho.

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

  3. Atualize os certificados de CA e regenere o pacote de certificados usando o comando apropriado para sua distribuição Linux.

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

    sudo update-ca-certificates

    Para sistemas 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 para a sua distribuição Linux.

Conectar-se ao emulador a partir 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 a API do Azure Cosmos DB para NoSQL .NET SDK para se conectar ao emulador a partir de um aplicativo .NET.

  1. Comece em uma pasta vazia.

  2. Criar um novo aplicativo de console .NET

    dotnet new console

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

    dotnet add package Microsoft.Azure.Cosmos

  4. Abra o arquivo Program.cs .

  5. Exclua qualquer conteúdo existente no arquivo.

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

    using Microsoft.Azure.Cosmos;

  7. Crie uma nova instância de uso das credenciais do CosmosClient emulador.

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

  8. Crie um novo banco de dados e 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 UpsertItemAsynco .

    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 desativar o TLS/SSL para seu aplicativo. Isso geralmente ocorre se você estiver desenvolvendo em sua máquina local, usando o emulador do Azure Cosmos DB em um contêiner, e não tiver importado o certificado SSL do contêiner. Para resolver isso, configure as opções do cliente para desabilitar a validação 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
);

Gorjeta

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 a partir de um aplicativo .NET.

  1. Comece em uma pasta vazia.

  2. Criar um novo aplicativo de console .NET

    dotnet new console

  3. Adicione o MongoDB.Driver pacote do NuGet.

    dotnet add package MongoDB.Driver

  4. Abra o arquivo Program.cs .

  5. Exclua qualquer conteúdo existente no arquivo.

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

    using MongoDB.Driver;

  7. Crie uma nova instância de uso das credenciais do MongoClient 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 InsertOneAsynco .

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

await collection.InsertOneAsync(item);

  10. Execute o aplicativo .NET.

    dotnet run

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

  1. Comece em uma pasta vazia.

  2. Criar um novo aplicativo de console .NET

    dotnet new console

  3. Adicione o CassandraCSharpDriver pacote do NuGet.

    dotnet add package CassandraCSharpDriver

  4. Abra o arquivo Program.cs .

  5. Exclua qualquer conteúdo existente no arquivo.

  6. Adicione um bloco using para o Cassandra namespace.

    using Cassandra;

  7. Crie uma nova instância de uso das credenciais do Cluster emulador. Crie uma nova sessão usando Connecto .

    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 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 iniciar, a API para Apache Gremlin requer 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 tão baixo quanto você gostaria.

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

  1. Comece em uma pasta vazia.

  2. Criar um novo aplicativo de console .NET

    dotnet new console

  3. Adicione o Gremlin.Net pacote do NuGet.

    dotnet add package Gremlin.Net

  4. Abra o arquivo Program.cs .

  5. Exclua qualquer conteúdo existente no arquivo.

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

    using Gremlin.Net.Driver;

  7. Crie uma nova instância de 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 gráfico usando SubmitAsync.

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

  9. Use SubmitAsync novamente para adicionar um novo item ao gráfico 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 a partir de um aplicativo .NET.

  1. Comece em uma pasta vazia.

  2. Criar um novo aplicativo de console .NET

    dotnet new console

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

    dotnet add package Azure.Data.Tables

  4. Abra o arquivo Program.cs .

  5. Exclua qualquer conteúdo existente no arquivo.

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

    using Azure.Data.Tables;

  7. Crie uma nova instância de uso das credenciais do TableServiceClient 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 com o nome da TableClient tabela. Em seguida, verifique se a tabela existe usando CreateIfNotExistsAsync.

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

await client.CreateIfNotExistsAsync();

  9. Crie um novo record tipo 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 Replace modo.

    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 de ações do GitHub

Use o emulador do Azure Cosmos DB com um conjunto de testes da estrutura de sua escolha para executar uma carga de trabalho de integração contínua que valida automaticamente seu aplicativo. O emulador do Azure Cosmos DB está pré-instalado na windows-latest variante dos corredores 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 em seu repositório GitHub em um arquivo chamado .github/workflows/ci.yml.

  3. Adicione um trabalho ao seu fluxo de trabalho para iniciar o emulador do Azure Cosmos DB usando o PowerShell e executar seu pacote de teste 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

    Nota

    Inicie o emulador a partir da 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óximo passo

Analise as notas de versão do emulador