Share via

Sviluppare in locale usando l'emulatore di Azure Cosmos DB

  • Articolo

Un caso d'uso comune per l'emulatore consiste nel fungere da database di sviluppo durante la compilazione delle applicazioni. L'uso dell'emulatore per lo sviluppo consente di apprendere le caratteristiche della creazione e della modellazione dei dati per un database come Azure Cosmos DB senza incorrere in costi di servizio. Inoltre, l'uso dell'emulatore come parte di un flusso di lavoro di automazione può garantire che sia possibile eseguire la stessa suite di test di integrazione. È possibile assicurarsi che gli stessi test vengano eseguiti in locale nel computer di sviluppo e in remoto in un processo di integrazione continua.

Prerequisiti

Installare l'emulatore

Esistono più varianti dell'emulatore e ogni variante ha un processo di installazione relativamente senza attriti.

Per iniziare, ottenere la variante Linux dell'immagine del contenitore dal Registro Contenitori Microsoft (MCR).To get started, get the Linux-variant of the container image from the Microsoft Container Registry (MCR).

  1. Eseguire il pull dell'immagine mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator del contenitore Linux dal registro contenitori all'host Docker locale.

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

  2. Verificare che l'immagine dell'emulatore sia stata estratta nell'host Docker locale.

    docker images

Per iniziare, ottenere la variante Linux dell'immagine del contenitore dal Registro Contenitori Microsoft (MCR).To get started, get the Linux-variant of the container image from the Microsoft Container Registry (MCR).

  1. Eseguire il pull dell'immagine mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator del contenitore Linux usando il mongodb tag dal registro contenitori all'host Docker locale.

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

  2. Verificare che l'immagine dell'emulatore sia stata estratta nell'host Docker locale.

    docker images

La variante del contenitore Docker (Linux o Windows) dell'emulatore non supporta l'API per Apache Cassandra, l'API per Apache Gremlin o l'API per Table.

Avviare l'emulatore

Dopo il download, avviare l'emulatore con l'API specificata abilitata.

La variante del contenitore Docker dell'emulatore non supporta l'API per Apache Cassandra.

La variante del contenitore Docker dell'emulatore non supporta l'API per Apache Gremlin.

La variante del contenitore Docker dell'emulatore non supporta l'API per Table.

  1. Eseguire un nuovo contenitore usando l'immagine del contenitore e la configurazione seguente:

    Descrizione
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(opzionale) Specificare il numero di partizioni da usare.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(opzionale) Abilitare la persistenza dei dati tra le esecuzioni dell'emulatore.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(opzionale) Eseguire l'override dell'indirizzo IP predefinito dell'emulatore. 
    docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --interactive \
    --tty \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. Passare a per accedere a https://localhost:8081/_explorer/index.html Esplora dati.

  1. Eseguire un nuovo contenitore usando l'immagine del contenitore e la configurazione seguente:

    Descrizione
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT Specificare la versione dell'endpoint MongoDB da usare. Gli endpoint supportati includono: 3.2, 3.6o 4.0.
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(opzionale) Specificare il numero di partizioni da usare.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(opzionale) Abilitare la persistenza dei dati tra le esecuzioni dell'emulatore.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(opzionale) Eseguire l'override dell'indirizzo IP predefinito dell'emulatore. 
    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. Passare a per accedere a https://localhost:8081/_explorer/index.html Esplora dati.

Importare il certificato TLS/SSL dell'emulatore

Importare il certificato TLS/SSL dell'emulatore per usare l'emulatore con l'SDK per sviluppatori preferito senza disabilitare TLS/SSL nel client.

La variante del contenitore Docker (Linux o Windows) dell'emulatore non supporta l'API per Apache Cassandra, l'API per Apache Gremlin o l'API per Table.

Il certificato per l'emulatore è disponibile nel percorso _explorer/emulator.pem del contenitore in esecuzione. Usare curl per scaricare il certificato dal contenitore in esecuzione nel computer locale.

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

