البرنامج التعليمي: تطوير تطبيق وحدة تحكم .NET باستخدام Azure Cosmos DB ل NoSQL

ينطبق على: NoSQL

يسمح لك Azure SDK ل .NET بإضافة بيانات إلى API لحاوية NoSQL إما عمليات فردية غير متزامنة أو دفعة معاملات. يستعرض هذا البرنامج التعليمي عملية إنشاء تطبيق وحدة تحكم .NET جديد يضيف عناصر متعددة إلى حاوية.

في هذا البرنامج التعليمي، تتعلم كيفية:

المتطلبات الأساسية

• حساب Azure Cosmos DB ل NoSQL موجود.
  • إذا كان لديك اشتراك Azure موجود، فبادر بإنشاء حساب جديد.
  • لا يوجد اشتراك في Azure؟ يمكنك تجربة Azure Cosmos DB مجانا دون الحاجة إلى بطاقة ائتمان.
• Visual Studio Code
• .NET 8 أو أحدث
• خبرة في كتابة تطبيقات C#‎.

إنشاء واجهة برمجة تطبيقات لموارد NoSQL

أولا، قم بإنشاء قاعدة بيانات فارغة في واجهة برمجة التطبيقات الموجودة لحساب NoSQL. يمكنك إنشاء حاوية باستخدام Azure SDK ل .NET لاحقا.

1. انتقل إلى واجهة برمجة التطبيقات الموجودة لحساب NoSQL في مدخل Microsoft Azure.

2. في قائمة الموارد، حدد Keys.

   

3. في صفحة Keys، لاحظ وسجل قيمة حقلي URI و PRIMARY KEY. يتم استخدام هذه القيم خلال البرنامج التعليمي.

   

4. في قائمة الموارد، حدد Data Explorer.

   

5. في صفحة Data Explorer ، حدد الخيار New Database في شريط الأوامر.

   

6. في مربع الحوار قاعدة بيانات جديدة، أنشئ حاوية جديدة بالإعدادات التالية:

   	القيمة‬
   مُعرِّف قاعدة البيانات	cosmicworks
   نوع معدل نقل قاعدة البيانات	يدوي
   مقدار معدل نقل قاعدة البيانات	400

   

7. حدد موافق لإنشاء قاعدة البيانات.

إنشاء تطبيق وحدة تحكم .NET

الآن، يمكنك إنشاء تطبيق وحدة تحكم .NET جديد واستيراد Azure SDK ل .NET باستخدام المكتبة Microsoft.Azure.Cosmos من NuGet.

1. افتح محطة طرفية في دليل فارغ.

2. إنشاء تطبيق وحدة تحكم جديد باستخدام القالب console المضمن

   dotnet new console --langVersion preview
   

3. أضف إصدار 3.31.1-preview من الحزمة Microsoft.Azure.Cosmos من NuGet.

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

4. أضف أيضا إصدار ما قبل الإصدار من الحزمة System.CommandLine من NuGet.

   dotnet add package System.CommandLine --prerelease
   

5. أضف أيضا الحزمة Humanizer من NuGet.

   dotnet add package Humanizer
   

6. إنشاء مشروع تطبيق وحدة التحكم.

   dotnet build
   

7. افتح Visual Studio Code باستخدام مجلد المشروع الحالي كمساحة عمل.

   تلميح

   يمكنك تشغيل code . في المحطة الطرفية لفتح Visual Studio Code وفتح دليل العمل تلقائيا كمساحة العمل الحالية.

8. انتقل إلى ملف Program.cs وافتحه. حذف كافة التعليمات البرمجية الموجودة في الملف.

9. أضف هذه التعليمة البرمجية إلى الملف لاستخدام مكتبة System.CommandLine لتحليل سطر الأوامر لسلسلتين تم تمريرهما عبر الخيارين --first و --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);
   

   إشعار

   بالنسبة لهذا البرنامج التعليمي، ليس من المهم تماما أن تفهم كيفية عمل محلل سطر الأوامر. يحتوي المحلل على أربعة خيارات يمكن تحديدها عند تشغيل التطبيق. ثلاثة من الخيارات مطلوبة حيث سيتم استخدامها لإنشاء حقول المعرف ومفتاح القسم.

10. عند هذه النقطة، لن يتم بناء المشروع نظرا لأنك لم تحدد الأسلوب الثابت CosmosHandler.ManageCustomerAsync بعد.

