Oktatóanyag: .NET-konzolalkalmazás fejlesztése a NoSQL-hez készült Azure Cosmos DB-vel

A KÖVETKEZŐRE VONATKOZIK: NoSQL

• .NET

A .NET-hez készült Azure SDK lehetővé teszi adatok hozzáadását egy API for NoSQL-tárolóhoz, akár aszinkron egyéni műveletekhez, akár tranzakciós kötegekhez. Ez az oktatóanyag végigvezeti egy új .NET-konzolalkalmazás létrehozásának folyamatán, amely több elemet ad hozzá egy tárolóhoz.

Ebben az oktatóanyagban az alábbiakkal fog megismerkedni:

• Adatbázis létrehozása a NoSQL-hez készült API használatával
• .NET-konzolalkalmazás létrehozása és az Azure SDK hozzáadása a .NET-hez
• Egyéni elemek hozzáadása egy API for NoSQL-tárolóhoz
• Elemek hatékony lekérése egy API for NoSQL-tárolóból
• Tranzakció létrehozása kötegmódosításokkal a NoSQL-tároló API-hoz

Előfeltételek

• Egy meglévő Azure Cosmos DB for NoSQL-fiók.
  • Ha már rendelkezik Azure-előfizetéssel, hozzon létre egy új fiókot.
  • Nincs Azure-előfizetés? Ingyenesen kipróbálhatja az Azure Cosmos DB-t hitelkártya nélkül.
• Visual Studio Code
• .NET 8 vagy újabb
• C#-alkalmazások írásának tapasztalata.

API létrehozása NoSQL-erőforrásokhoz

Először hozzon létre egy üres adatbázist a Meglévő API for NoSQL-fiókban. Egy tárolót később az Azure SDK for .NET használatával hozhat létre.

1. Nyissa meg a meglévő API for NoSQL-fiókját az Azure Portalon.

2. Az erőforrás menüjében válassza a Kulcsok lehetőséget.

   

3. A Kulcsok lapon figyelje meg és rögzítse az URI és az ELSŐDLEGES KULCS mezők értékét. Ezeket az értékeket az oktatóanyag során használjuk.

   

4. Az erőforrásmenüben válassza az Adatkezelő lehetőséget.

   

5. Az Adatkezelő lapon válassza az Új adatbázis lehetőséget a parancssávon.

   

6. Az Új adatbázis párbeszédpanelen hozzon létre egy új tárolót a következő beállításokkal:

   	Érték
   Adatbázis azonosítója	cosmicworks
   Adatbázis átviteli sebességének típusa	Kézi
   Adatbázis átviteli sebességének mennyisége	400

   

7. Az adatbázis létrehozásához kattintson az OK gombra .

.NET-konzolalkalmazás létrehozása

Most hozzon létre egy új .NET-konzolalkalmazást, és importálja a .NET-hez készült Azure SDK-t a Microsoft.Azure.Cosmos NuGet könyvtárával.

1. Nyisson meg egy terminált egy üres könyvtárban.

2. Új konzolalkalmazás létrehozása a console beépített sablonnal

   dotnet new console --langVersion preview
   

3. Adja hozzá a csomag 3.31.1-es előzetes verzióját a Microsoft.Azure.Cosmos NuGetből.

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

4. Emellett adja hozzá a csomag előzetes verzióját a System.CommandLine NuGetből.

   dotnet add package System.CommandLine --prerelease
   

5. Emellett vegye fel a csomagot a Humanizer NuGetből.

   dotnet add package Humanizer
   

6. Hozza létre a konzolalkalmazás-projektet.

   dotnet build
   

7. Nyissa meg a Visual Studio Code-ot az aktuális projektmappával munkaterületként.

   Tipp.

   A terminálon futtatva code . megnyithatja a Visual Studio Code-ot, és automatikusan megnyithatja a munkakönyvtárat aktuális munkaterületként.

8. Nyissa meg és nyissa meg a Program.cs fájlt. Törölje a fájl összes meglévő kódját.

