Utveckla lokalt med hjälp av Azure Cosmos DB-emulatorn

  • Gäller för: ✅ NoSQL

Ett vanligt användningsfall för emulatorn är att fungera som en utvecklingsdatabas när du skapar dina program. Att använda emulatorn för utveckling kan hjälpa dig att lära dig egenskaper för att skapa och modellera data för en databas som Azure Cosmos DB utan att medföra några tjänstkostnader. Om du använder emulatorn som en del av ett automationsarbetsflöde kan du dessutom se till att du kan köra samma uppsättning integreringstester. Du kan se till att samma tester körs både lokalt på utvecklingsdatorn och via fjärranslutning i ett kontinuerligt integrationsjobb.

Prerequisites

Installera emulatorn

Det finns flera varianter av emulatorn och varje variant har en relativt friktionsfri installationsprocess.

Kom igång genom att hämta Linux-varianten av containeravbildningen från Microsoft Container Registry (MCR).

  1. Ladda ner Linux-containeravbildningen mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator från containerregistret till den lokala Docker-värden.

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

  2. Kontrollera för att säkerställa att emulatorbilden är tillgänglig på din lokala Docker-värd.

    docker images

Kom igång genom att hämta Linux-varianten av containeravbildningen från Microsoft Container Registry (MCR).

  1. Hämta Linux-containeravbildningen mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator med taggen mongodb från containerregistret till den lokala Docker-värdmaskinen.

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

  2. Kontrollera för att säkerställa att emulatorbilden är tillgänglig på din lokala Docker-värd.

    docker images

Docker-containervarianten (Linux eller Windows) för emulatorn stöder inte API:et för Apache Cassandra, API för Apache Gremlin eller API för Table.

Starta emulatorn

När du har laddat ned startar du emulatorn med det angivna API:et aktiverat.

Docker-containervarianten för emulatorn stöder inte API:et för Apache Cassandra.

Docker-containervarianten av emulatorn stöder inte API:et för Apache Gremlin.

Docker-containervarianten för emulatorn stöder inte API:et för table.

  1. Kör en ny container med containeravbildningen och följande konfiguration:

    Description
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT (Valfritt) Ange antalet partitioner som ska användas.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE (Valfritt) Aktivera datapersistence mellan emulatorkörningar.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE (Valfritt) Åsidosätt emulatorns standard-IP-adress.

    För Linux-system använder du:

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

    För Windows system använder du:

    $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. Gå till https://localhost:8081/_explorer/index.html för att komma åt datautforskaren.

  1. Kör en ny container med containeravbildningen och följande konfiguration:

    Description
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT Ange vilken version av MongoDB-slutpunkten som ska användas. Slutpunkter som stöds är: 3.2, 3.6eller 4.0.
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT (Valfritt) Ange antalet partitioner som ska användas.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE (Valfritt) Aktivera datapersistence mellan emulatorkörningar.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE (Valfritt) Åsidosätt emulatorns standard-IP-adress.

    För Linux-system använder du:

    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

    För Windows system använder du:

    $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. Gå till https://localhost:8081/_explorer/index.html för att komma åt datautforskaren.

Importera emulatorns TLS/SSL-certifikat

Importera emulatorns TLS/SSL-certifikat för att använda emulatorn med önskad utvecklar-SDK utan att inaktivera TLS/SSL på klienten.

Docker-containervarianten (Linux eller Windows) för emulatorn stöder inte API:et för Apache Cassandra, API för Apache Gremlin eller API för Table.

Certifikatet för emulatorn är tillgängligt på sökvägen _explorer/emulator.pem i containern som körs. Använd curl för att ladda ned certifikatet från containern som körs till den lokala datorn.

  1. Hämta certifikatet från containern som körs.

    För Linux-system använder du:

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

    För Windows system använder du:

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

  2. Återskapa certifikatpaketet med hjälp av lämpligt kommando för operativsystemet.

    För Debianbaserade Linux-system (till exempel Ubuntu) använder du:

    sudo update-ca-certificates

    För Red Hat-baserade Linux-system (till exempel CentOS, Fedora) använder du:

    sudo update-ca-trust

    För Windows system använder du:

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

    Mer detaljerade instruktioner finns i dokumentationen som är specifik för ditt operativsystem.

