Självstudie: Utveckla ett .NET-konsolprogram med Azure Cosmos DB för NoSQL

  • Artikel

GÄLLER FÖR: NoSQL

Med Azure SDK för .NET kan du lägga till data i ett API för NoSQL-container, antingen asynkrona enskilda åtgärder eller en transaktionsbatch. I den här självstudien går vi igenom processen med att skapa ett nytt .NET-konsolprogram som lägger till flera objekt i en container.

I den här självstudien lär du dig att:

  • Skapa en databas med API för NoSQL
  • Skapa ett .NET-konsolprogram och lägg till Azure SDK för .NET
  • Lägga till enskilda objekt i ett API för NoSQL-container
  • Hämta objekt som är effektiva från ett API för NoSQL-container
  • Skapa en transaktion med batchändringar för API:et för NoSQL-containern

Förutsättningar

Skapa API för NoSQL-resurser

Skapa först en tom databas i det befintliga API:et för NoSQL-kontot. Du skapar en container med hjälp av Azure SDK för .NET senare.

  1. Gå till ditt befintliga API för NoSQL-konto i Azure-portalen.

  2. I resursmenyn väljer du Nycklar.

    Screenshot of an API for NoSQL account page. The Keys option is highlighted in the resource menu.

  3. På sidan Nycklar observerar och registrerar du värdet för fälten URI och PRIMÄRNYCKEL . Dessa värden kommer att användas under hela självstudien.

    Screenshot of the Keys page with the URI and Primary Key fields highlighted.

  4. I resursmenyn väljer du Datautforskaren.

    Screenshot of the Data Explorer option highlighted in the resource menu.

  5. På sidan Datautforskarenväljer du alternativet Ny databas i kommandofältet.

    Screenshot of the New Database option in the Data Explorer command bar.

  6. I dialogrutan Ny databas skapar du en ny container med följande inställningar:

    Värde
    Databas-ID cosmicworks
    Databasdataflödestyp Manuell
    Databasdataflödesbelopp 400

    Screenshot of the New Database dialog in the Data Explorer with various values in each field.

  7. Välj OK för att skapa databasen.

Skapa .NET-konsolprogram

Nu ska du skapa ett nytt .NET-konsolprogram och importera Azure SDK för .NET med hjälp Microsoft.Azure.Cosmos av biblioteket från NuGet.

  1. Öppna en terminal i en tom katalog.

  2. Skapa ett nytt konsolprogram med den console inbyggda mallen

    dotnet new console --langVersion preview

  3. Lägg till 3.31.1-förhandsversionen av Microsoft.Azure.Cosmos paketet från NuGet.

    dotnet add package Microsoft.Azure.Cosmos --version 3.31.1-preview

  4. Lägg också till förhandsversionen av System.CommandLine paketet från NuGet.

    dotnet add package System.CommandLine --prerelease

  5. Lägg också till Humanizer paketet från NuGet.

    dotnet add package Humanizer

  6. Skapa konsolprogramprojektet.

    dotnet build

  7. Öppna Visual Studio Code med den aktuella projektmappen som arbetsyta.

    Dricks

    Du kan köra code . i terminalen för att öppna Visual Studio Code och automatiskt öppna arbetskatalogen som den aktuella arbetsytan.

  8. Gå till och öppna filen Program.cs . Ta bort all befintlig kod i filen.

  9. Lägg till den här koden i filen för att använda biblioteket System.CommandLine för att parsa kommandoraden för två strängar som skickas via --first alternativen och --last .

    using System.CommandLine;

var command = new RootCommand();

var nameOption = new Option<string>("--name") { IsRequired = true };
var emailOption = new Option<string>("--email");
var stateOption = new Option<string>("--state") { IsRequired = true };
var countryOption = new Option<string>("--country") { IsRequired = true };

command.AddOption(nameOption);
command.AddOption(emailOption);
command.AddOption(stateOption);
command.AddOption(countryOption);

command.SetHandler(
    handle: CosmosHandler.ManageCustomerAsync, 
    nameOption, 
    emailOption,
    stateOption,
    countryOption
);

await command.InvokeAsync(args);

    Kommentar

    I den här självstudien är det inte helt viktigt att du förstår hur kommandoradsparsern fungerar. Parsern har fyra alternativ som kan anges när programmet körs. Tre av alternativen krävs eftersom de används för att konstruera ID- och partitionsnyckelfälten.

  10. Nu skapas inte projektet eftersom du inte har definierat den statiska CosmosHandler.ManageCustomerAsync metoden ännu.

  11. Spara filen Program.cs.

Lägga till objekt i en container med hjälp av SDK