9. Adja hozzá ezt a kódot a fájlhoz, hogy a System.CommandLine kódtár használatával elemezhesse a parancssort a megadott és --last a beállítások között --first átadott két sztringhez.

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

   Feljegyzés

   Ebben az oktatóanyagban nem teljesen fontos, hogy megértse a parancssori elemző működését. Az elemző négy lehetőséggel rendelkezik, amelyek az alkalmazás futtatásakor adhatók meg. Három lehetőségre van szükség, mivel az azonosító és a partíciókulcs mezőinek létrehozására lesznek használva.

10. Ezen a ponton a projekt nem fog létrejönni, mivel még nem definiálta a statikus CosmosHandler.ManageCustomerAsync metódust.

11. Mentse a Program.cs fájlt.

Elemek hozzáadása tárolóhoz az SDK használatával

Ezután egyéni műveletekkel adhat hozzá elemeket az API for NoSQL-tárolóhoz. Ebben a szakaszban definiálja a metódust CosmosHandler.ManageCustomerAsync .

1. Hozzon létre egy új CosmosHandler.cs fájlt.

2. A CosmosHandler.cs fájlban adjon hozzá egy új, a névterekre és Microsoft.Azure.Cosmos névterekre Humanizer vonatkozó irányelvet.

   using Humanizer;
   using Microsoft.Azure.Cosmos;
   

3. Hozzon létre egy új statikus osztályt .CosmosHandler

   public static class CosmosHandler
   { }
   

4. Az alkalmazás működésének ellenőrzéséhez hozza létre a statikus ManageCustomerAsync metódus rövid implementációját a parancssori bemenet nyomtatásához.

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

5. Mentse a CosmosHandler.cs fájlt.

6. Futtassa az alkalmazást a terminálban.

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

7. A parancs kimenetének szórakoztató üdvözlésnek kell lennie.

   Hello Mica Pereira of Washington, United States!
   

8. Térjen vissza a CosmosHandler.cs fájlhoz.

9. A statikus CosmosHandler osztályban adjon hozzá egy újprivate static readonly, névvel ellátott tagot CosmosClient _client.

   private static readonly CosmosClient _client;
   

10. Hozzon létre egy új statikus konstruktort az CosmosHandler osztályhoz.

    static CosmosHandler()
    { }
    

11. A konstruktoron belül hozzon létre egy új példányt az CosmosClient osztálynak, amely két sztringparaméterben halad át a laborban korábban rögzített URI - és ELSŐDLEGESKULCS-értékekkel . Tárolja ezt az új példányt a _client tagban.

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

12. A statikus CosmosHandler osztályban hozzon létre egy új aszinkron metódust GetContainerAsync , amely egy Container.

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

13. A következő lépésekhez adja hozzá ezt a kódot a metódushoz GetContainerAsync .

    1. Kérje le az adatbázist cosmicworks , és tárolja egy nevű databaseváltozóban.

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

    2. Hozzon létre egy új általános List<> string értéket a hierarchikus partíciókulcs elérési útjainak listájában, és tárolja egy nevesített keyPathsváltozóban.

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

    3. Hozzon létre egy új ContainerProperties változót a tároló (customers) nevével és a partíciókulcs elérési útjainak listájával.

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

    4. A metódussal CreateContainerIfNotExistsAsync adja meg a tároló tulajdonságait, és kérje le a tárolót. Ez a metódus név szerint aszinkron módon hozza létre a tárolót, ha még nem létezik az adatbázisban. Adja vissza az eredményt a metódus kimeneteként GetContainerAsync .

       return await database.CreateContainerIfNotExistsAsync(
           containerProperties: properties
       );
       

14. Törölje az összes kódot a metóduson ManageCustomerAsync belül.

15. A következő lépésekhez adja hozzá ezt a kódot a metódushoz ManageCustomerAsync .

    1. Aszinkron módon hívja meg a metódust GetContainerAsync , és tárolja az eredményt egy nevesített containerváltozóban.

       Container container = await GetContainerAsync();
       

    2. Hozzon létre egy új változótid, amely a Kebaberize Humanizer metódusát használja a name metódusparaméter átalakításához.

       string id = name.Kebaberize();
       

       Feljegyzés

       A Kebaberize metódus az összes szóközt kötőjelekre cseréli, és kisbetűsre konvergálja a szöveget.

    3. Hozzon létre egy új névtelen típusú elemet a name, state, és country metódusparaméterek és a id változó használatával. Tárolja az elemet egy névvel ellátott customerváltozóként.

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

    4. A tároló aszinkron metódusával hozzon CreateItemAsync létre egy új elemet a tárolóban, és rendelje hozzá a HTTP-válasz metaadatait egy nevű responseváltozóhoz.

       var response = await container.CreateItemAsync(customer);
       

    5. Írja be a változó StatusCode és RequestCharge a response tulajdonságok értékeit a konzolra. Írja meg a változó értékét id is.

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