Certifikatet för emulatorn är tillgängligt på sökvägen /_explorer/emulator.pem i containern som körs.

  1. Ladda ned certifikatet från containern som körs till den lokala datorn.

    För Linux-system använder du:

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

    För Windows system använder du:

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

    Anmärkning

    Du kan behöva ändra värdnamn (eller IP-adress) och portnummer om du redan har ändrat dem.

  2. Installera certifikatet enligt den process som vanligtvis används för operativsystemet. I Linux kopierar du till exempel certifikatet till /usr/local/share/ca-certificates/ sökvägen.

    För Linux-system använder du:

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

    För Windows system använder du:

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

  3. För Linux-system återskapar du certifikatpaketet med hjälp av lämpligt kommando för Din Linux-distribution.

    För Debianbaserade Linux-system (till exempel Ubuntu) använder du:

    sudo update-ca-certificates

    För Red Hat-baserade Linux-system (till exempel CentOS, Fedora) använder du:

    sudo update-ca-trust

    Mer detaljerade instruktioner finns i dokumentationen som är specifik för ditt operativsystem.

Ansluta till emulatorn från SDK

Varje SDK innehåller en klientklass som vanligtvis används för att ansluta SDK:et till ditt Azure Cosmos DB konto. Genom att använda emulatorns autentiseringsuppgifter kan du ansluta SDK:n till emulatorinstansen i stället.

Använd API:et Azure Cosmos DB för NoSQL .NET SDK för att ansluta till emulatorn från ett .NET program.

  1. Starta i en tom mapp.

  2. Skapa ett nytt .NET-konsolprogram

    dotnet new console

  3. Lägg till paketet Microsoft.Azure.Cosmos från NuGet.

    dotnet add package Microsoft.Azure.Cosmos

  4. Öppna filen Program.cs .

  5. Ta bort befintligt innehåll i filen.

  6. Lägg till ett användningsblock för namnområdet Microsoft.Azure.Cosmos.

    using Microsoft.Azure.Cosmos;

  7. Skapa en ny instans av CosmosClient med emulatorns autentiseringsuppgifter.

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

  8. Skapa en ny databas och container med hjälp av CreateDatabaseIfNotExistsAsync och CreateContainerIfNotExistsAsync.

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

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

  9. Skapa ett nytt objekt i containern med .UpsertItemAsync

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

await container.UpsertItemAsync(item);

  10. Kör .NET-programmet.

    dotnet run

    Varning

    Om du får ett SSL-fel kan du behöva inaktivera TLS/SSL för ditt program. Detta inträffar ofta om du utvecklar på den lokala datorn med hjälp av Azure Cosmos DB-emulatorn i en container och inte har importerat containerns SSL-certifikat. Lös problemet genom att konfigurera klientens alternativ för att inaktivera TLS/SSL-validering innan du skapar klienten:

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

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

Tips/Råd

Läs utvecklarguiden .NET för fler åtgärder som du kan utföra med hjälp av .NET SDK.

Använd drivrutinen MongoDB .NET för att ansluta till emulatorn från ett .NET program.

  1. Starta i en tom mapp.

  2. Skapa ett nytt .NET-konsolprogram

    dotnet new console

  3. Lägg till paketet MongoDB.Driver från NuGet.

    dotnet add package MongoDB.Driver

  4. Öppna filen Program.cs .

  5. Ta bort befintligt innehåll i filen.

  6. Lägg till ett användningsblock för namnområdet MongoDB.Driver.

    using MongoDB.Driver;

  7. Skapa en ny instans av MongoClient med emulatorns autentiseringsuppgifter.

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

  8. Hämta databasen och containern med hjälp av GetDatabase och GetCollection<>.

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

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

  9. Skapa ett nytt objekt i XXX med .InsertOneAsync

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

await collection.InsertOneAsync(item);

  10. Kör .NET-programmet.

    dotnet run

