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

مقالة
04/09/2024

ينطبق على: NoSQL

يسمح لك Azure SDK ل .NET بالاستعلام عن البيانات في واجهة برمجة التطبيقات لحاوية NoSQL باستخدام LINQ في C#‎ أو سلسلة استعلام SQL. سيستعرض هذا البرنامج التعليمي عملية تحديث تطبيق ويب ASP.NET موجود يستخدم بيانات العنصر النائب للاستعلام بدلا من ذلك من واجهة برمجة التطبيقات.

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

إنشاء قاعدة بيانات وحاوية وتعبئتها باستخدام واجهة برمجة التطبيقات ل NoSQL
إنشاء تطبيق ويب ASP.NET من قالب
الاستعلام عن البيانات من واجهة برمجة التطبيقات لحاوية NoSQL باستخدام Azure SDK ل .NET

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

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

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

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

انتقل إلى واجهة برمجة التطبيقات الموجودة لحساب NoSQL في مدخل Microsoft Azure.
في قائمة الموارد، حدد Keys.
في صفحة Keys ، لاحظ قيمة الحقل PRIMARY CONNECTION STRING* وسجلها. سيتم استخدام هذه القيمة خلال البرنامج التعليمي.
في قائمة الموارد، حدد Data Explorer.
في صفحة Data Explorer ، حدد الخيار New Container في شريط الأوامر.

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

الإعداد	القيمة‬
مُعرِّف قاعدة البيانات	`cosmicworks`
نوع معدل نقل قاعدة البيانات	يدوي
مقدار معدل نقل قاعدة البيانات	`1000`
معرف الحاوية	`products`
⁧ مفتاح التقسيم⁧	`/category/name`

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

هام

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

حدد OK لإنشاء قاعدة البيانات والحاوية.
افتح محطة طرفية لتشغيل الأوامر لملء الحاوية بالبيانات.

تلميح

يمكنك اختياريا استخدام Azure Cloud Shell هنا.

تثبيت v2 من cosmicworks أداة dotnet من NuGet.

dotnet tool install --global cosmicworks  --version 2.*

cosmicworks استخدم الأداة لملء API لحساب NoSQL الخاص بك مع نموذج بيانات المنتج باستخدام قيم URI و PRIMARY KEY التي سجلتها سابقا في هذا المختبر. سيتم استخدام هذه القيم المسجلة endpoint للمعلمات و key على التوالي.
```
cosmicworks \
    --number-of-products 1759 \
    --number-of-employees 0 \
    --disable-hierarchical-partition-keys \
    --connection-string <nosql-connection-string>
```

لاحظ الإخراج من أداة سطر الأوامر. يجب أن تضيف 1759 عنصرا إلى الحاوية. يتم اقتطاع مثال الإخراج المضمن للإيجاز.

── Parsing connection string ────────────────────────────────────────────────────────────────
╭─Connection string──────────────────────────────────────────────────────────────────────────╮
│ AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>;  │
╰────────────────────────────────────────────────────────────────────────────────────────────╯
── Populating data ──────────────────────────────────────────────────────────────────────────
╭─Products configuration─────────────────────────────────────────────────────────────────────╮
│ Database   cosmicworks                                                                     │
│ Container  products                                                                        │
│ Count      1,759                                                                           │
╰────────────────────────────────────────────────────────────────────────────────────────────╯
...
[SEED]  00000000-0000-0000-0000-000000005951 | Road-650 Black, 60 - Bikes
[SEED]  00000000-0000-0000-0000-000000005950 | Mountain-100 Silver, 42 - Bikes
[SEED]  00000000-0000-0000-0000-000000005949 | Men's Bib-Shorts, L - Clothing
[SEED]  00000000-0000-0000-0000-000000005948 | ML Mountain Front Wheel - Components
[SEED]  00000000-0000-0000-0000-000000005947 | Mountain-500 Silver, 42 - Bikes

ارجع إلى صفحة مستكشف البيانات لحسابك.
في قسم Data ، قم بتوسيع عقدة cosmicworks قاعدة البيانات ثم حدد Scale.
تقليل معدل النقل من 1000 إلى 400.
في شريط الأوامر، حدد Save.
في قسم البيانات ، قم بتوسيع وتحديد عقدة حاوية المنتجات .
في شريط الأوامر، حدد استعلام SQL جديد.

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

