Condividi tramite

Sviluppare in locale con l'emulatore di Azure Cosmos DB

  • Articolo

Un caso d'uso comune per l'emulatore è 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 sia in locale nel computer di sviluppo, sia in remoto in un processo di integrazione continua.

Prerequisiti

Installare l'emulatore

Esistono più varianti dell'emulatore, ognuna delle quali ha un processo di installazione relativamente fluido.

Per iniziare, ottenere la variante Linux dell'immagine del contenitore dal Registro Container Microsoft (MCR).

  1. Eseguire il pull dell'immagine del contenitore Linux mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator 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 disponibile nell'host Docker locale.

    docker images

Per iniziare, ottenere la variante Linux dell'immagine del contenitore dal Registro Container Microsoft (MCR).

  1. Eseguire il pull dell'immagine del contenitore Linux mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator usando il tag mongodb 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 disponibile 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.

    Per i sistemi Linux, usare:

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

    Per i sistemi Windows, usare:

    $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. Passare a https://localhost:8081/_explorer/index.html per accedere a 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.6 o 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.

    Per i sistemi Linux, usare:

    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

    Per i sistemi Windows, usare:

    $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. Passare a https://localhost:8081/_explorer/index.html per accedere a Esplora dati.

Importare il certificato TLS/SSL dell'emulatore

Importare il certificato TLS/SSL dell'emulatore per usare l'emulatore con il proprio 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.

  1. Ottenere il certificato dal contenitore in esecuzione.

    Per i sistemi Linux, usare:

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

    Per i sistemi Windows, usare:

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

  2. Rigenerare il bundle del certificato usando il comando appropriato per il sistema operativo in uso.

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

    sudo update-ca-certificates

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

    sudo update-ca-trust

    Per i sistemi Windows, usare:

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

    Per istruzioni più dettagliate, consultare la documentazione specifica per il sistema operativo in uso.

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

  1. Scaricare il certificato dal contenitore in esecuzione nel computer locale.

    Per i sistemi Linux, usare:

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

    Per i sistemi Windows, usare:

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

    Nota

    Può 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 percorso /usr/local/share/ca-certificates/.

    Per i sistemi Linux, usare:

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

    Per i sistemi Windows, usare:

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

  3. Per i sistemi Linux, rigenerare il bundle del certificato usando il comando appropriato per la distribuzione Linux in uso.

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

    sudo update-ca-certificates

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

    sudo update-ca-trust

    Per istruzioni più dettagliate, consultare la documentazione specifica per il sistema operativo in uso.

Connettersi 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, è invece possibile connettere l'SDK all'istanza dell'emulatore.

Usare l'SDK .NET dell'API di Azure Cosmos DB for NoSQL 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 pacchetto Microsoft.Azure.Cosmos 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 nomi Microsoft.Azure.Cosmos.

    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, può essere necessario disabilitare TLS/SSL per l'applicazione. Questo problema 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 il 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 l'SDK .NET, vedere la guida per sviluppatori .NET.

Usare il driver .NET di MongoDB per eseguire la connessione 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 pacchetto MongoDB.Driver 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 nomi MongoDB.Driver.

    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 .NET di Apache Cassandra per eseguire la connessione 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 pacchetto CassandraCSharpDriver 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 nomi Cassandra.

    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. Usare 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 si preferisce.

Usare il driver .NET di Apache Gremlin per eseguire la connessione 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 pacchetto Gremlin.Net 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 nomi Gremlin.Net.Driver.

    using Gremlin.Net.Driver;

  7. Creare una nuova istanza di GremlinServer e GremlinClient usando 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 grafo usando SubmitAsync.

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

  9. Usare di nuovo SubmitAsync per aggiungere un nuovo elemento al grafo 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 l'SDK per .NET di Tabelle di Azure per eseguire la connessione 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 pacchetto Azure.Data.Tables 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 nomi Azure.Data.Tables.

    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. Usare 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 tipo record 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 modalità 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. Eseguire l'applicazione .NET.

    dotnet run

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

Per eseguire un carico di lavoro di integrazione continua che convalida automaticamente l'applicazione, usare l'emulatore di Azure Cosmos DB con un gruppo di test del proprio framework preferito. L'emulatore di Azure Cosmos DB è preinstallato nella variante windows-latest degli strumenti di esecuzione ospitati di GitHub Actions.

Eseguire un gruppo di test usando il driver di test predefinito per .NET e un framework di test, ad esempio MSTest, NUnito 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 gli argomenti della riga di comando dell'emulatore.

Passaggio successivo

Esaminare le note sulla versione dell'emulatore