Använd drivrutinen Apache Cassandra .NET för att ansluta till emulatorn från ett .NET program.

  1. Starta i en tom mapp.

  2. Skapa ett nytt .NET-konsolprogram

    dotnet new console

  3. Lägg till paketet CassandraCSharpDriver från NuGet.

    dotnet add package CassandraCSharpDriver

  4. Öppna filen Program.cs .

  5. Ta bort befintligt innehåll i filen.

  6. Lägg till ett användningsblock för namnområdet Cassandra.

    using Cassandra;

  7. Skapa en ny instans av Cluster med emulatorns autentiseringsuppgifter. Skapa en ny session med .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. Skapa en ny databas och container med hjälp av PrepareAsync och 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. Skapa ett nytt objekt i tabellen med .ExecuteAsync Använd Bind för att tilldela egenskaper till objektet.

    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. Kör .NET-programmet.

    dotnet run

Important

Innan du börjar kräver API:et för Apache Gremlin att du skapar dina resurser i emulatorn. Skapa en databas med namnet db1 och en container med namnet coll1. Dataflödesinställningarna är irrelevanta för den här guiden och kan anges så lågt som du vill.

Använd drivrutinen Apache Gremlin .NET för att ansluta till emulatorn från ett .NET program.

  1. Starta i en tom mapp.

  2. Skapa ett nytt .NET-konsolprogram

    dotnet new console

  3. Lägg till paketet Gremlin.Net från NuGet.

    dotnet add package Gremlin.Net

  4. Öppna filen Program.cs .

  5. Ta bort befintligt innehåll i filen.

  6. Lägg till ett användningsblock för namnområdet Gremlin.Net.Driver.

    using Gremlin.Net.Driver;

  7. Skapa en ny instans av GremlinServer och GremlinClient med emulatorns autentiseringsuppgifter.

    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. Rensa diagrammet med hjälp av SubmitAsync.

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

  9. Använd SubmitAsync igen om du vill lägga till ett nytt objekt i diagrammet med de angivna parametrarna.

    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. Kör .NET-programmet.

    dotnet run

Använd Azure Tables SDK för .NET för att ansluta till emulatorn från ett .NET program.

  1. Starta i en tom mapp.

  2. Skapa ett nytt .NET-konsolprogram

    dotnet new console

  3. Lägg till paketet Azure.Data.Tables från NuGet.

    dotnet add package Azure.Data.Tables

  4. Öppna filen Program.cs .

  5. Ta bort befintligt innehåll i filen.

  6. Lägg till ett användningsblock för namnområdet Azure.Data.Tables.

    using Azure.Data.Tables;

  7. Skapa en ny instans av TableServiceClient med emulatorns autentiseringsuppgifter.

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

  8. Använd GetTableClient för att skapa en ny instans av TableClient med tabellens namn. Kontrollera sedan att tabellen finns med hjälp av CreateIfNotExistsAsync.

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

await client.CreateIfNotExistsAsync();

  9. Skapa en ny record typ för objekt.

    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. Skapa ett nytt objekt i tabellen med hjälp av UpsertEntityAsync och Replace läget.

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

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

  11. Kör .NET-programmet.

    dotnet run

Använda emulatorn i ett GitHub Actions CI-arbetsflöde

Om du vill köra en kontinuerlig integreringsarbetsbelastning som automatiskt validerar ditt program använder du Azure Cosmos DB-emulatorn med en testsvit från valfri ramverk. Azure Cosmos DB-emulatorn är förinstallerad i windows-latest varianten av GitHub Actions värdbaserade körningar.

Kör en testsvit med den inbyggda testdrivrutinen för .NET och ett testramverk som MSTest, NUnit eller XUnit.

  1. Kontrollera att enhetstestpaketet för ditt program fungerar som förväntat.

    dotnet test

  2. Skapa ett nytt arbetsflöde i din GitHub-lagringsplats i en fil med namnet .github/workflows/ci.yml.

  3. Lägg till ett jobb i arbetsflödet för att starta Azure Cosmos DB-emulatorn med hjälp av PowerShell och kör enhetstestpaketet.

    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

    Anmärkning

    Starta emulatorn från kommandoraden med hjälp av olika argument eller PowerShell-kommandon. Mer information finns i kommandoradsargument för emulatorn.

Nästa steg

Granska emulatorns versionsanteckningar

  • Last updated on