Freigeben über

Lokale Entwicklung mit dem Azure Cosmos DB-Emulator

  • Artikel

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 helfen, die Merkmale des Erstellens und Modellierens von Daten für eine Datenbank wie Azure Cosmos DB zu erlernen, ohne dass Dienstkosten 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.

Voraussetzungen

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 dem 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 dem 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:mongodb

  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 für 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:

    Beschreibung
    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 Folgendes:

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

    Beschreibung
    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 Folgendes:

    $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 für 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 Folgendes:

    $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 Folgendes:

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

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

    Hinweis

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

    $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 normalerweise 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 Microsoft.Azure.Cosmos-Paket aus 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 Microsoft.Azure.Cosmos-Namespace 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

    Warnung

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

Tipp

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 eine Verbindung mit dem Emulator über eine .NET-Anwendung herzustellen.

  1. Starten Sie in einem leeren Ordner.

  2. Erstellen einer neuen .NET-Konsolenanwendung

    dotnet new console

  3. Fügen Sie das MongoDB.Driver-Paket aus 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 MongoDB.Driver-Namespace 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 eine Verbindung mit dem Emulator über eine .NET-Anwendung herzustellen.

  1. Starten Sie in einem leeren Ordner.

  2. Erstellen einer neuen .NET-Konsolenanwendung

    dotnet new console

  3. Fügen Sie das CassandraCSharpDriver-Paket aus 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 Cassandra-Namespace 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

Wichtig

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 Cassandra .NET-Treiber, um eine Verbindung mit dem Emulator über eine .NET-Anwendung herzustellen.

  1. Starten Sie in einem leeren Ordner.

  2. Erstellen einer neuen .NET-Konsolenanwendung

    dotnet new console

  3. Fügen Sie das Gremlin.Net-Paket aus 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 Gremlin.Net.Driver-Namespace 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: 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. 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 Azure.Data.Tables-Paket aus 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 Azure.Data.Tables-Namespace 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 Continuous Integration-Workload auszuführen, die Ihre Anwendung automatisch validiert, verwenden Sie den Azure Cosmos DB-Emulator mit einer Testsammlung aus dem Framework Ihrer Wahl. Der Azure Cosmos DB-Emulator ist in der windows-latest-Variante der gehosteten Runner von GitHub Action vorinstalliert.

Führen Sie eine Testsammlung 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 mit dem Namen .github/workflows/ci.yml.

  3. Fügen Sie Ihrem Workflow einen Auftrag hinzu, um den Azure Cosmos DB-Emulator mithilfe von PowerShell zu starten und Ihre Komponententestsammlung 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

    Hinweis

    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