Share via

Helyi fejlesztés az Azure Cosmos DB emulátor használatával

  • Cikk

Az emulátor gyakori használati esete, hogy fejlesztési adatbázisként szolgál az alkalmazások létrehozása során. Az emulátor fejlesztési célokra való használatával megismerheti az olyan adatbázisok adatainak létrehozásának és modellezésének jellemzőit, mint az Azure Cosmos DB, anélkül, hogy szolgáltatási költségekkel járna. Emellett az emulátor automatizálási munkafolyamat részeként való használata biztosítja, hogy ugyanazt az integrációs tesztcsomagot futtathatja. Gondoskodhat arról, hogy ugyanazok a tesztek helyileg és távolról is fussanak egy folyamatos integrációs feladatban.

Előfeltételek

  • .NET 6 vagy újabb, Node.js LTS vagy Python 3.7 vagy újabb
    • Győződjön meg arról, hogy az összes szükséges végrehajtható fájl elérhető a PATHsaját fájljában.
  • Windows emulátor
    • 64 bites Windows Server 2016, 2019, Windows 10 vagy Windows 11.
    • Minimális hardverkövetelmények:
      • 2 GB RAM
      • 10 GB szabad merevlemez-terület
  • Docker emulátor

Az emulátor telepítése

Az emulátor több változata is létezik, és mindegyik változat viszonylag súrlódásmentes telepítési folyamatokkal rendelkezik.

Első lépésként szerezze be a tárolórendszerkép Linux-variánsát a Microsoft Container Registryből (MCR).

  1. Kérje le a mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linux-tárolólemezképet a tárolóregisztrációs adatbázisból a helyi Docker-gazdagépre.

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

  2. Ellenőrizze, hogy az emulátor rendszerképe le lett-e húzva a helyi Docker-gazdagépre.

    docker images

Első lépésként szerezze be a tárolórendszerkép Linux-variánsát a Microsoft Container Registryből (MCR).

  1. Kérje le a mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linux-tárolórendszerképet a mongodb tárolóregisztrációs adatbázis címkéjének használatával a helyi Docker-gazdagépre.

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

  2. Ellenőrizze, hogy az emulátor rendszerképe le lett-e húzva a helyi Docker-gazdagépre.

    docker images

Az emulátor Docker-tárolóvariánsa (Linux vagy Windows) nem támogatja az Apache Cassandra API-t, az Apache Gremlin API-t vagy a Table API-t.

Az emulátor indítása

Miután letöltötte, indítsa el az emulátort a megadott API engedélyezésével.

Az emulátor Docker-tárolóvariánsa nem támogatja az Apache Cassandra API-t.

Az emulátor Docker-tárolóvariánsa nem támogatja az Apache Gremlin API-t.

Az emulátor Docker-tárolóvariánsa nem támogatja a Table API-t.

  1. Futtasson egy új tárolót a tárolórendszerkép és a következő konfiguráció használatával:

    Leírás
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Nem kötelező) Adja meg a használni kívánt partíciók számát.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Nem kötelező) Adatmegőrzés engedélyezése az emulátor futtatásai között.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Nem kötelező) Bírálja felül az emulátor alapértelmezett IP-címét. 
    docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --interactive \
    --tty \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. Lépjen az https://localhost:8081/_explorer/index.html adatkezelő eléréséhez.

  1. Futtasson egy új tárolót a tárolórendszerkép és a következő konfiguráció használatával:

    Leírás
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT Adja meg a használni kívánt MongoDB-végpont verzióját. A támogatott végpontok a következők: 3.2, 3.6vagy 4.0.
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Nem kötelező) Adja meg a használni kívánt partíciók számát.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Nem kötelező) Adatmegőrzés engedélyezése az emulátor futtatásai között.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Nem kötelező) Bírálja felül az emulátor alapértelmezett IP-címét. 
    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. Lépjen az https://localhost:8081/_explorer/index.html adatkezelő eléréséhez.

Az emulátor TLS/SSL-tanúsítványának importálása

Importálja az emulátor TLS/SSL-tanúsítványát, hogy az emulátort az előnyben részesített fejlesztői SDK-val használja anélkül, hogy letiltotta volna a TLS/SSL protokollt az ügyfélen.

Az emulátor Docker-tárolóvariánsa (Linux vagy Windows) nem támogatja az Apache Cassandra API-t, az Apache Gremlin API-t vagy a Table API-t.

Az emulátor tanúsítványa a futó tároló elérési útján _explorer/emulator.pem érhető el. A tanúsítvány a futó tárolóból a helyi gépre való letöltéséhez használható curl .

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