11. احفظ ملف Program.cs.

إضافة عناصر إلى حاوية باستخدام SDK

بعد ذلك، يمكنك استخدام عمليات فردية لإضافة عناصر إلى واجهة برمجة التطبيقات لحاوية NoSQL. في هذا القسم، يمكنك تعريف CosmosHandler.ManageCustomerAsync الأسلوب .

1. إنشاء ملف CosmosHandler.cs جديد.

2. في ملف CosmosHandler.cs ، أضف توجيها جديدا باستخدام لمساحات Humanizer الأسماء و Microsoft.Azure.Cosmos .

   using Humanizer;
   using Microsoft.Azure.Cosmos;
   

3. إنشاء فئة ثابتة جديدة باسم CosmosHandler.

   public static class CosmosHandler
   { }
   

4. فقط للتحقق من صحة عمل هذا التطبيق، قم بإنشاء تنفيذ قصير للأسلوب الثابت ManageCustomerAsync لطباعة إدخال سطر الأوامر.

   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.

6. مرة أخرى في المحطة الطرفية، قم بتشغيل التطبيق.

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

7. يجب أن يكون إخراج الأمر تحية ممتعة.

   Hello Mica Pereira of Washington, United States!
   

8. ارجع إلى ملف CosmosHandler.cs .

9. ضمن فئة CosmosHandler الثابتة، أضف عضوا جديدا private static readonly من النوع CosmosClient المسمى _client.

   private static readonly CosmosClient _client;
   

10. إنشاء منشئ ثابت جديد للفئة CosmosHandler .

    static CosmosHandler()
    { }
    

11. ضمن الدالة الإنشائية، قم بإنشاء مثيل جديد للفئة CosmosClient التي تمر في معلمتين للسلسلة باستخدام قيم URI و PRIMARY KEY التي سجلتها مسبقا في المختبر. قم بتخزين هذا المثيل الجديد في _client العضو.

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

12. مرة أخرى داخل فئة CosmosHandler الثابتة، قم بإنشاء أسلوب جديد غير متزامن يسمى GetContainerAsync الذي يقوم بإرجاع Container.

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

13. للخطوات التالية، أضف هذه التعليمة البرمجية GetContainerAsync داخل الأسلوب .

    1. احصل على cosmicworks قاعدة البيانات وقم بتخزينها في متغير يسمى database.

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

    2. إنشاء عام List<> جديد من string القيم ضمن قائمة مسارات مفتاح القسم الهرمي وتخزينها في متغير يسمى keyPaths.

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

    3. إنشاء متغير جديد ContainerProperties باسم الحاوية (customers) وقائمة مسارات مفتاح القسم.

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

    4. CreateContainerIfNotExistsAsync استخدم الأسلوب لتوفير خصائص الحاوية واسترداد الحاوية. سيقوم هذا الأسلوب، وفقا للاسم، بإنشاء الحاوية بشكل غير متزامن إذا لم تكن موجودة بالفعل داخل قاعدة البيانات. إرجاع النتيجة كإخراج الأسلوب GetContainerAsync .

       return await database.CreateContainerIfNotExistsAsync(
           containerProperties: properties
       );
       

14. احذف كافة التعليمات البرمجية ManageCustomerAsync داخل الأسلوب .

15. للخطوات التالية، أضف هذه التعليمة البرمجية ManageCustomerAsync داخل الأسلوب .

    1. استدعاء GetContainerAsync الأسلوب بشكل غير متزامن وتخزين النتيجة في متغير يسمى container.

       Container container = await GetContainerAsync();
       

    2. إنشاء متغير جديد يسمى id يستخدم الأسلوب من Humanizer لتحويل معلمة name الأسلوب.Kebaberize

       string id = name.Kebaberize();
       

       إشعار

       Kebaberize سيستبدل الأسلوب كافة المسافات بواصلات ويحيط النص بالأحرف الصغيرة.

    3. إنشاء عنصر جديد مكتوب مجهول باستخدام namestateمعلمات الأسلوب و و country والمتغيرid. تخزين العنصر كمتغير يسمى customer.

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

    4. استخدم أسلوب الحاوية غير المتزامن CreateItemAsync لإنشاء عنصر جديد في الحاوية وتعيين بيانات تعريف استجابة HTTP إلى متغير يسمى response.

       var response = await container.CreateItemAsync(customer);
       

    5. اكتب قيم response المتغير StatusCode وخصائصه RequestCharge إلى وحدة التحكم. اكتب أيضا قيمة id المتغير .

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