Il certificato per l'emulatore è disponibile nel percorso _explorer/emulator.pem del contenitore in esecuzione.

  1. Usare curl per scaricare il certificato dal contenitore in esecuzione nel computer locale.

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

    Nota

    Potrebbe essere necessario modificare l'host (o l'indirizzo IP) e il numero di porta se tali valori sono stati modificati in precedenza.

  2. Installare il certificato in base al processo usato in genere per il sistema operativo. Ad esempio, in Linux si copia il certificato nel /usr/local/share/ca-certificates/ percorso.

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

  3. Aggiornare i certificati CA e rigenerare il bundle di certificati usando il comando appropriato per la distribuzione linux.

    Per i sistemi basati su Debian (ad esempio, Ubuntu), usare:

    sudo update-ca-certificates

    Per i sistemi basati su Red Hat (ad esempio, CentOS, Fedora), usare:

    sudo update-ca-trust

    Per istruzioni più dettagliate, vedere la documentazione specifica per la distribuzione di Linux.

Connessione all'emulatore dall'SDK

Ogni SDK include in genere una classe client usata per connettere l'SDK all'account Azure Cosmos DB. Usando le credenziali dell'emulatore, è possibile connettere l'SDK all'istanza dell'emulatore.

Usare l'API di Azure Cosmos DB per NoSQL .NET SDK per connettersi all'emulatore da un'applicazione .NET.

  1. Iniziare in una cartella vuota.

  2. Creare una nuova applicazione console .NET

    dotnet new console

  3. Aggiungere il Microsoft.Azure.Cosmos pacchetto da NuGet.

    dotnet add package Microsoft.Azure.Cosmos

  4. Aprire il file Program.cs.

  5. Eliminare qualsiasi contenuto esistente all'interno del file.

  6. Aggiungere un blocco using per lo spazio dei Microsoft.Azure.Cosmos nomi.

    using Microsoft.Azure.Cosmos;

  7. Creare una nuova istanza di CosmosClient usando le credenziali dell'emulatore.

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

  8. Creare un nuovo database e un nuovo contenitore usando CreateDatabaseIfNotExistsAsync e CreateContainerIfNotExistsAsync.

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

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

  9. Creare un nuovo elemento nel contenitore usando UpsertItemAsync.

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

await container.UpsertItemAsync(item);

  10. Eseguire l'applicazione .NET.

    dotnet run

    Avviso

    Se viene visualizzato un errore SSL, potrebbe essere necessario disabilitare TLS/SSL per l'applicazione. Ciò si verifica in genere se si sviluppa nel computer locale, usando l'emulatore di Azure Cosmos DB in un contenitore e non è stato importato il certificato SSL del contenitore. Per risolvere questo problema, configurare le opzioni del client per disabilitare la convalida TLS/SSL prima di creare il client:

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

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

Suggerimento

Per altre operazioni che è possibile eseguire con .NET SDK, vedere la Guida per sviluppatori .NET.

Usare il driver .NET mongoDB per connettersi all'emulatore da un'applicazione .NET.

  1. Iniziare in una cartella vuota.

  2. Creare una nuova applicazione console .NET

    dotnet new console

  3. Aggiungere il MongoDB.Driver pacchetto da NuGet.

    dotnet add package MongoDB.Driver

  4. Aprire il file Program.cs.

  5. Eliminare qualsiasi contenuto esistente all'interno del file.

  6. Aggiungere un blocco using per lo spazio dei MongoDB.Driver nomi.

    using MongoDB.Driver;

  7. Creare una nuova istanza di MongoClient usando le credenziali dell'emulatore.

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

  8. Ottenere il database e il contenitore usando GetDatabase e GetCollection<>.

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

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

  9. Creare un nuovo elemento in XXX usando InsertOneAsync.

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

await collection.InsertOneAsync(item);

  10. Eseguire l'applicazione .NET.

    dotnet run