Az emulátor tanúsítványa a futó tároló elérési útján _explorer/emulator.pem érhető el.

  1. A tanúsítvány a futó tárolóból a helyi gépre való letöltéséhez használható curl .

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

    Feljegyzés

    Előfordulhat, hogy módosítania kell a gazdagépet (vagy IP-címet) és a portszámot, ha korábban módosította ezeket az értékeket.

  2. Telepítse a tanúsítványt az operációs rendszerhez általában használt folyamatnak megfelelően. Linuxon például a tanúsítványt az /usr/local/share/ca-certificates/ elérési útra másolná.

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

  3. Frissítse a hitelesítésszolgáltatói tanúsítványokat, és hozza létre újra a tanúsítványcsomagot a Linux-disztribúció megfelelő parancsával.

    Debian-alapú rendszerekhez (pl. Ubuntu) használja a következőt:

    sudo update-ca-certificates

    Red Hat-alapú rendszerekhez (pl. CentOS, Fedora) használja a következőket:

    sudo update-ca-trust

    Részletesebb útmutatásért tekintse meg a Linux-disztribúcióra vonatkozó dokumentációt.

Csatlakozás az emulátorhoz az SDK-ból

Minden SDK tartalmaz egy ügyfélosztályt, amely általában az SDK-t az Azure Cosmos DB-fiókhoz csatlakoztatja. Az emulátor hitelesítő adataival az SDK-t csatlakoztathatja az emulátorpéldányhoz.

Az Azure Cosmos DB API for NoSQL .NET SDK használatával csatlakozzon az emulátorhoz egy .NET-alkalmazásból.

  1. Kezdje egy üres mappában.

  2. Új .NET-konzolalkalmazás létrehozása

    dotnet new console

  3. Adja hozzá a csomagot a Microsoft.Azure.Cosmos NuGetből.

    dotnet add package Microsoft.Azure.Cosmos

  4. Nyissa meg a Program.cs fájlt.

  5. Törölje a fájlban lévő összes meglévő tartalmat.

  6. Adjon hozzá egy használatblokkot a Microsoft.Azure.Cosmos névtérhez.

    using Microsoft.Azure.Cosmos;

  7. Hozzon létre egy új példányt CosmosClient az emulátor hitelesítő adatainak használatával.

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

  8. Hozzon létre egy új adatbázist és tárolót az CreateDatabaseIfNotExistsAsync and CreateContainerIfNotExistsAsync.

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

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

  9. Hozzon létre egy új elemet a tárolóban a következő használatával UpsertItemAsync: .

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

await container.UpsertItemAsync(item);

  10. Futtassa a .NET-alkalmazást.

    dotnet run

    Figyelmeztetés

    Ssl-hiba esetén előfordulhat, hogy le kell tiltania a TLS/SSL protokollt az alkalmazáshoz. Ez általában akkor fordul elő, ha a helyi gépen fejleszt, az Azure Cosmos DB emulátort használja egy tárolóban, és nem importálta a tároló SSL-tanúsítványát. A probléma megoldásához konfigurálja az ügyfél beállításait a TLS/SSL-érvényesítés letiltására az ügyfél létrehozása előtt:

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

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

Tipp.

A .NET SDK használatával elvégezhető további műveletekért tekintse meg a .NET fejlesztői útmutatóját.

A MongoDB .NET-illesztővel csatlakozhat az emulátorhoz egy .NET-alkalmazásból.

  1. Kezdje egy üres mappában.

  2. Új .NET-konzolalkalmazás létrehozása

    dotnet new console

  3. Adja hozzá a csomagot a MongoDB.Driver NuGetből.

    dotnet add package MongoDB.Driver

  4. Nyissa meg a Program.cs fájlt.

  5. Törölje a fájlban lévő összes meglévő tartalmat.

  6. Adjon hozzá egy használatblokkot a MongoDB.Driver névtérhez.

    using MongoDB.Driver;

  7. Hozzon létre egy új példányt MongoClient az emulátor hitelesítő adatainak használatával.

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

  8. Kérje le az adatbázist és a tárolót az GetDatabase and GetCollection<>.

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

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

  9. Hozzon létre egy új elemet a XXX-ben a következő használatával InsertOneAsync: .

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

await collection.InsertOneAsync(item);

  10. Futtassa a .NET-alkalmazást.

    dotnet run

