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

GÄLLER FÖR: SQL API

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

Viktigt

.NET V4 SDK för Azure Azure AzureS DB är för närvarande en offentlig förhandsversion. Den här förhandsversionen tillhandahålls utan ett servicenivåavtal och vi rekommenderar den inte för produktionsarbetsbelastningar. Vissa funktioner kanske inte stöds eller kan ha begränsade funktioner.

Mer information finns i Kompletterande användningsvillkor för våra Microsoft Azure förhandsversioner.

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

  • Skapa en Azure Azure Azures-databas och en behållare.
  • Lägg till exempeldata i behållaren.
  • Skapa en fråga för data.
  • Ta bort databasen.

BibliotekskällakodPaket (NuGet)

Krav

Konfigurera

I det här avsnittet får du hjälp med att skapa ett Azure Azures-konto och konfigurera ett projekt som använder Azure Azure Azures DB SQL API-klientbibliotek för .NET för att hantera resurser.

Den exempelkod som beskrivs i den här artikeln skapar FamilyDatabase en databas och familjemedlemmar i den databasen. Varje familjemedlem är ett objekt och har egenskaper som Id , , , , , och FamilyNameFirstNameLastNameParentsChildrenAddress . Egenskapen LastName används som partitionsnyckel för behållaren.

Skapa ett Azure Azure Azures-konto

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

Om du har en egen Azure-prenumeration eller skapat en prenumeration kostnadsfritt bör du skapa ett Azure Azures-konto. Följande kod skapar ett Azure Azures-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 Azure Azures-kontot. Azure Cloud Shell är ett interaktivt, autentiserat, webbläsartillgängligt gränssnitt för hantering av Azure-resurser. Det ger flexibiliteten att välja det gränssnitt som passar bäst på det sätt du arbetar: antingen Bash eller PowerShell.

Använd Bash för den här snabbstarten. Azure Cloud Shell kräver också ett lagringskonto. Du kan skapa en när du uppmanas att göra det.

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

  2. Kopiera och klistra in följande kod i Azure Cloud Shell och kör den. Azure Azure Azures-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 ett tag att skapa Azure Azure Azures-kontot. När åtgärden har lyckats visas bekräftelsedata. Logga in på Azure Portal och kontrollera att Azure Azure Azures-kontot med det angivna namnet finns. Du kan stänga Azure Cloud Shell-fönstret när resursen har skapats.

Skapa en .NET-app

Skapa ett .NET-program i den redigerare eller det IDE du föredrar. Ö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 din katalog till den nyligen skapade programmappen och skapa programmet:

cd todo
dotnet build

Den förväntade utdata från versionen 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 Azure Azures DB-paketet

Medan du fortfarande är i programkatalogen installerar du Azure Azure Azures DB-klientbibliotek för .NET Core med hjälp av dotnet add package kommandot:

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

Kopiera dina autentiseringsuppgifter för Azure Azure Azures-kontot från Azure Portal

Exempelprogrammet måste autentiseras för ditt Azure Azure Azure-konto. Du autentiserar genom att överföra Azure Azure Azures-kontouppgifterna till programmet. Skaffa dina azure Azure Azures-kontoautentiseringsuppgifter genom att följa de här stegen:

  1. Logga in på Azure Portal.

  2. Gå till ditt Azure Azure Azures-konto.

  3. Öppna fönstret Nycklar och kopiera URI- ochPRIMÄRNYCKEL-värdena för kontot. Du lägger till URI-värden och nyckelvärden till en miljövariabel i nästa procedur.

Lär dig objektmodellen

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

  • Azure Azure Azures-konto
  • Databaser
  • Behållare
  • Artiklar

Mer information om enheternas hierarki finns i artikeln Azure Azure Azures DB-resursmodell. Du använder följande .NET-klasser för att interagera med de här resurserna:

  • CosmosClient. Den här klassen utgör en logisk representation på klientsidan för Azure Azure Azures 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 behållare som en asynkron åtgärd. Du kan kontrollera statuskoden från svaret för att avgöra om behållaren skapades (201) eller om en befintlig behållare returnerades (200).
  • CreateItemAsync. Med den här metoden skapas ett objekt i behållaren.
  • UpsertItemAsync. Med den här metoden skapas ett objekt i behållaren om det inte redan finns eller ersätter objektet om det redan finns.
  • GetItemQueryIterator. Med den här metoden skapas en fråga för objekt under en behållare i en Azure Azure-databas genom att ett SQL med parametervärden.
  • DeleteAsync. Den här metoden tar bort den angivna databasen från ditt Azure Azure Azure-konto.

Konfigurera kodexempel

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

Innan du fyller i data för Azure Azure Azure-kontot definierar du egenskaperna för ett familjeobjekt. Skapa en ny klass Family.cs som namnges på rotnivån i 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ägga till med hjälp av en direktiv och definiera klientobjektet

Öppna filen Program.cs i projektkatalogen i redigeraren och lägg till följande direktiv högst upp 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 Program klassen. De här variablerna innehåller slutpunkten och auktoriseringsnycklarna, namnet på databasen och behållaren som du skapar. Se till att ersätta slutpunkten och auktoriseringsnyckelvärdena i enlighet med 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 sedan 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. Med den här metoden FamilyDatabase skapas 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 behållare

Definiera CreateContainerAsync metoden i Program klassen. Den här metoden skapar FamilyContainer behållaren 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 eller CreateItemAsync metoden 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);
}

Skapa en fråga för objekten

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

/// <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 sedan 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 nödvändiga metoder sparar du filen Program.cs.

Kör koden

Kör programmet för att skapa Azure Azure Azure Dbs 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-portalen och se de nödvändiga objekten i ditt Azure Azure Azures-konto.

Rensa resurser

När du inte längre behöver Azure Azures-kontot och motsvarande resursgrupp kan du använda Azure CLI eller Azure PowerShell 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 att skapa ett Azure Azure Azure-konto, skapa en databas och skapa en behållare med hjälp av en .NET Core-app. Nu kan du importera mer data till ditt Azure Azure Azure-konto genom att följa anvisningarna i följande artikel:

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