Snelstart: Een console-app maken met behulp van de .NET V4 SDK (preview) voor het beheren van Azure Cosmos DB SQL API-accountresources

VAN TOEPASSING OP: SQL API

Ga aan de slag met de Azure Cosmos DB SQL API-clientbibliotheek voor .NET. Volg de stappen in dit artikel om het .NET V4-pakket (Azure.Cosmos) te installeren en een app te maken. Probeer vervolgens de voorbeeldcode voor basisbewerkingen voor het maken, lezen, bijwerken en verwijderen (CRUD) van de gegevens die zijn opgeslagen in Azure Cosmos DB.

Belangrijk

De .NET V4 SDK voor Azure Cosmos DB is momenteel in openbare preview. Deze preview-versie wordt geleverd zonder een serviceovereenkomst en we raden deze niet aan voor productiebelastingen. Bepaalde functies worden mogelijk niet ondersteund of hebben mogelijk beperkte mogelijkheden.

Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure previews voor meer informatie.

Azure Cosmos DB is de snelle NoSQL-database van Microsoft met open API's voor elke schaal. U kunt Azure Cosmos DB gebruiken om snel databases met sleutels/waarden, documenten en grafieken te maken en te query's maken. Gebruik de Azure Cosmos DB SQL API-clientbibliotheek voor .NET om:

  • Maak een Azure Cosmos-database en een container.
  • Voeg voorbeeldgegevens toe aan de container.
  • Query uitvoeren op de gegevens.
  • Verwijder de database.

BibliotheekbroncodePakket (NuGet)

Vereisten

  • Azure-abonnement. Maak er gratis een. U kunt Azure Cosmos DB ook uitproberen zonder een Azure-abonnement, gratis en zonder toezeggingen.
  • NET Core 3 SDK. U kunt controleren welke versie beschikbaar is in uw omgeving door het uitvoeren dotnet --version van .

Instellen

In deze sectie kunt u een Azure Cosmos-account maken en een project instellen dat gebruikmaakt van de Azure Cosmos DB SQL API-clientbibliotheek voor .NET om resources te beheren.

Met de voorbeeldcode die in dit artikel wordt beschreven, worden FamilyDatabase een database en gezinsleden in die database gemaakt. Elk gezinslid is een item en heeft eigenschappen Id zoals , , , , , en FamilyNameFirstNameLastNameParentsChildrenAddress . De LastName eigenschap wordt gebruikt als de partitiesleutel voor de container.

Een Azure Cosmos-account maken

Als u de gratis optie Probeer Azure Cosmos DB gebruikt om een Azure Cosmos-account te maken, moet u een Azure Cosmos-account van het type API SQL maken. Er is al een Azure Cosmos-testaccount voor u gemaakt. U hoeft het account niet expliciet te maken, dus u kunt deze sectie overslaan en naar de volgende sectie gaan.

Als u uw eigen Azure-abonnement hebt of gratis een abonnement hebt gemaakt, moet u expliciet een Azure Cosmos-account maken. Met de volgende code wordt een Azure Cosmos-account met sessieconsistentie aangemaakt. Het account wordt gerepliceerd in South Central USNorth Central US en .

U kunt Azure Cloud Shell gebruiken om het Azure Cosmos-account te maken. Azure Cloud Shell is een interactieve, geverifieerde, browser toegankelijke shell voor het beheren van Azure-resources. Het biedt de flexibiliteit om de shell-ervaring te kiezen die het beste past bij de manier waarop u werkt: Bash of PowerShell.

Voor deze quickstart gebruikt u Bash. Azure Cloud Shell vereist ook een opslagaccount. U kunt er een maken wanneer u daarom wordt gevraagd.

  1. Selecteer de knop Uitproberen naast de volgende code, kies Bash-modus, selecteer een opslagaccount makenen meld u aan bij Cloud Shell.

  2. Kopieer en plak de volgende code in Azure Cloud Shell en voer deze uit. De naam van het Azure Cosmos-account moet globaal uniek zijn, dus zorg ervoor dat u de waarde bij werk voordat mysqlapicosmosdb u de opdracht uit te voeren.

    
    # Set variables for the new SQL API account, database, and container
    resourceGroupName='myResourceGroup'
    location='southcentralus'
    
    # The Azure Cosmos account name must be globally unique, so be sure to update the `mysqlapicosmosdb` value before you run the command
    accountName='mysqlapicosmosdb'
    
    # Create a resource group
    az group create \
        --name $resourceGroupName \
        --location $location
    
    # Create a SQL API Cosmos DB account with session consistency and multi-region writes enabled
    az cosmosdb create \
        --resource-group $resourceGroupName \
        --name $accountName \
        --kind GlobalDocumentDB \
        --locations regionName="South Central US" failoverPriority=0 --locations regionName="North Central US" failoverPriority=1 \
        --default-consistency-level "Session" \
        --enable-multiple-write-locations true
    
    

Het maken van het Azure Cosmos-account duurt even. Nadat de bewerking is geslaagd, kunt u de bevestigingsuitvoer zien. Meld u aan bij de Azure-portal en controleer of het Azure Cosmos-account met de opgegeven naam bestaat. U kunt het venster Azure Cloud Shell sluiten nadat de resource is gemaakt.

Een .NET-app maken

Maak een .NET-toepassing in de gewenste editor of IDE. Open de Windows opdrachtprompt of een terminalvenster vanaf uw lokale computer. U voert alle opdrachten uit in de volgende secties van de opdrachtprompt of terminal.

Voer de volgende dotnet new opdracht uit om een app met de naam te todo maken. De --langVersion parameter stelt de eigenschap in het gemaakte LangVersion projectbestand in.

dotnet new console --langVersion:8 -n todo

Gebruik de volgende opdrachten om uw adreslijst te wijzigen in de nieuwe app-map en de toepassing te maken:

cd todo
dotnet build

De verwachte uitvoer van de build ziet er zo uit:

  Restore completed in 100.37 ms for C:\Users\user1\Downloads\CosmosDB_Samples\todo\todo.csproj.
  todo -> C:\Users\user1\Downloads\CosmosDB_Samples\todo\bin\Debug\netcoreapp3.0\todo.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:34.17

Het Azure Cosmos DB-pakket installeren

Terwijl u zich nog steeds in de toepassingsmap hebt, installeert u de Azure Cosmos DB-clientbibliotheek voor .NET Core met de dotnet add package opdracht:

dotnet add package Azure.Cosmos --version 4.0.0-preview3

Uw Azure Cosmos-accountreferenties kopiëren vanuit de Azure-portal

De voorbeeldtoepassing moet zich verifiëren bij uw Azure Cosmos-account. Als u wilt verifiëren, moet u de referenties van het Azure Cosmos-account doorgeven aan de toepassing. Haal uw Azure Cosmos-accountreferenties op door de volgende stappen uit te voeren:

  1. Meld u aan bij de Azure-portal.

  2. Ga naar uw Azure Cosmos-account.

  3. Open het deelvenster Sleutels en kopieer de waarden URI en PRIMAIRE SLEUTEL voor uw account. In de volgende procedure voegt u de URI- en sleutelwaarden toe aan een omgevingsvariabele.

Meer informatie over het objectmodel

Voordat u verder gaat met het maken van de toepassing, bekijken we de hiërarchie van resources in Azure Cosmos DB en het objectmodel dat wordt gebruikt om deze resources te maken en te openen. Azure Cosmos DB maakt resources in de volgende volgorde:

  • Azure Cosmos-account
  • Databases
  • Containers
  • Items

Zie het artikel Azure Cosmos DB-resourcemodel voor meer informatie over de hiërarchie van entiteiten. U gebruikt de volgende .NET-klassen om met deze bronnen te werken:

  • CosmosClient. Deze klasse biedt een logische weergave aan de clientzijde voor de Azure Cosmos DB-service. Het clientobject wordt gebruikt om aanvragen voor de service te configureren en uit te voeren.
  • CreateDatabaseIfNotExistsAsync. Met deze methode wordt een databaseresource gemaakt (als deze niet bestaat) of (als deze al bestaat) als een asynchrone bewerking.
  • CreateContainerIfNotExistsAsync. Met deze methode wordt een container gemaakt (als deze niet bestaat) of wordt (als deze al bestaat) een container als asynchrone bewerking gemaakt. U kunt de statuscode van het antwoord controleren om te bepalen of de container nieuw is gemaakt (201) of dat een bestaande container is geretourneerd (200).
  • CreateItemAsync. Met deze methode wordt een item in de container gemaakt.
  • UpsertItemAsync. Met deze methode wordt een item in de container gemaakt als dit nog niet bestaat of als het item al bestaat.
  • GetItemQueryIterator. Met deze methode wordt een query gemaakt voor items onder een container in een Azure Cosmos-database met behulp van SQL instructie met parameterwaarden.
  • DeleteAsync. Met deze methode wordt de opgegeven database verwijderd uit uw Azure Cosmos-account.

Voorbeelden van code configureren

Met de voorbeeldcode die in dit artikel wordt beschreven, wordt een gezinsdatabase gemaakt in Azure Cosmos DB. De gezinsdatabase bevat familiegegevens, zoals naam, adres, locatie, ouders, kinderen en huisdieren.

Voordat u de gegevens voor uw Azure Cosmos-account vult, definieert u de eigenschappen van een gezinsitem. Maak een nieuwe klas met Family.cs de naam op het hoofdniveau van de voorbeeldtoepassing en voeg de volgende code toe:

using System.Text.Json;
using System.Text.Json.Serialization;

namespace todo
{
    public class Family
    {
        [JsonPropertyName("id")]
        public string Id { get; set; }
        public string LastName { get; set; }
        public Parent[] Parents { get; set; }
        public Child[] Children { get; set; }
        public Address Address { get; set; }
        public bool IsRegistered { get; set; }
        public override string ToString()
        {
            return JsonSerializer.Serialize(this);
        }
    }

    public class Parent
    {
        public string FamilyName { get; set; }
        public string FirstName { get; set; }
    }

    public class Child
    {
        public string FamilyName { get; set; }
        public string FirstName { get; set; }
        public string Gender { get; set; }
        public int Grade { get; set; }
        public Pet[] Pets { get; set; }
    }

    public class Pet
    {
        public string GivenName { get; set; }
    }

    public class Address
    {
        public string State { get; set; }
        public string County { get; set; }
        public string City { get; set; }
    }
}

De gebruiksrichtlijnen toevoegen en het clientobject definiëren

Open vanuit de projectmap het program.cs-bestand in de editor en voeg de volgende richtlijnen boven aan uw toepassing toe:

using System;
using System.Collections.Generic;
using System.Net;
using System.Threading.Tasks;
using Azure.Cosmos;

Voeg de volgende globale variabelen in uw klas Program toe. Deze variabelen omvatten de eindpunt- en autorisatiesleutels, de naam van de database en de container die u gaat maken. Zorg ervoor dat u de waarden van het eindpunt en de autorisatiesleutels vervangt op basis van uw omgeving.

private const string EndpointUrl = "https://<your-account>.documents.azure.com:443/";
private const string AuthorizationKey = "<your-account-key>";
private const string DatabaseId = "FamilyDatabase";
private const string ContainerId = "FamilyContainer";

Vervang ten slotte de Main methode:

static async Task Main(string[] args)
{
    
    CosmosClient cosmosClient = new CosmosClient(EndpointUrl, AuthorizationKey);
    await Program.CreateDatabaseAsync(cosmosClient);
    await Program.CreateContainerAsync(cosmosClient);
    await Program.AddItemsToContainerAsync(cosmosClient);
    await Program.QueryItemsAsync(cosmosClient);
    await Program.ReplaceFamilyItemAsync(cosmosClient);
    await Program.DeleteFamilyItemAsync(cosmosClient);
    await Program.DeleteDatabaseAndCleanupAsync(cosmosClient);
}

Een database maken

CreateDatabaseAsyncDefinieer de methode binnen de program.cs klas. Met deze methode wordt de FamilyDatabase database gemaakt als deze nog niet bestaat.

/// <summary>
/// Create the database if it does not exist
/// </summary>
private static async Task CreateDatabaseAsync(CosmosClient cosmosClient)
{
    // Create a new database
    CosmosDatabase database = await cosmosClient.CreateDatabaseIfNotExistsAsync(Program.DatabaseId);
    Console.WriteLine("Created Database: {0}\n", database.Id);
}

Een container maken

CreateContainerAsyncDefinieer de methode binnen de Program klas. Met deze methode wordt FamilyContainer de container gemaakt als deze nog niet bestaat.

/// <summary>
/// Create the container if it does not exist. 
/// Specify "/LastName" as the partition key since we're storing family information, to ensure good distribution of requests and storage.
/// </summary>
/// <returns></returns>
private static async Task CreateContainerAsync(CosmosClient cosmosClient)
{
    // Create a new container
    CosmosContainer container = await cosmosClient.GetDatabase(Program.DatabaseId).CreateContainerIfNotExistsAsync(Program.ContainerId, "/LastName");
    Console.WriteLine("Created Container: {0}\n", container.Id);
}

Een item maken

Maak een gezinsitem door de AddItemsToContainerAsync methode toe te voegen met de volgende code. U kunt de CreateItemAsyncUpsertItemAsync of-methode gebruiken om een item te maken.

/// <summary>
/// Add Family items to the container
/// </summary>
private static async Task AddItemsToContainerAsync(CosmosClient cosmosClient)
{
    // Create a family object for the Andersen family
    Family andersenFamily = new Family
    {
        Id = "Andersen.1",
        LastName = "Andersen",
        Parents = new Parent[]
        {
            new Parent { FirstName = "Thomas" },
            new Parent { FirstName = "Mary Kay" }
        },
        Children = new Child[]
        {
            new Child
            {
                FirstName = "Henriette Thaulow",
                Gender = "female",
                Grade = 5,
                Pets = new Pet[]
                {
                    new Pet { GivenName = "Fluffy" }
                }
            }
        },
        Address = new Address { State = "WA", County = "King", City = "Seattle" },
        IsRegistered = false
    };

    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);
    try
    {
        // Read the item to see if it exists.  
        ItemResponse<Family> andersenFamilyResponse = await container.ReadItemAsync<Family>(andersenFamily.Id, new PartitionKey(andersenFamily.LastName));
        Console.WriteLine("Item in database with id: {0} already exists\n", andersenFamilyResponse.Value.Id);
    }
    catch(CosmosException ex) when (ex.Status == (int)HttpStatusCode.NotFound)
    {
        // Create an item in the container representing the Andersen family. Note we provide the value of the partition key for this item, which is "Andersen"
        ItemResponse<Family> andersenFamilyResponse = await container.CreateItemAsync<Family>(andersenFamily, new PartitionKey(andersenFamily.LastName));

        // Note that after creating the item, we can access the body of the item with the Resource property off the ItemResponse.
        Console.WriteLine("Created item in database with id: {0}\n", andersenFamilyResponse.Value.Id);
    }

    // Create a family object for the Wakefield family
    Family wakefieldFamily = new Family
    {
        Id = "Wakefield.7",
        LastName = "Wakefield",
        Parents = new Parent[]
        {
            new Parent { FamilyName = "Wakefield", FirstName = "Robin" },
            new Parent { FamilyName = "Miller", FirstName = "Ben" }
        },
        Children = new Child[]
        {
            new Child
            {
                FamilyName = "Merriam",
                FirstName = "Jesse",
                Gender = "female",
                Grade = 8,
                Pets = new Pet[]
                {
                    new Pet { GivenName = "Goofy" },
                    new Pet { GivenName = "Shadow" }
                }
            },
            new Child
            {
                FamilyName = "Miller",
                FirstName = "Lisa",
                Gender = "female",
                Grade = 1
            }
        },
        Address = new Address { State = "NY", County = "Manhattan", City = "NY" },
        IsRegistered = true
    };

    // Create an item in the container representing the Wakefield family. Note we provide the value of the partition key for this item, which is "Wakefield"
    ItemResponse<Family> wakefieldFamilyResponse = await container.UpsertItemAsync<Family>(wakefieldFamily, new PartitionKey(wakefieldFamily.LastName));

    // Note that after creating the item, we can access the body of the item with the Resource property off the ItemResponse. We can also access the RequestCharge property to see the amount of RUs consumed on this request.
    Console.WriteLine("Created item in database with id: {0}\n", wakefieldFamilyResponse.Value.Id);
}

Query's uitvoeren op de items

Nadat u een item hebt invoegen, kunt u een query uitvoeren om de details van de Andersen-familie op te halen. In de volgende code ziet u hoe u de query uitvoert met de SQL query. De SQL om de Familiegegevens van Andersen te krijgen is SELECT * FROM c WHERE c.LastName = 'Andersen' . QueryItemsAsyncDefinieer de methode in Program de klas en voeg de volgende code toe:

/// <summary>
/// Run a query (using Azure Cosmos DB SQL syntax) against the container
/// </summary>
private static async Task QueryItemsAsync(CosmosClient cosmosClient)
{
    var sqlQueryText = "SELECT * FROM c WHERE c.LastName = 'Andersen'";

    Console.WriteLine("Running query: {0}\n", sqlQueryText);

    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);

    QueryDefinition queryDefinition = new QueryDefinition(sqlQueryText);

    List<Family> families = new List<Family>();

    await foreach (Family family in container.GetItemQueryIterator<Family>(queryDefinition))
    {
        families.Add(family);
        Console.WriteLine("\tRead {0}\n", family);
    }
}

Een item vervangen

Lees een gezinsitem en werk het bij door de methode toe te voegen ReplaceFamilyItemAsync met de volgende code:

/// <summary>
/// Replace an item in the container
/// </summary>
private static async Task ReplaceFamilyItemAsync(CosmosClient cosmosClient)
{
    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);

    ItemResponse<Family> wakefieldFamilyResponse = await container.ReadItemAsync<Family>("Wakefield.7", new PartitionKey("Wakefield"));
    Family itemBody = wakefieldFamilyResponse;
    
    // update registration status from false to true
    itemBody.IsRegistered = true;
    // update grade of child
    itemBody.Children[0].Grade = 6;

    // replace the item with the updated content
    wakefieldFamilyResponse = await container.ReplaceItemAsync<Family>(itemBody, itemBody.Id, new PartitionKey(itemBody.LastName));
    Console.WriteLine("Updated Family [{0},{1}].\n \tBody is now: {2}\n", itemBody.LastName, itemBody.Id, wakefieldFamilyResponse.Value);
}

Een item verwijderen

Verwijder een gezinsitem door de DeleteFamilyItemAsync methode toe te voegen met de volgende code:

/// <summary>
/// Delete an item in the container
/// </summary>
private static async Task DeleteFamilyItemAsync(CosmosClient cosmosClient)
{
    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);

    string partitionKeyValue = "Wakefield";
    string familyId = "Wakefield.7";

    // Delete an item. Note we must provide the partition key value and id of the item to delete
    ItemResponse<Family> wakefieldFamilyResponse = await container.DeleteItemAsync<Family>(familyId,new PartitionKey(partitionKeyValue));
    Console.WriteLine("Deleted Family [{0},{1}]\n", partitionKeyValue, familyId);
}

De database verwijderen

U kunt de database verwijderen door de methode DeleteDatabaseAndCleanupAsync toe te voegen met de volgende code:

/// <summary>
/// Delete the database and dispose of the Cosmos Client instance
/// </summary>
private static async Task DeleteDatabaseAndCleanupAsync(CosmosClient cosmosClient)
{
    CosmosDatabase database = cosmosClient.GetDatabase(Program.DatabaseId);
    DatabaseResponse databaseResourceResponse = await database.DeleteAsync();

    Console.WriteLine("Deleted Database: {0}\n", Program.DatabaseId);
}

Nadat u alle vereiste methoden hebt toegevoegd, kunt u het bestand Program.cs opslaan.

De code uitvoeren

Voer de toepassing uit om de Azure Cosmos DB-resources te maken:

dotnet run

De volgende uitvoer wordt gegenereerd wanneer u de toepassing uitvoert:

Created Database: FamilyDatabase

Created Container: FamilyContainer

Created item in database with id: Andersen.1

Running query: SELECT * FROM c WHERE c.LastName = 'Andersen'

        Read {"id":"Andersen.1","LastName":"Andersen","Parents":[{"FamilyName":null,"FirstName":"Thomas"},{"FamilyName":null   "FirstName":"Mary Kay"}],"Children":[{"FamilyName":null,"FirstName":"Henriette Thaulow","Gender":"female","Grade":5,"Pets": [{"GivenName":"Fluffy"}]}],"Address":{"State":"WA","County":"King","City":"Seattle"},"IsRegistered":false}

Updated Family [Wakefield,Wakefield.7].
        Body is now: {"id":"Wakefield.7","LastName":"Wakefield","Parents":[{"FamilyName":"Wakefield","FirstName":"Robin"}   {"FamilyName":"Miller","FirstName":"Ben"}],"Children":[{"FamilyName":"Merriam","FirstName":"Jesse","Gender":"female","Grade":6   "Pets":[{"GivenName":"Goofy"},{"GivenName":"Shadow"}]},{"FamilyName":"Miller","FirstName":"Lisa","Gender":"female","Grade":1   "Pets":null}],"Address":{"State":"NY","County":"Manhattan","City":"NY"},"IsRegistered":true}

Deleted Family [Wakefield,Wakefield.7]

Deleted Database: FamilyDatabase

End of demo, press any key to exit.

U kunt valideren dat de gegevens worden gemaakt door u aan te melden bij de Azure-portal en de vereiste items in uw Azure Cosmos-account te zien.

Resources ops schonen

Wanneer u het Azure Cosmos-account en de bijbehorende resourcegroep niet meer nodig hebt, kunt u de Azure CLI of Azure PowerShell gebruiken om deze te verwijderen. In de volgende opdracht ziet u hoe u de resourcegroep verwijdert met behulp van de Azure CLI:

az group delete -g "myResourceGroup"

Volgende stappen

In deze quickstart hebt u geleerd hoe u een Azure Cosmos-account maakt, een database maakt en een container maakt met behulp van een .NET Core-app. U kunt nu meer gegevens importeren in uw Azure Cosmos-account via de instructies in het volgende artikel:

Wilt u capaciteitsplanning uitvoeren voor een migratie naar Azure Cosmos DB? U kunt informatie over uw bestaande databasecluster gebruiken voor capaciteitsplanning.

  • Als u alleen het aantal vcores en servers in uw bestaande databasecluster weet, leest u over het schatten van aanvraageenheden met vCores of vCPUs
  • Als u de gebruikelijke aanvraagtarieven voor uw huidige databasewerkbelasting kent, leest u meer over het schatten van aanvraageenheden met behulp van De capaciteitsplanner van Azure Cosmos DB