16. احفظ ملف CosmosHandler.cs.

17. مرة أخرى في المحطة الطرفية، قم بتشغيل التطبيق مرة أخرى.

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

18. يجب أن يتضمن إخراج الأمر حالة وتكلفة طلب للعملية.

    [Created]       mica-pereira    7.05 RUs
    

    إشعار

    قد تختلف رسوم طلبك.

19. قم بتشغيل التطبيق مرة أخرى.

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

20. هذه المرة، يجب أن يتعطل البرنامج. إذا قمت بالتمرير عبر رسالة الخطأ، فسترى حدوث العطل بسبب تعارض في المعرف الفريد للعناصر.

    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

الآن بعد أن قمت بإنشاء العنصر الأول في الحاوية، يمكنك استخدام نفس SDK لاسترداد العنصر. هنا، ستقوم بالاستعلام والإشارة إلى قراءة العنصر لمقارنة الفرق في استهلاك وحدة الطلب (RU).

1. ارجع إلى ملف CosmosHandler.cs أو افتحه.

2. احذف كافة أسطر التعليمات البرمجية ManageCustomerAsync من الأسلوب باستثناء السطرين الأولين.

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

3. للخطوات التالية، أضف هذه التعليمة البرمجية ManageCustomerAsync داخل الأسلوب .

   1. استخدم أسلوب الحاوية غير المتزامن CreateItemAsync لإنشاء عنصر جديد في الحاوية وتعيين بيانات تعريف استجابة HTTP إلى متغير يسمى response.

      var response = await container.CreateItemAsync(customer);
      

   2. إنشاء سلسلة جديدة باسم sql مع استعلام SQL لاسترداد العناصر حيث يتطابق عامل التصفية (@id).

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

   3. إنشاء متغير جديد QueryDefinition يسمى query تمرير في sql السلسلة كمعلمة الاستعلام الوحيدة. أيضا، استخدم WithParameter الأسلوب السائل لتطبيق قيمة المتغير id على المعلمة @id .

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

   4. GetItemQueryIterator<> استخدم الأسلوب العام والمتغير query لإنشاء مكرر يحصل على البيانات من Azure Cosmos DB. تخزين المكرر في متغير يسمى feed. قم بتضمين هذا التعبير بأكمله في عبارة استخدام للتخلص من المكرر لاحقا.

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

   5. استدعاء ReadNextAsync أسلوب feed المتغير بشكل غير متزامن وتخزين النتيجة في متغير يسمى response.

      var response = await feed.ReadNextAsync();
      

   6. اكتب قيم response المتغير StatusCode وخصائصه RequestCharge إلى وحدة التحكم. اكتب أيضا قيمة id المتغير .

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

4. احفظ ملف CosmosHandler.cs.

5. مرة أخرى في المحطة الطرفية، قم بتشغيل التطبيق لقراءة العنصر الفردي باستخدام استعلام SQL.

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

6. يجب أن يشير إخراج الأمر إلى أن الاستعلام يتطلب وحدات طلب متعددة (RUs).

   [OK]    mica-pereira    2.82 RUs
   

7. مرة أخرى في ملف CosmosHandler.cs ، احذف كافة أسطر التعليمات البرمجية ManageCustomerAsync من الأسلوب مرة أخرى باستثناء السطرين الأولين.

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

8. للخطوات التالية، أضف هذه التعليمة البرمجية ManageCustomerAsync داخل الأسلوب .

   1. إنشاء مثيل جديد من PartitionKeyBuilder عن طريق إضافة state المعلمات و country كقيمة مفتاح قسم متعدد الأجزاء.

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

   2. استخدم أسلوب الحاوية ReadItemAsync<> للإشارة إلى قراءة العنصر من الحاوية باستخدام id المتغيرين و partitionKey . احفظ النتيجة في متغير يسمى response.

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

   3. اكتب قيم response المتغير StatusCode وخصائصه RequestCharge إلى وحدة التحكم. اكتب أيضا قيمة id المتغير .

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

9. احفظ ملف CosmosHandler.cs مرة أخرى.

