Esplorare Microsoft .NET SDK v3 per Azure Cosmos DB

  • 3 minuti

Questa unità è incentrata su Azure Cosmos DB .NET SDK v3 per l'API per NoSQL. (Pacchetto NuGet Microsoft.Azure.Cosmos). Se si ha familiarità con la versione precedente di .NET SDK, si dovrebbe avere familiarità con i termini raccolta e documento.

Il repository GitHub azure-cosmos-dotnet-v3 include le soluzioni .NET di esempio più recenti. Queste soluzioni consentono di eseguire operazioni CRUD (creare, leggere, aggiornare ed eliminare) e altre operazioni comuni sulle risorse di Azure Cosmos DB.

Poiché Azure Cosmos DB supporta più modelli di API, nella versione 3 di .NET SDK vengono usati i termini generici contenitore ed elemento. Un contenitore può essere una raccolta, un grafo o una tabella. Un elemento può essere un documento, un arco/vertice o una riga ed è il contenuto all'interno di un contenitore.

Di seguito sono riportati alcuni esempi che illustrano alcune delle operazioni chiave con cui si deve acquisire familiarità. Per altri esempi, visitare il collegamento a GitHub mostrato in precedenza. Gli esempi seguenti usano la versione asincrona dei metodi.

CosmosClient

Crea un nuovo oggetto CosmosClient con una stringa di connessione. CosmosClient è thread-safe. È consigliabile mantenere una singola istanza di CosmosClient per durata dell'applicazione che renda più efficienti la gestione e le prestazioni delle connessioni.

CosmosClient client = new CosmosClient(endpoint, key);

Esempi di database

Creazione di un database

Il metodo CosmosClient.CreateDatabaseAsync genera un'eccezione se esiste già un database con lo stesso nome.

// New instance of Database class referencing the server-side database
Database database1 = await client.CreateDatabaseAsync(
    id: "adventureworks-1"
);

L'oggetto CosmosClient.CreateDatabaseIfNotExistsAsync verifica se esiste un database e, se non esiste, lo crea. Viene usato solo il database id per verificare se è presente un database esistente.

// New instance of Database class referencing the server-side database
Database database2 = await client.CreateDatabaseIfNotExistsAsync(
    id: "adventureworks-2"
);

Leggere un database in base all'ID

Legge un database del servizio Azure Cosmos DB come operazione asincrona.

DatabaseResponse readResponse = await database.ReadAsync();

Eliminare un database

Eliminare un database come operazione asincrona.

await database.DeleteAsync();

Esempi di contenitore

Creazione di un contenitore

Il metodo Database.CreateContainerIfNotExistsAsync controlla se esiste un contenitore e, se non esiste, lo crea. Viene usato solo il contenitore id per verificare se è presente un contenitore esistente.

// Set throughput to the minimum value of 400 RU/s
ContainerResponse simpleContainer = await database.CreateContainerIfNotExistsAsync(
    id: containerId,
    partitionKeyPath: partitionKey,
    throughput: 400);

Ottenere un contenitore in base all'ID

Container container = database.GetContainer(containerId);
ContainerProperties containerProperties = await container.ReadContainerAsync();

Eliminare un contenitore

Eliminare un contenitore come operazione asincrona.

await database.GetContainer(containerId).DeleteContainerAsync();

Esempi di elementi

Creare un elemento

Usare il metodo Container.CreateItemAsync per creare un elemento. Il metodo richiede un oggetto JSON serializzabile che deve contenere una proprietà id e un oggetto partitionKey.

ItemResponse<SalesOrder> response = await container.CreateItemAsync(salesOrder, new PartitionKey(salesOrder.AccountNumber));

Leggere un elemento

Usare il metodo Container.ReadItemAsync per leggere un elemento. Il metodo richiede il tipo per cui serializzare l'elemento insieme a una proprietà id e un oggetto partitionKey.

string id = "[id]";
string accountNumber = "[partition-key]";
ItemResponse<SalesOrder> response = await container.ReadItemAsync(id, new PartitionKey(accountNumber));

Eseguire una query su un elemento

Il metodo Container.GetItemQueryIterator crea una query per gli elementi in un contenitore di un database di Azure Cosmos usando un'istruzione SQL contenente valori con parametri. Verrà restituita un'istanza di FeedIterator.

QueryDefinition query = new QueryDefinition(
    "select * from sales s where s.AccountNumber = @AccountInput ")
    .WithParameter("@AccountInput", "Account1");

FeedIterator<SalesOrder> resultSet = container.GetItemQueryIterator<SalesOrder>(
    query,
    requestOptions: new QueryRequestOptions()
    {
        PartitionKey = new PartitionKey("Account1"),
        MaxItemCount = 1
    });

Altre risorse