Quickstart: استخدم Azure DocumentDB مع MongoDB driver for C#‎

• TypeScript
• JavaScript
• Python
• C#‎
• Java
• ذهب

في هذا البدء السريع، تنشئ تطبيق Azure DocumentDB الأساسي باستخدام C#. Azure DocumentDB هو مخزن بيانات NoSQL يسمح للتطبيقات بتخزين المستندات في السحابة والوصول إليها باستخدام برامج تشغيل MongoDB الرسمية. يوضح هذا الدليل كيفية إنشاء المستندات وأداء المهام الأساسية في عنقود Azure DocumentDB باستخدام C#‎.

مرجع | APIالشيفرة | المصدريةالحزمة (NuGet)

Prerequisites

• اشتراك Azure

  • إذا لم يكن لديك اشتراك Azure، فقم بإنشاء حساب مجاني

• .NET 10.0 أو أحدث

إنشاء عنقود Azure DocumentDB

للبدء، تحتاج أولا إلى إنشاء مجموعة Azure DocumentDB، والتي تعد الأساس لتخزين وإدارة بيانات NoSQL الخاصة بك.

1. تسجيل الدخول إلى بوابة Azure (https://portal.azure.com).

2. من قائمة مدخل Microsoft Azure أو الصفحة الرئيسية، حدد إنشاء مورد.

3. في الصفحة الجديدة ، ابحث عن Azure DocumentDB واختر ذلك.

   

4. في صفحة مجموعة إنشاء Azure DocumentDB وداخل قسم الأساسيات ، اختر خيار التكوين داخل قسم مستوى العنقود .

   

5. في صفحة المقياس ، قم بتكوين هذه الخيارات ثم اختر الحفظ لاستمرار تغييراتك في مستوى العنقود.

   	القيمة‬
   طبقة نظام المجموعة	M30 tier, 2 vCore, 8-GiB RAM
   التخزين لكل جزء	128 GiB

   

6. في قسم الأساسيات، قم بتكوين الخيارات التالية:

   	القيمة‬
   اشتراك	حدد اشتراك Azure الخاص بك
   مجموعة الموارد	إنشاء مجموعة موارد جديدة أو تحديد مجموعة موارد موجودة
   اسم شبكة نظام المجموعة	توفير اسم فريد عالميا
   Location	تحديد منطقة Azure مدعومة لاشتراكك
   نسخة MongoDB	تحديد 8.0
   "Admin username"	إنشاء اسم مستخدم للوصول إلى المجموعة كمسؤول مستخدم
   كلمة المرور	استخدم كلمة مرور فريدة مرتبطة باسم المستخدم

   

   Tip

   سجل القيم التي تستخدمها لاسم المستخدموكلمة المرور. تستخدم هذه القيم لاحقا في هذا الدليل. لمزيد من المعلومات حول القيم الصحيحة، انظر حدود التجمع.

7. حدد Next: Networking.

8. في قسم قواعد جدار الحماية في تبويب الشبكات ، قم بتكوين هذه الخيارات:

   	القيمة‬
   أسلوب الاتصال	Public access
   السماح بالوصول العام من خدمات وموارد Azure داخل Azure إلى هذا العنقود	Enabled

9. أضف قاعدة جدار حماية لجهاز العميل الحالي الخاص بك لمنح الوصول إلى العنقود عن طريق اختيار + إضافة عنوان IP الحالي للعميل.

   

   Tip

   في العديد من بيئات الشركة، يتم إخفاء عناوين IP لجهاز المطور بسبب VPN أو إعدادات شبكة الشركة الأخرى. في هذه الحالات، يمكنك السماح مؤقتا بالوصول إلى جميع عناوين IP بإضافة 0.0.0.0 - 255.255.255.255 نطاق عناوين IP كقاعدة جدار حماية. استخدم قاعدة جدار الحماية هذه مؤقتا فقط كجزء من اختبار وتطوير الاتصال.

10. حدد "Review + create".

11. راجع الإعدادات التي تقدمها، ثم حدد إنشاء. يستغرق بضع دقائق لإنشاء المجموعة. انتظر حتى يكتمل نشر الموارد.

12. وأخيرا، اختر Go to resource للانتقال إلى عنقود Azure DocumentDB في البوابة.

الحصول على بيانات اعتماد نظام المجموعة

احصل على بيانات الاعتماد التي تستخدمها للاتصال بالعنقود.

1. في صفحة المجموعة، اختر خيار سلاسل الاتصال في قائمة الموارد.

2. في قسم سلاسل الاتصال ، قم بنسخ أو تسجيل القيمة من حقل سلسلة الاتصال .

Important

لا تتضمن سلسلة الاتصال في البوابة الإلكترونية قيمة كلمة المرور. يجب استبدال العنصر النائب <password> ببيانات الاعتماد التي أدخلتها عند إنشاء نظام المجموعة أو إدخال كلمة المرور بشكل تفاعلي.

تهيئة المشروع

أنشئ مشروع تطبيق جديد لوحدة تحكم .NET في مجلدك الحالي.

1. ابدأ في دليل فارغ.

2. افتح طرفية في الدليل الحالي.

3. أنشئ تطبيق جديد لوحدة تحكم .NET.

   dotnet new console
   

4. ابن المشروع لضمان إنشاؤه بنجاح.

   dotnet build
   

تثبيت مكتبة العميل

تتوفر مكتبة العميل من خلال NuGet، كحزمة MongoDB.Driver .

1. قم بتثبيت برنامج تشغيل MongoDB .NET باستخدام مدير حزم NuGet.

   dotnet add package MongoDB.Driver
   

2. افتح وراجع ملف azure-documentdb-dotnet-quickstart.csproj للتحقق من وجود مرجع الحزمة.

3. استيراد المساحات الاسمية المطلوبة إلى رمز التطبيق الخاص بك:

   using System;
   using System.Collections.Generic;
   using System.Threading.Tasks;
   using MongoDB.Bson;
   using MongoDB.Bson.Serialization.Attributes;
   using MongoDB.Driver;
   

نموذج الكائن

Name	Description
MongoClient	النوع المستخدم للاتصال ب MongoDB.
IMongoDatabase	يمثل قاعدة بيانات في نظام المجموعة.
IMongoCollection<T>	يمثل مجموعة داخل قاعدة بيانات في نظام المجموعة.

أمثلة على التعليمات البرمجية

• مصادقة العميل
• الحصول على مجموعة
• أنشئ مستند
• استرجاع مستند
• الاستعلام عن المستندات

يرتبط الكود في هذا التطبيق بقاعدة بيانات مسماة adventureworks ومجموعة باسم products. تحتوي المجموعة products على تفاصيل مثل الاسم، الفئة، الكمية، معرف فريد، وعلم بيع لكل منتج. عينات الكود هنا تقوم بأكثر العمليات شيوعا عند العمل مع مجموعة.

مصادقة العميل

أولا، اتصل بالعميل باستخدام سلسلة اتصال أساسية.

1. أنشئ الطريقة الرئيسية وقم بإعداد سلسلة الاتصال. استبدل <your-cluster-name>، <your-username>، و <your-password> بمعلومات العنقود الفعلية الخاصة بك.

   class Program
   {
       static async Task Main(string[] args)
       {
           // Connection string for Azure DocumentDB cluster
           string connectionString = "mongodb+srv://<your-username>:<your-password>@<your-cluster-name>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000";
   
           // Create MongoDB client settings
           var settings = MongoClientSettings.FromConnectionString(connectionString);
   

2. أنشئ عميل MongoDB وتحقق من الاتصال.

           // Create a new client and connect to the server
           var client = new MongoClient(settings);
   
           // Ping the server to verify connection
           var database = client.GetDatabase("admin");
           var pingCommand = new BsonDocument("ping", 1);
           await database.RunCommandAsync<BsonDocument>(pingCommand);
   
           Console.WriteLine("Successfully connected and pinged Azure DocumentDB");
   

الحصول على مجموعة

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

1. احصل على مرجع لقاعدة البيانات.

           // Get database reference
           var adventureWorksDatabase = client.GetDatabase("adventureworks");
           Console.WriteLine($"Connected to database: {adventureWorksDatabase.DatabaseNamespace.DatabaseName}");
   

2. احصل على مرجع للمجموعة داخل قاعدة البيانات.

           // Get collection reference
           var productsCollection = adventureWorksDatabase.GetCollection<Product>("products");
           Console.WriteLine($"Connected to collection: products");
   

إنشاء مستند

ثم، أنشئ بعض المستندات الجديدة ضمن مجموعتك. قم بترقية الوثائق لضمان استبدال أي مستندات موجودة إذا كانت موجودة بالفعل بنفس المعرف الفريد.

1. حدد فئة منتج وأنشئ نماذج مستندات منتج.

           // Create sample products
           var products = new List<Product>
           {
               new Product
               {
                   Id = "00000000-0000-0000-0000-000000004018",
                   Name = "Windry Mittens",
                   Category = "apparel-accessories-gloves-and-mittens",
                   Quantity = 121,
                   Price = 35.00m,
                   Sale = false
               },
               new Product
               {
                   Id = "00000000-0000-0000-0000-000000004318",
                   Name = "Niborio Tent",
                   Category = "gear-camp-tents",
                   Quantity = 140,
                   Price = 420.00m,
                   Sale = true
               }
           };
   

2. أدخل المستندات باستخدام عمليات upsert.

           // Insert documents with upsert
           foreach (var product in products)
           {
               var filter = Builders<Product>.Filter.Eq(p => p.Id, product.Id);
               var options = new ReplaceOptions { IsUpsert = true };
   
               await productsCollection.ReplaceOneAsync(filter, product, options);
               Console.WriteLine($"Upserted product: {product.Name}");
           }
   

3. أضف تعريف فئة المنتج في نهاية ملف Program.cs الخاص بك.

   public class Product
   {
       [BsonId]
       [BsonElement("_id")]
       public string Id { get; set; }
   
       [BsonElement("name")]
       public string Name { get; set; }
   
       [BsonElement("category")]
       public string Category { get; set; }
   
       [BsonElement("quantity")]
       public int Quantity { get; set; }
   
       [BsonElement("price")]
       public decimal Price { get; set; }
   
       [BsonElement("sale")]
       public bool Sale { get; set; }
   }
   

استرجاع مستند

بعد ذلك، قم بإجراء عملية قراءة نقطية لاسترجاع مستند معين من مجموعتك.

1. حدد الفلتر للعثور على مستند معين حسب معرف.

           // Retrieve a specific document by ID
           var filter = Builders<Product>.Filter.Eq(p => p.Id, "00000000-0000-0000-0000-000000004018");
   

2. نفذ الاستعلام واسترج النتيجة.

           var retrievedProduct = await productsCollection.Find(filter).FirstOrDefaultAsync();
   
           if (retrievedProduct != null)
           {
               Console.WriteLine($"Retrieved product: {retrievedProduct.Name} - ${retrievedProduct.Price}");
           }
           else
           {
               Console.WriteLine("Product not found");
           }
   

الاستعلام عن المستندات

وأخيرا، استعلام عدة مستندات باستخدام لغة الاستعلام MongoDB (MQL).

1. حدد استعلاما للعثور على مستندات تطابق معايير محددة.

           // Query for products on sale
           var saleFilter = Builders<Product>.Filter.Eq(p => p.Sale, true);
           var saleProducts = await productsCollection.Find(saleFilter).ToListAsync();
   

2. كرر النتائج لعرض المستندات المطابقة.

           Console.WriteLine("Products on sale:");
           foreach (var product in saleProducts)
           {
               Console.WriteLine($"- {product.Name}: ${product.Price:F2} (Category: {product.Category})");
           }
       }
   }
   

استكشف بياناتك باستخدام كود Visual Studio

استخدم امتداد DocumentDB في كود Visual Studio لأداء العمليات الأساسية لقواعد البيانات، بما في ذلك الاستعلام، والإدراج، والتحديث، وحذف البيانات.

1. فتح Visual Studio Code.

2. انتقل إلى عرض الامتدادات وابحث عن المصطلح DocumentDB. حدد موقع امتداد DocumentDB ل VS Code .

3. اختر زر التثبيت الخاص بالامتداد. انتظر حتى يكتمل التثبيت. أعد تحميل كود فيجوال ستوديو إذا طلب منك ذلك.

4. انتقل إلى امتداد DocumentDB باختيار الأيقونة المقابلة في شريط النشاط.

5. في صفحة DocumentDB Connections ، اختر + اتصال جديد....

6. في الحوار، اختر Service Discovery ثم Azure DocumentDB - Azure Service Discovery.

7. اختر اشتراك Azure الخاص بك ومجموعة Azure DocumentDB التي أنشأتها حديثا.

   Tip

   في العديد من بيئات الشركة، يتم إخفاء عناوين IP لجهاز المطور بسبب VPN أو إعدادات شبكة الشركة الأخرى. في هذه الحالات، يمكنك السماح مؤقتا بالوصول إلى جميع عناوين IP بإضافة 0.0.0.0 - 255.255.255.255 نطاق عناوين IP كقاعدة جدار حماية. استخدم قاعدة جدار الحماية هذه مؤقتا فقط كجزء من اختبار وتطوير الاتصال. لمزيد من المعلومات، راجع تكوين جدار الحماية.

8. في نافذة DocumentDB Connections ، قم بتوسيع العقدة الخاصة بمجموعتك وانتقل إلى عقد المستندات والمجموعات الحالية.

9. افتح قائمة السياق للمجموعة ثم اختر DocumentDB Scrapbook > New DocumentDB Scrapbook.

10. أدخل أوامر لغة الاستعلام (MQL) التالية من MongoDB ثم اختر تشغيل الكل. راقب مخرجات الأوامر.

    db.products.find({
      price: { $gt: 200 },
      sale: true
    })
    .sort({ price: -1 })
    .limit(3)
    

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

عندما تنتهي من مجموعة Azure DocumentDB، يمكنك حذف الموارد التي أنشأتها في Azure حتى لا تتحمل المزيد من الرسوم.

1. في شريط البحث في مدخل Microsoft Azure، ابحث عن Resource groups وحددها.

   

2. في القائمة، حدد مجموعة الموارد التي استخدمتها لهذا التشغيل السريع.

   

3. في صفحة مجموعة الموارد، حدد "Delete resource group".

4. في مربع حوار تأكيد الحذف، أدخل اسم مجموعة الموارد لتأكيد أنك تنوي حذفها. وأخيرا، حدد حذف لحذف مجموعة الموارد نهائيا.

   

محتوى ذو صلة

• ما هو Azure DocumentDB؟