Kurz: Vývoj konzolové aplikace .NET pomocí služby Azure Cosmos DB for NoSQL

PLATÍ PRO: NoSQL

Sada Azure SDK pro .NET umožňuje přidat data do kontejneru API pro NoSQL buď asynchronní jednotlivé operace , nebo transakční dávku. Tento kurz vás provede procesem vytvoření nové konzolové aplikace .NET, která do kontejneru přidá více položek.

V tomto kurzu se naučíte:

• Vytvoření databáze pomocí rozhraní API pro NoSQL
• Vytvoření konzolové aplikace .NET a přidání sady Azure SDK pro .NET
• Přidání jednotlivých položek do kontejneru API for NoSQL
• Efektivní načtení položek z kontejneru API pro NoSQL
• Vytvoření transakce s dávkovými změnami pro kontejner ROZHRANÍ API pro NoSQL

Požadavky

• Existující účet Azure Cosmos DB for NoSQL.
  • Pokud máte existující předplatné Azure, vytvořte nový účet.
  • Žádné předplatné Azure? Službu Azure Cosmos DB můžete vyzkoušet zdarma bez nutnosti platební karty.
• Visual Studio Code
• .NET 8 nebo novější
• Zkušenosti s psaním aplikací v jazyce C#.

Vytvoření rozhraní API pro prostředky NoSQL

Nejprve vytvořte prázdnou databázi v existujícím účtu rozhraní API pro NoSQL. Kontejner vytvoříte pomocí sady Azure SDK pro .NET později.

1. Na webu Azure Portal přejděte ke svému stávajícímu účtu API for NoSQL.

2. V nabídce prostředků vyberte Klíče.

   

3. Na stránce Klíče sledujte a poznamenejte hodnotu polí identifikátoru URI a PRIMÁRNÍ KLÍČ. Tyto hodnoty se používají v průběhu kurzu.

   

4. V nabídce prostředků vyberte Průzkumník dat.

   

5. Na stránce Průzkumník dat vyberte na panelu příkazů možnost Nová databáze.

   

6. V dialogovém okně Nová databáze vytvořte nový kontejner s následujícím nastavením:

   	Hodnota
   ID databáze	cosmicworks
   Typ propustnosti databáze	Ruční
   Velikost propustnosti databáze	400

   

7. Vyberte OK a vytvořte databázi.

Vytvoření konzolové aplikace .NET

Teď vytvoříte novou konzolovou aplikaci .NET a naimportujete sadu Azure SDK pro .NET pomocí Microsoft.Azure.Cosmos knihovny z NuGetu.

1. Otevřete terminál v prázdném adresáři.

2. Vytvoření nové konzolové aplikace pomocí console předdefinované šablony

   Bash

   dotnet new console --langVersion preview
   

3. Přidejte verzi Microsoft.Azure.Cosmos balíčku verze 3.31.1-Preview z NuGetu.

   Bash

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

4. Přidejte také předběžnou verzi System.CommandLine balíčku z NuGetu.

   Bash

   dotnet add package System.CommandLine --prerelease
   

5. Humanizer Přidejte také balíček z NuGetu.

   Bash

   dotnet add package Humanizer
   

6. Sestavte projekt konzolové aplikace.

   Bash

   dotnet build
   

7. Otevřete Visual Studio Code pomocí aktuální složky projektu jako pracovního prostoru.

   Tip

   V terminálu můžete spustit code . visual Studio Code a automaticky otevřít pracovní adresář jako aktuální pracovní prostor.

8. Přejděte na soubor Program.cs a otevřete ho. Odstraňte veškerý existující kód v souboru.

9. Přidejte tento kód do souboru pro použití knihovny System.CommandLine k analýze příkazového řádku pro dva řetězce předané prostřednictvím --first a --last možností.

   C#

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

   Poznámka

   Pro účely tohoto kurzu není zcela důležité pochopit, jak analyzátor příkazového řádku funguje. Analyzátor má čtyři možnosti, které je možné zadat při spuštění aplikace. Tři z těchto možností jsou povinné, protože se použijí k vytvoření polí ID a klíče oddílu.