SELECT
  p.sku,
  p.price
FROM products p
WHERE p.price < 2000
ORDER BY p.price DESC

حدد Execute Query لتشغيل الاستعلام ومراقبة النتائج.
يجب أن تكون النتائج مصفوفة مرقمة من جميع العناصر في الحاوية بقيمة price أقل من 2000 تم فرزها من أعلى سعر إلى أدنى سعر. للإيجاز، يتم تضمين مجموعة فرعية من الإخراج هنا.
```
[
  {
    "sku": "BK-R79Y-48",
    "price": 1700.99
  },
  ...
  {
    "sku": "FR-M94B-46",
    "price": 1349.6
  },
...
```

استبدل محتوى محرر الاستعلام بهذا الاستعلام ثم حدد Execute Query مرة أخرى لمراقبة النتائج.

SELECT
    p.name,
    p.category.name AS category,
    p.category.subCategory.name AS subcategory,
    p.tags
FROM products p
JOIN tag IN p.tags
WHERE STRINGEQUALS(tag, "yellow", true)

يجب أن تكون النتائج عبارة عن صفيف أصغر من العناصر التي تمت تصفيتها لتحتوي فقط على عناصر تتضمن علامة واحدة على الأقل بقيمة اسم .Tag-32 مرة أخرى، يتم تضمين مجموعة فرعية من الإخراج هنا للإيجاز.
```
[
  ...
  {
    "name": "HL Touring Frame - Yellow, 60",
    "category": "Components",
    "subcategory": "Touring Frames",
    "tags": [
      "Components",
      "Touring Frames",
      "Yellow",
      "60"
    ]
  },
  ...
]
```

إنشاء تطبيق ويب ASP.NET

الآن، ستقوم بإنشاء تطبيق ويب ASP.NET جديد باستخدام نموذج قالب مشروع. ثم ستستكشف التعليمات البرمجية المصدر وتشغل العينة للتعرف على التطبيق قبل إضافة اتصال Azure Cosmos DB باستخدام Azure SDK ل .NET.

هام

يسحب هذا البرنامج التعليمي الحزم بشفافية من NuGet. يمكنك استخدام dotnet nuget list source للتحقق من مصادر الحزمة الخاصة بك. إذا لم يكن لديك NuGet كمصدر حزمة، فاستخدم dotnet nuget add source لتثبيت الموقع كمصدر.

افتح محطة طرفية في دليل فارغ.
تثبيت حزمة cosmicworks.template.web قالب المشروع من NuGet.
```
dotnet new install cosmicworks.template.web
```
إنشاء مشروع تطبيق ويب جديد باستخدام القالب المثبت dotnet new cosmosdbnosql-webapp حديثا.
```
dotnet new cosmosdbnosql-webapp
```
إنشاء مشروع تطبيق الويب وتشغيله.
```
dotnet run
```

لاحظ إخراج أمر التشغيل. يجب أن يتضمن الإخراج قائمة بالمنافذ وعناوين URL حيث يتم تشغيل التطبيق.

...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
...

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

تلميح

استخدم الأمر Ctrl+C لإيقاف عملية قيد التشغيل. بدلا من ذلك، يمكنك إغلاق المحطة الطرفية وإعادة فتحها.
افتح Visual Studio Code باستخدام مجلد المشروع الحالي كمساحة عمل.

تلميح

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

انتقل إلى ملف Services/ICosmosService.cs وافتحه. RetrieveActiveProductsAsync راقب تنفيذي الأسلوب الافتراضي وRetrieveAllProductsAsync. تنشئ هذه الطرق قائمة ثابتة بالمنتجات لاستخدامها عند تشغيل المشروع للمرة الأولى. يتم توفير مثال مقتطع لإحدى الطرق هنا.

public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync()
{
    await Task.Delay(1);

    return new List<Product>()
    {
        new Product(id: "baaa4d2d-5ebe-45fb-9a5c-d06876f408e0", category: new Category(name: "Components, Road Frames"), sku: "FR-R72R-60", name: """ML Road Frame - Red, 60""", description: """The product called "ML Road Frame - Red, 60".""", price: 594.83000000000004m),
        new Product(id: "bd43543e-024c-4cda-a852-e29202310214", category: new Category(name: "Components, Forks"), sku: "FK-5136", name: """ML Fork""", description: """The product called "ML Fork".""", price: 175.49000000000001m),
        ...
    };
}

