Öğretici: NoSQL için Azure Cosmos DB ile .NET konsol uygulaması geliştirme

UYGULANANLAR: NoSQL

.NET için Azure SDK, NoSQL kapsayıcısı için bir API'ye zaman uyumsuz tek tek işlemler veya işlem toplu işlemi eklemenizi sağlar. Bu öğretici, kapsayıcıya birden çok öğe ekleyen yeni bir .NET konsol uygulaması oluşturma işleminde yol gösterir.

Bu öğreticide aşağıdakilerin nasıl yapılacağını öğreneceksiniz:

Önkoşullar

• Mevcut bir NoSQL için Azure Cosmos DB hesabı.
  • Mevcut bir Azure aboneliğiniz varsa yeni bir hesap oluşturun.
  • Azure aboneliği yok mu? Kredi kartı gerektirmeden Azure Cosmos DB'i ücretsiz deneyebilirsiniz.
• Visual Studio Code
• .NET 8 veya üzeri
• C# uygulamaları yazma deneyimi.

NoSQL kaynakları için API oluşturma

İlk olarak, NoSQL hesabı için mevcut API'de boş bir veritabanı oluşturun. Daha sonra .NET için Azure SDK'sını kullanarak bir kapsayıcı oluşturursunuz.

1. Azure portalında mevcut NoSQL hesabı API'nize gidin.

2. Kaynak menüsünde Anahtarlar'ı seçin.

   

3. Anahtarlar sayfasında URI ve BİRİnCİl ANAHTAR alanlarının değerini gözlemleyin ve kaydedin. Bu değerler öğretici boyunca kullanılır.

   

4. Kaynak menüsünde Veri Gezgini'ı seçin.

   

5. Veri Gezgini sayfasında, komut çubuğundaKi Yeni Veritabanı seçeneğini belirleyin.

   

6. Yeni Veritabanı iletişim kutusunda aşağıdaki ayarlarla yeni bir kapsayıcı oluşturun:

   	Değer
   Veritabanı kimliği	cosmicworks
   Veritabanı aktarım hızı türü	El ile
   Veritabanı aktarım hızı miktarı	400

   

7. Veritabanını oluşturmak için Tamam'ı seçin.

.NET konsol uygulaması oluşturma

Şimdi yeni bir .NET konsol uygulaması oluşturacak ve NuGet kitaplığını kullanarak .NET için Azure SDK'yı Microsoft.Azure.Cosmos içeri aktaracaksınız.

1. Boş bir dizinde bir terminal açın.

2. Yerleşik şablonu kullanarak console yeni bir konsol uygulaması oluşturma

   dotnet new console --langVersion preview
   

3. NuGet'ten paketin 3.31.1-preview sürümünü Microsoft.Azure.Cosmos ekleyin.

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

4. Ayrıca, NuGet'ten paketin System.CommandLine yayın öncesi sürümünü ekleyin.

   dotnet add package System.CommandLine --prerelease
   

5. Ayrıca NuGet'ten Humanizer paketi ekleyin.

   dotnet add package Humanizer
   

6. Konsol uygulaması projesini oluşturun.

   dotnet build
   

7. Çalışma alanı olarak geçerli proje klasörünü kullanarak Visual Studio Code'yu açın.

   İpucu

   Terminalde çalıştırarak code . Visual Studio Code'u açabilir ve çalışma dizinini otomatik olarak geçerli çalışma alanı olarak açabilirsiniz.

8. Program.cs dosyasına gidin ve dosyayı açın. Dosyadaki mevcut kodun tümünü silin.

9. Ve --last seçenekleri aracılığıyla geçirilen iki dize için komut satırını ayrıştırmak üzere System.CommandLine kitaplığını kullanmak üzere bu kodu dosyaya --first ekleyin.

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

   Not

   Bu öğreticide, komut satırı ayrıştırıcısının nasıl çalıştığını anlamanız tamamen önemli değildir. Ayrıştırıcı, uygulama çalışırken belirtilebilen dört seçeneğe sahiptir. Kimlik ve bölüm anahtarı alanlarını oluşturmak için kullanılacakları için seçeneklerden üçü gereklidir.

