Lokal mithilfe des Azure Cosmos DB Emulators entwickeln

  • Gilt für:: ✅ NoSQL

Ein häufiger Anwendungsfall für den Emulator besteht darin, als Entwicklungsdatenbank zu dienen, während Sie Ihre Anwendungen erstellen. Die Verwendung des Emulators für die Entwicklung kann Ihnen dabei helfen, Merkmale des Erstellens und Modellierens von Daten für eine Datenbank wie Azure Cosmos DB zu erlernen, ohne dass Servicekosten anfallen. Darüber hinaus kann die Verwendung des Emulators als Teil eines Automatisierungsworkflows sicherstellen, dass Sie dieselbe Suite von Integrationstests ausführen können. Sie können sicherstellen, dass dieselben Tests sowohl lokal auf Ihrem Entwicklungscomputer als auch remote in einem Continuous Integration-Auftrag ausgeführt werden.

Prerequisites

Installieren des Emulators

Es gibt mehrere Varianten des Emulators, und jede Variante hat einen relativ reibungslosen Installationsprozess.

Rufen Sie zunächst die Linux-Variante des Containerimages aus der Microsoft Container Registry (MCR) ab.

  1. Pullen Sie das mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linux-Containerimage aus der Containerregistrierung auf den lokalen Docker-Host.

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

  2. Stellen Sie sicher, dass das Emulatorimage auf Ihrem lokalen Docker-Host verfügbar ist.

    docker images

Rufen Sie zunächst die Linux-Variante des Containerimages aus der Microsoft Container Registry (MCR) ab.

  1. Pullen Sie das mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linux-Containerimage mit dem mongodb-Tag aus der Containerregistrierung auf den lokalen Docker-Host.

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

  2. Stellen Sie sicher, dass das Emulatorimage auf Ihrem lokalen Docker-Host verfügbar ist.

    docker images

Die Docker-Containervariante (Linux oder Windows) des Emulators unterstützt die API für Apache Cassandra, API für Apache Gremlin oder API for Table nicht.

Starten des Emulators

Starten Sie nach dem Herunterladen den Emulator mit aktivierter angegebener API.

Die Docker-Containervariante des Emulators unterstützt die API für Apache Cassandra nicht.

Die Docker-Containervariante des Emulators unterstützt die API für Apache Gremlin nicht.

Die Docker-Containervariante des Emulators unterstützt die API für Table nicht.

  1. Führen Sie einen neuen Container mit dem Containerimage und der folgenden Konfiguration aus:

    Description
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT (Optional) Geben Sie die Anzahl der zu verwendenden Partitionen an.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE (Optional) Aktivieren Sie die Datenpersistenz zwischen Emulatorausführungen.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE (Optional) Überschreiben Sie die Standard-IP-Adresse des Emulators.

    Verwenden Sie für Linux-Systeme Folgendes:

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

    Verwenden Sie für Windows Systeme:

    $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. Navigieren Sie zu https://localhost:8081/_explorer/index.html, um auf den Daten-Explorer zuzugreifen.

  1. Führen Sie einen neuen Container mit dem Containerimage und der folgenden Konfiguration aus:

    Description
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT Geben Sie die Version des zu verwendenden MongoDB-Endpunkts an. Zu den unterstützten Endpunkten gehören: 3.2, 3.6oder 4.0.
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT (Optional) Geben Sie die Anzahl der zu verwendenden Partitionen an.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE (Optional) Aktivieren Sie die Datenpersistenz zwischen Emulatorausführungen.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE (Optional) Überschreiben Sie die Standard-IP-Adresse des Emulators.

    Verwenden Sie für Linux-Systeme Folgendes:

    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

    Verwenden Sie für Windows Systeme:

    $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. Navigieren Sie zu https://localhost:8081/_explorer/index.html, um auf den Daten-Explorer zuzugreifen.

Importieren des TLS-/SSL-Zertifikats des Emulators