16. Mentse a CosmosHandler.cs fájlt.

17. Futtassa újra az alkalmazást a terminálban.

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

18. A parancs kimenetének tartalmaznia kell a művelet állapotát és a kérelem díját.

    [Created]       mica-pereira    7.05 RUs
    

    Feljegyzés

    A kérelem díja eltérő lehet.

19. Futtassa még egyszer az alkalmazást.

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

20. Ezúttal a program összeomlik. Ha végiggörget a hibaüzeneten, láthatja, hogy az összeomlás az elemek egyedi azonosítójában lévő ütközés miatt történt.

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

Elem lekérése az SDK használatával

Most, hogy létrehozta az első elemet a tárolóban, ugyanazt az SDK-t használhatja az elem lekéréséhez. Itt lekérdezi és felolvassa az elemet, hogy összehasonlítsa a kérelemegységek (RU) fogyasztásának különbségét.

1. Térjen vissza vagy nyissa meg a CosmosHandler.cs fájlt.

2. Törölje a metódus összes kódsorát az ManageCustomerAsync első két sor kivételével.

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

3. A következő lépésekhez adja hozzá ezt a kódot a metódushoz ManageCustomerAsync .

   1. A tároló aszinkron metódusával hozzon CreateItemAsync létre egy új elemet a tárolóban, és rendelje hozzá a HTTP-válasz metaadatait egy nevű responseváltozóhoz.

      var response = await container.CreateItemAsync(customer);
      

   2. Hozzon létre egy SQL-lekérdezéssel elnevezett sql új sztringet az olyan elemek lekéréséhez, amelyekben egy szűrő (@id) egyezik.

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

   3. Hozzon létre egy új QueryDefinition változót, amely query a sztringben lesz az sql egyetlen lekérdezési paraméter. Emellett a WithParameter folyadékmetódus használatával alkalmazza a változó id értékét a @id paraméterre.

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

   4. GetItemQueryIterator<> Az általános módszer és a query változó használatával hozzon létre egy iterátort, amely adatokat kap az Azure Cosmos DB-ből. Tárolja az iterátort egy nevesített feedváltozóban. Az iterátor későbbi elidegenítéséhez csomagolja be ezt a teljes kifejezést egy használandó utasításba.

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

   5. Aszinkron módon hívja meg a ReadNextAsync változó metódusát feed , és tárolja az eredményt egy nevesített responseváltozóban.

      var response = await feed.ReadNextAsync();
      

   6. Írja be a változó StatusCode és RequestCharge a response tulajdonságok értékeit a konzolra. Írja meg a változó értékét id is.

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

4. Mentse a CosmosHandler.cs fájlt.

5. Futtassa az alkalmazást a terminálban az egyetlen elem SQL-lekérdezéssel való olvasásához.

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

6. A parancs kimenetének azt kell jeleznie, hogy a lekérdezéshez több kérelemegységre (KÉRELEM) volt szükség.

   [OK]    mica-pereira    2.82 RUs
   

7. A CosmosHandler.cs fájlban törölje ismét a metódus összes kódsorát, ManageCustomerAsync kivéve az első két sort.

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

8. A következő lépésekhez adja hozzá ezt a kódot a metódushoz ManageCustomerAsync .

   1. Hozzon létre egy új példányt PartitionKeyBuilder úgy, hogy többrészes partíciókulcs-értékként adja hozzá a paramétereket és country a state paramétereket.

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

   2. A tároló metódusával ReadItemAsync<> pontozza az elemet a tárolóból a változók és partitionKey a id változók használatával. Mentse az eredményt egy névvel ellátott responseváltozóba.

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

   3. Írja be a változó StatusCode és RequestCharge a response tulajdonságok értékeit a konzolra. Írja meg a változó értékét id is.

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