10. Bu noktada, statik CosmosHandler.ManageCustomerAsync yöntemi henüz tanımlamadığınız için proje derlenmez.

11. Program.cs dosyasını kaydedin.

SDK kullanarak kapsayıcıya öğe ekleme

Ardından, NoSQL kapsayıcısı için API'ye öğe eklemek için tek tek işlemleri kullanırsınız. Bu bölümde yöntemini tanımlarsınız CosmosHandler.ManageCustomerAsync .

1. Yeni bir CosmosHandler.cs dosyası oluşturun.

2. CosmosHandler.cs dosyasında ve Microsoft.Azure.Cosmos ad alanları için Humanizer yeni bir using yönergesi ekleyin.

   using Humanizer;
   using Microsoft.Azure.Cosmos;
   

3. adlı CosmosHandleryeni bir statik sınıf oluşturun.

   public static class CosmosHandler
   { }
   

4. Bu uygulamanın çalıştığını doğrulamak için, komut satırı girişini yazdırmak için statik ManageCustomerAsync yöntemin kısa bir uygulamasını oluşturun.

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

5. CosmosHandler.cs dosyasını kaydedin.

6. Terminale geri dönüp uygulamayı çalıştırın.

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

7. Komutun çıkışı eğlenceli bir karşılama olmalıdır.

   Hello Mica Pereira of Washington, United States!
   

8. CosmosHandler.cs dosyasına dönün.

9. Statik CosmosHandler sınıfı içinde adlı _clienttüründe CosmosClient yeni private static readonly bir üye ekleyin.

   private static readonly CosmosClient _client;
   

10. sınıfı için CosmosHandler yeni bir statik oluşturucu oluşturun.

    static CosmosHandler()
    { }
    

11. Oluşturucu içinde, daha önce laboratuvarda CosmosClient kaydettiğiniz URI ve BİRİnCİl ANAHTAR değerleriyle iki dize parametresini geçirerek sınıfın yeni bir örneğini oluşturun. Bu yeni örneği üyede depolayın _client .

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

12. Statik CosmosHandler sınıfına geri dönüp adlı yeni bir zaman uyumsuz yöntem GetContainerAsync oluşturun.Container

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

13. Sonraki adımlar için bu kodu yöntemine GetContainerAsync ekleyin.

    1. cosmicworks Veritabanını alın ve adlı databasebir değişkende depolayın.

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

    2. Hiyerarşik bölüm anahtarı yolları listesinde yeni bir değer geneli List<> string oluşturun ve adlı keyPathsbir değişkende depolayın.

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

    3. Kapsayıcı adı (customers) ve bölüm anahtarı yolları listesiyle yeni ContainerProperties bir değişken oluşturun.

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

    4. CreateContainerIfNotExistsAsync Kapsayıcı özelliklerini sağlamak ve kapsayıcıyı almak için yöntemini kullanın. Bu yöntem, veritabanında zaten yoksa, ad başına kapsayıcıyı zaman uyumsuz olarak oluşturur. Sonucu yöntemin çıktısı GetContainerAsync olarak döndürür.

       return await database.CreateContainerIfNotExistsAsync(
           containerProperties: properties
       );
       

14. yöntemindeki tüm kodu ManageCustomerAsync silin.

15. Sonraki adımlar için bu kodu yöntemine ManageCustomerAsync ekleyin.

    1. yöntemini zaman uyumsuz olarak çağırın GetContainerAsync ve sonucu adlı containerbir değişkende depolayın.

       Container container = await GetContainerAsync();
       

    2. Yöntem parametresini Kebaberize dönüştürmek name için Humanizer yöntemini kullanan adlı id yeni bir değişken oluşturun.

       string id = name.Kebaberize();
       

       Not

       Kebaberize yöntemi, tüm boşlukları kısa çizgilerle değiştirir ve metni küçük harfle yakınsar.

    3. , , stateve yöntem parametrelerini ve country değişkenini nameid kullanarak yeni bir anonim türlenmiş öğe oluşturun. Öğeyi adlı customerbir değişken olarak depolayın.

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

    4. Kapsayıcıda yeni bir öğe oluşturmak ve HTTP yanıt meta verilerini adlı responsebir değişkene atamak için kapsayıcının zaman uyumsuz CreateItemAsync yöntemini kullanın.

       var response = await container.CreateItemAsync(customer);
       

    5. Değişkenin response StatusCode ve RequestCharge özelliklerinin değerlerini konsola yazın. Değişkenin değerini id de yazın.

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

