Utveckla lokalt med Azure Cosmos DB-emulatorn

  • Artikel

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.

Förutsättningar

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. Hämta 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 att emulatorbilden har hämtats till 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 hjälp av taggen mongodb från containerregistret till den lokala Docker-värden.

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

  2. Kontrollera att emulatorbilden har hämtats till 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:

    beskrivning
    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. 
    docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --interactive \
    --tty \
    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:

    beskrivning
    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. 
    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. 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.

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

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

  1. Använd curl för att ladda ned certifikatet från containern som körs till den lokala datorn.

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

    Kommentar

    Du kan behöva ändra värden (eller IP-adressen) och portnumret om du tidigare har ändrat dessa värden.

  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.

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

  3. Uppdatera CA-certifikat och återskapa certifikatpaketet med hjälp av lämpligt kommando för Din Linux-distribution.

    För Debianbaserade system (t.ex. Ubuntu) använder du:

    sudo update-ca-certificates

    För Red Hat-baserade system (t.ex. CentOS, Fedora) använder du:

    sudo update-ca-trust

    Mer detaljerade instruktioner finns i dokumentationen som är specifik för din Linux-distribution.

Anslut till emulatorn från SDK:n

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 Azure Cosmos DB API 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. Microsoft.Azure.Cosmos Lägg till paketet 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 Microsoft.Azure.Cosmos namnområdet.

    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å din lokala dator 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
);

Dricks

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

Använd MongoDB .NET-drivrutinen 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. MongoDB.Driver Lägg till paketet 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 MongoDB.Driver namnområdet.

    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 Apache Cassandra .NET-drivrutinen 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. CassandraCSharpDriver Lägg till paketet 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 Cassandra namnområdet.

    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

Viktigt!

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 Apache Gremlin .NET-drivrutinen 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. Gremlin.Net Lägg till paketet 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 Gremlin.Net.Driver namnområdet.

    using Gremlin.Net.Driver;

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

    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. 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. Azure.Data.Tables Lägg till paketet 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 Azure.Data.Tables namnområdet.

    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

Använd Azure Cosmos DB-emulatorn med en testsvit från ditt ramverk för att köra en kontinuerlig integreringsarbetsbelastning som automatiskt validerar ditt program. Azure Cosmos DB-emulatorn är förinstallerad i varianten windows-latest av GitHub Actions värdbaserade löpare.

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 på 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öra 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

    Kommentar

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

Gå vidare

Granska emulatorns viktig information