Importieren Sie das TLS-/SSL Zertifikat des Emulators, um den Emulator mit Ihrem bevorzugten Entwickler-SDK zu verwenden, ohne TLS/SSL auf dem Client zu deaktivieren.

Die Docker-Containervariante (Linux oder Windows) des Emulators unterstützt die API für Apache Cassandra, API für Apache Gremlin oder API for Table nicht.

Das Zertifikat für den Emulator ist unter dem Pfad _explorer/emulator.pem des laufenden Containers verfügbar. Verwenden Sie curl, um das Zertifikat aus dem laufenden Container auf Ihren lokalen Computer herunterzuladen.

  1. Rufen Sie das Zertifikat aus dem Container, der gerade ausgeführt wird, ab.

    Verwenden Sie für Linux-Systeme Folgendes:

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

    Verwenden Sie für Windows Systeme:

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

  2. Generieren Sie das Zertifikatpaket mit dem entsprechenden Befehl für Ihr Betriebssystem neu.

    Verwenden Sie für Debian-basierte Linux-Systeme (z. B. Ubuntu) Folgendes:

    sudo update-ca-certificates

    Verwenden Sie für Red Hat-basierte Linux-Systeme (z. B. CentOS, Fedora) Folgendes:

    sudo update-ca-trust

    Verwenden Sie für Windows Systeme:

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

    Ausführlichere Anweisungen finden Sie in der Dokumentation zu Ihrem Linux-Betriebssystem.

Das Zertifikat für den Emulator ist unter dem Pfad /_explorer/emulator.pem des laufenden Containers verfügbar.

  1. Laden Sie das Zertifikat aus dem laufenden Container auf Ihren lokalen Computer herunter.

    Verwenden Sie für Linux-Systeme Folgendes:

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

    Verwenden Sie für Windows Systeme:

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

    Note

    Möglicherweise müssen Sie den Host (oder die IP-Adresse) und die Portnummer ändern, wenn Sie diese Werte zuvor geändert haben.

  2. Installieren Sie das Zertifikat gemäß dem Prozess, der normalerweise für Ihr Betriebssystem verwendet wird. Unter Linux würden Sie das Zertifikat beispielsweise in den /usr/local/share/ca-certificates/-Pfad kopieren.

    Verwenden Sie für Linux-Systeme Folgendes:

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

    Verwenden Sie für Windows Systeme:

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

  3. Für Linux-Systeme generieren Sie das Zertifikatpaket mithilfe des entsprechenden Befehls für Ihre Linux-Distribution neu.

    Verwenden Sie für Debian-basierte Linux-Systeme (z. B. Ubuntu) Folgendes:

    sudo update-ca-certificates

    Verwenden Sie für Red Hat-basierte Linux-Systeme (z. B. CentOS, Fedora) Folgendes:

    sudo update-ca-trust

    Ausführlichere Anweisungen finden Sie in der Dokumentation zu Ihrem Linux-Betriebssystem.

Herstellen einer Verbindung mit dem Emulator über das SDK

Jedes SDK enthält eine Clientklasse, die in der Regel verwendet wird, um das SDK mit Ihrem Azure Cosmos DB Konto zu verbinden. Mithilfe der Anmeldeinformationen des Emulators können Sie stattdessen das SDK mit der Emulatorinstanz verbinden.

Verwenden Sie die Azure Cosmos DB-API für NoSQL .NET SDK, um über eine .NET Anwendung eine Verbindung mit dem Emulator herzustellen.

  1. Starten Sie in einem leeren Ordner.

  2. Erstellen einer neuen .NET Konsolenanwendung

    dotnet new console

  3. Fügen Sie das paket Microsoft.Azure.Cosmos von NuGet hinzu.

    dotnet add package Microsoft.Azure.Cosmos

  4. Öffnen Sie die Datei Program.cs.

  5. Löschen Sie alle vorhandenen Inhalte in der Datei.

  6. Fügen Sie einen using-Block für den Namespace Microsoft.Azure.Cosmos hinzu.

    using Microsoft.Azure.Cosmos;

  7. Erstellen Sie unter Verwendung der Anmeldeinformationen des Emulators eine neue Instanz von CosmosClient.

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

  8. Erstellen Sie eine neue Datenbank und einen Container mithilfe von CreateDatabaseIfNotExistsAsync und CreateContainerIfNotExistsAsync.

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

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

  9. Erstellen Sie mithilfe von UpsertItemAsync ein neues Element im Container.

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

