Разработка локально с помощью эмулятора Azure Cosmos DB

  • Статья

Распространенный вариант использования эмулятора — служить базой данных разработки при создании приложений. С помощью эмулятора для разработки можно узнать характеристики создания и моделирования данных для базы данных, такой как Azure Cosmos DB, без каких-либо затрат на обслуживание. Кроме того, использование эмулятора в рамках рабочего процесса автоматизации может обеспечить выполнение одного набора тестов интеграции. Вы можете убедиться, что одни и те же тесты выполняются локально на компьютере разработки и удаленно в задании непрерывной интеграции.

Необходимые компоненты

Установка эмулятора

Существует несколько вариантов эмулятора, и каждый вариант имеет относительно беспокойный процесс установки.

Чтобы приступить к работе, получите вариант образа контейнера Linux из реестра контейнеров Майкрософт (MCR).

  1. mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Извлеките образ контейнера Linux из реестра контейнеров на локальный узел Docker.

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

  2. Убедитесь, что образ эмулятора был извлечен на локальный узел Docker.

    docker images

Чтобы приступить к работе, получите вариант образа контейнера Linux из реестра контейнеров Майкрософт (MCR).

  1. mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Извлеките образ контейнера Linux с помощью mongodb тега из реестра контейнеров на локальный узел Docker.

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

  2. Убедитесь, что образ эмулятора был извлечен на локальный узел Docker.

    docker images

Вариант контейнера Docker (Linux или Windows) эмулятора не поддерживает API для Apache Cassandra, API для Apache Gremlin или API для таблицы.

Запуск эмулятора

После скачивания запустите эмулятор с включенным вашим API.

Вариант контейнера Docker эмулятора не поддерживает API для Apache Cassandra.

Вариант контейнера Docker эмулятора не поддерживает API для Apache Gremlin.

Вариант контейнера Docker эмулятора не поддерживает API для таблицы.

  1. Запустите новый контейнер с помощью образа контейнера и следующей конфигурации:

    Description
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Необязательно) Укажите количество используемых секций.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Необязательно) Включите сохраняемость данных между запусками эмулятора.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Необязательно) Переопределите IP-адрес эмулятора по умолчанию. 
    docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --interactive \
    --tty \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. Перейдите к https://localhost:8081/_explorer/index.html обозревателе данных.

  1. Запустите новый контейнер с помощью образа контейнера и следующей конфигурации:

    Description
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT Укажите версию используемой конечной точки MongoDB. Поддерживаемые конечные точки включают: 3.2, 3.6или 4.0.
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Необязательно) Укажите количество используемых секций.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Необязательно) Включите сохраняемость данных между запусками эмулятора.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Необязательно) Переопределите IP-адрес эмулятора по умолчанию. 
    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. Перейдите к https://localhost:8081/_explorer/index.html обозревателе данных.

Импорт TLS/SSL-сертификата эмулятора

Импортируйте TLS/SSL-сертификат эмулятора, чтобы использовать эмулятор с предпочитаемым пакетом SDK разработчика без отключения TLS/SSL на клиенте.

Вариант контейнера Docker (Linux или Windows) эмулятора не поддерживает API для Apache Cassandra, API для Apache Gremlin или API для таблицы.

Сертификат для эмулятора доступен по пути _explorer/emulator.pem в работающем контейнере. Используется curl для скачивания сертификата из запущенного контейнера на локальный компьютер.

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

Сертификат для эмулятора доступен по пути _explorer/emulator.pem в работающем контейнере.

  1. Используется curl для скачивания сертификата из запущенного контейнера на локальный компьютер.

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

    Примечание.

    Возможно, потребуется изменить узел (или IP-адрес) и номер порта, если вы ранее изменили эти значения.

  2. Установите сертификат в соответствии с процессом, который обычно используется для операционной системы. Например, в Linux вы скопируете сертификат в /usr/local/share/ca-certificates/ путь.

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

  3. Обновите сертификаты ЦС и повторно создайте пакет сертификатов с помощью соответствующей команды для дистрибутива Linux.

    Для систем на основе Debian (например, Ubuntu) используйте:

    sudo update-ca-certificates

    Для систем на основе Red Hat (например, CentOS, Fedora) используйте:

    sudo update-ca-trust

    Дополнительные инструкции см. в документации по дистрибутиву Linux.

Подключение эмулятору из пакета SDK

Каждый пакет SDK включает класс клиента, обычно используемый для подключения пакета SDK к учетной записи Azure Cosmos DB. Используя учетные данные эмулятора, вы можете подключить пакет SDK к экземпляру эмулятора.

Используйте API Azure Cosmos DB для NoSQL .NET SDK для подключения к эмулятору из приложения .NET.

  1. Запустите пустую папку.

  2. Создание консольного приложения .NET

    dotnet new console

  3. Microsoft.Azure.Cosmos Добавьте пакет из NuGet.

    dotnet add package Microsoft.Azure.Cosmos

  4. Откройте файл Program.cs.

  5. Удалите любое существующее содержимое в файле.

  6. Добавьте блок using для Microsoft.Azure.Cosmos пространства имен.

    using Microsoft.Azure.Cosmos;

  7. Создайте новый экземпляр CosmosClient с помощью учетных данных эмулятора.

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

  8. Создание базы данных и контейнера с помощью CreateDatabaseIfNotExistsAsync и CreateContainerIfNotExistsAsync.

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

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

  9. Создайте новый элемент в контейнере с помощью UpsertItemAsync.

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

