共用方式為

使用 Azure Cosmos DB 模擬器在本機開發

  • 發行項

模擬器的常見使用案例是在建置應用程式時做為開發資料庫。 使用模擬器進行開發，可協助您瞭解為 Azure Cosmos DB 等資料庫建立和模型化資料的特性，而不會產生任何服務成本。 此外，使用模擬器作為自動化工作流程的一部分，可確保您可以執行相同的整合測試套件。 您可以確定相同的測試會在開發機器上本機執行，也會在持續整合作業中從遠端執行。

必要條件

安裝模擬器

模擬器有多個變化，而且每個變化都有安裝程式，彼此之間沒有衝突。

若要開始使用，請從 Microsoft Container Registry (MCR) 取得容器映像的 Linux 變體。

  1. 將 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linux 容器映像從容器登錄提取到本機 Docker 主機。

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

  2. 檢查以確定模擬器映像在您的本機 Docker 主機可用。

    docker images

若要開始使用，請從 Microsoft Container Registry (MCR) 取得容器映像的 Linux 變體。

  1. 使用 mongodb 標籤，將 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linux 容器映像從容器登錄提取到本機 Docker 主機。

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

  2. 檢查以確定模擬器映像在您的本機 Docker 主機可用。

    docker images

模擬器的 Docker 容器變體 (Linux 或 Windows) 不支援 API for Apache Cassandra、API for Apache Gremlin 以及 API for Table。

啟動模擬器

下載之後，啟動已啟用指定 API 的模擬器。

模擬器的 Docker 容器變體不支援 API for Apache Cassandra。

模擬器的 Docker 容器變體不支援 API for Apache Gremlin。

模擬器的 Docker 容器變體不支援 API for Table。

  1. 使用容器映像和下列組態執行新的容器：

    描述
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(選擇性) 指定要使用的分割區數目。
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(選擇性) 啟用模擬器執行之間的資料持續性。
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(選擇性) 覆寫模擬器的預設 IP 位址。

    針對 Linux 系統，請使用：

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

    針對 Windows 系統，請使用：

    $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. 瀏覽至 https://localhost:8081/_explorer/index.html 以存取資料總管。

  1. 使用容器映像和下列組態執行新的容器：

    描述
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT 指定要使用的 MongoDB 端點版本。 支援的端點包括 3.2、3.6 和 4.0。
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(選擇性) 指定要使用的分割區數目。
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(選擇性) 啟用模擬器執行之間的資料持續性。
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(選擇性) 覆寫模擬器的預設 IP 位址。

    針對 Linux 系統，請使用：

    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

    針對 Windows 系統，請使用：

    $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. 瀏覽至 https://localhost:8081/_explorer/index.html 以存取資料總管。

匯入模擬器的 TLS/SSL 憑證

匯入模擬器的 TLS/SSL 憑證，以搭配您慣用的開發人員 SDK 使用模擬器，而不需要在用戶端上停用 TLS/SSL。

模擬器的 Docker 容器變體 (Linux 或 Windows) 不支援 API for Apache Cassandra、API for Apache Gremlin 以及 API for Table。

模擬器的憑證位於執行中容器的 _explorer/emulator.pem 路徑中。 使用 curl 將憑證從執行中的容器下載到本機電腦。

  1. 從執行中的容器取得憑證。

    針對 Linux 系統，請使用：

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

    針對 Windows 系統，請使用：

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

  2. 使用作業系統的適當命令重新產生憑證套件組合。

    針對 Debian 型 Linux 系統 (例如 Ubuntu)，請使用：

    sudo update-ca-certificates

    針對 Red Hat 型 Linux 系統 (例如 CentOS、Fedora)，請使用：

    sudo update-ca-trust

    針對 Windows 系統，請使用：

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

    如需更詳細的指示，請參閱屬於您作業系統的文件。

模擬器的憑證位於執行中容器的 /_explorer/emulator.pem 路徑中。

  1. 將憑證從執行中的容器下載到本機電腦。

    針對 Linux 系統，請使用：

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

    針對 Windows 系統，請使用：

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

    注意

    如果您先前修改過這些值，您可能需要變更主機 (或 IP 位址) 和埠號碼。

  2. 根據通常用於操作系統的程式安裝憑證。 例如，在 Linux 中，您需要將憑證複製到 /usr/local/share/ca-certificates/ 路徑。

    針對 Linux 系統，請使用：

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

    針對 Windows 系統，請使用：

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

  3. 針對 Linux 系統，使用 Linux 通訊的適當命令重新產生憑證套件組合。

    針對 Debian 型 Linux 系統 (例如 Ubuntu)，請使用：

    sudo update-ca-certificates

    針對 Red Hat 型 Linux 系統 (例如 CentOS、Fedora)，請使用：

    sudo update-ca-trust

    如需更詳細的指示，請參閱屬於您作業系統的文件。

從 SDK 連線到模擬器

每個 SDK 都包含一個用戶端類別，通常用來將 SDK 連線到您的 Azure Cosmos DB 帳戶。 透過使用模擬器的認證，您可以改為將 SDK 連線到模擬器執行個體。

使用 Azure Cosmos DB API for NoSQL .NET SDK 從 .NET 應用程式連線到模擬器。

  1. 從空白資料夾中開始。

  2. 建立新的 .NET 主控台應用程式

    dotnet new console

  3. 從 NuGet 新增 Microsoft.Azure.Cosmos 套件。

    dotnet add package Microsoft.Azure.Cosmos

  4. 開啟 Program.cs 檔案。

  5. 刪除檔案內的任何現有內容。

  6. 為 Microsoft.Azure.Cosmos 命名空間新增 using 區塊。

    using Microsoft.Azure.Cosmos;

  7. 使用模擬器的認證建立 CosmosClient 的新執行個體。

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

  8. 使用 CreateDatabaseIfNotExistsAsync 和 CreateContainerIfNotExistsAsync 建立新的資料庫和容器。

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

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

  9. 使用 UpsertItemAsync 在容器中建立新項目。

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