9. Mentse ismét a CosmosHandler.cs fájlt.

10. A terminálban futtassa még egyszer az alkalmazást, hogy az egyetlen elem olvasására mutasson.

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

11. A parancs kimenetének azt kell jeleznie, hogy a lekérdezéshez egyetlen ru szükséges.

    [OK]    mica-pereira    1 RUs
    

Tranzakció létrehozása az SDK használatával

Végül a létrehozott elemet beolvassa, és egy másik kapcsolódó elemet hoz létre egyetlen tranzakció részeként a .NET-hez készült Azure SDK használatával.

1. Térjen vissza vagy nyissa meg a CosmosHandler.cs fájlt.

2. Törölje ezeket a kódsorokat a ManageCustomerAsync metódusból.

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

3. A következő lépésekhez adja hozzá ezt az új kódot a metódushoz ManageCustomerAsync .

   1. Hozzon létre egy új névtelen típusú elemet a name, state, és country metódusparaméterek és a id változó használatával. Tárolja az elemet egy névvel ellátott customerCartváltozóként. Ez az elem egy valós idejű bevásárlókocsit jelöl az aktuálisan üres ügyfél számára.

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

   2. Hozzon létre egy új névtelen típusú elemet a name, state, és metódusparaméterek és country a id változó használatával. Tárolja az elemet egy névvel ellátott customerCartváltozóként. Ez az elem az ügyfél szállítási és kapcsolattartási adatait jelöli.

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

   3. Hozzon létre egy új köteget a változóban partitionKey átadott tároló metódusávalCreateTransactionalBatch. Tárolja a köteget egy nevesített batchváltozóban. A fluent metódusokkal hajtsa végre a következő műveleteket:

      Metódus	Paraméter
      ReadItem	id sztringváltozó
      CreateItem	customerCart névtelen típusváltozó
      CreateItem	customerContactInfo névtelen típusváltozó

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

   4. A tranzakció elindításához használja a köteg ExecuteAsync metódusát. Mentse az eredményt egy névvel ellátott responseváltozóba.

      using var response = await batch.ExecuteAsync();
      

   5. Írja be a változó StatusCode és RequestCharge a response tulajdonságok értékeit a konzolra. Írja meg a változó értékét id is.

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

4. Mentse ismét a CosmosHandler.cs fájlt.

5. A terminálban futtassa még egyszer az alkalmazást, hogy az egyetlen elem olvasására mutasson.

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

6. A parancs kimenetének a teljes tranzakcióhoz használt kérelemegységeket kell megjelenítenie.

   [OK]    16.05 RUs
   

   Feljegyzés

   A kérelem díja eltérő lehet.

A végleges adatok ellenőrzése az Adatkezelőben

A dolgok burkolásához az Azure Portal Adatkezelője segítségével tekintheti meg az ebben az oktatóanyagban létrehozott adatokat és tárolót.

1. Nyissa meg a meglévő API for NoSQL-fiókját az Azure Portalon.

2. Az erőforrásmenüben válassza az Adatkezelő lehetőséget.

   

3. Az Adatkezelő lapon bontsa ki az adatbázistcosmicworks, majd válassza ki a tárolótcustomers.

   

4. A parancssávon válassza az Új SQL-lekérdezés lehetőséget.

   

5. A lekérdezésszerkesztőben figyelje meg ezt az SQL-lekérdezési sztringet.

   SELECT * FROM c
   

6. Válassza a Lekérdezés végrehajtása lehetőséget a lekérdezés futtatásához és az eredmények megfigyeléséhez.

   

7. Az eredményeknek tartalmazniuk kell egy JSON-tömböt, amely három elemet tartalmaz ebben az oktatóanyagban. Figyelje meg, hogy az összes elem azonos hierarchikus partíciókulcs-értékkel, de egyedi azonosítómezővel rendelkezik. A példakimenet a rövidség kedvéért csonkolt.

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

Az erőforrások eltávolítása

Ha már nincs rá szükség, törölje az oktatóanyagban használt adatbázist. Ehhez lépjen a fiók lapjára, válassza az Adatkezelőt, jelölje ki az adatbázist, majd válassza a cosmicworks Törlés lehetőséget.