await container.UpsertItemAsync(item);

  10. Запустите приложение .NET.

    dotnet run

    Предупреждение

    При возникновении ошибки SSL может потребоваться отключить TLS/SSL для приложения. Это обычно происходит, если вы разрабатываете на локальном компьютере, используя эмулятор Azure Cosmos DB в контейнере и не импортировали SSL-сертификат контейнера. Чтобы устранить эту проблему, настройте параметры клиента, чтобы отключить проверку TLS/SSL перед созданием клиента:

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

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

Совет

Дополнительные операции, которые можно выполнить с помощью пакета SDK для .NET, см. в руководстве разработчика .NET.

Используйте драйвер MongoDB .NET для подключения к эмулятору из приложения .NET.

  1. Запустите пустую папку.

  2. Создание консольного приложения .NET

    dotnet new console

  3. MongoDB.Driver Добавьте пакет из NuGet.

    dotnet add package MongoDB.Driver

  4. Откройте файл Program.cs.

  5. Удалите любое существующее содержимое в файле.

  6. Добавьте блок using для MongoDB.Driver пространства имен.

    using MongoDB.Driver;

  7. Создайте новый экземпляр MongoClient с помощью учетных данных эмулятора.

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

  8. Получение базы данных и контейнера с помощью GetDatabase и GetCollection<>.

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

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

  9. Создайте новый элемент в XXX с помощью InsertOneAsync.

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

await collection.InsertOneAsync(item);

  10. Запустите приложение .NET.

    dotnet run

Используйте драйвер Apache Cassandra .NET для подключения к эмулятору из приложения .NET.

  1. Запустите пустую папку.

  2. Создание консольного приложения .NET

    dotnet new console

  3. CassandraCSharpDriver Добавьте пакет из NuGet.

    dotnet add package CassandraCSharpDriver

  4. Откройте файл Program.cs.

  5. Удалите любое существующее содержимое в файле.

  6. Добавьте блок using для Cassandra пространства имен.

    using Cassandra;

  7. Создайте новый экземпляр Cluster с помощью учетных данных эмулятора. Создание нового сеанса с помощью 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. Создание базы данных и контейнера с помощью PrepareAsync и 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. Создайте новый элемент в таблице с помощью ExecuteAsync. Используется Bind для назначения свойств элементу.

    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. Запустите приложение .NET.

    dotnet run

Внимание

Перед началом работы API для Apache Gremlin требуется создать ресурсы в эмуляторе. Создайте базу данных с именем db1 и контейнером с именем coll1. Параметры пропускной способности не относятся к этому руководству и могут быть заданы так же низко, как вы хотите.

Используйте драйвер Apache Gremlin .NET для подключения к эмулятору из приложения .NET.

  1. Запустите пустую папку.

  2. Создание консольного приложения .NET

    dotnet new console

  3. Gremlin.Net Добавьте пакет из NuGet.

    dotnet add package Gremlin.Net

  4. Откройте файл Program.cs.

  5. Удалите любое существующее содержимое в файле.

  6. Добавьте блок using для Gremlin.Net.Driver пространства имен.

    using Gremlin.Net.Driver;

  7. Создайте новый экземпляр GremlinServer и GremlinClient с помощью учетных данных эмулятора.

    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. Очистка графа с помощью SubmitAsync.

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

  9. Используйте SubmitAsync еще раз, чтобы добавить новый элемент в граф с указанными параметрами.

    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. Запустите приложение .NET.

    dotnet run

Используйте пакет SDK таблиц Azure для .NET для подключения к эмулятору из приложения .NET.

  1. Запустите пустую папку.

  2. Создание консольного приложения .NET

    dotnet new console

  3. Azure.Data.Tables Добавьте пакет из NuGet.

    dotnet add package Azure.Data.Tables

  4. Откройте файл Program.cs.

  5. Удалите любое существующее содержимое в файле.

  6. Добавьте блок using для Azure.Data.Tables пространства имен.

    using Azure.Data.Tables;

  7. Создайте новый экземпляр TableServiceClient с помощью учетных данных эмулятора.

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

  8. Используется GetTableClient для создания нового экземпляра TableClient с именем таблицы. Затем убедитесь, что таблица существует с помощью CreateIfNotExistsAsync.

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

await client.CreateIfNotExistsAsync();

  9. Создайте новый record тип для элементов.

    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. Создайте новый элемент в таблице с помощью UpsertEntityAsync и 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. Запустите приложение .NET.

    dotnet run

Использование эмулятора в рабочем процессе CI GitHub Actions

Используйте эмулятор Azure Cosmos DB с набором тестов из выбранной платформы, чтобы запустить рабочую нагрузку непрерывной интеграции, которая автоматически проверяет приложение. Эмулятор Azure Cosmos DB предварительно установлен в windows-latest варианте размещенных средств выполнения GitHub Action.

Запустите набор тестов с помощью встроенного тестового драйвера для .NET и платформы тестирования, например MSTest, NUnit или XUnit.

  1. Убедитесь, что набор модульных тестов для приложения работает должным образом.

    dotnet test

  2. Создайте рабочий процесс в репозитории GitHub в файле с именем .github/workflows/ci.yml.

  3. Добавьте задание в рабочий процесс, чтобы запустить эмулятор Azure Cosmos DB с помощью PowerShell и запустить набор модульных тестов.

    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

    Примечание.

    Запустите эмулятор из командной строки с помощью различных аргументов или команд PowerShell. Дополнительные сведения см . в аргументах командной строки эмулятора.

Следующий шаг

Просмотрите заметки о выпуске эмулятора