10. V tomto okamžiku se projekt nevytvoře, protože jste ještě nedefinovat statickou CosmosHandler.ManageCustomerAsync metodu.

11. Uložte soubor Program.cs.

Přidání položek do kontejneru pomocí sady SDK

Dále pomocí jednotlivých operací přidáte položky do kontejneru API pro NoSQL. V této části definujete metodu CosmosHandler.ManageCustomerAsync .

1. Vytvořte nový soubor CosmosHandler.cs .

2. Do souboru CosmosHandler.cs přidejte novou direktivu using pro obory Humanizer názvů a Microsoft.Azure.Cosmos obory názvů.

   C#

   using Humanizer;
   using Microsoft.Azure.Cosmos;
   

3. Vytvořte novou statickou třídu s názvem CosmosHandler.

   C#

   public static class CosmosHandler
   { }
   

4. Stačí ověřit, že tato aplikace funguje, vytvořte krátkou implementaci statické ManageCustomerAsync metody pro tisk vstupu příkazového řádku.

   C#

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

5. Uložte soubor CosmosHandler.cs.

6. Zpátky v terminálu spusťte aplikaci.

   Bash

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

7. Výstupem příkazu by měl být zábavný pozdrav.

   Output

   Hello Mica Pereira of Washington, United States!
   

8. Vraťte se do souboru CosmosHandler.cs .

9. Ve statické třídě CosmosHandler přidejte nového private static readonly člena typu CosmosClient s názvem _client.

   C#

   private static readonly CosmosClient _client;
   

10. Vytvořte nový statický konstruktor pro CosmosHandler třídu.

    C#

    static CosmosHandler()
    { }
    

11. V rámci konstruktoru CosmosClient vytvořte novou instanci třídy, která předává dva parametry řetězce s hodnotami URI a PRIMARY KEY , které jste předtím zaznamenali v testovacím prostředí. Uložte tuto novou instanci do člena _client .

    C#

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

12. Zpět ve statické třídě CosmosHandler vytvořte novou asynchronní metodu s názvemGetContainerAsync, která vrací .Container

    C#

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

13. Pro další kroky přidejte tento kód do GetContainerAsync metody.

    1. cosmicworks Získejte databázi a uložte ji do proměnné s názvem database.

       C#

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

    2. Vytvořte nový obecný typ List<> string hodnot v seznamu hierarchických cest klíčů oddílu a uložte ho do proměnné s názvem keyPaths.

       C#

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

    3. Vytvořte novou ContainerProperties proměnnou s názvem kontejneru (customers) a seznamem cest klíče oddílu.

       C#

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

    4. CreateContainerIfNotExistsAsync Pomocí metody zadejte vlastnosti kontejneru a načtěte kontejner. Tato metoda podle názvu asynchronně vytvoří kontejner, pokud ještě v databázi neexistuje. Vrátí výsledek jako výstup GetContainerAsync metody.

       C#

       return await database.CreateContainerIfNotExistsAsync(
           containerProperties: properties
       );
       

14. Odstraňte veškerý kód v rámci ManageCustomerAsync metody.

15. Pro další kroky přidejte tento kód do ManageCustomerAsync metody.

    1. Asynchronní volání GetContainerAsync metody a uložení výsledku do proměnné s názvem container.

       C#

       Container container = await GetContainerAsync();
       

    2. Vytvořte novou proměnnou s názvemid, která pomocí Kebaberize metody Humanizer transformuje name parametr metody.

       C#

       string id = name.Kebaberize();
       

       Poznámka

       Metoda Kebaberize nahradí všechny mezery pomlčkami a konveruje text na malá písmena.

    3. Pomocí parametrů a parametrů metody a country proměnné vytvořte novou anonymní typovou položkuname.id state Uložte položku jako proměnnou s názvem customer.

       C#

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

    4. Pomocí asynchronní CreateItemAsync metody kontejneru vytvořte novou položku v kontejneru a přiřaďte metadata odpovědi HTTP proměnné s názvem response.

       C#

       var response = await container.CreateItemAsync(customer);
       

    5. Napište do konzoly hodnoty proměnných response StatusCode a RequestCharge vlastností. Zapište také hodnotu id proměnné.

       C#

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