Sedan använder du enskilda åtgärder för att lägga till objekt i API:et för NoSQL-containern. I det här avsnittet definierar CosmosHandler.ManageCustomerAsync du metoden.

  1. Skapa en ny CosmosHandler.cs-fil .

  2. I filen CosmosHandler.cs lägger du till ett nytt användningsdirektiv för Humanizer namnrymderna och Microsoft.Azure.Cosmos .

    using Humanizer;
using Microsoft.Azure.Cosmos;

  3. Skapa en ny statisk klass med namnet CosmosHandler.

    public static class CosmosHandler
{ }

  4. Bara för att verifiera att den här appen fungerar skapar du en kort implementering av den statiska ManageCustomerAsync metoden för att skriva ut kommandoradsindata.

    public static async Task ManageCustomerAsync(string name, string email, string state, string country)
{
    await Console.Out.WriteLineAsync($"Hello {name} of {state}, {country}!");
}

  5. Spara filen CosmosHandler.cs.

  6. Kör programmet i terminalen.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  7. Kommandots utdata bör vara en rolig hälsning.

    Hello Mica Pereira of Washington, United States!

  8. Gå tillbaka till filen CosmosHandler.cs .

  9. I den statiska CosmosHandler-klassen lägger du till en ny private static readonly medlem av typen CosmosClient med namnet _client.

    private static readonly CosmosClient _client;

  10. Skapa en ny statisk konstruktor för CosmosHandler klassen.

    static CosmosHandler()
{ }

  11. I konstruktorn skapar du en ny instans av CosmosClient klassen som skickar in två strängparametrar med de URI - och PRIMARY KEY-värden som du tidigare registrerade i labbet. Lagra den här nya instansen _client i medlemmen.

    static CosmosHandler()
{
    _client = new CosmosClient(
        accountEndpoint: "<uri>", 
        authKeyOrResourceToken: "<primary-key>"
    );
}

  12. Tillbaka i den statiska CosmosHandler-klassen skapar du en ny asynkron metod med namnet GetContainerAsync som returnerar en Container.

    private static async Task<Container> GetContainer()
{ }

  13. Lägg till den här koden i metoden för GetContainerAsync nästa steg.

    1. cosmicworks Hämta databasen och lagra den i en variabel med namnet database.

      Database database = _client.GetDatabase("cosmicworks");

    2. Skapa ett nytt generiskt List<>string värde i en lista över hierarkiska partitionsnyckelsökvägar och lagra den i en variabel med namnet keyPaths.

      List<string> keyPaths = new()
{
    "/address/country",
    "/address/state"
};

    3. Skapa en ny ContainerProperties variabel med namnet på containern (customers) och listan över partitionsnyckelsökvägar.

      ContainerProperties properties = new(
    id: "customers",
    partitionKeyPaths: keyPaths
);

    4. CreateContainerIfNotExistsAsync Använd metoden för att ange containeregenskaperna och hämta containern. Den här metoden skapar, per namn, containern asynkront om den inte redan finns i databasen. Returnera resultatet som utdata för GetContainerAsync metoden.

      return await database.CreateContainerIfNotExistsAsync(
    containerProperties: properties
);

  14. Ta bort all kod i ManageCustomerAsync metoden.

  15. Lägg till den här koden i metoden för ManageCustomerAsync nästa steg.

    1. Anropa GetContainerAsync metoden asynkront och lagra resultatet i en variabel med namnet container.

      Container container = await GetContainerAsync();

    2. Skapa en ny variabel med namnet id som använder Kebaberize metoden från Humanizer för att transformera metodparametern name .

      string id = name.Kebaberize();

      Kommentar

      Metoden Kebaberize ersätter alla blanksteg med bindestreck och sammanfogar texten till gemener.

    3. Skapa ett nytt anonymt skrivobjekt med hjälp av parametrarna name, stateoch country -metoden och variabeln id . Lagra objektet som en variabel med namnet customer.

      var customer = new {
    id = id,
    name = name,
    address = new {
        state = state,
        country = country
    }
};

    4. Använd containerns asynkrona CreateItemAsync metod för att skapa ett nytt objekt i containern och tilldela HTTP-svarsmetadata till en variabel med namnet response.

      var response = await container.CreateItemAsync(customer);

    5. Skriv värdena för variabelns responseStatusCode och RequestCharge egenskaperna till konsolen. Skriv även värdet för variabeln id .

      Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");

  16. Spara filen CosmosHandler.cs.

  17. Kör programmet igen i terminalen.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  18. Kommandots utdata bör innehålla en status- och begärandeavgift för åtgärden.

    [Created]       mica-pereira    7.05 RUs

    Kommentar

    Din begärandeavgift kan variera.

  19. Kör programmet en gång till.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  20. Den här gången bör programmet krascha. Om du bläddrar igenom felmeddelandet ser du att kraschen inträffade på grund av en konflikt i den unika identifieraren för objekten.

    Unhandled exception: Microsoft.Azure.Cosmos.CosmosException : Response status code does not indicate success: Conflict (409);Reason: (
    Errors : [
      "Resource with specified id or name already exists."
    ]
);

