Delen via

Lokaal ontwikkelen met behulp van de Azure Cosmos DB-emulator

  • Artikel

Een veelvoorkomend gebruiksvoorbeeld voor de emulator is om te fungeren als een ontwikkelingsdatabase terwijl u uw toepassingen bouwt. Het gebruik van de emulator voor ontwikkeling kan u helpen bij het leren van kenmerken van het maken en modelleren van gegevens voor een database zoals Azure Cosmos DB zonder dat er servicekosten in rekening worden gebracht. Daarnaast kan het gebruik van de emulator als onderdeel van een automatiseringswerkstroom ervoor zorgen dat u dezelfde reeks integratietests kunt uitvoeren. U kunt ervoor zorgen dat dezelfde tests zowel lokaal worden uitgevoerd op uw ontwikkelcomputer als op afstand in een continue integratietaak.

Vereisten

De emulator installeren

Er zijn meerdere variaties van de emulator en elke variatie heeft een relatief wrijvingloos installatieproces.

Om aan de slag te gaan, haalt u de Linux-variant van de containerinstallatiekopieën op uit microsoft containerregister (MCR).

  1. Haal de Installatiekopie van de mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linux-container uit het containerregister op naar de lokale Docker-host.

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

  2. Controleer of de emulatorinstallatiekopie beschikbaar is op uw lokale Docker-host.

    docker images

Om aan de slag te gaan, haalt u de Linux-variant van de containerinstallatiekopieën op uit microsoft containerregister (MCR).

  1. Haal de mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linux-containerinstallatiekopie op met behulp van de mongodb tag uit het containerregister naar de lokale Docker-host.

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

  2. Controleer of de emulatorinstallatiekopie beschikbaar is op uw lokale Docker-host.

    docker images

De Docker-containervariant (Linux of Windows) van de emulator biedt geen ondersteuning voor de API voor Apache Cassandra, API voor Apache Gremlin of API voor Table.

De emulator starten

Nadat u de emulator hebt gedownload, start u de emulator waarvoor de opgegeven API is ingeschakeld.

De Docker-containervariant van de emulator biedt geen ondersteuning voor de API voor Apache Cassandra.

De Docker-containervariant van de emulator biedt geen ondersteuning voor de API voor Apache Gremlin.

De Docker-containervariant van de emulator biedt geen ondersteuning voor de API voor Table.

  1. Voer een nieuwe container uit met behulp van de containerinstallatiekopieën en de volgende configuratie:

    Beschrijving
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Optioneel) Geef het aantal te gebruiken partities op.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Optioneel) Schakel gegevenspersistentie tussen emulatoruitvoeringen in.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Optioneel) Overschrijf het standaard-IP-adres van de emulator.

    Voor Linux-systemen gebruikt u:

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

    Gebruik voor Windows-systemen:

    $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. Navigeer naar https://localhost:8081/_explorer/index.html toegang tot data explorer.

  1. Voer een nieuwe container uit met behulp van de containerinstallatiekopieën en de volgende configuratie:

    Beschrijving
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT Geef de versie op van het MongoDB-eindpunt dat moet worden gebruikt. Ondersteunde eindpunten zijn: 3.2, 3.6of 4.0.
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Optioneel) Geef het aantal te gebruiken partities op.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Optioneel) Schakel gegevenspersistentie tussen emulatoruitvoeringen in.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Optioneel) Overschrijf het standaard-IP-adres van de emulator.

    Voor Linux-systemen gebruikt u:

    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

    Gebruik voor Windows-systemen:

    $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. Navigeer naar https://localhost:8081/_explorer/index.html toegang tot data explorer.

TLS/SSL-certificaat van de emulator importeren

Importeer het TLS/SSL-certificaat van de emulator om de emulator te gebruiken met uw favoriete ontwikkelaars-SDK zonder TLS/SSL op de client uit te schakelen.

De Docker-containervariant (Linux of Windows) van de emulator biedt geen ondersteuning voor de API voor Apache Cassandra, API voor Apache Gremlin of API voor Table.

Het certificaat voor de emulator is beschikbaar op het pad _explorer/emulator.pem in de actieve container. Gebruik curl dit om het certificaat te downloaden van de actieve container naar uw lokale computer.

  1. Haal het certificaat op uit de actieve container.

    Voor Linux-systemen gebruikt u:

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

    Gebruik voor Windows-systemen:

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

  2. Genereer de certificaatbundel opnieuw met behulp van de juiste opdracht voor uw besturingssysteem.

    Gebruik voor Linux-systemen op basis van Debian (bijvoorbeeld Ubuntu):

    sudo update-ca-certificates

    Gebruik voor Op Red Hat gebaseerde Linux-systemen (bijvoorbeeld CentOS, Fedora):

    sudo update-ca-trust

    Gebruik voor Windows-systemen:

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

    Raadpleeg de documentatie die specifiek is voor uw besturingssysteem voor meer gedetailleerde instructies.

