Introduzione ad Azure Cosmos DB per NoSQL con .NET

  • Si applica a: ✅ NoSQL

Questo articolo illustra come connettersi ad Azure Cosmos DB per NoSQL usando .NET SDK. Dopo la connessione, è possibile eseguire operazioni su database, contenitori ed elementi.

Pacchetto (NuGet) | Informazioni di riferimento | sulle APICodice sorgente | della libreriaInviare commenti e suggerimenti

Prerequisiti

Configurare il progetto

Creare una nuova applicazione .NET usando il comando dotnet new con il modello console.

dotnet new console

Importare il pacchetto NuGet Microsoft.Azure.Cosmos usando il dotnet add package comando .

dotnet add package Microsoft.Azure.Cosmos

Aggiungere anche il pacchetto NuGet Newtonsoft.Json, necessario per il pacchetto Microsoft.Azure.Cosmos.

dotnet add package Newtonsoft.Json

Creare il progetto con il comando dotnet build.

dotnet build

Connettersi ad Azure Cosmos DB for NoSQL

Per connettersi all'API per NoSQL di Azure Cosmos DB, creare un'istanza della classe CosmosClient. Questa classe è il punto di partenza per eseguire tutte le operazioni sui database.

Per connettersi all'account API NoSQL con Microsoft Entra, utilizzare un'entità di sicurezza. Il tipo esatto di principale dipenderà da dove è ospitato il codice dell'applicazione. La tabella seguente funge da guida di riferimento rapido.

Dove viene eseguita l'applicazione Entità di sicurezza
Computer locale (sviluppo e test) Identità utente o principale del servizio
Azure Identità gestita
Server o client esterni ad Azure Service Principal

Importare Azure.Identity

Il pacchetto NuGet Azure.Identity contiene funzionalità di autenticazione di base condivise tra tutte le librerie dell’SDK di Azure.

Importare il pacchetto NuGet Azure.Identity con il comando dotnet add package.

dotnet add package Azure.Identity

Ricostruire il progetto con il comando dotnet build.

dotnet build

Nell'editor di codice, aggiungi direttive using per i namespace Azure.Core e Azure.Identity.

using Azure.Core;
using Azure.Identity;

Annotazioni

Oltre a Azure.Core e Azure.Identity, l'applicazione deve fare riferimento allo spazio dei nomi Microsoft.Azure.Cosmos. Questo spazio dei nomi fornisce i tipi di client Azure Cosmos DB, ad esempio CosmosClient, Database e Contenitore, usati nella parte restante di questo articolo. Senza questo riferimento allo spazio dei nomi, l'applicazione non verrà compilata.

Creare CosmosClient con l'implementazione di credenziali predefinita

Se si esegue un test in un computer locale o se l'applicazione verrà eseguita in servizi di Azure con supporto diretto per le identità gestite, ottenere un token OAuth creando un'istanza di DefaultAzureCredential.

Per questo esempio l'istanza è stata salvata in una variabile di tipo TokenCredential perché si tratta di un tipo più generico riutilizzabile tra gli SDK.

// Credential class for testing on a local machine or Azure services
TokenCredential credential = new DefaultAzureCredential();

Creare una nuova istanza della classe CosmosClient con l'endpoint Azure Cosmos DB e l'oggetto TokenCredential come parametri.

CosmosClient client = new(
    accountEndpoint: "<azure-cosmos-db-endpoint>",
    tokenCredential: credential
);

Compilare l'applicazione

Durante la compilazione dell'applicazione, il codice interagirà essenzialmente con due tipi di risorse:

  • L'API per account NoSQL, che rappresenta il namespace univoco di primo livello per i dati di Azure Cosmos DB.

  • Database, che organizzano i contenitori nell'account.

  • Contenitori, che contengono una serie di singoli elementi nel database.

  • Elementi, che rappresentano un documento JSON nel contenitore.

Il diagramma seguente illustra la relazione tra queste risorse.

Diagramma della gerarchia di Azure Cosmos DB, che include account, database, contenitori ed elementi.

Ogni tipo di risorsa è rappresentato da una o più classi .NET associate. Ecco un elenco delle classi più comuni:

Class Description
CosmosClient Questa classe fornisce una rappresentazione logica lato client per il servizio Azure Cosmos DB. L'oggetto client viene usato per configurare ed eseguire richieste nel servizio.
Database Questa classe è un riferimento a un database che potrebbe, o non, esistere ancora nel servizio. Il database viene convalidato sul lato server quando si tenta di accedervi o di eseguire un'operazione su di esso.
Container Questa classe è un riferimento a un contenitore che potrebbe non esistere ancora nel servizio. Il contenitore viene convalidato sul lato server quando si tenta di usarlo.

Le guide seguenti illustrano come usare ognuna di queste classi per costruire la tua applicazione.

Guida Description
Creare un database Creare basi di dati
Creare un contenitore Creare contenitori
Leggere un elemento Leggere un elemento specifico
Elementi da interrogare Eseguire query su più elementi

Vedere anche

Passaggi successivi

Creare un database in Azure Cosmos DB per un database NoSQL utilizzando .NET

  • Last updated on