Guida introduttiva: Azure Cosmos DB per MongoDB per .NET con il driver MongoDB

  • Articolo

SI APPLICA A: MongoDB

Introduzione a MongoDB per creare database, raccolte e documenti all'interno della risorsa di Azure Cosmos DB. Seguire questa procedura per distribuire una soluzione minima nell'ambiente usando Azure Developer CLI.

Documentazione | di riferimento dell'API per MongoDB Package (NuGet) packages/Microsoft.Azure.Cosmos ) | Interfaccia della riga di comando per sviluppatori di Azure

Prerequisiti

Configurazione

Distribuire il contenitore di sviluppo di questo progetto nell'ambiente. Usare quindi l'interfaccia della riga di comando per sviluppatori di Azure (azd) per creare un account Azure Cosmos DB per MongoDB e distribuire un'applicazione di esempio in contenitori. L'applicazione di esempio usa la libreria client per gestire, creare, leggere ed eseguire query sui dati di esempio.

Aprire in GitHub Codespaces

Aprire nel contenitore di sviluppo

Importante

Gli account GitHub includono un diritto di archiviazione e ore di core senza costi. Per altre informazioni, vedere le ore di archiviazione e i core inclusi per gli account GitHub.

  1. Aprire un terminale nella directory radice del progetto.

  2. Eseguire l'autenticazione in Azure Developer CLI usando azd auth login. Seguire i passaggi specificati dallo strumento per eseguire l'autenticazione all'interfaccia della riga di comando usando le credenziali di Azure preferite.

    azd auth login

  3. Usare azd init per inizializzare il progetto.

    azd init

  4. Durante l'inizializzazione, configurare un nome di ambiente univoco.

    Suggerimento

    Il nome dell'ambiente verrà usato anche come nome del gruppo di risorse di destinazione. Per questa guida di avvio rapido, usare msdocs-cosmos-db.

  5. Distribuire l'account Azure Cosmos DB usando azd up. I modelli Bicep distribuiscono anche un'applicazione Web di esempio.

    azd up

  6. Durante il processo di provisioning, selezionare la sottoscrizione e il percorso desiderato. Attendere il completamento del processo di provisioning. Per il processo sono necessari circa 5 minuti.

  7. Una volta completato il provisioning delle risorse di Azure, nell'output viene incluso l'URL dell'applicazione Web in esecuzione.

    Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

  8. Usare l'URL nella console per passare all'applicazione Web nel browser. Osservare l'output dell'app in esecuzione.

    Screenshot dell'applicazione Web in esecuzione.

Installare la libreria client

La libreria client è disponibile tramite NuGet, come pacchetto Microsoft.Azure.Cosmos.

  1. Aprire un terminale e passare alla cartella /src/web:

    cd ./src/web

  2. Se non è già installato, installare il pacchetto MongoDb.Driver usando dotnet add package.

    dotnet add package MongoDb.Driver

  3. Installare anche il pacchetto Azure.Identity se non è già stato fatto.

    dotnet add package Azure.Identity

Modello a oggetti

Prima di iniziare a compilare l'applicazione, verrà esaminata la gerarchia di risorse in Azure Cosmos DB. Azure Cosmos DB ha un modello a oggetti specifico usato per creare e accedere alle risorse. Azure Cosmos DB crea risorse in una gerarchia costituita da account, database, raccolte e documenti.

Diagramma della gerarchia di Azure Cosmos DB, inclusi account, database, raccolte e documenti.

Per interagire con queste risorse, si useranno le classi di MongoDB seguenti:

  • MongoClient: questa classe fornisce una rappresentazione logica lato client per il livello dell'API per MongoDB in Azure Cosmos DB. L'oggetto client viene usato per configurare ed eseguire richieste nel servizio.
  • MongoDatabase: questa classe è un riferimento a un database che può esistere o meno nel servizio. Il database viene convalidato sul lato server quando si tenta di accedervi o di eseguire un'operazione su di essa.
  • Collection : questa classe è un riferimento a una raccolta che può non esistere ancora nel servizio. La raccolta viene convalidata sul lato server quando si tenta di usarla.