16. CosmosHandler.cs dosyasını kaydedin.

17. Terminale geri dönüp uygulamayı yeniden çalıştırın.

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

18. Komutun çıktısı işlem için bir durum ve istek ücreti içermelidir.

    [Created]       mica-pereira    7.05 RUs
    

    Not

    İstek ücretiniz farklılık gösterebilir.

19. Uygulamayı bir kez daha çalıştırın.

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

20. Bu kez program kilitlenmelidir. Hata iletisinde kaydırma yaparsanız, kilitlenmenin öğelerin benzersiz tanımlayıcısında bir çakışma nedeniyle oluştuğunı görürsünüz.

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

SDK kullanarak öğe alma

Kapsayıcıda ilk öğenizi oluşturduğunuza göre, öğeyi almak için aynı SDK'yı kullanabilirsiniz. Burada, istek birimi (RU) tüketimindeki farkı karşılaştırmak için öğeyi sorgulayıp nokta okuması yapacaksınız.

1. CosmosHandler.cs dosyasına dönün veya dosyayı açın.

2. yöntemden ManageCustomerAsync ilk iki satır dışındaki tüm kod satırlarını silin.

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

3. Sonraki adımlar için bu kodu yöntemine ManageCustomerAsync ekleyin.

   1. Kapsayıcıda yeni bir öğe oluşturmak ve HTTP yanıt meta verilerini adlı responsebir değişkene atamak için kapsayıcının zaman uyumsuz CreateItemAsync yöntemini kullanın.

      var response = await container.CreateItemAsync(customer);
      

   2. Bir filtrenin (@id) eşleştiği öğeleri almak için SQL sorgusuyla adlı sql yeni bir dize oluşturun.

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

   3. Dizeyi sql tek sorgu parametresi olarak geçirme adlı query yeni QueryDefinition bir değişken oluşturun. Ayrıca değişken değerini id @id parametreye uygulamak için akışkan yöntemini kullanınWithParameter.

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

   4. Azure Cosmos DB'den GetItemQueryIterator<> veri alan bir yineleyici oluşturmak için genel yöntemi ve query değişkenini kullanın. Yineleyiciyi adlı feedbir değişkende depolayın. Yineleyiciyi daha sonra atmak için bu ifadenin tamamını bir using deyimine sarmalayın.

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

   5. Zaman uyumsuz olarak değişkeninin ReadNextAsync yöntemini çağırın feed ve sonucu adlı responsebir değişkende depolayın.

      var response = await feed.ReadNextAsync();
      

   6. Değişkenin response StatusCode ve RequestCharge özelliklerinin değerlerini konsola yazın. Değişkenin değerini id de yazın.

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

4. CosmosHandler.cs dosyasını kaydedin.

5. Terminale döndüğünüzde, sql sorgusu kullanarak tek öğeyi okumak için uygulamayı çalıştırın.

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

6. Komutun çıkışı, sorgunun birden çok istek birimi (RU) gerektirdiğini göstermelidir.

   [OK]    mica-pereira    2.82 RUs
   

7. CosmosHandler.cs dosyasına geri dönün, ilk iki satır dışındaki tüm kod satırlarını yöntemden ManageCustomerAsync yeniden silin.

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

8. Sonraki adımlar için bu kodu yöntemine ManageCustomerAsync ekleyin.

   1. ve country parametrelerini çok parçalı bölüm anahtarı değeri olarak ekleyerek state yeni bir örneği PartitionKeyBuilder oluşturun.

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

   2. ve partitionKey değişkenlerini kullanarak kapsayıcıdan ReadItemAsync<> öğeyi okumak için kapsayıcının id yöntemini kullanın. Sonucu adlı responsebir değişkene kaydedin.

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

   3. Değişkenin response StatusCode ve RequestCharge özelliklerinin değerlerini konsola yazın. Değişkenin değerini id de yazın.

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

9. CosmosHandler.cs dosyasını yeniden kaydedin.