Hämta ett objekt med hjälp av SDK

Nu när du har skapat ditt första objekt i containern kan du använda samma SDK för att hämta objektet. Här frågar och pekar du på objektet för att jämföra skillnaden i RU-förbrukning (request unit).

  1. Gå tillbaka till eller öppna filen CosmosHandler.cs .

  2. Ta bort alla kodrader från ManageCustomerAsync metoden förutom de två första raderna.

    public static async Task ManageCustomerAsync(string name, string email, string state, string country)
{
    Container container = await GetContainerAsync();

    string id = name.Kebaberize();
}

  3. Lägg till den här koden i metoden för ManageCustomerAsync nästa steg.

    1. Använd containerns asynkrona CreateItemAsync metod för att skapa ett nytt objekt i containern och tilldela HTTP-svarsmetadata till en variabel med namnet response.

      var response = await container.CreateItemAsync(customer);

    2. Skapa en ny sträng med namnet sql med en SQL-fråga för att hämta objekt där ett filter (@id) matchar.

      string sql = """
SELECT
    *
FROM customers c
WHERE c.id = @id
""";

    3. Skapa en ny QueryDefinition variabel med namnet query som skickar in strängen sql som den enda frågeparametern. WithParameter Använd även vätskemetoden för att tillämpa värdet för variabeln id på parametern@id.

      var query = new QueryDefinition(
    query: sql
)
    .WithParameter("@id", id);

    4. Använd den GetItemQueryIterator<> allmänna metoden och variabeln query för att skapa en iterator som hämtar data från Azure Cosmos DB. Lagra iteratorn i en variabel med namnet feed. Omslut hela uttrycket i en using-instruktion för att ta bort iteratorn senare.

      using var feed = container.GetItemQueryIterator<dynamic>(
    queryDefinition: query
);

    5. Anropa ReadNextAsync metoden för variabeln feed asynkront och lagra resultatet i en variabel med namnet response.

      var response = await feed.ReadNextAsync();

    6. Skriv värdena för variabelns responseStatusCode och RequestCharge egenskaperna till konsolen. Skriv även värdet för variabeln id .

      Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");

  4. Spara filen CosmosHandler.cs.

  5. Tillbaka i terminalen kör du programmet för att läsa det enskilda objektet med hjälp av en SQL-fråga.

    dotnet run -- --name 'Mica Pereira'

  6. Kommandots utdata bör indikera att frågan krävde flera RU:er.

    [OK]    mica-pereira    2.82 RUs

  7. Tillbaka i filen CosmosHandler.cs tar du bort alla kodrader från ManageCustomerAsync metoden igen förutom de två första raderna.

    public static async Task ManageCustomerAsync(string name, string email, string state, string country)
{
    Container container = await GetContainerAsync();

    string id = name.Kebaberize();
}

  8. Lägg till den här koden i metoden för ManageCustomerAsync nästa steg.

    1. Skapa en ny instans av PartitionKeyBuilder genom att lägga till parametrarna state och country som ett partitionsnyckelvärde i flera delar.

      var partitionKey = new PartitionKeyBuilder()
    .Add(country)
    .Add(state)
    .Build();

    2. Använd containerns ReadItemAsync<> metod för att peka på att läsa objektet från containern med hjälp av variablerna id och partitionKey . Spara resultatet i en variabel med namnet response.

      var response = await container.ReadItemAsync<dynamic>(
    id: id, 
    partitionKey: partitionKey
);

    3. Skriv värdena för variabelns responseStatusCode och RequestCharge egenskaperna till konsolen. Skriv även värdet för variabeln id .

      Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RU");

  9. Spara filen CosmosHandler.csigen.

  10. Tillbaka i terminalen kör du programmet en gång till för att peka på att läsa det enskilda objektet.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  11. Utdata från kommandot bör indikera att frågan krävde en enskild RU.

    [OK]    mica-pereira    1 RUs

Skapa en transaktion med hjälp av SDK