Esempi di codice

Il codice di esempio illustrato in questo articolo crea un database denominato con una raccolta denominata adventureworksproducts. La raccolta products è progettata per contenere dettagli del prodotto, ad esempio nome, categoria, quantità e indicatore di vendita. Ogni prodotto contiene anche un identificatore univoco.

Autenticare il client

Dalla directory del progetto aprire il file Program.cs. Nell'editor aggiungere una direttiva using per MongoDB.Driver.

using MongoDB.Driver;

Definire una nuova istanza della classe MongoClient utilizzando il costruttore e Environment.GetEnvironmentVariable per leggere la stringa di connessione impostata in precedenza.

// New instance of CosmosClient class
var client = new MongoClient(Environment.GetEnvironmentVariable("MONGO_CONNECTION"));

Creazione di un database

Usare il MongoClient.GetDatabase metodo per creare un nuovo database, se non esiste già. Questo metodo restituirà un riferimento al database esistente o appena creato.

// Database reference with creation if it does not already exist
var db = client.GetDatabase("adventure");

Creare una raccolta

MongoDatabase.GetCollection Crea una nuova raccolta se non esiste già e restituisce un riferimento alla raccolta.

// Container reference with creation if it does not alredy exist
var _products = db.GetCollection<Product>("products");

Creare un elemento

Il modo più semplice per creare un nuovo elemento in una raccolta consiste nel creare una classe O un tipo di record C# con tutti i membri da serializzare in JSON. In questo esempio, il record C# ha un identificatore univoco, un campo categoria per la chiave di partizione e campi aggiuntivi, quantità e vendita.

public record Product(
    string Id,
    string Category,
    string Name,
    int Quantity,
    bool Sale
);

Creare un elemento nella raccolta usando il Product record chiamando IMongoCollection<TDocument>.InsertOne.

// Create new object and upsert (create or replace) to container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Yamba Surfboard", 
    12, 
    false
));

Ottenere un elemento

In Azure Cosmos DB è possibile recuperare gli elementi componendo query usando Linq. Nell'SDK chiamare IMongoCollection.FindAsync<> e passare un'espressione C# per filtrare i risultati.

// Read a single item from container
var product = (await _products.FindAsync(p => p.Name.Contains("Yamba"))).FirstOrDefault();
Console.WriteLine("Single product:");
Console.WriteLine(product.Name);

Eseguire query sugli elementi

Dopo aver inserito un elemento, è possibile eseguire una query per ottenere tutti gli elementi che corrispondono a un filtro specifico considerando la raccolta come .IQueryable In questo esempio viene usata un'espressione per filtrare i prodotti per categoria. Una volta effettuata la chiamata a AsQueryable , chiamare MongoQueryable.Where per recuperare un set di elementi filtrati.

// Read multiple items from container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Sand Surfboard",
    4,
    false
));

var products = _products.AsQueryable().Where(p => p.Category == "gear-surf-surfboards");

Console.WriteLine("Multiple products:");
foreach (var prod in products)
{
    Console.WriteLine(prod.Name);
}

Eseguire il codice

Questa app crea un database e una raccolta dell'API MongoDb di Azure Cosmos DB. L'esempio crea quindi un elemento e successivamente rilegge esattamente lo stesso elemento. Infine, l'esempio crea un secondo elemento e quindi esegue una query che deve restituire più elementi. Ad ogni passaggio, l'esempio restituisce metadati alla console sui passaggi eseguiti.

Per eseguire l'app, utilizzare un terminale per accedere alla directory dell'applicazione e quindi eseguire l'applicazione.

dotnet run

L'output dell'app sarà simile a questo esempio:

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

Pulire le risorse

Quando l'account Azure Cosmos DB for MongoDB non è più necessario, è possibile eliminare il gruppo di risorse corrispondente.

Usare il comando az group delete per eliminare il gruppo di risorse.

az group delete --name $resourceGroupName