Snabbstart: Skapa en konsolapp med hjälp av .NET V4 SDK (förhandsversion) för att hantera Azure Cosmos DB SQL API-kontoresurser

Artikel
11/24/2021
13 minuter för att läsa

GÄLLER FÖR: SQL API

Kom igång med Azure Cosmos DB SQL API-klientbiblioteket för .NET. Följ stegen i den här artikeln för att installera .NET V4-paketet (Azure.Cosmos) och skapa en app. Prova sedan exempelkoden för grundläggande CRUD-åtgärder (skapa, läsa, uppdatera och ta bort) på data som lagras i Azure Cosmos DB.

Viktigt

.NET V4 SDK för Azure Cosmos DB för närvarande i offentlig förhandsversion. Den här förhandsversionen tillhandahålls utan serviceavtal och vi rekommenderar det inte för produktionsarbetsbelastningar. Vissa funktioner kanske inte stöds eller kan vara begränsade.

Mer information finns i Kompletterande villkor för användning av Microsoft Azure-förhandsversioner.

Azure Cosmos DB är Microsofts snabba NoSQL-databas med öppna API:er för alla skalor. Du kan använda Azure Cosmos DB för att snabbt skapa och fråga efter nyckel/värde-, dokument- och grafdatabaser. Använd Azure Cosmos DB SQL API-klientbiblioteket för .NET för att:

Skapa en Azure Cosmos-databas och en container.
Lägg till exempeldata i containern.
Fråga efter data.
Ta bort databasen.

Bibliotekskällkod | Paket (NuGet)

Förutsättningar

En Azure-prenumeration. Skapa ett utan kostnad. Du kan också prova Azure Cosmos DB utan en Azure-prenumeration, utan kostnad och åtaganden.
NET Core 3 SDK. Du kan kontrollera vilken version som är tillgänglig i din miljö genom att köra dotnet --version .

Konfigurera

Det här avsnittet vägled dig genom att skapa ett Azure Cosmos-konto och konfigurera ett projekt som använder Azure Cosmos DB SQL API-klientbiblioteket för .NET för att hantera resurser.

Exempelkoden som beskrivs i den här artikeln skapar FamilyDatabase en databas och en gruppmedlemmar i databasen. Varje familjemedlem är ett objekt och har egenskaper som Id , , , , , och FamilyName FirstName LastName Parents Children Address . Egenskapen LastName används som partitionsnyckel för containern.

Skapa ett Azure Cosmos-konto

Om du använder alternativet Prova Azure Cosmos DB kostnadsfritt för att skapa ett Azure Cosmos-konto måste du skapa ett Azure Cosmos-konto av typen SQL API. Ett Azure Cosmos-testkonto har redan skapats åt dig. Du behöver inte skapa kontot uttryckligen, så du kan hoppa över det här avsnittet och gå vidare till nästa avsnitt.

Om du har en egen Azure-prenumeration eller om du har skapat en prenumeration kostnadsfritt bör du uttryckligen skapa ett Azure Cosmos-konto. Följande kod skapar ett Azure Cosmos-konto med sessionskonsekvens. Kontot replikeras i South Central US och North Central US .

Du kan använda Azure Cloud Shell för att skapa Azure Cosmos-kontot. Azure Cloud Shell är ett interaktivt, autentiserat skal för hantering av Azure-resurser via webbläsare. Det ger dig flexibiliteten att välja den gränssnittsupplevelse som passar bäst för ditt sätt att arbeta: antingen Bash eller PowerShell.

I den här snabbstarten använder du Bash. Azure Cloud Shell kräver också ett lagringskonto. Du kan skapa en när du uppmanas till det.

Välj knappen Prova bredvid följande kod, välj Bash-läge, välj Skapa ett lagringskonto och logga in på Cloud Shell.

Kopiera och klistra in följande kod för att Azure Cloud Shell och köra den. Azure Cosmos-kontonamnet måste vara globalt unikt, så se till att uppdatera mysqlapicosmosdb värdet innan du kör kommandot.


# 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

Det tar en stund att skapa Azure Cosmos-kontot. När åtgärden har lyckats kan du se bekräftelseutdata. Logga in på Azure Portal och kontrollera att Azure Cosmos-kontot med det angivna namnet finns. Du kan stänga Azure Cloud Shell när resursen har skapats.

Skapa en NET-app

Skapa ett .NET-program i önskat redigeringsprogram eller IDE. Öppna Windows kommandotolken eller ett terminalfönster från den lokala datorn. Du kör alla kommandon i nästa avsnitt från kommandotolken eller terminalen.

Kör följande kommando dotnet new för att skapa en app med namnet todo . Parametern --langVersion anger egenskapen i den skapade LangVersion projektfilen.

dotnet new console --langVersion:8 -n todo

Använd följande kommandon för att ändra katalogen till den nyligen skapade appmappen och skapa programmet:

cd todo
dotnet build

Förväntade utdata från bygget bör se ut ungefär så här:

  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

Installera Azure Cosmos DB paketet

När du fortfarande är i programkatalogen installerar du Azure Cosmos DB för .NET Core med hjälp av dotnet add package kommandot :

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

Kopiera autentiseringsuppgifterna för ditt Azure Cosmos-konto från Azure Portal

Exempelprogrammet måste autentisera till ditt Azure Cosmos-konto. För att autentisera skickar du autentiseringsuppgifterna för Azure Cosmos-kontot till programmet. Hämta autentiseringsuppgifterna för ditt Azure Cosmos-konto genom att följa dessa steg:

Logga in på Azure-portalen.
Gå till ditt Azure Cosmos-konto.
Öppna fönstret Nycklar och kopiera värdena för URI och PRIMÄRNYCKEL för ditt konto. Du lägger till URI:en och nyckelvärdena i en miljövariabel i nästa procedur.