Az Apache Cassandra .NET-illesztővel csatlakozhat az emulátorhoz egy .NET-alkalmazásból.

  1. Kezdje egy üres mappában.

  2. Új .NET-konzolalkalmazás létrehozása

    dotnet new console

  3. Adja hozzá a csomagot a CassandraCSharpDriver NuGetből.

    dotnet add package CassandraCSharpDriver

  4. Nyissa meg a Program.cs fájlt.

  5. Törölje a fájlban lévő összes meglévő tartalmat.

  6. Adjon hozzá egy használatblokkot a Cassandra névtérhez.

    using Cassandra;

  7. Hozzon létre egy új példányt Cluster az emulátor hitelesítő adatainak használatával. Hozzon létre egy új munkamenetet a következő használatával 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. Hozzon létre egy új adatbázist és tárolót az PrepareAsync and 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. Hozzon létre egy új elemet a táblában a következővel ExecuteAsync: . Tulajdonságok Bind hozzárendelése az elemhez.

    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. Futtassa a .NET-alkalmazást.

    dotnet run

Fontos

A kezdés előtt az Apache Gremlin API-hoz létre kell hoznia az erőforrásokat az emulátorban. Hozzon létre egy elnevezett db1 adatbázist és egy tárolót.coll1 Az átviteli sebesség beállításai nem relevánsak ebben az útmutatóban, és tetszés szerint beállíthatók.

Az Apache Gremlin .NET-illesztővel csatlakozhat az emulátorhoz egy .NET-alkalmazásból.

  1. Kezdje egy üres mappában.

  2. Új .NET-konzolalkalmazás létrehozása

    dotnet new console

  3. Adja hozzá a csomagot a Gremlin.Net NuGetből.

    dotnet add package Gremlin.Net

  4. Nyissa meg a Program.cs fájlt.

  5. Törölje a fájlban lévő összes meglévő tartalmat.

  6. Adjon hozzá egy használatblokkot a Gremlin.Net.Driver névtérhez.

    using Gremlin.Net.Driver;

  7. Hozzon létre egy új példányt GremlinServer , és GremlinClient használja az emulátor hitelesítő adatait.

    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. A gráf törlése a következővel SubmitAsync: .

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

  9. Új SubmitAsync elem hozzáadása a gráfhoz a megadott paraméterekkel.

    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. Futtassa a .NET-alkalmazást.

    dotnet run

A .NET-hez készült Azure Tables SDK-val csatlakozhat az emulátorhoz egy .NET-alkalmazásból.

  1. Kezdje egy üres mappában.

  2. Új .NET-konzolalkalmazás létrehozása

    dotnet new console

  3. Adja hozzá a csomagot a Azure.Data.Tables NuGetből.

    dotnet add package Azure.Data.Tables

  4. Nyissa meg a Program.cs fájlt.

  5. Törölje a fájlban lévő összes meglévő tartalmat.

  6. Adjon hozzá egy használatblokkot a Azure.Data.Tables névtérhez.

    using Azure.Data.Tables;

  7. Hozzon létre egy új példányt TableServiceClient az emulátor hitelesítő adatainak használatával.

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

  8. A tábla nevével rendelkező új példány TableClient létrehozásához használhatóGetTableClient. Ezután győződjön meg arról, hogy a tábla létezik a következő használatával CreateIfNotExistsAsync: .

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

await client.CreateIfNotExistsAsync();

  9. Hozzon létre egy új record típust az elemekhez.

    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. Hozzon létre egy új elemet a táblában a használatával UpsertEntityAsync és a Replace móddal.

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

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

  11. Futtassa a .NET-alkalmazást.

    dotnet run

Az emulátor használata GitHub Actions CI-munkafolyamatban

Az Azure Cosmos DB emulátor egy választott keretrendszerből származó tesztcsomaggal futtathat egy folyamatos integrációs számítási feladatot, amely automatikusan ellenőrzi az alkalmazást. Az Azure Cosmos DB emulátor előre telepítve van a windows-latest GitHub Action üzemeltetett futóinak változatában.

Futtasson egy tesztcsomagot a .NET-hez készült beépített tesztillesztővel és egy olyan tesztelési keretrendszerrel, mint az MSTest, az NUnit vagy az XUnit.

  1. Ellenőrizze, hogy az alkalmazás egységtesztelési csomagja a várt módon működik-e.

    dotnet test

  2. Hozzon létre egy új munkafolyamatot a GitHub-adattárban egy nevű .github/workflows/ci.ymlfájlban.

  3. Adjon hozzá egy feladatot a munkafolyamathoz, hogy elindítsa az Azure Cosmos DB emulátort a PowerShell használatával, és futtassa az egységtesztelési csomagot.

    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

    Feljegyzés

    Indítsa el az emulátort a parancssorból különböző argumentumokkal vagy PowerShell-parancsokkal. További információ: Emulator parancssori argumentumok.

Következő lépés

Tekintse át az emulátor kibocsátási megjegyzéseit