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

SI APPLICA A: MongoDB

È possibile iniziare a usare MongoDB per creare database, raccolte e documenti all'interno della propria 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 | Pacchetto MongoDB (NuGet) packages/Microsoft.Azure.Cosmos) | Azure Developer CLI

Prerequisiti

Configurazione

Distribuire il contenitore di sviluppo di questo progetto nell'ambiente. Usare quindi Azure Developer CLI (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.

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 --template cosmos-db-mongodb-dotnet-quickstart
   

   Nota

   Questo avvio rapido usa il modello del repository GitHub azure-samples/cosmos-db-mongodb-dotnet-quickstart. Azure Developer CLI clonerà automaticamente questo progetto nel computer, se non è già presente.

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 questo avvio rapido è consigliabile 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 la posizione desiderata. Attendere il completamento del processo di provisioning. Per il processo sono necessari circa 5 minuti.

7. Al termine del provisioning delle risorse di Azure, nell'output viene incluso un 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.

   

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.

Per interagire con queste risorse, usare 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 potrebbe o non potrebbe esistere ancora nel servizio. Il database viene convalidato lato server quando si tenta di accedervi o di eseguire un'operazione su di esso.
• Collection: questa classe è un riferimento a una raccolta che potrebbe non esistere ancora nel servizio. La raccolta viene convalidata sul lato server quando si tenta di usarla.

Esempi di codice

• Autenticare il client
• Creare un database
• Creare un contenitore
• Creare un elemento
• Ottenere un elemento
• Eseguire query sugli elementi

Il codice di esempio dimostrato in questo articolo crea un database denominato adventureworks con una raccolta denominata products. 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 usando il costruttore e Environment.GetEnvironmentVariable per leggere la stringa di connessione impostata in precedenza da Azure Developer CLI.

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

Creazione di un database

Usare il metodo MongoClient.GetDatabase per creare uno nuovo database solo se non ne esiste già uno. Questo metodo restituisce 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 C# o un tipo di record 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 di nome quantitàe vendita.

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

Creare un elemento nella raccolta tramite la classe Product 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 un 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 Azure Cosmos DB MongoDb. L'esempio crea quindi un elemento e successivamente rilegge esattamente lo stesso elemento. L'esempio, infine, crea un secondo elemento ed esegue quindi una query che deve restituire più elementi. Con ogni passaggio, l’esempio restituisce i metadati nella console relativamente ai passaggi eseguiti.

Per eseguire l'app, usare un terminale per passare alla directory dell'applicazione ed 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.

az group delete --name $resourceGroupName

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters