Quickstart: Een console-app bouwen 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 bouwen. Probeer vervolgens de voorbeeldcode voor eenvoudige CRUD-bewerkingen (maken, lezen, bijwerken en verwijderen) voor de gegevens die zijn opgeslagen in Azure Cosmos DB.

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 voor belangrijke/waardevolle documenten en grafieken te maken en doorzoeken. 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's uitvoeren op de gegevens.
• Verwijder de database.

Broncode van de bibliotheek | Pakket (NuGet)

Vereisten

• Azure-abonnement. Maak er gratis een. U kunt ook Azure Cosmos DB zonder Azure-abonnement, zonder kosten en zonder verplichtingen.
• NET Core 3 SDK. U kunt controleren welke versie beschikbaar is in uw omgeving door dotnet --version uit te voeren.

Instellen

Deze sectie helpt u bij het maken van een Azure Cosmos-account en het instellen van een project dat gebruikmaakt van de Azure Cosmos DB SQL API-clientbibliotheek voor .NET voor het beheren van resources.

Met de voorbeeldcode die in dit artikel wordt beschreven, worden een database en FamilyDatabase familieleden in die database gemaakt. Elk lid van de familie is een item en heeft eigenschappen zoals Id , , , , , en FamilyName FirstName LastName Parents Children Address . De eigenschap LastName wordt gebruikt als de partitiesleutel voor de container.

Een Azure Cosmos-account maken

Als u de optie Gratis Azure Cosmos DB gebruiken om een Azure Cosmos-account te maken, moet u een Azure Cosmos-account van het type SQL API 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 doorgaan naar de volgende sectie.

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

U kunt Azure Cloud Shell gebruiken om het Azure Cosmos-account te maken. Azure Cloud Shell is een interactieve, geverifieerde en vanuit de browser toegankelijke shell voor het beheer 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 de Bash-modus, selecteer Een opslagaccount maken en meld u aan bij Cloud Shell.

2. Kopieer en plak de volgende code om de Azure Cloud Shell uit te voeren. De naam van het Azure Cosmos-account moet wereldwijd uniek zijn. Werk daarom de waarde bij mysqlapicosmosdb voordat u de opdracht gaat uitvoeren.

   
   # 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, ziet u de bevestigingsuitvoer. Meld u aan bij Azure Portal en controleer of het Azure Cosmos-account met de opgegeven naam bestaat. U kunt het Azure Cloud Shell-venster sluiten nadat de resource is gemaakt.

Een .NET-app maken

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

Voer de volgende opdracht dotnet new 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 map te wijzigen in de zojuist gemaakte app-map en de toepassing te bouwen:

cd todo
dotnet build

De verwachte uitvoer van de build moet er ongeveer als volgt uitzien:

  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, installeert u de Azure Cosmos DB clientbibliotheek voor .NET Core met behulp van de dotnet add package opdracht :

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

Kopieer uw Azure Cosmos-accountaanmeldingsgegevens vanuit de Azure-portal

De voorbeeldtoepassing moet de toegang tot uw Azure Cosmos-account verifiëren. Geef voor verificatie de referenties van het Azure Cosmos-account door aan de toepassing. U kunt de aanmeldingsgegevens van het opslagaccount weergeven door de volgende stappen te volgen:

1. Meld u aan bij de Azure-portal.

2. Ga naar uw Azure Cosmos-account.

3. Open het deelvenster Sleutels en kopieer de waarden voor de 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 bouwen van de toepassing, kijken we naar 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 te communiceren met deze resources:

• CosmosClient. Deze klasse biedt een logische weergave aan de clientzijde voor de Azure Cosmos DB service. Het clientobject wordt gebruikt om aanvragen aan de service te configureren en uitvoeren.
• CreateDatabaseIfNotExistsAsync. Met deze methode maakt u (als deze nog niet bestaat) of haalt u (als deze al bestaat) een databaseresource op als een asynchrone bewerking.
• CreateContainerIfNotExistsAsync. Met deze methode maakt u (als deze nog niet bestaat) of haalt u (als deze al bestaat) een container op als een asynchrone bewerking. 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 maakt u een item in de container.
• UpsertItemAsync. Met deze methode maakt u een item in de container als dit nog niet bestaat of vervangt u het item als het al bestaat.
• GetItemQueryIterator. Met deze methode maakt u een query voor items onder een container in een Azure Cosmos-database met behulp van een SQL-instructie met geparameteriseerde waarden.
• DeleteAsync. Met deze methode wordt de opgegeven database verwijderd uit uw Azure Cosmos-account.

Codevoorbeelden configureren

Met de voorbeeldcode die in dit artikel wordt beschreven, wordt een familiedatabase gemaakt in Azure Cosmos DB. De familiedatabase 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 familie-item. Maak een nieuwe klasse met de naam Family.cs op het hoofdniveau van uw 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 using-instructies toevoegen en het clientobject definiëren

Open vanuit de projectmap het bestand Program.cs in uw editor en voeg de volgende instructies toe boven using aan uw toepassing:

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

Voeg in de Program-klasse de volgende globale variabelen toe: Deze variabelen omvatten het eindpunt en de autorisatiesleutels, de naam van de database en de container die u gaat maken. Zorg ervoor dat u de waarden voor eindpunt- en 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 methode Main:

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

Definieer de methode CreateDatabaseAsync binnen de klasse program.cs. Met deze methode wordt FamilyDatabase de 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

Definieer de methode CreateContainerAsync binnen de klasse Program. 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 familie-item door de methode AddItemsToContainerAsync toe te voegen met de volgende code. U kunt de methode CreateItemAsync of gebruiken om een item te UpsertItemAsync 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. De volgende code laat zien hoe u de query rechtstreeks uitvoert met behulp van SQL query. De SQL om de details van de Andersen-familie op te halen, is SELECT * FROM c WHERE c.LastName = 'Andersen' . Definieer de methode QueryItemsAsync binnen de klasse Program 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 familie-item en werk het vervolgens bij door de methode ReplaceFamilyItemAsync toe te voegen 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 familie-item door de methode DeleteFamilyItemAsync 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, moet u het bestand Program.cs opslaan.

De code uitvoeren

Voer de toepassing uit om de Azure Cosmos DB 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 controleren of de gegevens zijn gemaakt door u aan te melden bij de Azure Portal de vereiste items in uw Azure Cosmos-account te bekijken.

Resources opschonen

Wanneer u het Azure Cosmos-account en de bijbehorende resourcegroep niet meer nodig hebt, kunt u de Azure CLI of Azure PowerShell gebruiken om ze te verwijderen. In de volgende opdracht ziet u hoe u de resourcegroep verwijdert met behulp van 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 met behulp van de instructies in het volgende artikel:

Probeert u capaciteitsplanning uit te 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 behulp van vCores of vCCPUs
• Als u de gebruikelijke aanvraagsnelheden voor uw huidige databaseworkload kent, leest u over het schatten van aanvraageenheden met behulp Azure Cosmos DB capacity planner