Slutligen tar du det objekt som du skapade, läser objektet och skapar ett annat relaterat objekt som en del av en enda transaktion med hjälp av Azure SDK för .NET.

  1. Gå tillbaka till eller öppna filen CosmosHandler.cs .

  2. Ta bort dessa kodrader från ManageCustomerAsync metoden.

    var response = await container.ReadItemAsync<dynamic>(
    id: id, 
    partitionKey: partitionKey
);

Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");

  3. Lägg till den nya koden i ManageCustomerAsync metoden för nästa steg.

    1. Skapa ett nytt anonymt skrivobjekt med hjälp av parametrarna name, stateoch country -metoden och variabeln id . Lagra objektet som en variabel med namnet customerCart. Det här objektet representerar en kundvagn i realtid för kunden som för närvarande är tom.

      var customerCart = new {
    id = $"{Guid.NewGuid()}",
    customerId = id,
    items = new string[] {},
    address = new {
        state = state,
        country = country
    }
};

    2. Skapa ett annat anonymt skrivet objekt med hjälp av parametrarna name, stateoch country -metoden och variabeln id . Lagra objektet som en variabel med namnet customerCart. Det här objektet representerar leverans- och kontaktinformation för kunden.

      var customerContactInfo = new {
    id = $"{id}-contact",
    customerId = id,
    email = email,
    location = $"{state}, {country}",
    address = new {
        state = state,
        country = country
    }
};

    3. Skapa en ny batch med hjälp av containerns CreateTransactionalBatch metod som skickar in variabeln partitionKey . Lagra batchen i en variabel med namnet batch. Använd fluent-metoder för att utföra följande åtgärder:

      Metod Parameter
      ReadItem id strängvariabel
      CreateItem customerCart variabel för anonym typ
      CreateItem customerContactInfo variabel för anonym typ 
      var batch = container.CreateTransactionalBatch(partitionKey)
    .ReadItem(id)
    .CreateItem(customerCart)
    .CreateItem(customerContactInfo);

    4. Använd batchmetoden ExecuteAsync för att starta transaktionen. Spara resultatet i en variabel med namnet response.

      using var response = await batch.ExecuteAsync();

    5. Skriv värdena för variabelns responseStatusCode och RequestCharge egenskaperna till konsolen. Skriv även värdet för variabeln id .

      Console.WriteLine($"[{response.StatusCode}]\t{response.RequestCharge} RUs");

  4. Spara filen CosmosHandler.csigen.

  5. Tillbaka i terminalen kör du programmet en gång till för att peka på att läsa det enskilda objektet.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  6. Utdata från kommandot ska visa de enheter för begäran som används för hela transaktionen.

    [OK]    16.05 RUs

    Kommentar

    Din begärandeavgift kan variera.

Verifiera de slutliga data i Datautforskaren

Om du vill avsluta saker använder du Datautforskaren i Azure-portalen för att visa data och containern som du skapade i den här självstudien.

  1. Gå till ditt befintliga API för NoSQL-konto i Azure-portalen.

  2. I resursmenyn väljer du Datautforskaren.

    Screenshot of the Data Explorer option highlighted in the resource menu.

  3. På sidan Datautforskaren expanderar du cosmicworks databasen och väljer sedan containern customers .

    Screenshot of the selected container node within the database node.

  4. I kommandofältet väljer du Ny SQL-fråga.

    Screenshot of the New SQL Query option in the Data Explorer command bar.

  5. Observera den här SQL-frågesträngen i frågeredigeraren.

    SELECT * FROM c

  6. Välj Kör fråga för att köra frågan och observera resultatet.

    Screenshot of the Execute Query option in the Data Explorer command bar.

  7. Resultatet bör innehålla en JSON-matris med tre objekt som skapats i den här självstudien. Observera att alla objekt har samma hierarkiska partitionsnyckelvärde, men unika ID-fält. Exempelutdata som ingår trunkeras för korthet.

    [
  {
    "id": "mica-pereira",
    "name": "Mica Pereira",
    "address": {
      "state": "Washington",
      "country": "United States"
    },
    ...
  },
  {
    "id": "33d03318-6302-4559-b5c0-f3cc643b2f38",
    "customerId": "mica-pereira",
    "items": [],
    "address": {
      "state": "Washington",
      "country": "United States"
    },
    ...
  },
  {
    "id": "mica-pereira-contact",
    "customerId": "mica-pereira",
    "email": null,
    "location": "Washington, United States",
    "address": {
      "state": "Washington",
      "country": "United States"
    },
    ...
  }
]

Rensa resurser

Ta bort databasen som används i den här självstudien när den inte längre behövs. Det gör du genom att gå till kontosidan, välja Datautforskarencosmicworks, välja databasen och sedan ta bort.

Nästa steg

Nu när du har skapat ditt första .NET-konsolprogram med Hjälp av Azure Cosmos DB kan du prova nästa självstudie där du uppdaterar ett befintligt webbprogram för att använda Azure Cosmos DB-data.

Självstudie: Utveckla en ASP.NET webbapp med Azure Cosmos DB för NoSQL