Desenvolver localmente usando o emulador Azure Cosmos DB

  • Aplica-se a: ✅ NoSQL

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 da criação e modelação de dados para uma base 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 do contentor no registo de contentores Microsoft (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 está disponível no host Docker local.

    docker images

Para começar, obtenha a variante Linux da imagem do contentor no registo de contentores Microsoft (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:latest

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

    docker images

A variante do contentor 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.

    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, utilize:

    $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 do contêiner e a seguinte configuração:

    Description
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT Especifique a versão do endpoint 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.

    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, utilize:

    $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 preferido sem desabilitar o TLS/SSL no cliente.

A variante do contentor 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.

  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, utilize:

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

  2. Regenere 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, utilize:

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

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

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

  1. Transfira o certificado do contentor em execução para o seu computador local.

    Para sistemas Linux, use:

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

    Para sistemas Windows, utilize:

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

    Para sistemas Linux, use:

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

    Para sistemas Windows, utilize:

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

  3. Para sistemas linux, regenere 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 a partir do SDK

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

Use a API Azure Cosmos DB para NoSQL .NET SDK para se ligar ao emulador a partir de uma aplicação .NET.

  1. Comece em uma pasta vazia.

  2. Criar uma nova aplicação de consola .NET

    dotnet new console

  3. Adicione o pacote Microsoft.Azure.Cosmos da 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 de uso para o espaço de nomes 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 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. Executa a aplicação .NET.

    dotnet run

    Warning

    Se você receber um erro SSL, talvez seja necessário desativar o TLS/SSL para seu aplicativo. Isto ocorre frequentemente se estiver a desenvolver na sua máquina local, usando o emulador de Azure Cosmos DB num contentor e não importou o certificado SSL do contentor. 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
);

Tip

Consulte o guia para desenvolvedores .NET para mais operações que pode realizar usando o SDK .NET.

Use o driver MongoDB .NET para se ligar ao emulador a partir de uma aplicação .NET.

  1. Comece em uma pasta vazia.

  2. Criar uma nova aplicação de consola .NET

    dotnet new console

  3. Adicione o pacote MongoDB.Driver da NuGet.

    dotnet add package MongoDB.Driver

  4. Abra o arquivo Program.cs .

  5. Exclua qualquer conteúdo existente no arquivo.

  6. Adicione um bloco de uso para o espaço de nomes 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. Executa a aplicação .NET.

    dotnet run

Usa o driver .NET Apache Cassandra para te ligares ao emulador a partir de uma aplicação .NET.

  1. Comece em uma pasta vazia.

  2. Criar uma nova aplicação de consola .NET

    dotnet new console

  3. Adicione o pacote CassandraCSharpDriver da NuGet.

    dotnet add package CassandraCSharpDriver

  4. Abra o arquivo Program.cs .

  5. Exclua qualquer conteúdo existente no arquivo.

  6. Adicione um bloco de uso para o espaço de nomes 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 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. Executa a aplicação .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 .NET Apache Gremlin para se ligar ao emulador a partir de uma aplicação .NET.

  1. Comece em uma pasta vazia.

  2. Criar uma nova aplicação de consola .NET

    dotnet new console

  3. Adicione o pacote Gremlin.Net da NuGet.

    dotnet add package Gremlin.Net

  4. Abra o arquivo Program.cs .

  5. Exclua qualquer conteúdo existente no arquivo.

  6. Adicione um bloco de uso para o espaço de nomes Gremlin.Net.Driver.

    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: 65400,
    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. Executa a aplicação .NET.

    dotnet run

Use o SDK de Tabelas Azure para .NET para se ligar ao emulador a partir de uma aplicação .NET.

  1. Comece em uma pasta vazia.

  2. Criar uma nova aplicação de consola .NET

    dotnet new console

  3. Adicione o pacote Azure.Data.Tables da 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 de uso para o espaço de nomes 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 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. Executa a aplicação .NET.

    dotnet run

Use o emulador num fluxo de trabalho CI do GitHub Actions

Para executar uma carga de trabalho de integração contínua que valide automaticamente a sua aplicação, use o emulador Azure Cosmos DB com uma suite de testes do seu framework preferido. O emulador do Azure Cosmos DB está pré-instalado na variante windows-latest dos agentes hospedados do GitHub Actions.

Execute uma suite de testes usando o driver de teste incorporado para .NET e uma framework de testes 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 seu repositório de GitHub num ficheiro chamado .github/workflows/ci.yml.

  3. Adiciona uma tarefa ao teu fluxo de trabalho para iniciar o emulador do Azure Cosmos DB usando PowerShell e executa a tua suite de testes unitários.

    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 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

  • Last updated on