await container.UpsertItemAsync(item);

  10. 執行 .NET 應用程式。

    dotnet run

    警告

    如果您收到 SSL 錯誤，您可能需要停用應用程式的 TLS/SSL。 如果您在本機電腦上開發、在容器中使用 Azure Cosmos DB 模擬器，而且尚未匯入容器的 SSL 憑證，通常會發生這種情況。 若要解決此問題，請在建立用戶端之前，先將用戶端的選項設定為停用 TLS/SSL 驗證：

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

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

提示

如需瞭解您可以使用 .NET SDK 執行哪些其他作業，請參閱 .NET 開發人員指南。

使用 MongoDB .NET 驅動程式從 .NET 應用程式連線到模擬器。

  1. 從空白資料夾中開始。

  2. 建立新的 .NET 主控台應用程式

    dotnet new console

  3. 從 NuGet 新增 MongoDB.Driver 套件。

    dotnet add package MongoDB.Driver

  4. 開啟 Program.cs 檔案。

  5. 刪除檔案內的任何現有內容。

  6. 為 MongoDB.Driver 命名空間新增 using 區塊。

    using MongoDB.Driver;

  7. 使用模擬器的認證建立 MongoClient 的新執行個體。

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

  8. 使用 GetDatabase 和 GetCollection<> 取得資料庫和容器。

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

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

  9. 使用 InsertOneAsync 在 XXX 中建立新項目。

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

await collection.InsertOneAsync(item);

  10. 執行 .NET 應用程式。

    dotnet run

使用 Apache Cassandra .NET 驅動程式從 .NET 應用程式連線到模擬器。

  1. 從空白資料夾中開始。

  2. 建立新的 .NET 主控台應用程式

    dotnet new console

  3. 從 NuGet 新增 CassandraCSharpDriver 套件。

    dotnet add package CassandraCSharpDriver

  4. 開啟 Program.cs 檔案。

  5. 刪除檔案內的任何現有內容。

  6. 為 Cassandra 命名空間新增 using 區塊。

    using Cassandra;

  7. 使用模擬器的認證建立 Cluster 的新執行個體。 使用 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. 使用 PrepareAsync 和 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. 使用 ExecuteAsync 在資料表中建立新項目。 使用 Bind 將屬性指派給項目。

    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. 執行 .NET 應用程式。

    dotnet run

重要

開始之前，API for Apache Gremlin 會要求您在模擬器中建立資源。 建立名為 db1 的資料庫，以及名為 coll1 的容器。 本指南的輸送量設定無關緊要，可以視需要設定任意大小的值。

使用 Apache Gremlin .NET 驅動程式從 .NET 應用程式連線到模擬器。

  1. 從空白資料夾中開始。

  2. 建立新的 .NET 主控台應用程式

    dotnet new console

  3. 從 NuGet 新增 Gremlin.Net 套件。

    dotnet add package Gremlin.Net

  4. 開啟 Program.cs 檔案。

  5. 刪除檔案內的任何現有內容。

  6. 為 Gremlin.Net.Driver 命名空間新增 using 區塊。

    using Gremlin.Net.Driver;

  7. 使用模擬器的認證建立 GremlinServer 和 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. 使用 SubmitAsync 清除圖表。

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

  9. 再次使用 SubmitAsync 將新項目新增至具有指定參數的圖表中。

    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. 執行 .NET 應用程式。

    dotnet run

使用 Azure Tables SDK for .NET 從 .NET 應用程式連線到模擬器。

  1. 從空白資料夾中開始。

  2. 建立新的 .NET 主控台應用程式

    dotnet new console

  3. 從 NuGet 新增 Azure.Data.Tables 套件。

    dotnet add package Azure.Data.Tables

  4. 開啟 Program.cs 檔案。

  5. 刪除檔案內的任何現有內容。

  6. 為 Azure.Data.Tables 命名空間新增 using 區塊。

    using Azure.Data.Tables;

  7. 使用模擬器的認證建立 TableServiceClient 的新執行個體。

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

  8. 使用 GetTableClient 新建一個具有資料表名稱之 TableClient 的執行個體。 然後使用 CreateIfNotExistsAsync 確定資料表存在。

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

await client.CreateIfNotExistsAsync();

  9. 為項目建立新的 record 類型。

    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. 使用 UpsertEntityAsync 和 Replace 模式，在資料表中建立新項目。

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

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

  11. 執行 .NET 應用程式。

    dotnet run

在 GitHub Actions CI 工作流程中使用模擬器

若要執行可自動驗證應用程式的持續整合工作負載，請使用 Azure Cosmos DB 模擬器搭配所選架構中的測試套件。 GitHub Action 裝載的執行器 windows-latest 變體中已經預安裝了 Azure Cosmos DB 模擬器。

使用適用於 .NET 的內建測試驅動程式和測試架構 (例如 MSTest、NUnit 或 XUnit) 來執行測試套件。

  1. 驗證應用程式的單元測試套件是否如預期般運作。

    dotnet test

  2. 在名為 .github/workflows/ci.yml 的檔案中，於 GitHub 存放庫中建立新的工作流程。

  3. 將作業新增至您的工作流程，以使用 PowerShell 啟動 Azure Cosmos DB 模擬器，並執行單元測試套件。

    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

    注意

    使用各種引數或 PowerShell 命令，從命令列中啟動模擬器。 如需詳細資訊，請參閱模擬器命令列引數。

後續步驟

檢閱模擬器的版本資訊