10. مرة أخرى في المحطة الطرفية، قم بتشغيل التطبيق مرة أخرى للإشارة إلى قراءة العنصر الفردي.

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

11. يجب أن يشير إخراج الأمر إلى أن الاستعلام يتطلب وحدة طلب واحدة.

    [OK]    mica-pereira    1 RUs
    

إنشاء معاملة باستخدام SDK

وأخيرا، يمكنك أخذ العنصر الذي قمت بإنشائه، وقراءة هذا العنصر، وإنشاء عنصر مرتبط مختلف كجزء من معاملة واحدة باستخدام Azure SDK ل .NET.

1. ارجع إلى ملف CosmosHandler.cs أو افتحه.

2. احذف أسطر التعليمات البرمجية ManageCustomerAsync هذه من الأسلوب .

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

3. للخطوات التالية، أضف هذه التعليمة البرمجية ManageCustomerAsync الجديدة داخل الأسلوب .

   1. إنشاء عنصر جديد مكتوب مجهول باستخدام namestateمعلمات الأسلوب و و country والمتغيرid. تخزين العنصر كمتغير يسمى customerCart. يمثل هذا العنصر عربة تسوق في الوقت الحقيقي للعميل فارغة حاليا.

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

   2. إنشاء عنصر مجهول آخر مكتوب باستخدام namestateمعلمات الأسلوب و و country والمتغيرid. تخزين العنصر كمتغير يسمى customerCart. يمثل هذا العنصر معلومات الشحن والاتصال للعميل.

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

   3. إنشاء دفعة جديدة باستخدام أسلوب الحاوية CreateTransactionalBatch تمرير في partitionKey المتغير. تخزين الدفعة في متغير يسمى batch. استخدم أساليب بطلاقة لتنفيذ الإجراءات التالية:

      الأسلوب	المعلمة‬
      ReadItem	id متغير السلسلة
      CreateItem	customerCart متغير نوع مجهول
      CreateItem	customerContactInfo متغير نوع مجهول

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

   4. استخدم أسلوب الدفعة ExecuteAsync لبدء المعاملة. احفظ النتيجة في متغير يسمى response.

      using var response = await batch.ExecuteAsync();
      

   5. اكتب قيم response المتغير StatusCode وخصائصه RequestCharge إلى وحدة التحكم. اكتب أيضا قيمة id المتغير .

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

4. احفظ ملف CosmosHandler.cs مرة أخرى.

5. مرة أخرى في المحطة الطرفية، قم بتشغيل التطبيق مرة أخرى للإشارة إلى قراءة العنصر الفردي.

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

6. يجب أن يظهر إخراج الأمر وحدات الطلب المستخدمة للمعاملة بأكملها.

   [OK]    16.05 RUs
   

   إشعار

   قد تختلف رسوم طلبك.

التحقق من صحة البيانات النهائية في مستكشف البيانات

لإنهاء الأمور، يمكنك استخدام Data Explorer في مدخل Microsoft Azure لعرض البيانات والحاوية التي أنشأتها في هذا البرنامج التعليمي.

1. انتقل إلى واجهة برمجة التطبيقات الموجودة لحساب NoSQL في مدخل Microsoft Azure.

2. في قائمة الموارد، حدد Data Explorer.

   

3. في صفحة Data Explorer ، قم بتوسيع cosmicworks قاعدة البيانات، ثم حدد الحاوية customers .

   

4. في شريط الأوامر، حدد استعلام SQL جديد.

   

5. في محرر الاستعلام، لاحظ سلسلة استعلام SQL هذه.

   SELECT * FROM c
   

6. حدد Execute Query لتشغيل الاستعلام ومراقبة النتائج.

   

7. يجب أن تتضمن النتائج صفيف JSON مع ثلاثة عناصر تم إنشاؤها في هذا البرنامج التعليمي. لاحظ أن جميع العناصر لها نفس قيمة مفتاح القسم الهرمي، ولكن حقول المعرف الفريدة. يتم اقتطاع مثال الإخراج المضمن للإيجاز.

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

تنظيف الموارد

عند عدم الحاجة، احذف قاعدة البيانات المستخدمة في هذا البرنامج التعليمي. للقيام بذلك، انتقل إلى صفحة الحساب، وحدد مستكشف البيانات، وحدد cosmicworks قاعدة البيانات، ثم حدد حذف.