10. Terminale geri dönüp uygulamayı bir kez daha çalıştırarak tek öğeyi okumasını sağlayın.

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

11. Komutun çıkışı, sorgunun tek bir RU gerektirdiğini göstermelidir.

    [OK]    mica-pereira    1 RUs
    

SDK kullanarak işlem oluşturma

Son olarak, oluşturduğunuz öğeyi alır, bu öğeyi okur ve .NET için Azure SDK'sını kullanarak tek bir işlemin parçası olarak farklı bir ilgili öğe oluşturursunuz.

1. CosmosHandler.cs dosyasına dönün veya dosyayı açın.

2. Yönteminden bu kod satırlarını ManageCustomerAsync silin.

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

3. Sonraki adımlar için bu yeni kodu yöntemine ManageCustomerAsync ekleyin.

   1. , , stateve yöntem parametrelerini ve country değişkenini nameid kullanarak yeni bir anonim türlenmiş öğe oluşturun. Öğeyi adlı customerCartbir değişken olarak depolayın. Bu öğe, şu anda boş olan müşteri için gerçek zamanlı bir alışveriş sepetini temsil eder.

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

   2. , , stateve yöntem parametrelerini ve country değişkenini nameid kullanarak anonim olarak yazılan başka bir öğe oluşturun. Öğeyi adlı customerCartbir değişken olarak depolayın. Bu öğe, müşterinin sevkiyat ve iletişim bilgilerini temsil eder.

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

   3. Değişkenini geçirerek partitionKey kapsayıcının CreateTransactionalBatch yöntemini kullanarak yeni bir toplu iş oluşturun. Toplu işlemi adlı batchbir değişkende depolayın. Aşağıdaki eylemleri gerçekleştirmek için akıcı yöntemleri kullanın:

      Metot	Parametre
      ReadItem	id dize değişkeni
      CreateItem	customerCart anonim tür değişkeni
      CreateItem	customerContactInfo anonim tür değişkeni

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

   4. İşlemi başlatmak için toplu işlemin ExecuteAsync yöntemini kullanın. Sonucu adlı responsebir değişkene kaydedin.

      using var response = await batch.ExecuteAsync();
      

   5. Değişkenin response StatusCode ve RequestCharge özelliklerinin değerlerini konsola yazın. Değişkenin değerini id de yazın.

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

4. CosmosHandler.cs dosyasını yeniden kaydedin.

5. Terminale geri dönüp uygulamayı bir kez daha çalıştırarak tek öğeyi okumasını sağlayın.

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

6. Komutun çıktısı, işlemin tamamı için kullanılan istek birimlerini göstermelidir.

   [OK]    16.05 RUs
   

   Not

   İstek ücretiniz farklılık gösterebilir.

Veri Gezgini son verileri doğrulama

Öğeleri sarmak için Azure portalındaki Veri Gezgini kullanarak verileri ve bu öğreticide oluşturduğunuz kapsayıcıyı görüntüleyebilirsiniz.

1. Azure portalında mevcut NoSQL hesabı API'nize gidin.

2. Kaynak menüsünde Veri Gezgini'ı seçin.

   

3. Veri Gezgini sayfasında veritabanını genişletin cosmicworks ve kapsayıcıyı customers seçin.

   

4. Komut çubuğunda Yeni SQL sorgusu'nu seçin.

   

5. Sorgu düzenleyicisinde bu SQL sorgu dizesini inceleyin.

   SELECT * FROM c
   

6. Sorguyu çalıştırmak ve sonuçları gözlemlemek için Sorguyu Yürüt'e tıklayın.

   

7. Sonuçlar, bu öğreticide oluşturulan üç öğeye sahip bir JSON dizisi içermelidir. Tüm öğelerin aynı hiyerarşik bölüm anahtarı değerine, ancak benzersiz kimlik alanlarına sahip olduğunu gözlemleyin. Dahil edilen örnek çıktı kısa olması için kesilir.

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

Kaynakları temizleme

Artık gerekli olmadığında, bu öğreticide kullanılan veritabanını silin. Bunu yapmak için hesap sayfasına gidin, Veri Gezgini seçin, veritabanını seçin cosmicworks ve ardından Sil'i seçin.