await container.UpsertItemAsync(item);

  10. Führen Sie die .NET Anwendung aus.

    dotnet run

    Warning

    Wenn sie einen SSL-Fehler erhalten, müssen Sie möglicherweise TLS/SSL für Ihre Anwendung deaktivieren. Dies tritt häufig auf, wenn Sie auf Ihrem lokalen Computer entwickeln, den Azure Cosmos DB Emulator in einem Container verwenden und das SSL-Zertifikat des Containers nicht importiert haben. Um dies zu beheben, konfigurieren Sie die Optionen des Clients zum Deaktivieren der TLS/SSL-Validierung, bevor Sie den Client erstellen:

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

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

Tip

Weitere Vorgänge, die Sie mit dem .NET SDK ausführen können, finden Sie im .NET Entwicklerhandbuch.

Verwenden Sie den MongoDB .NET Treiber, um über eine .NET Anwendung eine Verbindung mit dem Emulator herzustellen.

  1. Starten Sie in einem leeren Ordner.

  2. Erstellen einer neuen .NET Konsolenanwendung

    dotnet new console

  3. Fügen Sie das paket MongoDB.Driver von NuGet hinzu.

    dotnet add package MongoDB.Driver

  4. Öffnen Sie die Datei Program.cs.

  5. Löschen Sie alle vorhandenen Inhalte in der Datei.

  6. Fügen Sie einen using-Block für den Namespace MongoDB.Driver hinzu.

    using MongoDB.Driver;

  7. Erstellen Sie unter Verwendung der Anmeldeinformationen des Emulators eine neue Instanz von MongoClient.

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

  8. Rufen Sie die Datenbank und den Container mit GetDatabase und GetCollection<> ab.

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

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

  9. Erstellen Sie ein neues Element in XXX mit InsertOneAsync.

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

await collection.InsertOneAsync(item);

  10. Führen Sie die .NET Anwendung aus.

    dotnet run

Verwenden Sie den Apache Cassandra .NET Treiber, um über eine .NET Anwendung eine Verbindung mit dem Emulator herzustellen.

  1. Starten Sie in einem leeren Ordner.

  2. Erstellen einer neuen .NET Konsolenanwendung

    dotnet new console

  3. Fügen Sie das paket CassandraCSharpDriver von NuGet hinzu.

    dotnet add package CassandraCSharpDriver

  4. Öffnen Sie die Datei Program.cs.

  5. Löschen Sie alle vorhandenen Inhalte in der Datei.

  6. Fügen Sie einen using-Block für den Namespace Cassandra hinzu.

    using Cassandra;

  7. Erstellen Sie unter Verwendung der Anmeldeinformationen des Emulators eine neue Instanz von Cluster. Erstellen Sie mithilfe von Connect eine neue Sitzung.

    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. Erstellen Sie eine neue Datenbank und einen Container mithilfe von PrepareAsync und 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. Erstellen Sie mithilfe von ExecuteAsync ein neues Element in der Tabelle. Verwenden Sie Bind, um dem Element Eigenschaften zuzuweisen.

    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. Führen Sie die .NET Anwendung aus.

    dotnet run

Important

Vor dem Start erfordert die API für Apache Gremlin, dass Sie Ihre Ressourcen im Emulator erstellen. Erstellen Sie eine Datenbank namens db1 und einen Container mit dem Namen coll1. Die Durchsatzeinstellungen sind für diese Anleitung irrelevant und können so niedrig festgelegt werden, wie Sie möchten.