16. Uložte soubor CosmosHandler.cs.

17. Zpátky v terminálu spusťte aplikaci znovu.

    Bash

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

18. Výstup příkazu by měl obsahovat stav a poplatek za operaci.

    Output

    [Created]       mica-pereira    7.05 RUs
    

    Poznámka

    Poplatek za vaši žádost se může lišit.

19. Spusťte aplikaci ještě jednou.

    Bash

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

20. Tentokrát by program měl dojít k chybovému ukončení. Pokud se posunete chybovou zprávou, zobrazí se chybové ukončení kvůli konfliktu v jedinečném identifikátoru položek.

    Output

    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."
        ]
    );
    

Načtení položky pomocí sady SDK

Teď, když jste vytvořili první položku v kontejneru, můžete k načtení položky použít stejnou sadu SDK. Tady provedete dotaz a načtete položku a porovnáte rozdíl v spotřebě jednotek žádosti (RU).

1. Vraťte se do souboru CosmosHandler.cs nebo ho otevřete.

2. Odstraňte všechny řádky kódu z ManageCustomerAsync metody s výjimkou prvních dvou řádků.

   C#

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

3. Pro další kroky přidejte tento kód do ManageCustomerAsync metody.

   1. Pomocí asynchronní CreateItemAsync metody kontejneru vytvořte novou položku v kontejneru a přiřaďte metadata odpovědi HTTP proměnné s názvem response.

      C#

      var response = await container.CreateItemAsync(customer);
      

   2. Vytvořte nový řetězec s názvem sql dotazu SQL, který načte položky, ve kterých se filtr (@id) shoduje.

      C#

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

   3. Vytvořte novou QueryDefinition proměnnou s názvem query předávající sql řetězec jako jediný parametr dotazu. Použijte také metodu WithParameter tekutiny k použití hodnoty proměnné id na @id parametr.

      C#

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

   4. GetItemQueryIterator<> Použijte obecnou metodu a proměnnou k vytvoření iterátoruquery, který získává data ze služby Azure Cosmos DB. Uložte iterátor do proměnné s názvem feed. Zabalte tento celý výraz do příkazu using, aby se iterátor později vyřadil.

      C#

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

   5. Asynchronní volání ReadNextAsync metody feed proměnné a uložení výsledku do proměnné s názvem response.

      C#

      var response = await feed.ReadNextAsync();
      

   6. Napište do konzoly hodnoty proměnných response StatusCode a RequestCharge vlastností. Zapište také hodnotu id proměnné.

      C#

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

4. Uložte soubor CosmosHandler.cs.

5. Zpátky v terminálu spusťte aplikaci, aby přečetla jednu položku pomocí dotazu SQL.

   Bash

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

6. Výstup příkazu by měl znamenat, že dotaz vyžadoval více jednotek žádostí (RU).

   Output

   [OK]    mica-pereira    2.82 RUs
   

7. Zpět v CosmosHandler.cs souboru odstraňte všechny řádky kódu z ManageCustomerAsync metody znovu s výjimkou prvních dvou řádků.

   C#

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

8. Pro další kroky přidejte tento kód do ManageCustomerAsync metody.

   1. Vytvořte novou instanci PartitionKeyBuilder tak, že přidáte state parametry country jako hodnotu klíče oddílu s více částmi.

      C#

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

   2. Pomocí metody kontejneru ReadItemAsync<> nasměrujte na čtení položky z kontejneru pomocí id proměnných.partitionKey Uložte výsledek do proměnné s názvem response.

      C#

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

   3. Napište do konzoly hodnoty proměnných response StatusCode a RequestCharge vlastností. Zapište také hodnotu id proměnné.

      C#

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

9. Uložte soubor CosmosHandler.cs znovu.

10. Zpátky v terminálu spusťte aplikaci ještě jednou a nasměrujte tak čtení jedné položky.

    Bash

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

