Guida introduttiva: Azure Cosmos DB per MongoDB per .NET con il driver MongoDB
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
- Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
- Account GitHub
- Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
- Azure Developer CLI
- Docker Desktop
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.
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.
Aprire un terminale nella directory radice del progetto.
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
Usare
azd init
per inizializzare il progetto.azd init
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
.Distribuire l'account Azure Cosmos DB usando
azd up
. I modelli Bicep distribuiscono anche un'applicazione Web di esempio.azd up
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.
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.
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
.
Aprire un terminale e passare alla cartella
/src/web
:cd ./src/web
Se non è già installato, installare il pacchetto
MongoDb.Driver
usandodotnet add package
.dotnet add package MongoDb.Driver
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 gerarchico che mostra al vertice un account Azure Cosmos DB. L'account ha due partizioni di database figlio. Una delle partizioni del database include due partizioni di raccolta figlio. L'altra partizione di database include una singola partizione di raccolta figlio. La singola partizione di raccolta ha tre partizioni di documento figlio.
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
- Autenticare il client
- Creare un database
- Creare un contenitore
- Creare un elemento
- Ottenere un elemento
- Eseguire query sugli elementi
Il codice di esempio illustrato in questo articolo crea un database denominato con una raccolta denominata adventureworks
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
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