Verwenden Sie den Apache Gremlin .NET Treiber, um über eine .NET Anwendung eine Verbindung mit dem Emulator herzustellen.

  1. Starten Sie in einem leeren Ordner.

  2. Erstellen einer neuen .NET Konsolenanwendung

    dotnet new console

  3. Fügen Sie das paket Gremlin.Net von NuGet hinzu.

    dotnet add package Gremlin.Net

  4. Öffnen Sie die Datei Program.cs.

  5. Löschen Sie alle vorhandenen Inhalte in der Datei.

  6. Fügen Sie einen using-Block für den Namespace Gremlin.Net.Driver hinzu.

    using Gremlin.Net.Driver;

  7. Erstellen Sie unter Verwendung der Anmeldeinformationen des Emulators eine neue Instanz von GremlinServer und GremlinClient.

    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. Bereinigen Sie den Graphen mit SubmitAsync.

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

  9. Verwenden Sie SubmitAsync erneut, um dem Graphen mit den angegebenen Parametern ein neues Element hinzuzufügen.

    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. Führen Sie die .NET Anwendung aus.

    dotnet run

Verwenden Sie das Azure Tables SDK für .NET, um über eine .NET Anwendung eine Verbindung mit dem Emulator herzustellen.

  1. Starten Sie in einem leeren Ordner.

  2. Erstellen einer neuen .NET Konsolenanwendung

    dotnet new console

  3. Fügen Sie das paket Azure.Data.Tables von NuGet hinzu.

    dotnet add package Azure.Data.Tables

  4. Öffnen Sie die Datei Program.cs.

  5. Löschen Sie alle vorhandenen Inhalte in der Datei.

  6. Fügen Sie einen using-Block für den Namespace Azure.Data.Tables hinzu.

    using Azure.Data.Tables;

  7. Erstellen Sie unter Verwendung der Anmeldeinformationen des Emulators eine neue Instanz von TableServiceClient.

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

  8. Verwenden Sie GetTableClient, um eine neue Instanz von TableClient mit dem Namen der Tabelle zu erstellen. Stellen Sie dann mithilfe von CreateIfNotExistsAsync sicher, dass die Tabelle vorhanden ist.

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

await client.CreateIfNotExistsAsync();

  9. Erstellen Sie einen neuen record-Typ für Elemente.

    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. Erstellen Sie mithilfe von UpsertEntityAsync und dem Replace-Modus ein neues Element in der Tabelle.

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

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

  11. Führen Sie die .NET Anwendung aus.

    dotnet run

Verwenden des Emulators in einem GitHub Actions CI-Workflow

Um eine fortlaufende Integrationsworkload auszuführen, die Ihre Anwendung automatisch überprüft, verwenden Sie den Azure Cosmos DB Emulator mit einer Testsuite aus Ihrem von Ihnen gewählten Framework. Der Azure Cosmos DB Emulator ist in der windows-latest Variante der von GitHub gehosteten Runner-Varianten vorinstalliert.

Führen Sie eine Testsuite mit dem integrierten Testtreiber für .NET und einem Testframework wie MSTest, NUnit oder XUnit aus.

  1. Überprüfen Sie, ob die Komponententestsammlung für Ihre Anwendung wie erwartet funktioniert.

    dotnet test

  2. Erstellen Sie einen neuen Workflow in Ihrem GitHub-Repository in einer Datei namens .github/workflows/ci.yml.

  3. Fügen Sie Ihrem Workflow einen Auftrag hinzu, um den Azure Cosmos DB Emulator mit PowerShell zu starten und die Komponententestsuite auszuführen.

    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

    Note

    Starten Sie den Emulator über die Befehlszeile mit verschiedenen Argumenten oder PowerShell-Befehlen. Weitere Informationen finden Sie unter Emulator-Befehlszeilenargumente.

Nächster Schritt

Lesen Sie die Versionshinweise zum Emulator

  • Last updated on