11. Výstup příkazu by měl znamenat, že dotaz vyžadoval jednu RU.

    Output

    [OK]    mica-pereira    1 RUs
    

Vytvoření transakce pomocí sady SDK

Nakonec vezmete položku, kterou jste vytvořili, přečtete ji a vytvoříte jinou související položku jako součást jedné transakce pomocí sady Azure SDK pro .NET.

1. Vraťte se do souboru CosmosHandler.cs nebo ho otevřete.

2. Odstraňte tyto řádky kódu z ManageCustomerAsync metody.

   C#

   var response = await container.ReadItemAsync<dynamic>(
       id: id, 
       partitionKey: partitionKey
   );
   
   Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");
   

3. Pro další kroky přidejte tento nový kód do ManageCustomerAsync metody.

   1. Pomocí parametrů a parametrů metody a country proměnné vytvořte novou anonymní typovou položkuname.id state Uložte položku jako proměnnou s názvem customerCart. Tato položka představuje nákupní košík v reálném čase pro zákazníka, který je aktuálně prázdný.

      C#

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

   2. Pomocí parametrů a parametrů id metody a country proměnné vytvořte další novou anonymní typovou položkuname. state Uložte položku jako proměnnou s názvem customerCart. Tato položka představuje expediční a kontaktní informace pro zákazníka.

      C#

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

   3. Vytvořte novou dávku pomocí metody kontejneru CreateTransactionalBatch , která předává proměnnou partitionKey . Uložte dávku do proměnné s názvem batch. K provádění následujících akcí použijte fluentové metody:

      metoda	Parametr
      ReadItem	id řetězcová proměnná
      CreateItem	customerCart Proměnná anonymního typu
      CreateItem	customerContactInfo Proměnná anonymního typu

      C#

      var batch = container.CreateTransactionalBatch(partitionKey)
          .ReadItem(id)
          .CreateItem(customerCart)
          .CreateItem(customerContactInfo);
      

   4. Ke spuštění transakce použijte metodu dávky ExecuteAsync . Uložte výsledek do proměnné s názvem response.

      C#

      using var response = await batch.ExecuteAsync();
      

   5. Napište do konzoly hodnoty proměnných response StatusCode a RequestCharge vlastností. Zapište také hodnotu id proměnné.

      C#

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

4. Uložte soubor CosmosHandler.cs znovu.

5. Zpátky v terminálu spusťte aplikaci ještě jednou a nasměrujte tak čtení jedné položky.

   Bash

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

6. Výstup příkazu by měl zobrazit jednotky žádostí použité pro celou transakci.

   Output

   [OK]    16.05 RUs
   

   Poznámka

   Poplatek za vaši žádost se může lišit.

Ověření konečných dat v Průzkumníku dat

K zabalení dat použijete Průzkumník dat na webu Azure Portal k zobrazení dat a kontejneru, který jste vytvořili v tomto kurzu.

1. Na webu Azure Portal přejděte ke svému stávajícímu účtu API for NoSQL.

2. V nabídce prostředků vyberte Průzkumník dat.

   

3. Na stránce Průzkumník dat rozbalte cosmicworks databázi a pak vyberte customers kontejner.

   

4. Na panelu příkazů vyberte Nový dotaz SQL.

   

5. V editoru dotazů sledujte tento řetězec dotazu SQL.

   SQL

   SELECT * FROM c
   

6. Výběrem příkazu Spustit dotaz spusťte dotaz a prohlédněte si výsledky.

   

7. Výsledky by měly obsahovat pole JSON se třemi položkami vytvořenými v tomto kurzu. Všimněte si, že všechny položky mají stejnou hierarchickou hodnotu klíče oddílu, ale jedinečná pole ID. Ukázkový výstup je zkrácen pro stručnost.

   Output

   [
     {
       "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"
       },
       ...
     }
   ]
   

Vyčištění prostředků

Pokud už databázi použitou v tomto kurzu nepotřebujete, odstraňte ji. Uděláte to tak, že přejdete na stránku účtu, vyberete Průzkumník dat, vyberete cosmicworks databázi a pak vyberete Odstranit.