Het certificaat voor de emulator is beschikbaar op het pad /_explorer/emulator.pem in de actieve container.

  1. Download het certificaat van de actieve container naar uw lokale computer.

    Voor Linux-systemen gebruikt u:

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

    Gebruik voor Windows-systemen:

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

    Notitie

    Mogelijk moet u de host (of het IP-adres) en het poortnummer wijzigen als u deze waarden eerder hebt gewijzigd.

  2. Installeer het certificaat volgens het proces dat doorgaans wordt gebruikt voor uw besturingssysteem. In Linux kopieert u bijvoorbeeld het certificaat naar het /usr/local/share/ca-certificates/ pad.

    Voor Linux-systemen gebruikt u:

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

    Gebruik voor Windows-systemen:

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

  3. Voor Linux-systemen genereert u de certificaatbundel opnieuw met behulp van de juiste opdracht voor uw Linux-distributie.

    Gebruik voor Linux-systemen op basis van Debian (bijvoorbeeld Ubuntu):

    sudo update-ca-certificates

    Gebruik voor Op Red Hat gebaseerde Linux-systemen (bijvoorbeeld CentOS, Fedora):

    sudo update-ca-trust

    Raadpleeg de documentatie die specifiek is voor uw besturingssysteem voor meer gedetailleerde instructies.

Verbinding maken met de emulator vanuit de SDK

Elke SDK bevat een clientklasse die doorgaans wordt gebruikt om de SDK te verbinden met uw Azure Cosmos DB-account. Met behulp van de referenties van de emulator kunt u in plaats daarvan de SDK verbinden met het emulatorexemplaren.

Gebruik de Azure Cosmos DB-API voor NoSQL .NET SDK om vanuit een .NET-toepassing verbinding te maken met de emulator.

  1. Begin in een lege map.

  2. Een nieuwe .NET-consoletoepassing maken

    dotnet new console

  3. Voeg het Microsoft.Azure.Cosmos pakket toe vanuit NuGet.

    dotnet add package Microsoft.Azure.Cosmos

  4. Open het Program.cs-bestand .

  5. Verwijder alle bestaande inhoud in het bestand.

  6. Voeg een using-blok toe voor de Microsoft.Azure.Cosmos naamruimte.

    using Microsoft.Azure.Cosmos;

  7. Maak een nieuw exemplaar van het gebruik van de referenties van CosmosClient de emulator.

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

  8. Maak een nieuwe database en container met behulp van CreateDatabaseIfNotExistsAsync en CreateContainerIfNotExistsAsync.

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

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

  9. Maak een nieuw item in de container met behulp van UpsertItemAsync.

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

await container.UpsertItemAsync(item);

  10. Voer de .NET-toepassing uit.

    dotnet run

    Waarschuwing

    Als u een SSL-fout krijgt, moet u TLS/SSL mogelijk uitschakelen voor uw toepassing. Dit gebeurt meestal als u ontwikkelt op uw lokale computer, met behulp van de Azure Cosmos DB-emulator in een container en het SSL-certificaat van de container niet hebt geïmporteerd. U kunt dit oplossen door de opties van de client te configureren om TLS/SSL-validatie uit te schakelen voordat u de client maakt:

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

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

Tip

Raadpleeg de .NET-ontwikkelaarshandleiding voor meer bewerkingen die u kunt uitvoeren met behulp van de .NET SDK.

Gebruik het MongoDB .NET-stuurprogramma om verbinding te maken met de emulator vanuit een .NET-toepassing.

  1. Begin in een lege map.

  2. Een nieuwe .NET-consoletoepassing maken

    dotnet new console

  3. Voeg het MongoDB.Driver pakket toe vanuit NuGet.

    dotnet add package MongoDB.Driver

  4. Open het Program.cs-bestand .

  5. Verwijder alle bestaande inhoud in het bestand.

  6. Voeg een using-blok toe voor de MongoDB.Driver naamruimte.

    using MongoDB.Driver;

  7. Maak een nieuw exemplaar van het gebruik van de referenties van MongoClient de emulator.

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

  8. Haal de database en container op met behulp van GetDatabase en GetCollection<>.

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

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

  9. Maak een nieuw item in xxx met behulp van InsertOneAsync.

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

await collection.InsertOneAsync(item);

  10. Voer de .NET-toepassing uit.

    dotnet run