انتقل إلى ملف Services/CosmosService.cs وافتحه. مراقبة التنفيذ الحالي لفئة CosmosService . تنفذ هذه الفئة واجهة ICosmosService ولكنها لا تتجاوز أي أساليب. في هذا السياق، ستستخدم الفئة تنفيذ الواجهة الافتراضية حتى يتم توفير تجاوز التنفيذ في الواجهة.
```
public class CosmosService : ICosmosService
{ }
```
وأخيرا، انتقل إلى ملفات Models/Product.cs و Models/Category.cs وافتحها. لاحظ أنواع السجلات المعرفة في كل ملف. سيتم استخدام هذه الأنواع في الاستعلامات خلال هذا البرنامج التعليمي.
```
public record Product(
    string id,
    Category category,
    string sku,
    string name,
    string description,
    decimal price
);
```
```
public record Category(
    string name
);
```

الاستعلام عن البيانات باستخدام .NET SDK

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

مرة أخرى في المحطة الطرفية، أضف الحزمة Microsoft.Azure.Cosmos من NuGet.
```
dotnet add package Microsoft.Azure.Cosmos
```
أنشئ المشروع.
```
dotnet build
```
مرة أخرى في Visual Studio Code، انتقل مرة أخرى إلى ملف Services/CosmosService.cs .
أضف توجيها جديدا باستخدام لمساحات Microsoft.Azure.Cosmos الأسماء و Microsoft.Azure.Cosmos.Linq .
```
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Linq;
```
ضمن فئة CosmosService، أضف عضوا جديدا private readonly من النوع CosmosClient المسمى _client.
```
private readonly CosmosClient _client;
```
إنشاء منشئ فارغ جديد للفئة CosmosService .
```
public CosmosService()
{ }
```
داخل الدالة الإنشائية، قم بإنشاء مثيل جديد للفئة التي CosmosClient تمر في معلمة سلسلة بقيمة PRIMARY CONNECTION STRING التي سجلتها مسبقا في المختبر. قم بتخزين هذا المثيل الجديد في _client العضو.
```
public CosmosService()
{ 
    _client = new CosmosClient(
        connectionString: "<primary-connection-string>"
    );
}
```
مرة أخرى داخل فئة CosmosService ، قم بإنشاء خاصية جديدة private من النوع Container المسماة container. قم بتعيين الحصول على الملحق لإرجاع cosmicworks قاعدة البيانات والحاويةproducts.
```
private Container container
{
    get => _client.GetDatabase("cosmicworks").GetContainer("products");
}
```
قم بإنشاء أسلوب غير متزامن جديد يسمى RetrieveAllProductsAsync الذي يقوم بإرجاع IEnumerable<Product>.
```
public async Task<IEnumerable<Product>> RetrieveAllProductsAsync()
{ }
```
للخطوات التالية، أضف هذه التعليمة البرمجية RetrieveAllProductsAsync داخل الأسلوب .
1. GetItemLinqQueryable<> استخدم الأسلوب العام للحصول على عنصر من النوع IQueryable<> الذي يمكنك استخدامه لإنشاء استعلام متكامل اللغة (LINQ). قم بتخزين هذا الكائن في متغير يسمى queryable.
```
var queryable = container.GetItemLinqQueryable<Product>();
```
2. إنشاء استعلام LINQ باستخدام أسلوبي Where الملحق و OrderByDescending . استخدم أسلوب الملحق ToFeedIterator لإنشاء مكرر للحصول على البيانات من Azure Cosmos DB وتخزين المكرر في متغير يسمى feed. قم بتضمين هذا التعبير بأكمله في عبارة استخدام للتخلص من المكرر لاحقا.
```
using FeedIterator<Product> feed = queryable
    .Where(p => p.price < 2000m)
    .OrderByDescending(p => p.price)
    .ToFeedIterator();
```
3. إنشاء متغير جديد باسم results باستخدام النوع العام List<> .
```
List<Product> results = new();
```
4. إنشاء حلقة while التي سيتم تكرارها حتى HasMoreResults تقوم خاصية feed المتغير بإرجاع false. سيضمن هذا التكرار الحلقي تكرارا حلقيا عبر جميع صفحات النتائج من جانب الخادم.
```
while (feed.HasMoreResults)
{ }
```
5. ضمن التكرار الحلقي while ، قم باستدعاء ReadNextAsync أسلوب feed المتغير بشكل غير متزامن وتخزين النتيجة في متغير يسمى response.
```
while (feed.HasMoreResults)
{
    var response = await feed.ReadNextAsync();
}
```
6. لا يزال ضمن التكرار الحلقي while ، استخدم حلقة foreach للانتقال عبر كل عنصر في الاستجابة وإضافته إلى results القائمة.
```
while (feed.HasMoreResults)
{
    var response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        results.Add(item);
    }
}
```
7. results إرجاع القائمة كإخراج للأسلوبRetrieveAllProductsAsync.
```
return results;
```
قم بإنشاء أسلوب غير متزامن جديد يسمى RetrieveActiveProductsAsync الذي يقوم بإرجاع IEnumerable<Product>.
```
public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync()
{ }
```
للخطوات التالية، أضف هذه التعليمة البرمجية RetrieveActiveProductsAsync داخل الأسلوب .
1. إنشاء سلسلة جديدة باسم sql مع استعلام SQL لاسترداد حقول متعددة حيث يتم تطبيق عامل تصفية (@tagFilter) على صفيف علامات لكل عنصر.
```
string sql = """
SELECT
    p.id,
    p.name,
    p.category,
    p.sku,
    p.description,
    p.price
FROM products p
JOIN tag IN p.tags
WHERE STRINGEQUALS(tag, @tagFilter, true)
""";
```
2. إنشاء متغير جديد QueryDefinition يسمى query تمرير في sql السلسلة كمعلمة الاستعلام الوحيدة. أيضا، استخدم WithParameter الأسلوب fluid لتطبيق القيمة red على المعلمة @tagFilter .
```
var query = new QueryDefinition(
    query: sql
)
    .WithParameter("@tagFilter", "red");
```
3. GetItemQueryIterator<> استخدم الأسلوب العام والمتغير query لإنشاء مكرر يحصل على البيانات من Azure Cosmos DB. تخزين المكرر في متغير يسمى feed. قم بتضمين هذا التعبير بأكمله في عبارة استخدام للتخلص من المكرر لاحقا.
```
using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);
```
4. استخدم حلقة while للتكرار عبر صفحات متعددة من النتائج وتخزين القيمة في نتائج عامة مسماة List<>. إرجاع النتائج كإخراج للأسلوبRetrieveActiveProductsAsync.
```
List<Product> results = new();

while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        results.Add(item);
    }
}

return results;
```
احفظملف Services/CosmosClient.cs .