Lär dig objektmodellen

Innan du fortsätter att skapa programmet ska vi titta på hierarkin med resurser i Azure Cosmos DB och objektmodellen som används för att skapa och komma åt dessa resurser. Azure Cosmos DB skapar resurser i följande ordning:

Azure Cosmos-konto
Databaser
Containers
Poster

Mer information om entitetshierarkin finns i artikeln Azure Cosmos DB om resursmodell. Du använder följande .NET-klasser för att interagera med dessa resurser:

CosmosClient. Den här klassen tillhandahåller en logisk representation på klientsidan för Azure Cosmos DB tjänsten. Klientobjektet används för att konfigurera och köra begäranden mot tjänsten.
CreateDatabaseIfNotExistsAsync. Den här metoden skapar (om den inte finns) eller hämtar (om den redan finns) en databasresurs som en asynkron åtgärd.
CreateContainerIfNotExistsAsync. Den här metoden skapar (om den inte finns) eller hämtar (om den redan finns) en container som en asynkron åtgärd. Du kan kontrollera statuskoden från svaret för att avgöra om containern skapades nyligen (201) eller om en befintlig container returnerades (200).
CreateItemAsync. Den här metoden skapar ett objekt i containern.
UpsertItemAsync. Den här metoden skapar ett objekt i containern om det inte redan finns eller ersätter objektet om det redan finns.
GetItemQueryIterator. Den här metoden skapar en fråga för objekt under en container i en Azure Cosmos-databas med hjälp av en SQL-instruktion med parametriserade värden.
DeleteAsync. Den här metoden tar bort den angivna databasen från ditt Azure Cosmos-konto.

Konfigurera kodexempel

Exempelkoden som beskrivs i den här artikeln skapar en familjedatabas i Azure Cosmos DB. Familjedatabasen innehåller familjeinformation som namn, adress, plats, föräldrar, barn och husdjur.

Innan du fyller i data för ditt Azure Cosmos-konto definierar du egenskaperna för ett familjeobjekt. Skapa en ny klass med Family.cs namnet på rotnivån för exempelprogrammet och lägg till följande kod i den:

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; }
    }
}

Lägg till using-direktiv och definiera klientobjektet

Från projektkatalogen öppnar du filen Program.cs i redigeringsprogrammet och lägger till using följande -direktiv överst i programmet:

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

Lägg till följande globala variabler i klassen Program . Dessa variabler innehåller slutpunkts- och auktoriseringsnycklar, namnet på databasen och den container som du skapar. Se till att ersätta värdena för slutpunkt och auktoriseringsnyckel enligt din miljö.

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";

Ersätt slutligen Main metoden :

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);
}

Skapa en databas

Definiera CreateDatabaseAsync metoden i program.cs klassen . Den här metoden FamilyDatabase skapar databasen om den inte redan finns.

/// <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);
}

Skapa en container

Definiera CreateContainerAsync metoden i Program klassen . Den här metoden skapar FamilyContainer containern om den inte redan finns.

/// <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);
}

Skapa ett objekt

Skapa ett familjeobjekt genom att lägga AddItemsToContainerAsync till metoden med följande kod. Du kan använda metoden CreateItemAsync eller för att skapa ett UpsertItemAsync objekt.

/// <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);
}

Fråga objekten

När du har infogat ett objekt kan du köra en fråga för att få information om familjen Andersen. Följande kod visar hur du kör frågan med hjälp av SQL fråga direkt. Den SQL frågan för att hämta information om Andersen-familjen är SELECT * FROM c WHERE c.LastName = 'Andersen' . Definiera metoden QueryItemsAsync i klassen och lägg till följande kod i Program den:

/// <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);
    }
}

Ersätta ett objekt

Läs ett familjeobjekt och uppdatera det genom att lägga ReplaceFamilyItemAsync till metoden med följande kod:

/// <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);
}

Ta bort ett objekt

Ta bort ett familjeobjekt genom att DeleteFamilyItemAsync lägga till metoden med följande kod:

/// <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);
}

Ta bort databasen

Du kan ta bort databasen genom att lägga DeleteDatabaseAndCleanupAsync till metoden med följande kod:

/// <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);
}

När du har lagt till alla metoder som krävs sparar du filen Program.cs.

Kör koden

Kör programmet för att skapa Azure Cosmos DB resurser:

dotnet run

Följande utdata genereras när du kör programmet:

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.

Du kan verifiera att data skapas genom att logga in på Azure Portal och se de nödvändiga objekten i ditt Azure Cosmos-konto.

Rensa resurser

När du inte längre behöver Azure Cosmos-kontot och motsvarande resursgrupp kan du använda Azure CLI eller Azure PowerShell för att ta bort dem. Följande kommando visar hur du tar bort resursgruppen med hjälp av Azure CLI:

az group delete -g "myResourceGroup"

Nästa steg

I den här snabbstarten har du lärt dig hur du skapar ett Azure Cosmos-konto, skapar en databas och skapar en container med hjälp av en .NET Core-app. Du kan nu importera mer data till ditt Azure Cosmos-konto med hjälp av anvisningarna i följande artikel:

Försöker du göra kapacitetsplanering för en migrering till Azure Cosmos DB? Du kan använda information om ditt befintliga databaskluster för kapacitetsplanering.

Om allt du vet är antalet virtuella kärnor och servrar i ditt befintliga databaskluster kan du läsa om att uppskatta enheter för programbegäran med hjälp av virtuella kärnor eller virtuella processorer
Om du känner till vanliga begärandefrekvenser för din aktuella databasarbetsbelastning kan du läsa om att uppskatta enheter för programbegäran med Azure Cosmos DB kapacitetsplaneraren

Importera data till Azure Cosmos DB