Gebruik het Apache Cassandra .NET-stuurprogramma om vanuit een .NET-toepassing verbinding te maken met de emulator.

  1. Begin in een lege map.

  2. Een nieuwe .NET-consoletoepassing maken

    dotnet new console

  3. Voeg het CassandraCSharpDriver pakket toe vanuit NuGet.

    dotnet add package CassandraCSharpDriver

  4. Open het Program.cs-bestand .

  5. Verwijder alle bestaande inhoud in het bestand.

  6. Voeg een using-blok toe voor de Cassandra naamruimte.

    using Cassandra;

  7. Maak een nieuw exemplaar van het gebruik van de referenties van Cluster de emulator. Maak een nieuwe sessie met behulp van 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. Maak een nieuwe database en container met behulp van PrepareAsync en 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. Maak een nieuw item in de tabel met behulp van ExecuteAsync. Hiermee Bind kunt u eigenschappen toewijzen aan het 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. Voer de .NET-toepassing uit.

    dotnet run

Belangrijk

Voordat u begint, moet u voor de API voor Apache Gremlin uw resources maken in de emulator. Maak een database met de naam db1 en een container met de naam coll1. De doorvoerinstellingen zijn niet relevant voor deze handleiding en kunnen zo laag worden ingesteld als u wilt.

Gebruik het Apache Gremlin .NET-stuurprogramma om verbinding te maken met de emulator vanuit een .NET-toepassing.

  1. Begin in een lege map.

  2. Een nieuwe .NET-consoletoepassing maken

    dotnet new console

  3. Voeg het Gremlin.Net pakket toe vanuit NuGet.

    dotnet add package Gremlin.Net

  4. Open het Program.cs-bestand .

  5. Verwijder alle bestaande inhoud in het bestand.

  6. Voeg een using-blok toe voor de Gremlin.Net.Driver naamruimte.

    using Gremlin.Net.Driver;

  7. Maak een nieuw exemplaar van GremlinServer en GremlinClient gebruik de referenties van de emulator.

    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. De grafiek opschonen met behulp van SubmitAsync.

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

  9. Gebruik SubmitAsync opnieuw om een nieuw item toe te voegen aan de grafiek met de opgegeven parameters.

    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. Voer de .NET-toepassing uit.

    dotnet run

Gebruik de Azure Tables SDK voor .NET om vanuit een .NET-toepassing verbinding te maken met de emulator.

  1. Begin in een lege map.

  2. Een nieuwe .NET-consoletoepassing maken

    dotnet new console

  3. Voeg het Azure.Data.Tables pakket toe vanuit NuGet.

    dotnet add package Azure.Data.Tables

  4. Open het Program.cs-bestand .

  5. Verwijder alle bestaande inhoud in het bestand.

  6. Voeg een using-blok toe voor de Azure.Data.Tables naamruimte.

    using Azure.Data.Tables;

  7. Maak een nieuw exemplaar van het gebruik van de referenties van TableServiceClient de emulator.

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

  8. Hiermee GetTableClient maakt u een nieuw exemplaar van met de naam van TableClient de tabel. Controleer vervolgens of de tabel bestaat met behulp van CreateIfNotExistsAsync.

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

await client.CreateIfNotExistsAsync();

  9. Maak een nieuw record type voor items.

    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. Maak een nieuw item in de tabel met behulp van UpsertEntityAsync de Replace modus.

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

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

  11. Voer de .NET-toepassing uit.

    dotnet run

De emulator gebruiken in een CI-werkstroom voor GitHub Actions

Als u een workload voor continue integratie wilt uitvoeren waarmee uw toepassing automatisch wordt gevalideerd, gebruikt u de Azure Cosmos DB-emulator met een testpakket van uw keuzeframework. De Azure Cosmos DB-emulator is vooraf geïnstalleerd in de windows-latest variant van de gehoste hardlopers van GitHub Action.

Voer een testpakket uit met behulp van het ingebouwde teststuurprogramma voor .NET en een testframework zoals MSTest, NUnit of XUnit.

  1. Controleer of het eenheidstestpakket voor uw toepassing werkt zoals verwacht.

    dotnet test

  2. Maak een nieuwe werkstroom in uw GitHub-opslagplaats in een bestand met de naam .github/workflows/ci.yml.

  3. Voeg een taak toe aan uw werkstroom om de Azure Cosmos DB-emulator te starten met behulp van PowerShell en uw eenheidstestpakket uit te voeren.

    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

    Notitie

    Start de emulator vanaf de opdrachtregel met behulp van verschillende argumenten of PowerShell-opdrachten. Zie opdrachtregelargumenten van de emulator voor meer informatie.

Volgende stap

Bekijk de releaseopmerkingen van de emulator