Usare il driver Apache Cassandra .NET per connettersi all'emulatore da un'applicazione .NET.

  1. Iniziare in una cartella vuota.

  2. Creare una nuova applicazione console .NET

    dotnet new console

  3. Aggiungere il CassandraCSharpDriver pacchetto da NuGet.

    dotnet add package CassandraCSharpDriver

  4. Aprire il file Program.cs.

  5. Eliminare qualsiasi contenuto esistente all'interno del file.

  6. Aggiungere un blocco using per lo spazio dei Cassandra nomi.

    using Cassandra;

  7. Creare una nuova istanza di Cluster usando le credenziali dell'emulatore. Creare una nuova sessione usando 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. Creare un nuovo database e un nuovo contenitore usando PrepareAsync e 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. Creare un nuovo elemento nella tabella usando ExecuteAsync. Utilizzare Bind per assegnare proprietà all'elemento.

    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. Eseguire l'applicazione .NET.

    dotnet run

Importante

Prima di iniziare, l'API per Apache Gremlin richiede di creare le risorse nell'emulatore. Creare un database denominato db1 e un contenitore denominato coll1. Le impostazioni di velocità effettiva sono irrilevanti per questa guida e possono essere impostate come minimo.

Usare il driver Apache Gremlin .NET per connettersi all'emulatore da un'applicazione .NET.

  1. Iniziare in una cartella vuota.

  2. Creare una nuova applicazione console .NET

    dotnet new console

  3. Aggiungere il Gremlin.Net pacchetto da NuGet.

    dotnet add package Gremlin.Net

  4. Aprire il file Program.cs.

  5. Eliminare qualsiasi contenuto esistente all'interno del file.

  6. Aggiungere un blocco using per lo spazio dei Gremlin.Net.Driver nomi.

    using Gremlin.Net.Driver;

  7. Creare una nuova istanza di GremlinServer e GremlinClient usare le credenziali dell'emulatore.

    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. Pulire il grafico usando SubmitAsync.

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

  9. Usare SubmitAsync di nuovo per aggiungere un nuovo elemento al grafico con i parametri specificati.

    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. Eseguire l'applicazione .NET.

    dotnet run

Usare Azure Tables SDK per .NET per connettersi all'emulatore da un'applicazione .NET.

  1. Iniziare in una cartella vuota.

  2. Creare una nuova applicazione console .NET

    dotnet new console

  3. Aggiungere il Azure.Data.Tables pacchetto da NuGet.

    dotnet add package Azure.Data.Tables

  4. Aprire il file Program.cs.

  5. Eliminare qualsiasi contenuto esistente all'interno del file.

  6. Aggiungere un blocco using per lo spazio dei Azure.Data.Tables nomi.

    using Azure.Data.Tables;

  7. Creare una nuova istanza di TableServiceClient usando le credenziali dell'emulatore.

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

  8. Utilizzare GetTableClient per creare una nuova istanza di TableClient con il nome della tabella. Verificare quindi che la tabella esista usando CreateIfNotExistsAsync.

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

await client.CreateIfNotExistsAsync();

  9. Creare un nuovo record tipo per gli elementi.

    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. Creare un nuovo elemento nella tabella usando UpsertEntityAsync e la Replace modalità .

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

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

  11. Eseguire l'applicazione .NET.

    dotnet run

Usare l'emulatore in un flusso di lavoro ci di GitHub Actions

Usare l'emulatore di Azure Cosmos DB con un gruppo di test dal framework scelto per eseguire un carico di lavoro di integrazione continua che convalida automaticamente l'applicazione. L'emulatore di Azure Cosmos DB è preinstallato nella windows-latest variante degli strumenti di esecuzione ospitati di GitHub Action.

Eseguire un gruppo di test usando il driver di test predefinito per .NET e un framework di test come MSTest, NUnit o XUnit.

  1. Verificare che il gruppo di unit test per l'applicazione funzioni come previsto.

    dotnet test

  2. Creare un nuovo flusso di lavoro nel repository GitHub in un file denominato .github/workflows/ci.yml.

  3. Aggiungere un processo al flusso di lavoro per avviare l'emulatore di Azure Cosmos DB usando PowerShell ed eseguire il gruppo di unit test.

    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

    Nota

    Avviare l'emulatore dalla riga di comando usando vari argomenti o comandi di PowerShell. Per altre informazioni, vedere Argomenti della riga di comando dell'emulatore.

Passaggio successivo

Esaminare le note sulla versione dell'emulatore