تلميح

إذا لم تكن متأكدا من صحة التعليمات البرمجية الخاصة بك، يمكنك التحقق من التعليمات البرمجية المصدر مقابل نموذج التعليمات البرمجية على GitHub.

التحقق من صحة التطبيق النهائي

وأخيرا، ستقوم بتشغيل التطبيق مع تمكين عمليات إعادة التحميل الساخنة . سيؤدي تشغيل التطبيق إلى التحقق من أن التعليمات البرمجية الخاصة بك يمكنها الوصول إلى البيانات من واجهة برمجة التطبيقات ل NoSQL.

مرة أخرى في المحطة الطرفية، قم بتشغيل التطبيق.
```
dotnet run
```
يجب أن يتضمن إخراج أمر التشغيل قائمة بالمنافذ وعناوين URL حيث يتم تشغيل التطبيق. افتح مستعرضا جديدا وانتقل إلى تطبيق الويب قيد التشغيل. راقب جميع الصفحات الثلاث للتطبيق قيد التشغيل. يجب أن تتضمن كل صفحة الآن بيانات مباشرة من Azure Cosmos DB.

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

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

الخطوات التالية

الآن بعد أن قمت بإنشاء أول تطبيق ويب .NET باستخدام Azure Cosmos DB، يمكنك الآن التعمق في SDK لاستيراد المزيد من البيانات، وتنفيذ الاستعلامات المعقدة، وإدارة Azure Cosmos DB لموارد NoSQL.

بدء استخدام Azure Cosmos DB ل NoSQL و.NET

مشاركة عبر