Emiliano Montesdeoca

Blazor من الصفر: الفصل 3 — مكوّنات قابلة للتوسّع

Mon, 01 Jun 2026 00:00:00 +0000

مرحبًا بك في الفصل 3 من Blazor من الصفر. إذا فاتك الفصل 2، ابدأ به أولًا حتى يكون مشروعك الأساسي جاهزًا.

في الفصل 2 جعلنا التطبيق يعمل. في هذا الفصل سنجعل الكود قابلاً للصيانة.

مشاريع Blazor تصبح فوضوية بسرعة عندما تتحول كل صفحة إلى ملف .razor ضخم. المكوّنات هي الحل: اتساق أعلى، إعادة استخدام أفضل، وحدود أوضح بين أجزاء الواجهة.

ما هو مكوّن Blazor فعليًا؟

المكوّن هو ملف .razor يستطيع:

عرض الـ markup
حفظ حالة محلية
استقبال مدخلات عبر Parameters
إرسال أحداث إلى المكوّن الأب
عرض محتوى فرعي

أثناء التشغيل، يتعامل Blazor مع كل مكوّن كآلة حالة صغيرة. عند تغيّر الحالة يعيد التصيير ويطبّق DOM diff.

لذلك الهدف هو تصميم مدخلات واضحة وسلوك متوقّع.

الخطوة 1: ابدأ بمكوّن صغير ومحدد

أنشئ Components/Common/SectionHeader.razor:

<header class="section-header">
 <h2>@Title</h2>
 @if (!string.IsNullOrWhiteSpace(Subtitle))
 {
 <p>@Subtitle</p>
 }
</header>

@code {
 [Parameter] public string Title { get; set; } = string.Empty;
 [Parameter] public string? Subtitle { get; set; }
}

استخدمه في Components/Pages/Home.razor:

@page "/"

<PageTitle>Blazor من الصفر</PageTitle>

<SectionHeader
 Title="Blazor من الصفر"
 Subtitle="الفصل 3 عن المكوّنات." />

المثال بسيط، لكن الفكرة محورية: يجب أن يُفهم المكوّن من خلال معاملاته.

الخطوة 2: اجعل السلوك صريحًا بالمعاملات

لننشئ زرًا قابلاً لإعادة الاستخدام.

Components/Common/AppButton.razor:

<button class="app-button @VariantCssClass" @onclick="OnClick">
 @Text
</button>

@code {
 [Parameter] public string Text { get; set; } = "Button";
 [Parameter] public string Variant { get; set; } = "primary";
 [Parameter] public EventCallback OnClick { get; set; }

 private string VariantCssClass => Variant.ToLowerInvariant() switch
 {
 "secondary" => "app-button--secondary",
 "danger" => "app-button--danger",
 _ => "app-button--primary"
 };
}

الاستخدام:

@code {
 private int _savedCount;

 private void Save()
 {
 _savedCount++;
 }
}

<AppButton Text="Save" Variant="primary" OnClick="Save" />
<p>تم الحفظ @_savedCount مرة.</p>

المهم هنا هو تصميم العقد:

معاملات قليلة وواضحة
أسماء صريحة بدل سلوك “سحري”
قيم افتراضية آمنة

الخطوة 3: استخدم `RenderFragment` للتركيب

RenderFragment يسمح للمكوّن الأب بتمرير أجزاء واجهة إلى المكوّن الابن.

أنشئ Components/Common/Card.razor:

<article class="card">
 <header class="card__header">@Title</header>
 <section class="card__body">
 @ChildContent
 </section>
</article>

@code {
 [Parameter] public string Title { get; set; } = string.Empty;
 [Parameter] public RenderFragment? ChildContent { get; set; }
}

الاستخدام:

<Card Title="Roadmap">
 <ul>
 <li>المكوّنات</li>
 <li>Data binding</li>
 <li>Routing</li>
 </ul>
</Card>

هذا النمط يساعدك على بناء صفحات متناسقة بدون تكرار نفس wrapper markup.

الخطوة 4: فضّل التركيب على الصفحات العملاقة

عندما تكبر الصفحة، قسّمها حسب المسؤولية:

ProfileSummary لكتلة التعريف
ProfileStats للمؤشرات
ProfileActivityList للنشاط الأخير

بهذا تصبح الصفحة طبقة تنسيق، وليست مكانًا لكل التفاصيل.

الخطوة 5: وازن بين الـ markup والمنطق

في المكوّنات البسيطة، @code داخل الملف كافٍ.

في المكوّنات الكبيرة، انقل المنطق إلى code-behind:

UserCard.razor
UserCard.razor.cs

هذا يجعل كلًا من الواجهة ومنطق C# أسهل قراءة.

الخطوة 6: بنية مجلدات عملية

بنية فعالة مع النمو:

Components/Pages/ -> صفحات قابلة للتوجيه
Components/Layout/ -> هيكل التطبيق والتنقّل
Components/Common/ -> عناصر عامة مشتركة
Components/Features/<FeatureName>/ -> مكوّنات خاصة بكل ميزة

أخطاء شائعة في بدايات مشاريع Blazor

تمرير عدد كبير من المعاملات بدل نموذج مخصص
وضع قواعد العمل داخل مكوّنات الصفحات
إنشاء “مكوّن إلهي” بعدد هائل من الأسطر
تكرار markup بدل استخراج مكوّنات صغيرة قابلة لإعادة الاستخدام

الفصل القادم

في الفصل 4 سنركّز على Data binding والأحداث: @bind، التعامل مع الأحداث، مفاضلات two-way binding، وأنماط تبقي الحالة متوقعة.

Blazor من الصفر: الفصل 2 — أول تطبيق Blazor لك

Thu, 14 May 2026 00:00:00 +0000

مرحباً بك في الفصل 2 من Blazor من الصفر. إذا فاتك الفصل 1، اقرأه أولاً.

في هذا الفصل سننشئ تطبيق Blazor جديداً، نشغله محلياً، ونفهم دور الملفات المهمة.

الخطوة 1: إنشاء المشروع

من الطرفية:

dotnet new blazor -o BlazorFromScratch
cd BlazorFromScratch

هذا ينشئ تطبيق Blazor Web App على .NET 9 بالهيكل الافتراضي.

إذا طلبت منك الأداة اختيار نموذج التفاعلية، ابدأ بـ Interactive Server.

الخطوة 2: التشغيل محلياً

شغّل التطبيق:

dotnet watch

ثم افتح الرابط الذي يظهر في الطرفية (غالباً https://localhost:5xxx). يجب أن ترى الصفحات الافتراضية Home وCounter وWeather.

إذا عمل ذلك، فبيئة التطوير جاهزة.

الخطوة 3: فهم هيكل المشروع

هذه أهم الملفات والمجلدات التي تحتاج معرفتها أولاً:

Program.cs — تسجيل الخدمات وضبط HTTP pipeline.
Components/App.razor — المكوّن الجذري للتطبيق.
Components/Routes.razor — تعريف المسارات.
Components/Pages/ — الصفحات القابلة للتوجيه مثل Home وCounter.
Components/Layout/ — التخطيط المشترك (MainLayout.razor والقائمة).
wwwroot/ — الملفات الثابتة (CSS، الصور، favicon).
appsettings.json — قيم الإعدادات.

لا تحتاج لفهم كل ملف الآن. يكفي في هذه المرحلة معرفة مكان الواجهة ومكان إعداد التشغيل.

الخطوة 4: نفّذ أول تعديل

افتح Components/Pages/Home.razor واستبدل المحتوى بـ:

@page "/"

<PageTitle>Blazor من الصفر</PageTitle>

<h1>Blazor من الصفر</h1>
<p>الفصل 2 يعمل محلياً.</p>

احفظ الملف ثم حدّث المتصفح. مع dotnet watch سيظهر التغيير مباشرة.

هذا التعديل البسيط يؤكد الدورة الكاملة: تعديل -> بناء -> عرض.

الخطوة 5: اقرأ Program.cs مرة واحدة

لا تحتاج لحفظه، لكن تعرّف على الأسطر الأساسية:

AddRazorComponents() لتفعيل Razor components.
AddInteractiveServerComponents() لتفعيل المكوّنات التفاعلية على الخادم.
MapRazorComponents<App>() لربط المكوّن الجذري بنقاط النهاية.

هذه الأسطر توضّح كيف يبدأ التطبيق وما قدرات العرض المفعّلة.

مشاكل شائعة

إذا فشل التشغيل، فغالباً السبب أحد التالي:

إصدار SDK قديم: نفّذ dotnet --version وتأكد من .NET 9.
تحذير شهادة HTTPS: نفّذ dotnet dev-certs https --trust.
تعارض المنفذ: أوقف عمليات dotnet القديمة ثم أعد التشغيل.

القادم

في الفصل 3 سنتعمّق في المكوّنات: المعاملات، التركيب، وكيفية تنظيم واجهة قابلة لإعادة الاستخدام.

Blazor من الصفر: الفصل الأول — ما هو Blazor؟

Fri, 08 May 2026 00:00:00 +0000

مرحباً بك في الفصل الأول من سلسلة Blazor من الصفر. إذا فاتك منشور المقدمة حيث شرحت الغرض من هذه السلسلة والجمهور المستهدف، ابدأ بقراءته أولاً — فهو قصير.

في هذا الفصل سنجيب على السؤال الجوهري: ما هو Blazor؟ يبدو هذا بسيطاً، لكن الإجابة ذات طبقات متعددة — لا سيما أن “Blazor” اكتسب معاني متباينة قليلاً عبر السنوات. بنهاية هذا المنشور ستعرف ما هو Blazor، وكيف يندرج ضمن منظومة .NET، وما هي نماذج التصيير المختلفة، ولماذا قد تختاره بدلاً من إطار عمل JavaScript — أو لا تختاره.

نبذة تاريخية مختصرة

بدأ Blazor كمشروع تجريبي لـ Steve Sanderson في Microsoft حوالي عام 2017. كانت الفكرة استفزازية: تشغيل C# في المتصفح باستخدام WebAssembly، مما يُلغي الحاجة إلى JavaScript كلياً. كان ذلك دليلاً على المفهوم، والاسم كان مزجاً مقصوداً بين Blazer وRazor — محرك القوالب الذي بُني عليه Blazor في نهاية المطاف.

أثار التجربةُ حماساً كافياً جعل Microsoft تأخذها بجدية. شُحن Blazor كجزء من ASP.NET Core 3.0 في سبتمبر 2019 — أولاً كـ Blazor Server: نموذج يُشغّل كود C# على الخادم ويستخدم اتصال SignalR في الوقت الحقيقي لإرسال تحديثات واجهة المستخدم إلى المتصفح. تبعه Blazor WebAssembly كجزء من ASP.NET Core 3.1 في مايو 2020، مُجلِباً تنفيذاً حقيقياً على جانب العميل للإطار.

صقّل .NET 6 و7 تجربة المطورين. ثم جاء .NET 8، الذي صدر في نوفمبر 2023، ليُعيد التفكير جذرياً في نموذج التصيير بما أسمته Microsoft واجهة مستخدم ويب متكاملة. باتت التصيير الثابت من جانب الخادم، والتصيير المتدفق، والخادم التفاعلي، وWebAssembly التفاعلي، ووضع Auto الجديد تتعايش جميعها تحت سقف واحد في مشروع واحد. أسهم .NET 9 في البناء على هذا الأساس وتصحيح العقبات.

هذا هو المكان الذي نقف فيه اليوم.

ما هو Blazor فعلاً

في جوهره، Blazor هو إطار عمل لواجهة المستخدم مبني على المكونات لـ .NET. تبني واجهتك من مكونات — وحدات مستقلة من C# وترميز HTML قادرة على الاحتفاظ بالحالة والاستجابة للأحداث وتأليف هياكل أكبر. إذا عملت مع React أو Vue فسيبدو هذا النموذج الذهني مألوفاً. الفارق الرئيسي أنك تكتب C# بدلاً من JavaScript.

تُكتب المكونات في Blazor في ملفات .razor. يمزج ملف .razor بين ترميز HTML وكود C# باستخدام صيغة Razor التي ربما تعرفها من عروض ASP.NET MVC. هكذا يبدو مكوّن بسيط:

@page "/counter"

<h1>عدّاد</h1>
<p>العدد الحالي: @currentCount</p>
<button @onclick="IncrementCount">انقر هنا</button>

@code {
 private int currentCount = 0;

 private void IncrementCount()
 {
 currentCount++;
 }
}

لا أثر لـ JavaScript. يربط توجيه @onclick النقر على الزر بطريقة C#. يُصيّر التعبير @currentCount القيمة الحالية. حين تتغير الحالة يُحدد Blazor ما يجب تحديثه في DOM.

هذا هو الجوهر. كل ما سواه — التوجيه، وحقن التبعيات، والنماذج، واستدعاءات HTTP — مبني فوق نموذج المكونات هذا.

نماذج التصيير

هنا يتمركز كثير من الالتباس، فلنكن دقيقين. “Blazor” اليوم يُشير إلى عائلة من أوضاع التصيير، لا إلى نموذج نشر وحيد. فهم الفارق مهم لأنه يؤثر في الأداء ومتطلبات البنية التحتية وما يستطيع مكوناتك وما لا تستطيع فعله.

SSR الثابت

أبسط الأوضاع. تُصيَّر مكونات Razor على الخادم إلى HTML ويُرسل ذلك HTML إلى المتصفح. لا اتصال دائم، لا WebAssembly، ولا تفاعلية من جانب العميل افتراضياً. هذا جوهرياً ما تفعله Razor Pages، لكن باستخدام نموذج المكونات.

استخدمه للصفحات الغنية بالمحتوى، وصفحات الهبوط، وكل ما لا يحتاج إلى تفاعلية حية.

الخادم التفاعلي

يعمل كود المكون على الخادم. تُقام اتصال WebSocket عبر SignalR بين المتصفح والخادم. حين تنقر على زر أو تكتب في حقل إدخال، ينتقل الحدث عبر WebSocket إلى الخادم، يُنفَّذ كود C#، يُحسب الفرق، وتُرسل تحديثات DOM إلى المتصفح.

المزايا: وصول كامل لموارد الخادم (قواعد البيانات، نظام الملفات، الأسرار). تحميل أولي سريع. حجم تنزيل صغير. يعمل في متصفحات بلا دعم لـ WebAssembly.

العيوب: كل تفاعل مستخدم يستلزم رحلة ذهاباً وإياباً للخادم، مما يضيف زمن استجابة. تتوسع موارد الخادم مع عدد الاتصالات النشطة. تتدهور التطبيق عند انقطاع الاتصال.

استخدمه لتطبيقات الأعمال والأدوات الداخلية والتطبيقات التي يُقدَّم فيها الوصول للبيانات على الخادم على حساب قدرة العمل دون اتصال.

WebAssembly التفاعلي

يُنزَّل وقت تشغيل .NET إلى المتصفح ويعمل تطبيقك بالكامل على جانب العميل. بعد التنزيل الأولي يعمل التطبيق بشكل كامل دون اتصال وكل تفاعل فوري — لا رحلات للخادم لمنطق الواجهة.

المزايا: تنفيذ حقيقي من جانب العميل. يعمل دون اتصال. تقليل الحمل على الخادم بعد تحميل التطبيق.

العيوب: تنزيل أولي أكبر (وقت تشغيل .NET + تطبيقك). تحميل أبطأ عند أول زيارة. تحتاج إلى API للوصول إلى البيانات من جانب الخادم.

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

وضع Auto

مُقدَّم في .NET 8. يبدأ التطبيق في وضع الخادم التفاعلي (تحميل أولي سريع، دون انتظار تنزيل WebAssembly). بمجرد تنزيل ملفات WebAssembly في الخلفية تتحول الزيارات اللاحقة تلقائياً إلى وضع WebAssembly.

يمنحك هذا التحميل الأولي السريع لوضع الخادم والتنفيذ الكامل من جانب العميل لـ WebAssembly في نهاية المطاف. إنه أكثر النماذج تعقيداً في الاستيعاب، لكنه قيمة افتراضية عملية لكثير من التطبيقات.

مزج الأوضاع في التطبيق الواحد

في .NET 8 وما بعده لست مُقيَّداً بوضع تصيير واحد لكامل التطبيق. يمكن أن تكون صفحة الهبوط التسويقية SSR ثابتاً؛ ولوحة التحكم المُصادَق عليها خادماً تفاعلياً؛ وأداة تصور البيانات WebAssembly تفاعلياً. يتولى الإطار إدارة الانتقالات.

في هذه السلسلة سنبدأ بالخادم التفاعلي لأنه الأسهل تشغيلاً ويتميز بنموذج ذهني أكثر مباشرة. سنستكشف الأوضاع الأخرى مع التقدم.

كيف يقارن Blazor بأطر عمل JavaScript

إذا بنيت مع React أو Angular أو Vue فهذه على الأرجح المقارنة التي تستفسر عنها.

أوجه الشبه حقيقية. نموذج مكونات Blazor مشابه عمداً لـ React. لديك props (Parameters في Blazor)، وحالة محلية (حقول في كتلة @code)، وخطافات دورة الحياة، ونمط الاتصال ذاته: البيانات للأسفل والأحداث للأعلى. إذا عرفت React ستشعر بالألفة في غضون ساعات.

الفارق الرئيسي هو اللغة. في Blazor تكتب C#. يمكن مشاركة منطق الأعمال وقواعد التحقق ونماذج البيانات بين واجهتك في Blazor وخلفيتك في ASP.NET Core. لن تحتاج بعد الآن لتكرار صنف User في TypeScript وهو موجود لديك في C#.

الفجوة في النظام البيئي حقيقية لكنها تضيق. النظام البيئي لـ npm ضخم. النظام البيئي لـ NuGet لمكونات الواجهة أصغر، رغم أنه نما بشكل ملحوظ. إذا احتجت مكتبة رسوم بيانية محددة أو أداة سحب وإفلات فلا يزال JavaScript يوفر خيارات أكثر. لكن لمعظم تطبيقات الأعمال، ما هو متاح في عالم .NET يزيد على الكفاية.

التشغيل البيني مع JavaScript موجود حين تحتاجه. يتيح لك Blazor استدعاء JavaScript من C# وC# من JavaScript. لواجهات برمجة المتصفح التي تفتقر لغلاف .NET، أو حين تريد استخدام مكتبة JS موجودة، فالتشغيل البيني متاح. يُضيف طبقة لكنه ليس مؤلماً.

الإجابة الصادقة: إذا كان فريقك بالكامل من مطوري JavaScript ويبنون منتجاً عاماً يُعدّ فيه SEO والأداء ونظام npm البيئي أموراً جوهرية، التزم بـ JavaScript. إذا كان فريقك من مطوري .NET، أو إذا كنت تبني تطبيقات داخلية أو خاصة بالأعمال، أو إذا كانت مشاركة الكود بين الواجهتين الأمامية والخلفية مهمة لك، فـ Blazor خيار مقنع.

ما تحتاجه للمتابعة

لبقية هذه السلسلة ستحتاج إلى:

.NET 9 SDK — حمّله من dot.net
بيئة تطوير — Visual Studio 2022 (الإصدار المجتمعي مجاني)، أو VS Code مع امتداد C# Dev Kit، أو JetBrains Rider
إلمام أساسي بـ C# — الأصناف والخصائص والواجهات وasync/await

هذا كل شيء. لا Node، لا npm، لا webpack.

الفصل القادم

في الفصل الثاني سننشئ تطبيق Blazor الأول لك، ونستعرض هيكل المشروع، ونتأكد من قدرتك على تشغيله محلياً. ستخرج منه بتطبيق يعمل وصورة واضحة عما يفعله كل ملف.

نلتقي هناك.

Blazor من الصفر: سلسلة جديدة

Mon, 04 May 2026 00:00:00 +0000

أكتب عن Blazor منذ فترة — دورات حياة المكوّنات، CSS المعزول، نماذج التفاعل، المصادقة. كانت هذه المقالات مفيدة بحد ذاتها، لكنني دائمًا شعرت أنها تفتقر إلى الأساس. إذ تفترض أنك تعرف بالفعل ما هو Blazor، ولماذا وُجد، وكيف يندرج في منظومة .NET. ليس الجميع يعرف ذلك، وهذا أمر طبيعي تمامًا.

لذا أبدأ شيئًا جديدًا: Blazor من الصفر. سلسلة متكاملة، مبنية من الأساس، موجّهة للمطوّرين الذين يريدون فهمًا حقيقيًا لما يبنونه — لا مجرد لصق الكود حتى يعمل.

لمن هذه السلسلة

هذه السلسلة مناسبة لك إذا كنت:

مطوّر .NET سمعت عن Blazor لكن لم تجد الوقت أو نقطة الانطلاق المناسبة للتعمق فيه.
جرّبت Blazor وجعلته يعمل، لكنك تشعر أنك تخمّن لماذا تعمل الأشياء.
قادمًا من عالم JavaScript/React/Angular وتريد فهم رؤية Microsoft للواجهة الأمامية الحديثة.
تريد مرجعًا موحّدًا ومتسقًا بدلًا من توثيق متفرّق ومقالات مبعثرة.

لا تحتاج إلى أن تكون مطوّرًا متقدمًا. تحتاج فقط إلى إتقان أساسيات C# — الكلاسات، الواجهات، async/await. إذا كنت قادرًا على كتابة API CRUD بسيط في ASP.NET Core، فأنت مستعد.

ما سنتناوله

إليك خارطة الطريق التقريبية لما أخطط له:

ما هو Blazor؟ — نماذج الاستضافة، التاريخ، المقارنة مع تطوير الويب التقليدي
تطبيقك الأول في Blazor — البنية الأولية للمشروع، التشغيل محليًا
المكوّنات — اللبنة الأساسية لكل واجهة في Blazor
ربط البيانات والأحداث — جعل واجهتك تفاعلية
التواصل بين المكوّنات — المعاملات، EventCallbacks، القيم المتتالية
التوجيه والتنقل — كيف يتعامل Blazor مع الـ URLs وانتقالات الصفحات
حقن التبعيات — الخدمات، النطاقات، وحاوية DI في Blazor
النماذج والتحقق — EditForm، DataAnnotations، المحقّقات المخصصة
HTTP والبيانات الخارجية — استدعاء APIs من تطبيق Blazor
المصادقة والتفويض — تأمين تطبيقك بالطريقة الصحيحة
التشغيل البيني مع JavaScript — متى تحتاج للوصول إلى المتصفح
الأداء والتحسين — التمثيل الافتراضي، التحميل الكسول، استراتيجيات الرندر
اختبار مكوّنات Blazor — bUnit وكيف يبدو الاختبار الجيد
النشر — النشر على Azure وIIS والمضيفين الثابتين

ستتطور هذه القائمة. بعض المواضيع ستتوسع لتشمل عدة مقالات؛ وقد تتدمج أخرى. سأحدّث هذه المقالة مع تقدم السلسلة وأضيف الروابط عند النشر.

لماذا سلسلة، ولماذا الآن

نضج Blazor كثيرًا. مع .NET 8 و9، أُعيد تصميم نموذج الرندر جذريًا — SSR الثابت، streaming rendering، Server التفاعلي، WebAssembly التفاعلي، والوضع التلقائي، كلها تتعايش الآن تحت سقف واحد. إنه إطار عمل مثير للاهتمام وقادر حقًا، لكن التعقيد المتزايد يجعل تجربة البداية مربكة في أحيان كثيرة.

أريد بناء مرجع يلتقي بك حيث أنت ويأخذك عبر المنظومة بشكل منهجي. ليس بديلًا عن التوثيق الرسمي — فهو جيد ويجب أن تقرأه — بل رفيق يشرح لماذا وراء ماذا.

كيف تتابع السلسلة

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

كود كل مقالة سيكون متاحًا على GitHub. سأشارك الروابط مع التقدم.

إلى اللقاء في المقالة التالية.

أنواع اتحادات C#: النقابات التمييزية قادمة أخيرًا

Wed, 01 Apr 2026 00:00:00 +0000

إذا كنت تكتب C# لفترة طويلة من الوقت، فمن المحتمل جدًا أن تصطدم بحائط عند محاولتك تصميم شيء يمكن أن يكون “واحدًا من عدة أشياء”. ربما كنت بحاجة إلى طريقة لإرجاع قيمة نجاح أو خطأ. ربما كنت تقوم ببناء نظام دفع يتعامل مع بطاقات الائتمان والتحويلات المصرفية والمحافظ الرقمية، ولكل منها بيانات مختلفة تمامًا. أو ربما نظرت للتو إلى F# أو Rust وفكرت، “لماذا لا يمكنني الحصول على ذلك في C#؟”

لقد انتهى الانتظار تقريبًا. النقابات التي تعاني من التمييز تتجه إلى لغة C#.

لقد كانت هذه إحدى الميزات اللغوية الأكثر طلبًا لسنوات، حيث تمتد مناقشات المجتمع إلى عام 2017 وما قبله. يعمل فريق تصميم لغة C# على اقتراح يقدم كلمة رئيسية union لتحديد التسلسلات الهرمية للأنواع المغلقة مع مطابقة الأنماط الشاملة. في هذا المنشور، أريد أن أطلعكم على ماهية النقابات التي تعاني من التمييز، وسبب أهميتها إلى هذا الحد، وكيف كنا نقوم بتزييفها حتى الآن، وكيف تبدو الصيغة المقترحة بالفعل - مع أمثلة كود حقيقية لكل منها.

ملاحظة سريعة قبل أن نتعمق: حتى كتابة هذه السطور، لا تزال ميزة الأنواع الموحدة في مرحلة الاقتراح والمعاينة. يعتمد بناء الجملة والسلوك الذي أصفه هنا على أحدث وثائق التصميم المتاحة للجمهور والمناقشات من فريق تصميم لغة C#. قد تتغير الأمور قبل الإصدار النهائي. سأكون واضحًا بشأن ما تم تأكيده مقابل ما لا يزال قيد المناقشة.

ما هي النقابات التي تعاني من التمييز؟

في جوهره، الاتحاد التمييزي (يسمى أحيانًا “الاتحاد الموسوم” أو “نوع المجموع”) هو نوع يمكنه الاحتفاظ بواحدة من مجموعة ثابتة من القيم المحتملة، حيث يمكن لكل متغير أن يحمل بيانات مختلفة. الجزء “التمييزي” يعني أن وقت التشغيل يعرف دائمًا المتغير - هناك علامة تحدده.

فكر في الأمر مثل enum، ولكن حيث يمكن لكل عضو حمل حمولته الخاصة من البيانات.

إذا كنت قد استخدمت لغات أخرى، فمن المحتمل أنك رأيت هذا المفهوم من قبل:

F# لديها نقابات تمييزية منذ اليوم الأول:

type Shape =
 | Circle of radius: float
 | Rectangle of width: float * height: float
 | Triangle of base: float * height: float

الصدأ يستخدم enum لنفس الفكرة:

enum Shape {
 Circle { radius: f64 },
 Rectangle { width: f64, height: f64 },
 Triangle { base: f64, height: f64 },
}

يحقق TypeScript شيئًا مشابهًا مع الاتحادات ذات العلامات:

type Shape =
 | { kind: "circle"; radius: number }
 | { kind: "rectangle"; width: number; height: number }
 | { kind: "triangle"; base: number; height: number };

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

لم يكن لدى C# أبدًا طريقة من الدرجة الأولى للتعبير عن ذلك. حتى الآن.

كيف نحاكي النقابات اليوم

على مر السنين، توصل مجتمع C# إلى العديد من الحلول، ولكل منها مقايضاتها الخاصة. اسمحوا لي أن أتطرق إلى الأساليب الأكثر شيوعًا.

السجلات المجردة بالميراث

الحل البديل الأكثر اصطلاحًا في لغة C# الحديثة هو استخدام السجلات المجردة ذات الأنواع المشتقة المختومة:

public abstract record Shape
{
 public sealed record Circle(double Radius) : Shape;
 public sealed record Rectangle(double Width, double Height) : Shape;
 public sealed record Triangle(double Base, double Height) : Shape;

 private Shape() { } // Prevent external inheritance
}

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

double Area(Shape shape) => shape switch
{
 Shape.Circle c => Math.PI * c.Radius * c.Radius,
 Shape.Rectangle r => r.Width * r.Height,
 Shape.Triangle t => 0.5 * t.Base * t.Height,
 _ => throw new InvalidOperationException("Unknown shape")
};
```ولكن هناك عيوب كبيرة. لا يعرف المترجم أن التسلسل الهرمي مغلق، لذلك تحتاج دائمًا إلى `_` تجاهل الذراع أو تحصل على تحذير. إذا أضفت متغيرًا جديدًا، فلن يخبرك المترجم بجميع الأماكن التي نسيت التعامل معها — حيث يبتلعها التجاهل بصمت. وهذا يتعارض تمامًا مع الهدف.

### المكتبة الوحيدة

هناك طريقة شائعة أخرى وهي حزمة [OneOf](https://github.com/mcintyre321/OneOf) NuGet:

```csharp
public OneOf<Success<Order>, NotFound, ValidationError> ProcessOrder(OrderRequest request)
{
 // ...
}

// Usage
var result = ProcessOrder(request);
result.Switch(
 success => Console.WriteLine($"Order {success.Value.Id} processed"),
 notFound => Console.WriteLine("Order not found"),
 error => Console.WriteLine($"Validation failed: {error.Message}")
);

يوفر OneOf فحصًا شاملاً في وقت الترجمة من خلال معلمات النوع العامة، وهو أمر رائع. ولكنها تعتمد على المطابقة الموضعية (النوع الأول، النوع الثاني، وما إلى ذلك)، وتصبح التوقيعات العامة غير عملية بسرعة، ولا تتكامل مع مطابقة أنماط اللغة. إنه اختراق ذكي، لكنه لا يزال اختراقًا.

التعداد اليدوي + نمط البيانات

يتبع بعض المطورين المسار الكلاسيكي باستخدام علامة التعداد وحاوية البيانات:

public enum PaymentType { CreditCard, BankTransfer, DigitalWallet }

public class Payment
{
 public PaymentType Type { get; init; }
 public CreditCardInfo? CreditCard { get; init; }
 public BankTransferInfo? BankTransfer { get; init; }
 public DigitalWalletInfo? DigitalWallet { get; init; }
}

هذا هش. لا شيء يمنعك من ضبط Type على CreditCard ولكن ملء خاصية BankTransfer. لا يستطيع المترجم مساعدتك، وينتهي الأمر بأخطاء وقت التشغيل وعمليات التحقق من القيمة الفارغة في كل مكان. إنه أسلوب “الكتابة الصارمة” في نمذجة الكتابة، ولا يمكن قياسه.

تشترك كل هذه الأساليب في مشكلة أساسية: **إنهم يحاربون اللغة بدلاً من العمل بها. ** لا يستطيع المترجم التفكير في مجموعة الاحتمالات المغلقة، لذلك تفقد الخاصية الأكثر قيمة للنقابات التمييزية - التحقق الشامل.

اقتراح C#: الكلمة الرئيسية `union`

يقدم اقتراح فريق لغة C# كلمة رئيسية مخصصة union تحدد مجموعة مغلقة من الأعضاء المحددين، كل منهم يحمل بيانات اختياريًا. إليك بناء الجملة الأساسي كما تم اقتراحه:

union Shape
{
 Circle(double Radius),
 Rectangle(double Width, double Height),
 Triangle(double Base, double Height)
}

هذا كل شيء. نظيفة وموجزة، ويمكن قراءتها على الفور. يحدد كل عضو داخل الاتحاد متغيرًا مميزًا ببياناته الخاصة. يعرف المترجم أن Shape يمكن أن يكون واحدًا فقط من هذه الأشياء الثلاثة.

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

الأعضاء ذوو القيمة فقط

لا يتعين على أعضاء الاتحاد حمل البيانات. يمكنك مزج الأعضاء الحاملين للبيانات مع الأعضاء ذوي القيمة البسيطة:

union Option<T>
{
 Some(T Value),
 None
}

هذا هو النوع الكلاسيكي Option/Maybe الذي ظل المبرمجون الوظيفيون يطلبونه في لغة C# لسنوات. None لا يحمل أي بيانات — إنها مجرد علامة.

النقابات العامة

كما ترون من المثال Option<T> أعلاه، تدعم النقابات الأدوية العامة. فيما يلي مثال أكثر تعقيدًا:

union Result<T, E>
{
 Ok(T Value),
 Error(E Err)
}

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

النقابات مع الأساليب

يسمح الاقتراح أيضًا للنقابات بالحصول على أساليب وخصائص محسوبة وتنفيذ واجهات، تمامًا مثل أي نوع آخر:```csharp union Shape { Circle(double Radius), Rectangle(double Width, double Height), Triangle(double Base, double Height);

public double Area => this switch
{
Circle(var r) => Math.PI * r * r,
Rectangle(var w, var h) => w * h,
Triangle(var b, var h) => 0.5 * b * h
};
public double Perimeter => this switch
{
Circle(var r) => 2 * Math.PI * r,
Rectangle(var w, var h) => 2 * (w + h),
Triangle(var b, var h) => b + h + Math.Sqrt(b * b + h * h)
};

}


لاحظ كيف أن تعبير `switch` داخل `Area` و`Perimeter` لا يحتاج إلى ذراع افتراضي. يعرف المترجم أن الاتحاد شامل - هناك ثلاثة متغيرات فقط، ويتم التعامل مع الثلاثة جميعًا. إذا قمت بإضافة متغير رابع لاحقًا، فسيقوم المترجم بوضع علامة على كل `switch` الذي لا يتعامل معه.

## تكامل مطابقة الأنماط

لقد تطورت مطابقة الأنماط في لغة C# منذ الإصدار 7.0، وتم تصميم أنواع الاتحاد لتكون مواطنًا من الدرجة الأولى في هذا النظام.

### تعبيرات التبديل الشاملة

الميزة الأكثر تأثيرًا هي فحص التبديل الشامل. مع النقابات، المترجم **يعرف** جميع الحالات المحتملة:

```csharp
string Describe(Shape shape) => shape switch
{
 Circle(var r) => $"A circle with radius {r}",
 Rectangle(var w, var h) => $"A {w}x{h} rectangle",
 Triangle(var b, var h) => $"A triangle with base {b} and height {h}"
};

لا يوجد ذراع تجاهل. لا _ => throw new NotImplementedException(). إذا نسيت حالة ما، فسيقوم المترجم بإصدار خطأ، وليس تحذيرًا. وهذا تحسن أساسي في السلامة.

مطابقة الأنماط المتداخلة

تتكون النقابات بشكل طبيعي من أنماط متداخلة:

union Expr
{
 Literal(double Value),
 Add(Expr Left, Expr Right),
 Multiply(Expr Left, Expr Right),
 Negate(Expr Inner)
}

double Evaluate(Expr expr) => expr switch
{
 Literal(var v) => v,
 Add(var left, var right) => Evaluate(left) + Evaluate(right),
 Multiply(var left, var right) => Evaluate(left) * Evaluate(right),
 Negate(var inner) => -Evaluate(inner)
};

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

شروط الحراسة

مطابقة الأنماط مع النقابات تدعم حراس when تمامًا كما تتوقع:

string Classify(Shape shape) => shape switch
{
 Circle(var r) when r > 100 => "Large circle",
 Circle(var r) when r > 10 => "Medium circle",
 Circle(_) => "Small circle",
 Rectangle(var w, var h) when w == h => "Square",
 Rectangle _ => "Rectangle",
 Triangle _ => "Triangle"
};

أمثلة عملية

اسمحوا لي أن أستعرض بعض السيناريوهات الواقعية حيث تعمل أنواع الاتحادات على تحسين الكود بشكل كبير.

نمط النتيجة: استبدال الاستثناءات للأخطاء المتوقعة

أحد الأنماط الأكثر شيوعًا في تطوير التطبيقات الحديثة هو تمثيل العمليات التي يمكن أن تنجح أو تفشل دون استخدام استثناءات للتحكم في التدفق. يجب أن تكون الاستثناءات استثنائية — أشياء مثل فشل الشبكة أو حالات نفاد الذاكرة. يعد خطأ التحقق من الصحة أو نتيجة “لم يتم العثور عليه” نتيجة متوقعة، وليس استثناءً.

union Result<T, E>
{
 Ok(T Value),
 Error(E Err)
}

union OrderError
{
 NotFound(Guid OrderId),
 InsufficientStock(string ProductId, int Requested, int Available),
 PaymentDeclined(string Reason),
 ValidationFailed(IReadOnlyList<string> Errors)
}

Result<Order, OrderError> ProcessOrder(OrderRequest request)
{
 if (!Validate(request, out var errors))
 return new ValidationFailed(errors);

 var product = catalog.Find(request.ProductId);
 if (product is null)
 return new NotFound(request.OrderId);

 if (product.Stock < request.Quantity)
 return new InsufficientStock(request.ProductId, request.Quantity, product.Stock);

 var paymentResult = paymentGateway.Charge(request.Payment);
 if (!paymentResult.Success)
 return new PaymentDeclined(paymentResult.Message);

 var order = CreateOrder(request, product);
 return new Ok(order);
}

يُجبر المتصل بعد ذلك على التعامل مع كل النتائج المحتملة:

var result = ProcessOrder(request);

var response = result switch
{
 Ok(var order) => Results.Created($"/orders/{order.Id}", order),
 Error(NotFound(var id)) => Results.NotFound($"Order {id} not found"),
 Error(InsufficientStock(var pid, var req, var avail)) =>
 Results.Conflict($"Product {pid}: requested {req}, only {avail} available"),
 Error(PaymentDeclined(var reason)) =>
 Results.UnprocessableEntity($"Payment declined: {reason}"),
 Error(ValidationFailed(var errors)) =>
 Results.BadRequest(new { Errors = errors })
};

لا توجد كتل للمحاولة، ولا توجد أنواع استثناءات منسية، ولا توجد مفاجآت في وقت التشغيل. يكون كل وضع فشل مرئيًا في توقيع النوع ويتم فرضه بواسطة المترجم. يعد هذا تحسينًا هائلاً لموثوقية واجهة برمجة التطبيقات (API).

نمذجة النطاق: أنواع الدفع

فيما يلي مثال لنمذجة النطاق الواقعي — التعامل مع طرق الدفع المختلفة في نظام التجارة الإلكترونية:

union PaymentMethod
{
 CreditCard(string CardNumber, string Expiry, string Cvv),
 BankTransfer(string Iban, string Bic),
 DigitalWallet(string Provider, string Token),
 CashOnDelivery
}

decimal CalculateProcessingFee(PaymentMethod method, decimal amount) => method switch
{
 CreditCard _ => amount * 0.029m + 0.30m,
 BankTransfer _ => 1.50m,
 DigitalWallet(provider: "PayPal", _) => amount * 0.034m + 0.35m,
 DigitalWallet _ => amount * 0.025m,
 CashOnDelivery => 4.99m
};

string FormatForReceipt(PaymentMethod method) => method switch
{
 CreditCard(var num, _, _) => $"Credit Card ending in {num[^4..]}",
 BankTransfer(var iban, _) => $"Bank Transfer ({iban[..4]}****)",
 DigitalWallet(var provider, _) => $"Digital Wallet ({provider})",
 CashOnDelivery => "Cash on Delivery"
};

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

آلات الدولة

أجهزة الحالة موجودة في كل مكان في البرامج — معالجة الطلبات، ومحركات سير العمل، وإدارة الاتصال، وحالة واجهة المستخدم. النقابات تجعلها واضحة وآمنة:

union ConnectionState
{
 Disconnected,
 Connecting(string Host, int Port, DateTime StartedAt),
 Connected(string Host, int Port, TcpClient Client),
 Reconnecting(string Host, int Port, int Attempt, TimeSpan Delay),
 Failed(string Host, Exception Error)
}

ConnectionState HandleEvent(ConnectionState state, ConnectionEvent evt) => (state, evt) switch
{
 (Disconnected, Connect(var host, var port)) =>
 new Connecting(host, port, DateTime.UtcNow),

 (Connecting(var h, var p, _), ConnectionSucceeded(var client)) =>
 new Connected(h, p, client),

 (Connecting(var h, var p, _), ConnectionFailed(var ex)) =>
 new Reconnecting(h, p, Attempt: 1, Delay: TimeSpan.FromSeconds(1)),

 (Reconnecting(var h, var p, var attempt, _), ConnectionSucceeded(var client)) =>
 new Connected(h, p, client),

 (Reconnecting(var h, var p, var attempt, _), ConnectionFailed(var ex)) when attempt >= 5 =>
 new Failed(h, ex),

 (Reconnecting(var h, var p, var attempt, _), ConnectionFailed(_)) =>
 new Reconnecting(h, p, attempt + 1, TimeSpan.FromSeconds(Math.Pow(2, attempt))),

 (Connected(_, _, var client), Disconnect) =>
 new Disconnected,

 _ => state // Ignore events that don't apply to current state
};

تحمل كل ولاية بالضبط البيانات ذات الصلة بتلك الدولة. لا يمكنك الوصول عن طريق الخطأ إلى TcpClient عندما تكون في حالة Connecting لأنها غير موجودة في هذا المتغير. يفرض نظام الكتابة ثوابت آلة الحالة.

اعتبارات التسلسل والتشغيل المتداخلأحد الأسئلة العملية التي تطرح فورًا مع أنواع الاتحادات هو: كيف تقوم بتسلسلها؟ إذا كنت تقوم بإنشاء واجهات برمجة التطبيقات أو تخزين البيانات، فستحتاج إلى تسلسل JSON للعمل بشكل صحيح.

لقد ناقش فريق التصميم دعم System.Text.Json المدمج لأنواع الاتحادات. يتضمن النهج المتوقع إجراء تسلسل باستخدام خاصية التمييز:

{
 "$type": "Circle",
 "radius": 5.0
}

{
 "$type": "Rectangle",
 "width": 10.0,
 "height": 20.0
}

يتوافق هذا مع دعم التسلسل متعدد الأشكال الحالي المقدم في .NET 7 بسمات JsonDerivedType. من المتوقع أن تعمل النقابات مع System.Text.Json خارج الصندوق، باستخدام اسم المتغير كمميز للنوع افتراضيًا.

بالنسبة لـ Entity Framework Core، فإن النهج المحتمل هو تخزين القيم الموحدة باستخدام عمود تمييز - على غرار كيفية عمل تعيين وراثة الجدول لكل تسلسل هرمي (TPH) بالفعل. لا يزال التكامل الدقيق لـ EF Core قيد التصميم، ولكن البنية التحتية للتعامل مع التسلسلات الهرمية من النوع المغلق موجودة بالفعل.

تجدر الإشارة إلى أن التشغيل المتداخل مع لغات .NET الأخرى يجب أن يكون سلسًا، حيث سيتم تجميع النقابات إلى تسلسلات هرمية قياسية لفئة IL تحت الغطاء. كود F# الذي يستهلك اتحاد C# سوف يراه كنوع تسلسل هرمي قياسي، والعكس صحيح.

كيفية تجربتها

اعتبارًا من وقت كتابة هذا التقرير، تتوفر أنواع الاتحاد كميزة معاينة في أحدث معاينات .NET SDK. لتجربة بناء الجملة المقترح، ستحتاج إلى:

قم بتثبيت أحدث إصدار من SDK لمعاينة .NET
قم بتمكين إصدار لغة المعاينة في ملف مشروعك:

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
 <TargetFramework>net10.0</TargetFramework>
 <LangVersion>preview</LangVersion>
 </PropertyGroup>
</Project>

ضع في اعتبارك أن ميزات المعاينة عرضة للتغيير. قد يتطور بناء الجملة والسلوك وتشخيصات المترجم بشكل ملحوظ قبل الإصدار النهائي. لا تشحن كود الإنتاج بالاعتماد على ميزات لغة المعاينة - ولكن قم بتجربتها وقدم تعليقاتك. يقوم فريق C# بمراقبة مناقشات مستودع csharpang بشكل نشط.

إذا كنت تريد متابعة تقدم الاقتراح، فإن الأماكن الرئيسية التي يجب مراقبتها هي:

مستودع dotnet/csharpang لمناقشات تصميم اللغة
مستودع dotnet/roslyn لتقدم تنفيذ المترجم
مدونة .NET للإعلانات الرسمية

المقارنة مع المقاربات الموجودة

اسمحوا لي أن أقوم بإجراء مقارنة سريعة حتى تتمكن من رؤية كيفية تكديس الأساليب المختلفة:

ميزة	سجلات مجردة	واحد<T1,T2>	التعداد + البيانات	أنواع الاتحاد
فحص الشمولية	❌ لا	✅ نعم	❌ لا	✅ نعم
مطابقة الأنماط	✅ نعم	❌ محدودة	❌ دليل	✅ أصلي
إغلاق القسري للمترجم	❌ لا	✅ نعم	❌ لا	✅ نعم
البيانات لكل متغير	✅ نعم	✅ نعم	⚠️ هشة	✅ نعم
سهولة القراءة	⚠️ مطول	⚠️ الموضعية	❌فقير	✅ ممتاز
التسلسل	✅ دليل	⚠️ مجمع	✅ دليل	✅ مدمج
نموذجي	⚠️ معتدل	✅ منخفض	⚠️ عالي	✅ الحد الأدنى
لا تبعية خارجية	✅ نعم	❌ نوجيت	✅ نعم	✅ نعم

ماذا يعني هذا بالنسبة للنظام البيئي .NET

إن إدخال النقابات التمييزية سوف ينتشر عبر النظام البيئي .NET بأكمله. وإليكم ما أتوقع رؤيته:

سيتم تحسين تصميم المكتبة. ستتمكن واجهات برمجة التطبيقات التي تعرض حاليًا null للإشارة إلى “لم يتم العثور عليه” أو طرح استثناءات لفشل التحقق من الصحة، من إرجاع أنواع Result<T, E> بدلاً من ذلك. وهذا يجعل أوضاع الفشل واضحة في توقيع النوع - يمكنك معرفة الخطأ الذي يمكن أن يحدث من خلال النظر إلى توقيع الطريقة، وليس من خلال قراءة الوثائق أو التعليمات البرمجية المصدر.

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

أصبحت أفكار F# متاحة لمطوري C#. لقد أعجب العديد من مطوري C# بنظام كتابة F# عن بعد ولكنهم لم يتمكنوا من اعتماد F# في مؤسساتهم. تقدم أنواع Union إحدى أقوى ميزات F# إلى C#، وهو ما يعد مكسبًا لنظام .NET البيئي بأكمله.

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

الخلاصة

كانت النقابات التي تعاني من التمييز على رأس قائمة أمنيات مجتمع C# منذ ما يقرب من عقد من الزمن، وذلك لسبب وجيه. إنهم يحلون فجوة أساسية في نظام الكتابة - القدرة على نمذجة البيانات التي يمكن أن تكون “أحد الأشياء العديدة” مع الأمان الذي يفرضه المترجم.

توفر الكلمة الأساسية union المقترحة بنية واضحة وموجزة تتكامل بشكل عميق مع مطابقة أنماط C#، وتعمل مع الأدوية العامة، وتدعم الأساليب والواجهات، وتتيح فحصًا شاملاً لاكتشاف الأخطاء في وقت الترجمة بدلاً من وقت التشغيل.

سواء كنت تقوم ببناء نماذج المجال، أو تصميم واجهات برمجة التطبيقات (APIs) مع أنواع أخطاء واضحة، أو تنفيذ أجهزة الحالة، أو مجرد محاولة استبدال التسلسلات الهرمية الموروثة بشيء أكثر طبيعية - فإن أنواع الاتحاد ستغير طريقة كتابتك لـ C#.

لقد كنا ننتظر وقتا طويلا لهذا. إن بناء الجملة أنيق، والتكامل مع ميزات اللغة الحالية مدروس، وسيكون التأثير العملي محسوسًا عبر النظام البيئي .NET بأكمله.

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

بناء نظام RAG في C# مع Semantic Kernel

Wed, 18 Mar 2026 00:00:00 +0000

مقدمة

إذا حاولت استخدام LLM للإجابة على أسئلة حول بياناتك الخاصة - مستندات الشركة، ومواصفات المنتج، وقواعد المعرفة الداخلية - فمن المحتمل أنك لاحظت أنها إما تهذي أو تقول فقط “ليس لدي معلومات حول ذلك”. وذلك لأن النموذج يعرف فقط ما تم تدريبه عليه.

يعمل RAG (جيل الاسترجاع المعزز) على إصلاح هذه المشكلة. بدلاً من ضبط نموذج على بياناتك، يمكنك استرداد الأجزاء ذات الصلة من مستنداتك في وقت الاستعلام وتمريرها إلى LLM كسياق. يقوم النموذج بعد ذلك بإنشاء إجابات ترتكز على بياناتك الفعلية.

في هذا المنشور، سأرشدك خلال عملية إنشاء مسار RAG كامل في لغة C# باستخدام Semantic Kernel.

كيف يعمل RAG

التدفق واضح ومباشر:

الاستيعاب: قم بتقسيم مستنداتك إلى أجزاء، وقم بإنشاء تضمينات لكل جزء، ثم قم بتخزينها في قاعدة بيانات متجهة
الاستعلام: عندما يطرح المستخدم سؤالاً، أنشئ تضمينًا للاستعلام، وابحث في قاعدة بيانات المتجهات عن أجزاء مماثلة
إنشاء: قم بتمرير الأجزاء المستردة كسياق إلى LLM مع سؤال المستخدم

هذا كل شيء. يكمن السحر في التضمينات - فهي تلتقط المعنى الدلالي للنص كمتجهات، بحيث يمكنك العثور على المحتوى ذي الصلة حتى عندما لا تتطابق الكلمات تمامًا.

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

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Connectors.AzureOpenAI
dotnet add package Microsoft.Extensions.VectorData.Abstractions
dotnet add package Microsoft.SemanticKernel.Connectors.InMemory

بالنسبة للإنتاج، يمكنك تبديل مخزن الذاكرة بـ Azure AI Search أو Qdrant أو Pinecone أو أي قاعدة بيانات متجهة أخرى مدعومة. لكن الذاكرة الداخلية مثالية للتعلم وإنشاء النماذج الأولية.

إعداد النواة

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.AzureOpenAI;
using Microsoft.Extensions.VectorData;
using Microsoft.SemanticKernel.Connectors.InMemory;
using Microsoft.SemanticKernel.Embeddings;

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: config["AzureOpenAI:Endpoint"],
 apiKey: config["AzureOpenAI:ApiKey"]);

builder.AddAzureOpenAITextEmbeddingGeneration(
 deploymentName: "text-embedding-3-small",
 endpoint: config["AzureOpenAI:Endpoint"],
 apiKey: config["AzureOpenAI:ApiKey"]);

var kernel = builder.Build();

نحتاج إلى نموذجين: أحدهما لإكمال الدردشة (الإجابة على الأسئلة) والآخر لإنشاء التضمينات (تحويل النص إلى متجهات).

تحديد نموذج البيانات

نحتاج إلى فئة لتمثيل أجزاء المستند الخاصة بنا في متجر المتجهات:

using Microsoft.Extensions.VectorData;

public class DocumentChunk
{
 [VectorStoreRecordKey]
 public string Id { get; set; } = Guid.NewGuid().ToString();

 [VectorStoreRecordData]
 public string Content { get; set; } = string.Empty;

 [VectorStoreRecordData]
 public string Source { get; set; } = string.Empty;

 [VectorStoreRecordData]
 public int ChunkIndex { get; set; }

 [VectorStoreRecordVector(1536)]
 public ReadOnlyMemory<float> Embedding { get; set; }
}

تخبر السمة VectorStoreRecordVector(1536) مخزن المتجهات بأبعاد التضمينات الخاصة بنا. ينتج النموذج text-embedding-3-small متجهات ذات 1536 بُعدًا.

تقطيع المستندات

قبل أن نتمكن من إنشاء التضمينات، نحتاج إلى تقسيم مستنداتنا إلى أجزاء يمكن التحكم فيها. إليك مقسم نص بسيط:

public static class TextChunker
{
 public static List<string> SplitText(string text, int maxChunkSize = 500, int overlap = 50)
 {
 var chunks = new List<string>();
 var paragraphs = text.Split("\n\n", StringSplitOptions.RemoveEmptyEntries);
 var currentChunk = new System.Text.StringBuilder();

 foreach (var paragraph in paragraphs)
 {
 if (currentChunk.Length + paragraph.Length > maxChunkSize && currentChunk.Length > 0)
 {
 chunks.Add(currentChunk.ToString().Trim());

 // Keep overlap from the end of the previous chunk
 var overlapText = currentChunk.ToString();
 currentChunk.Clear();
 if (overlapText.Length > overlap)
 {
 currentChunk.Append(overlapText[^overlap..]);
 currentChunk.Append(' ');
 }
 }

 currentChunk.Append(paragraph);
 currentChunk.Append("\n\n");
 }

 if (currentChunk.Length > 0)
 {
 chunks.Add(currentChunk.ToString().Trim());
 }

 return chunks;
 }
}

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

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

الآن دعونا نجمع كل ذلك معًا لاستيعاب المستندات في متجر المتجهات الخاص بنا:

var vectorStore = new InMemoryVectorStore();
var collection = vectorStore.GetCollection<string, DocumentChunk>("documents");
await collection.CreateCollectionIfNotExistsAsync();

var embeddingService = kernel.GetRequiredService<ITextEmbeddingGenerationService>();

async Task IngestDocument(string content, string source)
{
 var chunks = TextChunker.SplitText(content);

 for (int i = 0; i < chunks.Count; i++)
 {
 var embedding = await embeddingService.GenerateEmbeddingAsync(chunks[i]);

 var chunk = new DocumentChunk
 {
 Content = chunks[i],
 Source = source,
 ChunkIndex = i,
 Embedding = embedding
 };

 await collection.UpsertAsync(chunk);
 }

 Console.WriteLine($"✅ Ingested {chunks.Count} chunks from {source}");
}

// Ingest some documents
var doc1 = await File.ReadAllTextAsync("docs/product-guide.md");
var doc2 = await File.ReadAllTextAsync("docs/faq.md");
var doc3 = await File.ReadAllTextAsync("docs/troubleshooting.md");

await IngestDocument(doc1, "product-guide.md");
await IngestDocument(doc2, "faq.md");
await IngestDocument(doc3, "troubleshooting.md");

البحث عن القطع ذات الصلة

عندما يطرح المستخدم سؤالاً، نقوم بإنشاء تضمين لاستعلامه والبحث عن أجزاء مماثلة:

async Task<List<DocumentChunk>> SearchAsync(string query, int topK = 3)
{
 var queryEmbedding = await embeddingService.GenerateEmbeddingAsync(query);

 var searchResults = await collection.VectorizedSearchAsync(
 queryEmbedding,
 new VectorSearchOptions { Top = topK });

 var results = new List<DocumentChunk>();
 await foreach (var result in searchResults.Results)
 {
 results.Add(result.Record);
 }

 return results;
}

توليد الإجابات مع السياق

الآن الجزء RAG - نأخذ الأجزاء المستردة وندرجها كسياق في موجهنا:

using Microsoft.SemanticKernel.ChatCompletion;

var chatService = kernel.GetRequiredService<IChatCompletionService>();

async Task<string> AskAsync(string question)
{
 // Step 1: Retrieve relevant chunks
 var relevantChunks = await SearchAsync(question);

 // Step 2: Build context from chunks
 var context = string.Join("\n\n---\n\n",
 relevantChunks.Select(c => $"[Source: {c.Source}]\n{c.Content}"));

 // Step 3: Generate answer with context
 var history = new ChatHistory();
 history.AddSystemMessage($$"""
 You are a helpful assistant that answers questions based on the provided context.
 Use ONLY the information from the context to answer. If the context doesn't contain
 enough information to answer the question, say "I don't have enough information
 to answer that question."

 Do not make up information. Always cite the source document when possible.

 Context:
 {{context}}
 """);

 history.AddUserMessage(question);

 var response = await chatService.GetChatMessageContentAsync(history);
 return response.Content ?? "No response generated.";
}

استخدامه

// Ask questions about your documents
var answer1 = await AskAsync("How do I reset my password?");
Console.WriteLine($"Q: How do I reset my password?\nA: {answer1}\n");

var answer2 = await AskAsync("What are the system requirements?");
Console.WriteLine($"Q: What are the system requirements?\nA: {answer2}\n");

var answer3 = await AskAsync("What's the capital of France?");
Console.WriteLine($"Q: What's the capital of France?\nA: {answer3}\n");
// Should respond with "I don't have enough information" since it's not in the docs

الانتقال إلى الإنتاج

يعد مخزن المتجهات الموجود في الذاكرة رائعًا للنماذج الأولية، ولكن بالنسبة للإنتاج، ستحتاج إلى قاعدة بيانات متجهات ثابتة. يحتوي Semantic Kernel على موصلات لعدة خيارات:

# Azure AI Search
dotnet add package Microsoft.SemanticKernel.Connectors.AzureAISearch

# Qdrant
dotnet add package Microsoft.SemanticKernel.Connectors.Qdrant

# Redis
dotnet add package Microsoft.SemanticKernel.Connectors.Redis

يعد التبديل أمرًا مباشرًا نظرًا لأن جميعهم ينفذون نفس واجهة IVectorStore:

// Instead of InMemoryVectorStore, use:
using Azure;
using Microsoft.SemanticKernel.Connectors.AzureAISearch;

var vectorStore = new AzureAISearchVectorStore(
 new Azure.Search.Documents.Indexes.SearchIndexClient(
 new Uri(config["AzureAISearch:Endpoint"]),
 new AzureKeyCredential(config["AzureAISearch:ApiKey"])));
```كل شيء آخر يبقى على حاله. هذا هو جمال التجريد.

## نصائح من بناء أنظمة RAG

بعض الأشياء التي تعلمتها بالطريقة الصعبة:

- **حجم القطعة مهم جدًا.** صغير جدًا ويؤدي إلى فقدان السياق. كبيرة جدًا وتضيع الرموز المميزة على محتوى غير ذي صلة. ابدأ بـ 500-800 رمزًا وقم بالتعديل بناءً على بياناتك.
- **التداخل يمنع مشاكل الحدود.** عادةً ما يكون التداخل بين القطع من 50 إلى 100 رمزًا كافيًا.
- **استرجع أكثر مما تعتقد.** ابدأ بـ `topK = 5` وقلل إذا كنت تحصل على الكثير من الضوضاء. من الأفضل أن يكون لديك سياق إضافي بدلاً من تفويت الجزء ذي الصلة.
- **تعد مطالبات النظام أمرًا بالغ الأهمية.** كن واضحًا جدًا بشأن استخدام السياق المتوفر فقط. وبدون هذه التعليمات، سوف يهلوس النموذج بسعادة "بناءً على بيانات التدريب الخاصة به".
- **تتبع المصادر.** قم دائمًا بتخزين البيانات الوصفية مع الأجزاء الخاصة بك حتى تتمكن من ذكر مصدر الإجابة. يثق المستخدمون في الإجابات بشكل أكبر عندما يمكنهم التحقق من المصدر.
- **أعد الترتيب إذا لزم الأمر.** تشابه المتجهات ليس مثاليًا. بالنسبة للتطبيقات الهامة، أضف خطوة إعادة التصنيف باستخدام نموذج التشفير المتبادل لتحسين الدقة.

## الخلاصة

يعد RAG أحد أكثر الأنماط العملية في الذكاء الاصطناعي في الوقت الحالي. فهو يتيح لك إنشاء أنظمة أسئلة وأجوبة مدعومة بالذكاء الاصطناعي على بياناتك الخاصة دون ضبط دقيق، كما أن Semantic Kernel يجعلها نظيفة بشكل مدهش في C#. ابدأ بالمخزن الموجود في الذاكرة، وقم بإجراء عملية التقطيع والمطالبات بشكل صحيح، ثم قم بالتبديل في قاعدة بيانات متجهة حقيقية عندما تكون جاهزًا للإنتاج.

ترميز سعيد!

## الموارد

- [وثائق مخزن ناقلات النواة الدلالية](https://learn.microsoft.com/en-us/semantic-kernel/concepts/vector-store-connectors/)
- [نمط RAG مع بحث Azure AI](https://learn.microsoft.com/en-us/azure/search/retrieval-augmented-generation-overview)
- [نماذج تضمين النص](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models#embeddings)

بناء سير عمل الوكيل باستخدام Microsoft Agent Framework

Tue, 10 Feb 2026 00:00:00 +0000

مقدمة

إذا كنت قد قرأت منشوراتي السابقة حول Microsoft Agent Framework، فأنت تعرف كيفية إنشاء وكلاء فرديين وحتى محادثات جماعية متعددة الوكلاء. ولكن في سيناريوهات العالم الحقيقي، غالبًا ما تحتاج إلى شيء أكثر تنظيماً - سير عمل حيث ينفذ الوكلاء بترتيب معين، ويمررون النتائج لبعضهم البعض، ويتعاملون مع منطق التفرع بناءً على النتائج.

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

ما هي مسارات عمل الوكيل؟

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

بعض الأمثلة:

خط أنابيب المحتوى: بحث ← مسودة ← مراجعة ← نشر
معالجة البيانات: استخراج ← تحويل ← التحقق من الصحة ← تحميل
دعم العملاء: التصنيف ← المسار ← الاستجابة ← المتابعة

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

تأكد من حصولك على أحدث حزم Agent Framework:

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Agents.Core

وتم تكوين نقطة نهاية Azure OpenAI أو OpenAI.

بناء سير عمل متسلسل

لنقم ببناء سير عمل لإنشاء المحتوى باستخدام ثلاثة وكلاء: باحث، وكاتب، ومحرر.

تعريف الوكلاء

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;

var kernel = Kernel.CreateBuilder()
 .AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: config["AzureOpenAI:Endpoint"],
 apiKey: config["AzureOpenAI:ApiKey"])
 .Build();

var researcher = new ChatCompletionAgent
{
 Name = "Researcher",
 Instructions = """
 You are a research specialist. Given a topic, find key facts, statistics,
 and talking points. Return a structured research brief with bullet points.
 Be thorough but concise.
 """,
 Kernel = kernel
};

var writer = new ChatCompletionAgent
{
 Name = "Writer",
 Instructions = """
 You are a technical blog writer. Given a research brief, write a clear
 and engaging blog post. Use a conversational tone, include code examples
 where relevant, and structure the post with clear headings.
 """,
 Kernel = kernel
};

var editor = new ChatCompletionAgent
{
 Name = "Editor",
 Instructions = """
 You are a senior editor. Review the blog post for clarity, accuracy,
 grammar, and flow. Return the corrected version with a summary of
 changes made at the end.
 """,
 Kernel = kernel
};

التنفيذ بالتسلسل

أبسط سير عمل هو سير عمل تسلسلي، حيث يقوم كل وكيل بمعالجة مخرجات الوكيل السابق:

using Microsoft.SemanticKernel.Agents.Chat;
using Microsoft.SemanticKernel.ChatCompletion;

async Task<string> RunSequentialWorkflow(string topic)
{
 var history = new ChatHistory();
 string currentInput = $"Research the following topic: {topic}";

 var agents = new[] { researcher, writer, editor };

 foreach (var agent in agents)
 {
 history.AddUserMessage(currentInput);

 var response = new System.Text.StringBuilder();
 await foreach (var message in agent.InvokeAsync(history))
 {
 response.Append(message.Content);
 }

 currentInput = response.ToString();
 Console.WriteLine($"✅ {agent.Name} completed");
 }

 return currentInput;
}

var result = await RunSequentialWorkflow("Blazor render modes in .NET 9");
Console.WriteLine(result);

يحصل كل وكيل على السياق المتراكم، ويعالجه، وتنتقل النتيجة إلى الخطوة التالية.

التنفيذ الموازي

في بعض الأحيان يمكن للوكلاء العمل بشكل مستقل. على سبيل المثال، قد ترغب في البحث عن موضوعات فرعية متعددة في نفس الوقت:

async Task<List<string>> RunParallelResearch(string[] topics)
{
 var tasks = topics.Select(async topic =>
 {
 var history = new ChatHistory();
 history.AddUserMessage($"Research: {topic}");

 var response = new System.Text.StringBuilder();
 await foreach (var message in researcher.InvokeAsync(history))
 {
 response.Append(message.Content);
 }

 Console.WriteLine($"✅ Research completed: {topic}");
 return response.ToString();
 });

 var results = await Task.WhenAll(tasks);
 return results.ToList();
}

var topics = new[]
{
 "Blazor SSR streaming",
 "Enhanced navigation in .NET 9",
 "Render mode boundaries"
};

var briefs = await RunParallelResearch(topics);

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

التفرع المشروط

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

var qualityChecker = new ChatCompletionAgent
{
 Name = "QualityChecker",
 Instructions = """
 You are a quality assurance reviewer. Evaluate the blog post on:
 1. Technical accuracy
 2. Clarity and readability
 3. Completeness

 Respond with either:
 - "APPROVED" if the post meets all criteria
 - "REVISION NEEDED: [specific feedback]" if changes are required

 Be strict. Only approve posts that are truly ready to publish.
 """,
 Kernel = kernel
};

async Task<string> RunWithQualityLoop(string topic, int maxRevisions = 3)
{
 var history = new ChatHistory();

 // Step 1: Research
 history.AddUserMessage($"Research: {topic}");
 string research = await InvokeAgent(researcher, history);

 // Step 2: Write
 history.AddUserMessage(research);
 string draft = await InvokeAgent(writer, history);

 // Step 3: Quality loop
 for (int i = 0; i < maxRevisions; i++)
 {
 var qaHistory = new ChatHistory();
 qaHistory.AddUserMessage($"Review this post:\n\n{draft}");
 string qaResult = await InvokeAgent(qualityChecker, qaHistory);

 if (qaResult.Contains("APPROVED", StringComparison.OrdinalIgnoreCase))
 {
 Console.WriteLine($"✅ Approved after {i + 1} review(s)");
 return draft;
 }

 Console.WriteLine($"🔄 Revision {i + 1}: {qaResult[..Math.Min(100, qaResult.Length)]}...");

 // Send back to writer with feedback
 history.AddUserMessage($"Please revise based on this feedback:\n{qaResult}");
 draft = await InvokeAgent(writer, history);
 }

 Console.WriteLine("⚠️ Max revisions reached, returning latest draft");
 return draft;
}

async Task<string> InvokeAgent(ChatCompletionAgent agent, ChatHistory history)
{
 var response = new System.Text.StringBuilder();
 await foreach (var message in agent.InvokeAsync(history))
 {
 response.Append(message.Content);
 }
 return response.ToString();
}

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

إضافة المكونات الإضافية إلى وكلاء سير العمل

يمكن للوكلاء في سير العمل استخدام المكونات الإضافية تمامًا مثل الوكلاء المستقلين. هذا هو المكان الذي تصبح فيه الأمور قوية حقًا - يمكن للوكلاء الاتصال بواجهات برمجة التطبيقات أو الاستعلام عن قواعد البيانات أو إجراء عمليات الملفات كجزء من خطوة سير العمل الخاصة بهم:

var researcherWithTools = new ChatCompletionAgent
{
 Name = "Researcher",
 Instructions = "Research the topic using available tools. Summarize findings.",
 Kernel = kernel
};

// Add a web search plugin
kernel.Plugins.AddFromType<WebSearchPlugin>();

// Add a database plugin
kernel.Plugins.AddFromObject(new DatabasePlugin(connectionString), "Database");

public class WebSearchPlugin
{
 [KernelFunction, Description("Search the web for information")]
 public async Task<string> SearchAsync(
 [Description("The search query")] string query)
 {
 // Your search implementation
 using var httpClient = new HttpClient();
 var response = await httpClient.GetStringAsync(
 $"https://api.search.example.com?q={Uri.EscapeDataString(query)}");
 return response;
 }
}

معالجة الأخطاء في سير العمل

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

async Task<WorkflowResult> RunResilientWorkflow(string input)
{
 var result = new WorkflowResult();

 try
 {
 result.Research = await InvokeAgent(researcher, new ChatHistory(input));
 }
 catch (Exception ex)
 {
 result.Errors.Add($"Research failed: {ex.Message}");
 return result;
 }

 try
 {
 var writeHistory = new ChatHistory(result.Research);
 result.Draft = await InvokeAgent(writer, writeHistory);
 }
 catch (Exception ex)
 {
 result.Errors.Add($"Writing failed: {ex.Message}");
 result.Draft = result.Research; // Fallback to research output
 }

 result.Success = result.Errors.Count == 0;
 return result;
}

class WorkflowResult
{
 public string Research { get; set; } = "";
 public string Draft { get; set; } = "";
 public List<string> Errors { get; set; } = new();
 public bool Success { get; set; }
}

أفضل الممارسات

بعد إنشاء العديد من مسارات عمل الوكيل، إليك ما تعلمته:- حافظ على تركيز تعليمات الوكيل — يجب على كل وكيل أن يفعل شيئًا واحدًا بشكل جيد. لا تحاول أن تصنع عميلاً بسكين الجيش السويسري.

السياق المحدد — لا تمرر سجل المحادثة بالكامل إلى كل وكيل. أعط كل خطوة ما تحتاجه فقط.
تعيين حدود للمراجعة — تعتبر حلقات الجودة رائعة ولكن يمكن تشغيلها إلى الأبد إذا لم تكن حذرًا. دائمًا ما يكون لديك حد أقصى للتكرارات.
تسجيل كل شيء — يمكن أن تكون مخرجات الوكيل غير متوقعة. قم بتسجيل مدخلات ومخرجات كل خطوة لتصحيح الأخطاء.
استخدم التنفيذ الموازي بحكمة — فهو يعمل على تسريع الأمور ولكن انتبه إلى حدود معدل واجهة برمجة التطبيقات (API) وتكاليف الرمز المميز.
اختبر النماذج الأصغر أولاً - قم بتطوير واختبار منطق سير العمل الخاص بك باستخدام GPT-3.5 قبل التبديل إلى GPT-4o للإنتاج.

الخلاصة

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

ترميز سعيد!

الموارد

دورة حياة مكون Blazor: الدليل الكامل

Thu, 15 Jan 2026 00:00:00 +0000

أنا أستخدم Blazor منذ فترة وبصراحة، لقد أربكتني أساليب دورة الحياة في البداية. OnInitialized ضد OnInitializedAsync؟ OnParametersSet ضد OnAfterRender؟ متى يقوم StateHasChanged فعليًا بتشغيل إعادة العرض؟ وبعد الكثير من التجربة والخطأ، أصبح لدي أخيرًا نموذج عقلي قوي لكل ذلك.

دورة الحياة في لمحة

عندما يتم عرض مكون Blazor، فإنه يمر عبر هذه الطرق بالترتيب:

SetParametersAsync
OnInitialized / OnInitializedAsync
OnParametersSet / OnParametersSetAsync
OnAfterRender / OnAfterRenderAsync
Dispose / DisposeAsync

دعونا نسير من خلال كل واحد.

#SetParametersAsync

هذه هي الطريقة الأولى التي تسمى. يتلقى ParameterView الخام من المكون الأصلي. في معظم الأوقات، لا تتجاوز هذا — حيث يتعامل Blazor مع معلمات التعيين تلقائيًا. ولكن إذا كنت بحاجة إلى معالجة المعلمات المخصصة أو التحقق من صحتها قبل تعيينها:

public override async Task SetParametersAsync(ParameterView parameters)
{
 // Custom logic before parameters are set
 if (parameters.TryGetValue<string>("Title", out var title))
 {
 Console.WriteLine($"Title is being set to: {title}");
 }

 await base.SetParametersAsync(parameters);
}

لقد استخدمت هذا مرة واحدة بالضبط في مشروع حقيقي. في معظم الأحيان سوف تخطي ذلك.

OnInitialized / OnInitializedAsync

هذا هو المكان الذي تقوم فيه بعمل الإعداد - تحميل البيانات، وتهيئة الخدمات، وتعيين القيم الافتراضية. يتم تشغيله مرة واحدة عند إنشاء المكون لأول مرة.

@code {
 private List<Product> products = new();

 protected override async Task OnInitializedAsync()
 {
 products = await Http.GetFromJsonAsync<List<Product>>("api/products");
 }
}

الشيء الوحيد الذي أزعجني: في Blazor Server، يتم استدعاء OnInitializedAsync مرتين أثناء العرض المسبق. المرة الأولى أثناء العرض المسبق من جانب الخادم، والمرة الثانية عند إنشاء اتصال SignalR. إذا كان استدعاء API الخاص بك مكلفًا، فقد ترغب في التعامل مع ذلك:

private bool isPrerendering = true;

protected override async Task OnInitializedAsync()
{
 products = await Http.GetFromJsonAsync<List<Product>>("api/products");
 isPrerendering = false;
}

أو من الأفضل استخدام PersistentComponentState لتجنب المكالمة المزدوجة تمامًا.

OnParametersSet / OnParametersSetAsync

يتم تشغيل هذا في كل مرة يقوم فيها المكون الأصلي بإعادة العرض وتمرير قيم المعلمات الجديدة. يتم إطلاقه أيضًا بعد OnInitialized. هذا هو المكان المناسب للرد على تغييرات المعلمات:

[Parameter]
public int CategoryId { get; set; }

private int previousCategoryId;
private List<Product> products = new();

protected override async Task OnParametersSetAsync()
{
 if (CategoryId != previousCategoryId)
 {
 previousCategoryId = CategoryId;
 products = await Http.GetFromJsonAsync<List<Product>>(
 $"api/products?category={CategoryId}");
 }
}

يعد التحقق من CategoryId != previousCategoryId أمرًا مهمًا — فبدونه، يمكنك إعادة تحميل البيانات في كل مرة يقوم فيها الأصل بإعادة العرض، حتى لو لم تتغير الفئة.

OnAfterRender / OnAfterRenderAsync

يتم تشغيل هذا بعد تقديم المكون إلى DOM. تخبرك المعلمة firstRender ما إذا كان هذا هو العرض الأولي. هذا هو المكان المناسب لاستدعاءات JS Interop نظرًا لوجود عناصر DOM في هذه المرحلة:

[Inject]
private IJSRuntime JS { get; set; }

protected override async Task OnAfterRenderAsync(bool firstRender)
{
 if (firstRender)
 {
 await JS.InvokeVoidAsync("initializeChart", chartElement);
 }
}

أستخدم firstRender كثيرًا لتجنب إعادة تهيئة مكتبات JavaScript في كل عملية إعادة عرض. إذا كنت تقوم بإعداد مستمعي الأحداث، أو مكتبات المخططات، أو أي شيء يلامس DOM مباشرة، فهذا هو المكان الذي تذهب إليه.

ينبغي تقديم

هذا أقل شهرة ولكنه مفيد للغاية. يتحكم في ما إذا كان المكون يُعاد عرضه عند استدعاء StateHasChanged:

private bool shouldRender = true;

protected override bool ShouldRender() => shouldRender;

private void HeavyOperation()
{
 shouldRender = false;

 // Do a bunch of state changes without triggering renders
 for (int i = 0; i < 1000; i++)
 {
 items[i].Process();
 }

 shouldRender = true;
 StateHasChanged(); // Now render once with all changes
}

لقد استخدمت هذا لتحسين المكونات التي تعالج القوائم الكبيرة. بدلاً من إعادة العرض عند كل تغيير في العنصر، يمكنك تجميع التحديثات وعرضها مرة واحدة في النهاية.

التخلص / التخلص من Async

عند إزالة مكون من واجهة المستخدم، يجب عليك تنظيف أي موارد. تنفيذ IDisposable أو IAsyncDisposable:

@implements IAsyncDisposable

@code {
 private Timer? timer;
 private IJSObjectReference? jsModule;

 protected override void OnInitialized()
 {
 timer = new Timer(OnTick, null, 0, 1000);
 }

 protected override async Task OnAfterRenderAsync(bool firstRender)
 {
 if (firstRender)
 {
 jsModule = await JS.InvokeAsync<IJSObjectReference>("import", "./timer.js");
 }
 }

 public async ValueTask DisposeAsync()
 {
 timer?.Dispose();

 if (jsModule is not null)
 {
 await jsModule.DisposeAsync();
 }
 }
}

الأشياء الشائعة التي يجب التخلص منها: المؤقتات، واشتراكات الأحداث، ومراجع وحدة JS، وCancellationTokenSource، وأي خدمات IDisposable أنشأتها.

#تغيرت الحالةهذه ليست طريقة دورة حياة، ولكنها مرتبطة ارتباطًا وثيقًا. يقول لـ Blazor “مرحبًا، لقد تغيرت حالتي، من فضلك أعد عرضي.” يستدعيه Blazor تلقائيًا بعد معالجات الأحداث، لكن في بعض الأحيان تحتاج إلى استدعائه يدويًا — عادةً عندما تتغير الحالة من خارج تدفق أحداث Blazor العادي:

private async Task StartPolling()
{
 while (!cts.Token.IsCancellationRequested)
 {
 data = await Http.GetFromJsonAsync<Data>("api/data");
 StateHasChanged(); // Manual call needed since this isn't a Blazor event
 await Task.Delay(5000, cts.Token);
 }
}

ملاحظة مهمة: إذا كنت تقوم بالتحديث من سلسلة محادثات في الخلفية في Blazor Server، فاستخدم InvokeAsync:

await InvokeAsync(() =>
{
 data = newData;
 StateHasChanged();
});

#الصورة كاملة

إليك الترتيب الذي يحدث فيه كل شيء:

Component created
 └─ SetParametersAsync
 └─ OnInitialized / OnInitializedAsync
 └─ OnParametersSet / OnParametersSetAsync
 └─ Render
 └─ OnAfterRender(firstRender: true)

Parameter change from parent
 └─ SetParametersAsync
 └─ OnParametersSet / OnParametersSetAsync
 └─ ShouldRender?
 └─ Render
 └─ OnAfterRender(firstRender: false)

Component removed
 └─ Dispose / DisposeAsync

بمجرد أن يكون لديك هذا التدفق في رأسك، يصبح تصحيح مشكلات دورة الحياة أسهل كثيرًا.

آمل أن تكونوا قد أحببت هذا المنصب! لا تتردد في الاتصال بي على أي وسائل التواصل الاجتماعي على **@emimontesdeoca **.

الموارد

Microsoft Agent Framework لإنقاذ عيد الميلاد

Tue, 16 Dec 2025 00:00:00 +0000

مقدمة

قد يكون العثور على هدايا عيد الميلاد المثالية أمرًا مرهقًا. بين تبادل الأفكار حول أفكار الهدايا، ومقارنة الأسعار عبر المتاجر، والتأكد من وصول كل شيء في الوقت المحدد، سرعان ما يصبح التسوق أثناء العطلات أمرًا مرهقًا. ماذا لو تمكنا من تفويض هذه المهام إلى عملاء الذكاء الاصطناعي المتخصصين الذين يعملون معًا؟ في هذا المنشور، سنستكشف كيفية استخدام Microsoft Agent Framework لبناء نظام متعدد الوكلاء حيث يتخصص كل وكيل في مهمة محددة، بدءًا من إنشاء أفكار الهدايا وحتى مقارنة الأسعار، ويتم تنسيق كل ذلك من خلال سير العمل.

التقويم التقني الاحتفالي لعام 2025

يعد هذا المشروع جزءًا من جلستي في Festive Tech Calendar 2025، وهو حدث مجتمعي رائع يحتفل بالتكنولوجيا خلال موسم العطلات. يمكنك العثور على المزيد حول الحدث على Sessionize.

ما هو إطار عمل وكيل Microsoft؟

Agent Framework هو حل Microsoft لبناء وتنسيق ونشر وكلاء الذكاء الاصطناعي والأنظمة متعددة الوكلاء. فهو يوفر أساسًا مرنًا لإنشاء الوكلاء الذين يمكنهم العمل بشكل تسلسلي أو متزامن أو من خلال أنماط التسليم. يدعم إطار العمل نماذج OpenAI وAzure OpenAI وMicrosoft Foundry، مما يجعله متعدد الاستخدامات بشكل لا يصدق.

تشمل الميزات الرئيسية ما يلي:

تنسيق متعدد الوكلاء: الدردشة الجماعية، وأنماط التسلسل، والمتزامنة، والتسليم
نظام المكونات الإضافية: يمتد ليشمل الوظائف الأصلية وOpenAPI وبروتوكول السياق النموذجي (MCP)
دعم سير العمل: أنشئ مسارات وكيل معقدة باستخدام منفذين وحواف

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

قبل الغوص في الكود، تأكد من أن لديك:

-.نت 9

الوصول إلى Azure OpenAI (أو مفتاح OpenAI API)
Visual Studio أو Visual Studio Code

قم بتثبيت الحزم المطلوبة (لاحظ أن علامة --prerelease مطلوبة أثناء المعاينة):

dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
dotnet add package Microsoft.Agents.AI.Workflows --prerelease
dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity
dotnet add package Azure.AI.Agents.Persistent --prerelease

وكلاء تسوق الهدايا

سيتكون مكتشف هدايا عيد الميلاد الخاص بنا من ثلاثة وكلاء متخصصين يعملون معًا:

** وكيل فكرة الهدية ** - يُنشئ اقتراحات هدايا إبداعية بناءً على الملف الشخصي للمستلم
** وكيل مقارنة الأسعار ** - يجد أفضل الأسعار عبر المتاجر المختلفة
وكيل الملخص - يجمع التوصيات النهائية

النماذج

لنبدأ بتحديد نماذج البيانات التي ستتدفق عبر مسار الوكلاء:

public class GiftRecipient
{
 public string Name { get; set; } = string.Empty;
 public int Age { get; set; }
 public List<string> Interests { get; set; } = [];
 public decimal Budget { get; set; }
}

public class GiftIdea
{
 public string Name { get; set; } = string.Empty;
 public string Description { get; set; } = string.Empty;
 public string Category { get; set; } = string.Empty;
 public decimal EstimatedPrice { get; set; }
}

public class PriceResult
{
 public string GiftName { get; set; } = string.Empty;
 public string Store { get; set; } = string.Empty;
 public decimal Price { get; set; }
 public string Url { get; set; } = string.Empty;
}

public class GiftRecommendation
{
 public GiftIdea Gift { get; set; } = new();
 public List<PriceResult> Prices { get; set; } = [];
 public PriceResult? BestDeal { get; set; }
}

بناء الوكلاء

يكمن جمال Agent Framework في مدى سهولة إنشاء وكلاء متخصصين. كل وكيل هو ببساطة ChatClientAgent مع موجه نظام محدد يحدد خبرته.

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;

public static class ChristmasAgentFactory
{
 public static AIAgent CreateGiftIdeaAgent(IChatClient chatClient)
 {
 return new ChatClientAgent(
 chatClient,
 @"You are a creative Christmas gift advisor. When given information about a person
 (age, interests, budget), you suggest thoughtful and personalized gift ideas.

 For each suggestion, provide:
 - Gift name
 - Brief description of why it's a good fit
 - Category (Electronics, Books, Fashion, Home, Experience, etc.)
 - Estimated price range

 Always suggest 3-5 gift options within the specified budget.
 Format your response as a structured list.");
 }

 public static AIAgent CreatePriceComparisonAgent(IChatClient chatClient)
 {
 return new ChatClientAgent(
 chatClient,
 @"You are a price comparison specialist. Given a list of gift ideas,
 you research and compare prices from different online retailers.

 For each gift, provide:
 - Store name (Amazon, Best Buy, Target, Walmart, etc.)
 - Current price
 - Any available discounts or deals

 Always highlight the best deal for each item.
 Consider shipping costs and delivery times for Christmas.");
 }

 public static AIAgent CreateSummaryAgent(IChatClient chatClient)
 {
 return new ChatClientAgent(
 chatClient,
 @"You are a gift recommendation summarizer. Take the gift ideas and price
 comparisons and create a final recommendation report.

 Your summary should:
 - Rank gifts by value (quality vs price)
 - Highlight the top pick with reasoning
 - Include total cost estimate
 - Add any tips for holiday shopping

 Make the summary cheerful and festive!");
 }
}

إنشاء سير العمل

والآن يأتي الجزء الممتع، وهو ربط وكلائنا بسير عمل متسلسل. يوفر إطار عمل الوكيل WorkflowBuilder وAgentWorkflowBuilder لتكوين الوكلاء في أنماط مختلفة.

public static class ChristmasGiftWorkflow
{
 public static async Task RunAsync()
 {
 // Set up the Azure OpenAI client
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
 ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")
 ?? "gpt-4o-mini";

 var chatClient = new AzureOpenAIClient(
 new Uri(endpoint),
 new DefaultAzureCredential())
 .GetChatClient(deploymentName)
 .AsIChatClient();

 // Create our specialized agents
 AIAgent giftIdeaAgent = ChristmasAgentFactory.CreateGiftIdeaAgent(chatClient);
 AIAgent priceAgent = ChristmasAgentFactory.CreatePriceComparisonAgent(chatClient);
 AIAgent summaryAgent = ChristmasAgentFactory.CreateSummaryAgent(chatClient);

 // Build a sequential workflow: Ideas -> Prices -> Summary
 var workflow = AgentWorkflowBuilder.BuildSequential(
 "ChristmasGiftFinder",
 [giftIdeaAgent, priceAgent, summaryAgent]);

 // Define our gift recipient
 var recipient = new GiftRecipient
 {
 Name = "Mom",
 Age = 55,
 Interests = ["gardening", "cooking", "reading", "yoga"],
 Budget = 100
 };

 var prompt = $@"Find Christmas gifts for {recipient.Name},
 age {recipient.Age}, who enjoys {string.Join(", ", recipient.Interests)}.
 Budget: ${recipient.Budget}";

 // Execute the workflow with streaming
 await using StreamingRun run = await InProcessExecution.StreamAsync(
 workflow,
 new ChatMessage(ChatRole.User, prompt));

 // Send the turn token to start processing
 await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

 // Watch for workflow events
 await foreach (WorkflowEvent evt in run.WatchStreamAsync())
 {
 if (evt is AgentRunUpdateEvent agentUpdate)
 {
 Console.Write(agentUpdate.Data);
 }
 else if (evt is WorkflowOutputEvent outputEvent)
 {
 Console.WriteLine("\n🎄 Final Recommendations:");
 Console.WriteLine(outputEvent.Data);
 }
 }
 }
}

تشغيل الوكلاء بشكل متزامن

ماذا لو أردنا البحث عن هدايا لعدة أشخاص في وقت واحد؟ يدعم Agent Framework التنفيذ المتزامن، وهو مثالي لهذا السيناريو:

public static async Task FindGiftsForEveryoneAsync(IChatClient chatClient, List<GiftRecipient> recipients)
{
 // Create an agent for each recipient
 var agents = recipients.Select(r => new ChatClientAgent(
 chatClient,
 $@"Find the perfect Christmas gift for {r.Name} (age {r.Age}),
 who loves {string.Join(", ", r.Interests)}. Budget: ${r.Budget}.
 Provide one well-researched recommendation with price."
 )).ToList();

 // Build a concurrent workflow - all agents run in parallel
 var workflow = AgentWorkflowBuilder.BuildConcurrent(
 "FamilyGiftFinder",
 agents);

 await using StreamingRun run = await InProcessExecution.StreamAsync(
 workflow,
 new ChatMessage(ChatRole.User, "Find gifts now!"));

 await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

 await foreach (WorkflowEvent evt in run.WatchStreamAsync())
 {
 if (evt is WorkflowOutputEvent output)
 {
 Console.WriteLine("🎁 All gift recommendations ready!");
 Console.WriteLine(output.Data);
 }
 }
}

منفذون مخصصون لمزيد من التحكمبالنسبة للسيناريوهات الأكثر تعقيدًا، يمكنك إنشاء برامج تنفيذية مخصصة تمنحك تحكمًا دقيقًا في سير العمل:

public sealed class GiftValidatorExecutor : Executor<List<ChatMessage>, List<ChatMessage>>
{
 public GiftValidatorExecutor() : base("GiftValidator") { }

 public override async ValueTask<List<ChatMessage>> HandleAsync(
 List<ChatMessage> messages,
 IWorkflowContext context,
 CancellationToken cancellationToken = default)
 {
 var lastMessage = messages.LastOrDefault()?.Text ?? "";

 // Validate that suggestions are within budget
 if (lastMessage.Contains("over budget", StringComparison.OrdinalIgnoreCase))
 {
 Console.WriteLine("⚠️ Some suggestions exceeded budget, filtering...");
 // Add validation logic here
 }

 Console.WriteLine("✅ Gift suggestions validated!");
 return messages;
 }
}

يمكنك بعد ذلك إدراج هذا المنفذ في سير العمل الخاص بك:

var validator = new GiftValidatorExecutor();

var workflow = new WorkflowBuilder(giftIdeaAgent)
 .AddEdge(giftIdeaAgent, validator)
 .AddEdge(validator, priceAgent)
 .AddEdge(priceAgent, summaryAgent)
 .WithOutputFrom(summaryAgent)
 .Build();

إضافة بحث ويب حقيقي باستخدام Bing Grounding

حتى الآن، يقوم وكلاؤنا بإنشاء استجابات بناءً على معرفة نموذج الذكاء الاصطناعي. ولكن ماذا لو أردنا البحث في الويب عن أسعار المنتجات الفعلية ومدى توفرها؟ هذا هو المكان الذي يأتي فيه التأريض باستخدام بحث Bing. إنها أداة متوفرة في Microsoft Foundry (المعروف سابقًا باسم Azure AI Foundry) والتي تسمح لعملائك بدمج بيانات الويب العامة في الوقت الفعلي عند إنشاء الاستجابات.

أولاً، ستحتاج إلى إنشاء مورد التأريض باستخدام بحث Bing في Azure Portal. تأكد من إنشائه في نفس مجموعة الموارد مثل مشروع الذكاء الاصطناعي الخاص بك.

إعداد التأريض باستخدام بحث Bing

إن جمال التأريض مع Bing Search هو أنه يتكامل مباشرة مع Azure AI Agents. يقرر الوكيل متى يستخدم أداة البحث بناءً على استعلام المستخدم، ويبحث في الويب، ويستخدم النتائج لإنشاء استجابة مرتكزة.

using Azure.AI.Agents.Persistent;
using Azure.Identity;

public static class BingGroundingSetup
{
 public static async Task<PersistentAgent> CreateAgentWithBingGroundingAsync(
 string projectEndpoint,
 string modelDeploymentName,
 string bingConnectionId)
 {
 // Create the Persistent Agents client
 var agentClient = new PersistentAgentsClient(projectEndpoint, new DefaultAzureCredential());

 // Configure the Bing Grounding tool
 var bingGroundingTool = new BingGroundingToolDefinition(
 new BingGroundingSearchToolParameters(
 [new BingGroundingSearchConfiguration(bingConnectionId)]
 )
 );

 // Create the agent with Bing Grounding enabled
 var agent = await agentClient.Administration.CreateAgentAsync(
 model: modelDeploymentName,
 name: "ChristmasPriceHunter",
 instructions: @"You are a Christmas gift price comparison specialist.

 When given gift ideas, use Bing to search for:
 - Current prices at major retailers (Amazon, Best Buy, Target, Walmart)
 - Available discounts and holiday deals
 - Shipping times to ensure delivery before Christmas

 Always provide URLs to the products you find.
 Highlight the best deals and recommend where to buy.",
 tools: [bingGroundingTool]
 );

 return agent;
 }
}

إنشاء وكيل لمقارنة الأسعار باستخدام بحث حقيقي

لنقم الآن بإنشاء وكيل كامل لمقارنة الأسعار يقوم بالبحث في الويب عن معلومات المنتج الحقيقية:

using Azure.AI.Agents.Persistent;
using Azure.Identity;

public class ChristmasPriceAgent
{
 private readonly PersistentAgentsClient _client;
 private readonly string _modelDeployment;
 private readonly string _bingConnectionId;

 public ChristmasPriceAgent(string projectEndpoint, string modelDeployment, string bingConnectionId)
 {
 _client = new PersistentAgentsClient(projectEndpoint, new DefaultAzureCredential());
 _modelDeployment = modelDeployment;
 _bingConnectionId = bingConnectionId;
 }

 public async Task<string> FindGiftPricesAsync(string giftIdeas)
 {
 // Create agent with Bing Grounding
 var bingTool = new BingGroundingToolDefinition(
 new BingGroundingSearchToolParameters(
 [new BingGroundingSearchConfiguration(_bingConnectionId)]
 )
 );

 var agent = await _client.Administration.CreateAgentAsync(
 model: _modelDeployment,
 name: "PriceHunter",
 instructions: @"Search the web for current prices on the given gift ideas.
 For each gift, find prices from at least 2-3 different stores.
 Include direct links to the products.
 Note any Christmas sales or discounts available.",
 tools: [bingTool]
 );

 try
 {
 // Create a thread for the conversation
 var thread = await _client.Threads.CreateThreadAsync();

 // Add the gift ideas as a message
 await _client.Messages.CreateMessageAsync(
 thread.Id,
 MessageRole.User,
 $"Find current prices for these gift ideas: {giftIdeas}"
 );

 // Run the agent
 var run = await _client.Runs.CreateRunAsync(thread.Id, agent.Id);

 // Wait for completion
 do
 {
 await Task.Delay(500);
 run = await _client.Runs.GetRunAsync(thread.Id, run.Id);
 }
 while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);

 // Get the response
 var messages = _client.Messages.GetMessages(thread.Id);
 var response = messages
 .Where(m => m.Role == MessageRole.Agent)
 .SelectMany(m => m.ContentItems)
 .OfType<MessageTextContent>()
 .FirstOrDefault();

 // Clean up
 await _client.Threads.DeleteThreadAsync(thread.Id);

 return response?.Text ?? "No results found.";
 }
 finally
 {
 // Clean up the agent
 await _client.Administration.DeleteAgentAsync(agent.Id);
 }
 }
}

دمج Bing Grounding في سير العمل

فيما يلي كيفية استخدام وكيل الأسعار المدعوم من Bing في سير عمل كامل للبحث عن الهدايا:

public static async Task RunWithBingGroundingAsync()
{
 var projectEndpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT")!;
 var modelDeployment = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
 var bingConnectionId = Environment.GetEnvironmentVariable("BING_CONNECTION_ID")!;
 // Connection ID format: /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}/connections/{connection}

 Console.WriteLine("🔍 Searching the web for real prices with Bing Grounding...\n");

 var priceAgent = new ChristmasPriceAgent(projectEndpoint, modelDeployment, bingConnectionId);

 // First, generate gift ideas (could come from another agent)
 var giftIdeas = "1. Milwaukee cordless drill set, 2. Weber portable grill, 3. Carhartt beanie";

 // Search for real prices
 var priceResults = await priceAgent.FindGiftPricesAsync(giftIdeas);

 Console.WriteLine("📊 Price Comparison Results:");
 Console.WriteLine(priceResults);
 Console.WriteLine("\n🎁 Happy Shopping! 🎁");
}

معالجة الاستشهادات من نتائج Bing

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

public static void ProcessBingGroundingResponse(IEnumerable<PersistentThreadMessage> messages)
{
 foreach (var message in messages.Where(m => m.Role == MessageRole.Agent))
 {
 foreach (var content in message.ContentItems)
 {
 if (content is MessageTextContent textContent)
 {
 var response = textContent.Text;

 // Process URL citations
 if (textContent.Annotations != null)
 {
 foreach (var annotation in textContent.Annotations)
 {
 if (annotation is MessageTextUriCitationAnnotation uriAnnotation)
 {
 // Replace citation placeholder with markdown link
 response = response.Replace(
 uriAnnotation.Text,
 $" [{uriAnnotation.UriCitation.Title}]({uriAnnotation.UriCitation.Uri})"
 );
 }
 }
 }

 Console.WriteLine(response);
 }
 }
 }
}

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

##البرنامج الكامل

إليك كيفية تجميع كل شيء معًا في Program.cs:

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;

Console.WriteLine("🎄 Christmas Gift Finder - Powered by AI Agents 🎄\n");

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!;
var deployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

var chatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
 .GetChatClient(deployment)
 .AsIChatClient();

// Create the agent team
var ideaAgent = ChristmasAgentFactory.CreateGiftIdeaAgent(chatClient);
var priceAgent = ChristmasAgentFactory.CreatePriceComparisonAgent(chatClient);
var summaryAgent = ChristmasAgentFactory.CreateSummaryAgent(chatClient);

// Build the workflow
var workflow = AgentWorkflowBuilder.BuildSequential(
 "ChristmasGiftWorkflow",
 [ideaAgent, priceAgent, summaryAgent]);

Console.Write("Who are you shopping for? ");
var recipientName = Console.ReadLine() ?? "Someone special";

Console.Write("What are their interests? ");
var interests = Console.ReadLine() ?? "general";

Console.Write("What's your budget? $");
var budget = Console.ReadLine() ?? "50";

var prompt = $"Find Christmas gifts for {recipientName} who enjoys {interests}. Budget: ${budget}";

Console.WriteLine("\n🔍 Searching for the perfect gifts...\n");

await using var run = await InProcessExecution.StreamAsync(
 workflow,
 new ChatMessage(ChatRole.User, prompt));

await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

await foreach (var evt in run.WatchStreamAsync())
{
 switch (evt)
 {
 case AgentRunUpdateEvent update:
 Console.Write(update.Update.Text);
 break;
 case WorkflowOutputEvent output:
 Console.WriteLine("\n\n🎁 Happy Shopping! 🎁");
 break;
 }
}

الخلاصة

يجعل Microsoft Agent Framework من السهل بشكل مدهش إنشاء أنظمة متعددة الوكلاء حيث يتخصص كل وكيل في مهمة محددة. ومن خلال تنسيق هؤلاء الوكلاء من خلال سير العمل، يمكننا معالجة المشكلات المعقدة مثل التسوق في عيد الميلاد بطريقة منظمة وفعالة.

ما يجعل هذا أكثر قوة هو القدرة على إضافة إمكانات العالم الحقيقي من خلال الأدوات. من خلال دمج Grounding مع Bing Search من Microsoft Foundry، يستطيع وكيل مقارنة الأسعار لدينا البحث فعليًا في الويب عن الأسعار والصفقات الحالية ومدى التوفر - مما يحول روبوت الدردشة البسيط الذي يعمل بالذكاء الاصطناعي إلى مساعد تسوق مفيد حقًا مع الاستشهادات المناسبة.

إن دعم إطار العمل للأنماط التسلسلية والمتزامنة والتسليم يعني أنه يمكنك تصميم أنظمة الوكلاء التي تتوافق مع احتياجاتك الدقيقة. سواء كان الأمر يتعلق بالعثور على الهدايا، أو التخطيط للرحلات، أو أي مهمة أخرى متعددة الخطوات، فإن Agent Framework يوفر العناصر الأساسية لتحقيق ذلك.في موسم العطلات هذا، اسمح لعملاء الذكاء الاصطناعي بالتعامل مع البحث بينما تركز أنت على تغليف الهدايا والاستمتاع بالوقت مع العائلة!

كود المصدر

تستند المفاهيم الموضحة في هذا المنشور إلى عينات إطار عمل الوكيل الرسمية. يمكنك استكشاف المزيد من الأمثلة على مستودع Microsoft Agent Framework GitHub.

إجازة سعيدة وترميز سعيد! 🎄

بناء مجمع تغذية RSS مدعوم بالذكاء الاصطناعي

Fri, 12 Dec 2025 00:00:00 +0000

باعتباري أحد أفضل اللاعبين في Microsoft وعشاقًا للتكنولوجيا، أجد نفسي دائمًا غارقًا في محيط من المحتوى المذهل المنشور عبر DevBlogs من Microsoft. بدءًا من إعلانات .NET وحتى تحديثات Visual Studio، ومن ابتكارات Azure إلى الأبحاث العميقة حول Semantic Kernel - هناك دائمًا شيء جديد ومثير يحدث في نظام Microsoft البيئي.

المشكلة؟ مواكبة كل ذلك يكاد يكون من المستحيل.

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

لذلك فعلت ما كان سيفعله أي مطور – لقد قمت بتشغيله تلقائيًا.

في هذا الدليل الشامل، سأرشدك عبر كيفية إنشاء مجمع موجزات RSS مدعوم بالذكاء الاصطناعي والذي يراقب خلاصات RSS المتعددة لـ Microsoft DevBlogs للمحتوى الجديد، ويستخدم Azure OpenAI وSemantic Kernel لتحليل المقالات وإنشاء منشورات جذابة، وإنشاء وثائق تخفيض السعر التفصيلية لكل مقالة تم تحليلها، وإرسال إشعارات عبر Telegram حتى أتمكن من مراجعة المحتوى ومشاركته، وتتبع كل شيء لتجنب المنشورات المكررة، وتشغيله تلقائيًا عبر GitHub Actions.

دعونا نتعمق في كل جانب من جوانب هذا الحل.

القصة وراء هذا المشروع

العيش مع الحمل الزائد للمعلومات

اسمحوا لي أن أرسم لكم صورة لصباحي النموذجي قبل أن أقوم ببناء هذه الأداة. كنت أستيقظ وأتناول قهوتي وأفتح جهاز الكمبيوتر المحمول الخاص بي للتحقق من الجديد في النظام البيئي لمطوري Microsoft. أولاً، سأنتقل إلى موقع DevBlogs الرئيسي لمعرفة ما إذا كان هناك أي إعلانات رئيسية. ثم سأقوم بمراجعة مدونة .NET على وجه التحديد لأن هذه هي مجموعتي التكنولوجية الأساسية. بعد ذلك، سأنتقل إلى مدونة Semantic Kernel نظرًا لأن الذكاء الاصطناعي أصبح ذا أهمية متزايدة. كانت مدونة Visual Studio هي التالية في القائمة لأن تحديثات IDE يمكن أن تؤثر بشكل كبير على سير العمل اليومي. ثم جاءت مدونة DevOps للأخبار المتعلقة بـ CI/CD وGitHub، تليها مدونة All Things Azure لتحديثات البنية التحتية السحابية، وأخيرًا مدونة Azure SQL لابتكارات قواعد البيانات.

هذه سبعة خلاصات مختلفة للتحقق منها. تنشر كل من هذه المدونات عدة مقالات أسبوعيًا، وأحيانًا عدة مقالات يوميًا خلال فترات الإعلان الرئيسية مثل .NET Conf أو Build. من المحتمل أن يكون هذا عشرات المقالات لتتبعها وقراءتها ومشاركتها. وهنا الأمر - كشخص يقدر مشاركة المعرفة مع المجتمع، لم أرغب في قراءة هذه المقالات فقط. أردت مشاركة أهم الأشياء مع شبكتي على LinkedIn، لمساعدة المطورين الآخرين على البقاء على اطلاع أيضًا.لكن إنشاء منشور جيد على LinkedIn يستغرق وقتًا. تحتاج إلى قراءة المقالة جيدًا، وفهم النقاط الرئيسية، والتفكير في سبب أهميتها لجمهورك، وكتابة رابط جذاب، وتنسيق كل شيء بشكل جيد. اضرب ذلك بعدة مقالات في الأسبوع، وستحصل على ساعات العمل.

ما أردته حقًا

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

وكان الاتساق عاملا كبيرا آخر. كنت أرغب في مشاركة المحتوى بانتظام دون الحاجة إلى تذكر القيام بذلك يدويًا كل يوم. كان جانب التتبع حاسمًا أيضًا - كنت بحاجة إلى طريقة لمعرفة ما قمت بمشاركته بالفعل لتجنب نشر التكرارات وإزعاج متابعي. أخيرًا، أردت أن أبقى منظمًا من خلال سجل دائم لكل ما قمت بمعالجته، حتى أتمكن من الرجوع إلى الوراء ومعرفة الموضوعات التي قمت بتغطيتها.

الحل يتبلور

سيتم تشغيل الحل الذي تصورته وفقًا لجدول زمني باستخدام GitHub Actions، بدون استخدام اليدين تمامًا. سيجلب جميع الخلاصات السبعة تلقائيًا دون الحاجة إلى فتح علامة تبويب متصفح واحدة. سيقرأ مكون الذكاء الاصطناعي المحتوى ويفهمه، ثم يلخصه بطريقة مفيدة لجمهوري. بدلاً من أن أضطر إلى كتابة منشورات من الصفر، فإنه سينشئ محتوى جاهزًا للمشاركة على وسائل التواصل الاجتماعي ويمكنني تعديله إذا لزم الأمر. سيتم إرسال كل شيء إلى Telegram الخاص بي للمراجعة، حتى أتمكن من إلقاء نظرة سريعة على هاتفي وتحديد ما سأشاركه. وبطبيعة الحال، فإنه سيحتفظ بسجل دائم لكل شيء للرجوع إليه في المستقبل.

قبل أن نبدأ البناء

ما ستحتاجه على جهازك

لمتابعة هذا البرنامج التعليمي، ستحتاج إلى تثبيت بعض الأشياء على جهاز التطوير الخاص بك. أهمها هو الإصدار 9.0 من .NET SDK أو الأحدث. هذا هو وقت التشغيل الخاص بنا ويوفر جميع أدوات البناء التي نحتاجها. إذا لم يكن مثبتًا لديك، فانتقل إلى dot.net وقم بتنزيل أحدث إصدار. التثبيت سهل ومباشر على أنظمة التشغيل Windows أو macOS أو Linux.

ستحتاج أيضًا إلى تثبيت Git للتحكم في الإصدار. سنقوم بإرسال الكود الخاص بنا إلى GitHub واستخدام إجراءات GitHub للأتمتة، لذا يعد إعداد Git محليًا أمرًا ضروريًا. أي نسخة حديثة سوف تعمل بشكل جيد.

بالنسبة لبيئة التطوير الخاصة بك، أوصي باستخدام Visual Studio أو VS Code. أنا شخصياً أستخدم VS Code في معظم أعمالي هذه الأيام لأنه خفيف الوزن ويتمتع بدعم ممتاز لـ C# من خلال ملحق C# Dev Kit. ولكن إذا كنت أكثر راحة مع Visual Studio الكامل، فهذا يعمل بشكل مثالي أيضًا.

الخدمات والحسابات التي ستحتاج إليهابالإضافة إلى الأدوات المحلية، ستحتاج إلى حسابات تحتوي على عدد قليل من الخدمات. وأهمها هو Azure OpenAI، الذي يدعم تحليل الذكاء الاصطناعي لدينا. هذه خدمة الدفع أولاً بأول، ولكن التكاليف ضئيلة بالنسبة لحالة الاستخدام هذه - فنحن نتحدث عن سنتات لكل مقالة يتم تحليلها. إذا لم يكن لديك حساب Azure، فيمكنك التسجيل للحصول على نسخة تجريبية مجانية تتضمن بعض الاعتمادات للبدء.

للإشعارات، سنستخدم Telegram Bot. إن الشيء العظيم في Telegram هو أن واجهة برمجة التطبيقات الخاصة بهم مجانية تمامًا للاستخدام. يمكنك إنشاء العدد الذي تريده من الروبوتات وإرسال رسائل غير محدودة. سأرشدك خلال عملية الإعداد لاحقًا في هذا الدليل.

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

المكتبات التي تجعل هذا ممكنًا

يعتمد مشروعنا على ثلاث حزم NuGet رئيسية، تخدم كل منها غرضًا محددًا.

الأول هو HtmlAgilityPack، وهو المعيار الذهبي لتحليل HTML في .NET. عندما نجلب مقالة من إحدى المدونات، فإننا نستعيد HTML الكامل للصفحة - بما في ذلك قوائم التنقل والتذييلات والإعلانات وجميع أنواع العناصر التي لا نهتم بها. يتيح لنا HtmlAgilityPack تحليل HTML واستخراج محتوى المقالة الذي نحتاجه فقط.

الحزمة الثانية هي Microsoft.SemanticKernel، وهي حزمة SDK من Microsoft لدمج نماذج الذكاء الاصطناعي في التطبيقات. فكر في الأمر كجسر بين كود .NET الخاص بك ونماذج اللغات الكبيرة مثل GPT-4. فهو يتعامل مع كل تعقيدات استدعاءات واجهة برمجة التطبيقات (API)، وإدارة الرموز المميزة، وتحليل الاستجابة، مما يتيح لك التركيز على ما تريد أن يفعله الذكاء الاصطناعي بالفعل.

الحزمة الثالثة هي System.ServiceModel.Synvation، والتي توفر دعمًا مدمجًا لتحليل خلاصات RSS وAtom. قد تبدو خدمة RSS بمثابة تقنية قديمة، ولكنها لا تزال أفضل طريقة للحصول على تحديثات منظمة من المدونات والمواقع الإخبارية. تعمل هذه الحزمة على تحويل موجزات XML الأولية إلى كائنات C# مكتوبة بقوة والتي يسهل التعامل معها.

فهم العمارة

كيف تتناسب القطع مع بعضها البعض

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

على أعلى مستوى، لدينا ملف Program.cs الرئيسي الذي يعمل كمنسق. هذه هي نقطة الدخول لتطبيقنا، وهي تنسق جميع المكونات الأخرى. عند تشغيل التطبيق، يقوم أولاً بتحميل التكوين من متغيرات البيئة – أشياء مثل مفاتيح API وبيانات اعتماد Telegram. ثم يخرج ويجلب موجزات RSS من جميع مصادر Microsoft DevBlogs السبعة. أثناء معالجة هذه الخلاصات، فإنها تعمل على إلغاء تكرار المقالات للتعامل مع الحالات التي تظهر فيها نفس المقالة في خلاصات متعددة. يقوم بفحص كل مقالة مقابل ملف التتبع الخاص بنا لمعرفة ما إذا كنا قد قمنا بمعالجتها بالفعل. بالنسبة للمقالات الجديدة، يتم تسليمها إلى محلل الذكاء الاصطناعي لمعالجتها.فئة ArticleAnalyzer هي المكان الذي يحدث فيه سحر الذكاء الاصطناعي. يتلقى هذا المكون مقالًا ويقوم بعدة أشياء به. أولاً، يقوم بجلب محتوى HTML الكامل من عنوان URL الخاص بالمقالة. ثم يقوم باستخراج نص نظيف من HTML، وإزالة كافة عناصر التنقل والبرامج النصية والتصميمات التي لا نحتاج إليها. بمجرد حصوله على نص نظيف، فإنه يرسل ذلك إلى Azure OpenAI من خلال Semantic Kernel بمطالبة مصممة بعناية. يقوم الذكاء الاصطناعي بتحليل المقالة وإرجاع استجابة منظمة تتضمن ملخصًا وموضوعات رئيسية وشرحًا لأهميتها، والأهم من ذلك، منشورًا جاهزًا للاستخدام على LinkedIn. يقوم المحلل بتحليل هذه الاستجابة وإرجاع كائن ArticleAnalogy الذي يحتوي على كل هذه المعلومات.

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

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

تدفق البيانات

اسمح لي أن أطلعك على ما يحدث عند نشر مقالة جديدة على مدونة .NET. يبدأ سير العمل عندما تقوم GitHub Actions بتشغيل تطبيقنا وفقًا لجدوله الزمني - لنفترض كل ست ساعات. ينشط التطبيق ويبدأ في جلب جميع خلاصات RSS السبعة. يعرض كل موجز مستند XML يحتوي على أحدث المقالات من تلك المدونة.

أثناء تحليل كل موجز، نقوم باستخراج المقالات الفردية وتخزينها في القائمة. ولكن هنا جزء صعب - غالبًا ما تتضمن خلاصة DevBlogs الرئيسية مقالات تظهر أيضًا في خلاصات الفئات الفردية. لذلك قد تظهر مقالة حول “.NET 10” في كل من الخلاصة الرئيسية والخلاصة الخاصة بـ .NET. نحن نتعامل مع هذا من خلال تتبع عناوين URL في HashSet، مما يمنع التكرارات تلقائيًا.

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

لكل مقال جديد، نبدأ مسار تحليل الذكاء الاصطناعي. يقوم المحلل بإحضار HTML للمقالة الكاملة، وينظفها، ويرسلها إلى GPT-4 مع مطالبتنا. يقرأ الذكاء الاصطناعي المقالة ويقوم بإنشاء تحليل شامل بالإضافة إلى منشور على LinkedIn. نحفظ هذا التحليل في ملف تخفيض السعر لسجلاتنا.بعد اكتمال التحليل، نقوم بتنسيق رسالة وإرسالها عبر Telegram. تتضمن الرسالة محتوى المنشور الذي تم إنشاؤه مع عنوان URL وعلامات التصنيف الملحقة. على هاتفي، أتلقى إشعارًا، وأراجع المنشور، وإذا أعجبتني، يمكنني نسخه ومشاركته على LinkedIn ببضع نقرات فقط.

أخيرًا، نقوم بتحديث ملف التتبع الخاص بنا لوضع علامة على هذه المقالة على أنها تمت معالجتها، لذلك لن نتعامل معها مرة أخرى في عمليات التشغيل المستقبلية. إذا تم إنشاء أي ملفات أو تعديلها، فإن GitHub Actions يُلزم هذه التغييرات مرة أخرى بالمستودع، مع الحفاظ على مزامنة كل شيء.

إعداد المشروع من الصفر

إنشاء هيكل الحل

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

أولاً، سنقوم بإنشاء ملف حل جديد. في .NET، الحل عبارة عن حاوية يمكنها الاحتفاظ بمشاريع متعددة. على الرغم من أنه لدينا مشروع واحد فقط في الوقت الحالي، فإن البدء بالحل يجعل من السهل إضافة المزيد من المشاريع لاحقًا إذا لزم الأمر. قم بتشغيل الأمر dotnet new sln -n vs-feed-linkedin لإنشاء حل باسم vs-feed-linkedin.

بعد ذلك، نحتاج إلى إنشاء مشروع تطبيق وحدة التحكم الخاص بنا. سنضع هذا في دليل فرعي src للحفاظ على تنظيم الأمور. قم بتشغيل dotnet new console -n VsFeedLinkedin -o src لإنشاء مشروع وحدة تحكم باسم VsFeedLinkedin في مجلد src. ثم أضف هذا المشروع إلى حلنا باستخدام dotnet sln add src/VsFeedLinkedin.csproj.

انتقل الآن إلى دليل src باستخدام cd src. هذا هو المكان الذي سنضيف فيه حزم NuGet الخاصة بنا ونقوم بمعظم عمليات التطوير لدينا.

إضافة الحزم المطلوبة

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

dotnet add package System.ServiceModel.Syndication --version 9.0.9
dotnet add package Microsoft.SemanticKernel --version 1.30.0
dotnet add package HtmlAgilityPack --version 1.11.72

بعد تشغيل هذه الأوامر، يجب أن يبدو ملف مشروعك كما يلي:

<Project Sdk="Microsoft.NET.Sdk">

 <PropertyGroup>
 <OutputType>Exe</OutputType>
 <TargetFramework>net9.0</TargetFramework>
 <ImplicitUsings>enable</ImplicitUsings>
 <Nullable>enable</Nullable>
 </PropertyGroup>

 <ItemGroup>
 <PackageReference Include="HtmlAgilityPack" Version="1.11.72" />
 <PackageReference Include="Microsoft.SemanticKernel" Version="1.30.0" />
 <PackageReference Include="System.ServiceModel.Syndication" Version="9.0.9" />
 </ItemGroup>

</Project>

يخبر ملف المشروع .NET أننا نبني ملفًا قابلاً للتنفيذ (OutputType هو Exe)، ونستهدف .NET 9.0، ونستخدم ميزات C# الحديثة مثل الاستخدامات الضمنية وأنواع المراجع الخالية. يسرد قسم ItemGroup تبعيات الحزمة الثلاثة مع إصداراتها الدقيقة.

الغوص العميق في خلاصات RSS

ما هو نظام RSS بالضبط؟

قبل أن نبدأ في كتابة التعليمات البرمجية لجلب الخلاصات، دعونا نتأكد من أننا نفهم ما نعمل معه. يرمز RSS إلى “Really Simple Syndication”، وهو تنسيق XML موحد لتوزيع تحديثات المحتوى. الفكرة بسيطة: بدلاً من مطالبة المستخدمين بزيارة موقع الويب الخاص بك لمعرفة ما إذا كان هناك محتوى جديد، يمكنك نشر ملف يمكن قراءته آليًا يسرد المحتوى الحديث الخاص بك. يمكن للتطبيقات بعد ذلك استقصاء هذا الملف بشكل دوري لاكتشاف مقالات جديدة.

كانت خدمة RSS موجودة منذ أواخر التسعينيات وأوائل العقد الأول من القرن الحادي والعشرين. قد تعتقد أنها تقنية قديمة، لكنها في الواقع لا تزال مستخدمة على نطاق واسع - خاصة من خلال المدونات والمواقع الإخبارية والبودكاست. جمال RSS هو بساطته. إنه مجرد ملف XML ذو بنية محددة، ويمكن لأي تطبيق تحليله.

بنية موجز مدونات المطورينعندما تقوم بإحضار موجز RSS من Microsoft DevBlogs، يمكنك استرجاع مستند XML يتبع بنية محددة. في المستوى الأعلى، يوجد عنصر RSS يحتوي على عنصر قناة واحد. تمثل القناة المدونة نفسها وتتضمن بيانات وصفية مثل عنوان المدونة وعنوان URL والوصف.

ستجد داخل القناة عناصر متعددة، يمثل كل منها منشور مدونة فرديًا. يتضمن كل عنصر عنوانًا (عنوان المقالة)، ورابطًا (عنوان URL الذي يمكنك من خلاله قراءة المقالة كاملة)، وتاريخ النشر (تاريخ نشر المقالة)، وعنصر dc:creator (اسم المؤلف)، وعنصر فئة واحد أو أكثر (علامات للمقالة)، ووصف (عادةً ملخص أو مقتطف من المقالة).

فيما يلي مثال مبسط لما يبدو عليه هذا:

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
 <channel>
 <title>.NET Blog</title>
 <link>https://devblogs.microsoft.com/dotnet</link>
 <description>The latest news about .NET</description>
 <item>
 <title>Announcing .NET 10</title>
 <link>https://devblogs.microsoft.com/dotnet/announcing-dotnet-10</link>
 <pubDate>Mon, 10 Dec 2025 12:00:00 GMT</pubDate>
 <dc:creator>Microsoft</dc:creator>
 <category>Announcements</category>
 <category>.NET</category>
 <description>Article summary...</description>
 </item>
 </channel>
</rss>

إن الشيء العظيم في حزمة System.ServiceModel.Synvation الخاصة بـ .NET هو أنها تقوم بتحليل كل هذا لنا. لا يتعين علينا التنقل يدويًا في عقد XML أو القلق بشأن إصدارات RSS المختلفة. نحن فقط نقوم بتحميل الخلاصة ونستعيد الكائنات المكتوبة بقوة.

الخلاصات السبعة التي نراقبها

أثناء تنفيذي، أراقب سبعة خلاصات مختلفة لـ Microsoft DevBlogs. يمنحنا موجز DevBlogs الرئيسي على devblogs.microsoft.com/feed رؤية واسعة لكل ما تنشره Microsoft عبر جميع مدونات المطورين الخاصة بها. يركز الموجز الخاص بـ .NET الموجود على devblogs.microsoft.com/dotnet/feed بشكل خاص على إصدارات .NET وميزاته وأفضل الممارسات. يغطي موجز Semantic Kernel الموجود على devblogs.microsoft.com/semantic-kernel/feed تنسيق الذكاء الاصطناعي وتكامله - وهو أمر ذو أهمية متزايدة حيث أصبح الذكاء الاصطناعي محوريًا في التطوير الحديث.

يبقيني موجز Visual Studio على devblogs.microsoft.com/visualstudio/feed على اطلاع دائم بتحسينات IDE وميزات الإنتاجية. يغطي موجز DevOps الموجود على devblogs.microsoft.com/devops/feed موضوعات Azure DevOps وGitHub وCI/CD. يركز موجز All Things Azure على devblogs.microsoft.com/all-things-azure/feed على الخدمات السحابية وأنماط الهندسة المعمارية. وأخيرًا، يغطي موجز Azure SQL الموجود على devblogs.microsoft.com/azure-sql/feed ابتكارات قواعد البيانات وميزاتها.

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

بناء منطق جلب RSS

وظيفة الجلب الأساسية

الآن دعونا نكتب بعض التعليمات البرمجية. أساس تطبيقنا هو القدرة على جلب وتحليل خلاصات RSS. إليك الوظيفة التي تتعامل مع هذا:

static async Task<SyndicationFeed?> FetchRssFeedAsync(string url)
{
 using var httpClient = new HttpClient();
 httpClient.DefaultRequestHeaders.Add("User-Agent", "VsFeedLinkedin/1.0");

 var response = await httpClient.GetStringAsync(url);

 using var stringReader = new StringReader(response);

 var settings = new XmlReaderSettings
 {
 DtdProcessing = DtdProcessing.Parse,
 MaxCharactersFromEntities = 1024
 };

 using var xmlReader = XmlReader.Create(stringReader, settings);

 return SyndicationFeed.Load(xmlReader);
}

اسمحوا لي أن أتعرف على ما يفعله هذا الرمز. نبدأ بإنشاء HttpClient، وهو فئة .NET المضمنة لتقديم طلبات HTTP. لقد قمنا بتعيين رأس وكيل المستخدم لأن بعض الخوادم تحظر الطلبات التي لا تحدد هويتها. من الممارسات الجيدة ضبط هذا حتى عندما لا تتطلب الخوادم ذلك.نقوم بعد ذلك بتقديم طلب GET إلى عنوان URL للخلاصة ونتلقى الرد كسلسلة. تحتوي هذه السلسلة على ملف XML الأولي لخلاصة RSS.

لتحليل ملف XML هذا، نقوم بإنشاء StringReader لتغليف سلسلة الاستجابة الخاصة بنا، ثم نقوم بتكوين بعض إعدادات XmlReaderSettings. يعد إعداد DtdProcessing مهمًا - تتضمن خلاصات RSS أحيانًا إعلانات DTD (تعريف نوع المستند) التي تحتاج إلى معالجة. يعد إعداد MaxCharactersFromEntities بمثابة إجراء أمني يمنع هجمات XML بالقنابل عن طريق الحد من مقدار توسيع الكيان الذي يمكن أن يحدث.

وأخيرًا، نقوم بإنشاء XmlReader بهذه الإعدادات واستخدام SyndicationFeed.Load لتحليل XML إلى كائن SyndicationFeed مكتوب بقوة. يمنحنا هذا إمكانية الوصول إلى البيانات التعريفية للخلاصة وجميع عناصرها من خلال خصائص C# الرائعة بدلاً من التنقل بتنسيق XML الأولي.

جلب موجزات متعددة مع معالجة الأخطاء

في العالم الحقيقي، تفشل طلبات الشبكة. تتعطل الخوادم، وتنتهي مهلة الاتصالات، ويمكن أن يكون XML مشوهًا. نحن بحاجة للتعامل مع هذه الحالات بأمان. إليك كيفية جلب جميع خلاصاتنا مع المرونة في مواجهة حالات الفشل:

var allArticles = new List<(SyndicationItem item, string feedUrl)>();
var seenUrls = new HashSet<string>();

foreach (var feedUrl in feedUrls)
{
 try
 {
 Console.WriteLine($" 📡 Fetching {feedUrl}...");
 var feed = await FetchRssFeedAsync(feedUrl);

 if (feed?.Items != null && feed.Items.Any())
 {
 foreach (var item in feed.Items)
 {
 var itemUrl = item.Links.FirstOrDefault()?.Uri.ToString() ?? "";
 if (!string.IsNullOrEmpty(itemUrl) && seenUrls.Add(itemUrl))
 {
 allArticles.Add((item, feedUrl));
 }
 }
 }
 }
 catch (Exception ex)
 {
 Console.WriteLine($" ⚠️ Failed to fetch {feedUrl}: {ex.Message}");
 }
}

نحن نحتفظ بمجموعتين هنا. ستحتوي قائمة allArticles على جميع المقالات التي نجدها، بالإضافة إلى الخلاصة التي أتت منها. يتتبع SeenUrls HashSet عناوين URL للمقالات التي رأيناها بالفعل، مما يساعدنا على تجنب التكرارات.

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

لكل خلاصة تم جلبها بنجاح، نقوم بالتكرار من خلال عناصرها. نقوم باستخراج عنوان URL للمقالة من مجموعة الروابط الخاصة بالعنصر. تقوم طريقة HashSet.Add بإرجاع خطأ إذا كان عنوان URL موجودًا بالفعل في المجموعة، وهو مثالي لمنطق إلغاء البيانات المكررة لدينا. نضيف المقالة إلى قائمتنا فقط إذا كانت جديدة.

نقوم بتخزين عنوان URL للخلاصة بجانب كل مقالة لأن هذه المعلومات قد تكون مفيدة لاحقًا - على سبيل المثال، قد نرغب في معرفة الخلاصة المحددة التي جاءت منها المقالة لأغراض تصحيح الأخطاء أو التسجيل.

التعامل مع التكرارات وحالة التتبع

تحدي إلغاء البيانات المكررة

كما ذكرت سابقًا، تمتلك Microsoft DevBlogs بنية موجزة هرمية تخلق تحديًا مثيرًا للاهتمام. عندما ينشر أحد أعضاء فريق .NET مقالًا حول، على سبيل المثال، تحسينات الأداء في .NET 10، فمن المحتمل أن تظهر هذه المقالة في كل من خلاصة DevBlogs الرئيسية والخلاصة الخاصة بـ .NET. في بعض الأحيان قد يظهر في موجز Visual Studio إذا كان يتعلق بميزات IDE.

إذا قمنا بسذاجة بمعالجة كل مقالة من كل خلاصة، فسينتهي بنا الأمر إلى تحليل ونشر نفس المقالة عدة مرات. سيؤدي ذلك إلى إهدار مكالمات API إلى Azure OpenAI، وإرسال بريد عشوائي إلى Telegram بإشعارات مكررة، وربما إزعاج متابعينا إذا قمنا بنشر نسخ مكررة.الحل هو إلغاء البيانات المكررة المستندة إلى عنوان URL. تحتوي كل مقالة على عنوان URL فريد، لذا يمكننا استخدامه كمعرف. تعتبر بنية بيانات HashSet مثالية لهذا لأنها توفر وقت بحث O(1) وتمنع التكرارات تلقائيًا. عندما نحاول إضافة عنوان URL موجود بالفعل في المجموعة، فإن طريقة الإضافة ترجع ببساطة خطأ، مما يتيح لنا معرفة أنه يجب علينا تخطي هذه المقالة.

الحالة المستمرة مع تخفيض السعر

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

لقد اخترت تخزين هذه الحالة في ملف تخفيض السعر المسمىpost-articles.md. لماذا تخفيض السعر؟ عدة أسباب. أولاً، إنها قابلة للقراءة من قبل الإنسان. يمكنني فتح الملف ورؤية المقالات التي قمت بمشاركتها على الفور. ثانيًا، يتم التحكم في الإصدار. وبما أن هذا الملف موجود في مستودع Git الخاص بنا، فلدي سجل كامل بمواعيد معالجة المقالات. ثالثًا، إنه بمثابة توثيق. يمكن لأي شخص ينظر إلى المستودع أن يرى ما فعله التطبيق.

تنسيق هذا الملف بسيط. يحتوي على رأس، وطابع زمني يوضح آخر مرة تم فيها تشغيل التطبيق، ثم قائمة بالمقالات بتنسيق رابط تخفيض السعر:

# Posted Articles

*Last run: 2025-12-10 15:30:00*

List of articles posted to LinkedIn:

- [Announcing .NET 10](https://devblogs.microsoft.com/dotnet/announcing-dotnet-10?wt.mc_id=DT-MVP-5004972) - Posted on 2025-12-10 15:30:00 (Published: 2025-12-10)
- [Visual Studio 2026 Preview](https://devblogs.microsoft.com/visualstudio/vs-2026-preview?wt.mc_id=DT-MVP-5004972) - Posted on 2025-12-09 10:15:00 (Published: 2025-12-09)

تحميل ملف التتبع وتحليله

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

static HashSet<string> LoadPostedArticles(string filePath)
{
 var postedUrls = new HashSet<string>();

 if (!File.Exists(filePath))
 {
 return postedUrls;
 }

 var lines = File.ReadAllLines(filePath);
 foreach (var line in lines)
 {
 var match = System.Text.RegularExpressions.Regex.Match(line, @"\(([^)]+)\)");
 if (match.Success)
 {
 var url = match.Groups[1].Value;

 if (url.Contains("?wt.mc_id="))
 {
 url = url.Substring(0, url.IndexOf("?wt.mc_id="));
 }
 else if (url.Contains("?"))
 {
 url = url.Substring(0, url.IndexOf("?"));
 }

 url = url.TrimEnd('/');
 postedUrls.Add(url);
 }
 }

 return postedUrls;
}

تقوم هذه الوظيفة بإرجاع HashSet الذي يحتوي على جميع عناوين URL التي قمنا بمعالجتها بالفعل. نبدأ بالتحقق من وجود الملف - عند التشغيل لأول مرة، لن يكون موجودًا، لذلك نعيد مجموعة فارغة.

لكل سطر في الملف، نستخدم regex لاستخراج عنوان URL من تنسيق رابط تخفيض السعر. يتطابق التعبير العادي $([^)]+)$ مع أي شيء داخل الأقواس، وهو المكان الذي تخزن فيه روابط تخفيض السعر عناوين URL الخاصة بها.

ثم تأتي خطوة مهمة: تطبيع عنوان URL. يمكن أن تختلف عناوين URL لنفس المقالة في التنسيق. قد يقدم لنا موجز RSS https://devblogs.microsoft.com/dotnet/article، ولكن نسختنا المحفوظة تحتوي على معلمة تتبع ملحقة: https://devblogs.microsoft.com/dotnet/article?wt.mc_id=DT-MVP-5004972. تحتوي بعض عناوين URL على خطوط مائلة زائدة، والبعض الآخر لا تحتوي عليها.

للتعامل مع هذا الأمر، نقوم بإزالة أي معلمات استعلام (كل شيء بعد ?) وإزالة الخطوط المائلة اللاحقة. يضمن هذا التطبيع أننا نتعرف على المقالات على أنها مكررة حتى لو كانت عناوين URL الخاصة بها تختلف بهذه الطرق السطحية.

حفظ المقالات الجديدة

عندما نعالج مقالة بنجاح، نحتاج إلى إضافتها إلى ملف التتبع الخاص بنا:

static void SavePostedArticle(string filePath, string url, string title, DateTimeOffset publishDate)
{
 var markdownEntry = $"- [{title}]({url}) - Posted on {DateTime.Now:yyyy-MM-dd HH:mm:ss} (Published: {publishDate:yyyy-MM-dd})\n";

 if (!File.Exists(filePath))
 {
 File.WriteAllText(filePath, "# Posted Articles\n\n*Last run: {DateTime.Now:yyyy-MM-dd HH:mm:ss}*\n\nList of articles posted:\n\n");
 }

 File.AppendAllText(filePath, markdownEntry);
}

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

محرك تحليل الذكاء الاصطناعي

فهم النواة الدلاليةنصل الآن إلى الجزء الأكثر إثارة من تطبيقنا - تحليل الذكاء الاصطناعي. Semantic Kernel هو SDK مفتوح المصدر من Microsoft لدمج نماذج اللغات الكبيرة في التطبيقات. إنه أكثر من مجرد غلاف حول مكالمات API. فهو يوفر إطارًا لبناء تطبيقات الذكاء الاصطناعي المتطورة مع ميزات مثل المكونات الإضافية والمخططات والذاكرة.

بالنسبة لحالة الاستخدام الخاصة بنا، فإننا نستخدم إمكانات إكمال الدردشة الخاصة بـ Semantic Kernel. سنرسل مطالبة إلى Azure OpenAI، وسيقوم النموذج بتحليل مقالتنا وإنشاء استجابة. يتعامل Semantic Kernel مع كل تعقيدات مصادقة واجهة برمجة التطبيقات (API)، وتنسيق الطلب، وتحليل الاستجابة.

إعداد محلل المقالات

دعونا نلقي نظرة على كيفية إعداد فئة المحلل لدينا:

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;
using HtmlAgilityPack;

namespace VsFeedLinkedin.Services;

public class ArticleAnalyzer
{
 private readonly Kernel _kernel;
 private readonly IChatCompletionService _chatService;

 public ArticleAnalyzer(string endpoint, string apiKey, string deploymentName)
 {
 var builder = Kernel.CreateBuilder();

 builder.AddAzureOpenAIChatCompletion(
 deploymentName: deploymentName,
 endpoint: endpoint,
 apiKey: apiKey
 );

 _kernel = builder.Build();
 _chatService = _kernel.GetRequiredService<IChatCompletionService>();
 }

يستخدم Semantic Kernel نمط البناء للتكوين. نقوم بإنشاء KernelBuilder، ونضيف خدمة إكمال الدردشة Azure OpenAI الخاصة بنا مع بيانات الاعتماد اللازمة، ثم نبني النواة. من النواة المبنية، نقوم باسترداد واجهة IChatCompletionService، والتي سنستخدمها لإرسال المطالبات وتلقي الاستجابات.

يأخذ المُنشئ ثلاث معلمات: نقطة نهاية Azure OpenAI (شيء مثل https://your-resource.openai.azure.com/)، ومفتاح واجهة برمجة التطبيقات (API)، واسم النشر (مثل gpt-4o). ويتم تمريرها من متغيرات البيئة، مما يحافظ على أمان بيانات الاعتماد الخاصة بنا.

صياغة الموجه المثالي

تعد المطالبة التي نرسلها إلى الذكاء الاصطناعي أمرًا بالغ الأهمية. تنتج المطالبة المصممة جيدًا مخرجات متسقة وعالية الجودة. تؤدي المطالبة الغامضة أو سيئة التنظيم إلى نتائج غير متسقة ومتواضعة. لقد أمضيت وقتًا طويلاً في تكرار هذه المطالبة للحصول على النتائج التي أسعدني:

var prompt = $"""
 You are a professional tech content analyst and LinkedIn content creator.
 Analyze the following Microsoft DevBlogs article and create an engaging LinkedIn post.

 Article Title: {title}
 Author: {author}
 URL: {url}
 Tags: {string.Join(", ", tags)}

 Article Content:
 {cleanContent}

 Please provide:
 1. A brief summary (2-3 sentences) of the key points
 2. The main technologies or topics covered
 3. Why this is relevant for developers/tech professionals
 4. An engaging LinkedIn post (max 1300 characters) that:
 - Starts with a hook or attention-grabbing statement
 - Highlights the key value for readers
 - Includes a call to action
 - Uses appropriate emojis (but not too many)
 - Maintains a professional yet approachable tone
 - DO NOT include hashtags in the post (they will be added separately)
 - DO NOT include the URL in the post (it will be added separately)

 Format your response as follows:
 ## Summary
 [Your summary here]

 ## Key Topics
 [List of main topics/technologies]

 ## Relevance
 [Why this matters]

 ## LinkedIn Post
 [Your engaging LinkedIn post here]
 """;

اسمحوا لي أن أشرح قرارات التصميم هنا. نبدأ بإعطاء الذكاء الاصطناعي دورًا واضحًا: “أنت محلل محتوى تقني محترف ومنشئ محتوى على LinkedIn”. يؤدي هذا إلى إعداد النموذج للاستجابة بالأسلوب والصوت المناسبين.

نحن نقدم كل السياق الذي يحتاجه الذكاء الاصطناعي: عنوان المقالة، والمؤلف، وعنوان URL، والعلامات من موجز RSS، ومحتوى المقالة بالكامل. كلما زاد السياق الذي نقدمه، كلما كان التحليل أفضل.

ثم نحدد بالضبط ما نريده مرة أخرى. أطلب أربعة أشياء: الملخص، والموضوعات الرئيسية، وشرح الصلة، ومنشور LinkedIn. بالنسبة لمنشور LinkedIn على وجه التحديد، أقدم تعليمات تفصيلية حول ما يجعل المنشور جيدًا - يجب أن يكون له تأثير، وقيمة مميزة، ويتضمن عبارة تحث المستخدم على اتخاذ إجراء، ويستخدم الرموز التعبيرية بشكل مناسب، ويحافظ على نبرة احترافية.

التعليمات السلبية لها نفس القدر من الأهمية. أخبر الذكاء الاصطناعي صراحةً بعدم تضمين علامات التصنيف أو عنوان URL في المنشور. لماذا؟ لأنني أضفتها بشكل منفصل، وإذا شملها الذكاء الاصطناعي، فسيكون لدي نسخ مكررة. هذا النوع من التعليمات الصريحة يمنع الأخطاء الشائعة.

وأخيرا، أحدد تنسيق الإخراج الدقيق. من خلال السؤال عن الأقسام المميزة برؤوس ##، أجعل من السهل تحليل الاستجابة برمجيًا. الذكاء الاصطناعي جيد جدًا في اتباع تعليمات التنسيق، وهذا الاتساق يجعل كود التحليل الخاص بنا أبسط وأكثر موثوقية.

تنفيذ التحليل

إليك كيفية تجميع كل ذلك معًا:

public async Task<ArticleAnalysis> AnalyzeArticleAsync(
 string title,
 string url,
 string htmlContent,
 string author,
 List<string> tags)
{
 var cleanContent = ExtractTextFromHtml(htmlContent);

 if (cleanContent.Length > 8000)
 {
 cleanContent = cleanContent.Substring(0, 8000) + "...";
 }

 var chatHistory = new ChatHistory();
 chatHistory.AddUserMessage(prompt);

 var response = await _chatService.GetChatMessageContentAsync(chatHistory);
 var responseText = response.Content ?? "";

 return ParseAnalysisResponse(responseText, title, url, author, tags);
}
```نقوم أولاً باستخراج النص النظيف من محتوى HTML (سأشرح ذلك في القسم التالي). ثم نقوم باقتطاع المحتوى إذا كان طويلاً جدًا. نماذج اللغات الكبيرة لها حدود رمزية، وقد تتجاوزها المقالات الطويلة جدًا. من خلال الحد الأقصى لعدد الأحرف وهو 8000 حرف، فإننا نضمن البقاء ضمن الحدود مع الاستمرار في توفير سياق جوهري.

نقوم بإنشاء كائن ChatHistory ونضيف مطالبتنا كرسالة مستخدم. هذا هو مفهوم Semantic Kernel للتفاعلات القائمة على الدردشة. نرسل هذا إلى خدمة إكمال الدردشة ونحصل على الرد. وأخيرا، نقوم بتحليل الاستجابة لاستخراج الأقسام الفردية.

### تحليل استجابة الذكاء الاصطناعي

يقوم الذكاء الاصطناعي بإرجاع استجابته كنص منسق بالبنية المطلوبة. نحن بحاجة إلى تحليل هذا في الحقول الفردية:

```csharp
private static ArticleAnalysis ParseAnalysisResponse(
 string response,
 string title,
 string url,
 string author,
 List<string> tags)
{
 var analysis = new ArticleAnalysis
 {
 Title = title,
 Url = url,
 Author = author,
 Tags = tags,
 RawAnalysis = response
 };

 var sections = response.Split("##", StringSplitOptions.RemoveEmptyEntries);

 foreach (var section in sections)
 {
 var lines = section.Trim().Split('\n', 2);
 if (lines.Length < 2) continue;

 var sectionTitle = lines[0].Trim().ToLower();
 var sectionContent = lines[1].Trim();

 switch (sectionTitle)
 {
 case "summary":
 analysis.Summary = sectionContent;
 break;
 case "key topics":
 analysis.KeyTopics = sectionContent;
 break;
 case "relevance":
 analysis.Relevance = sectionContent;
 break;
 case "linkedin post":
 analysis.LinkedInPost = sectionContent;
 break;
 }
 }

 return analysis;
}

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

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

استخراج المحتوى من HTML

لماذا نحتاج إلى تنظيف HTML

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

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

نحن بحاجة إلى استخراج محتوى المقالة فقط – الجزء الذي سيقرأه القارئ البشري بالفعل.

استخدام HtmlAgilityPack

HtmlAgilityPack عبارة عن مكتبة تحليل HTML قوية لـ .NET. على عكس XML، غالبًا ما يكون HTML مشوهًا - فقد لا يتم إغلاق العلامات بشكل صحيح، وقد لا يتم اقتباس السمات بشكل صحيح. يتعامل HtmlAgilityPack مع كل هذا بأمان، مما يمنحنا بنية تشبه DOM يمكننا الاستعلام عنها ومعالجتها.

ها هي وظيفة الاستخراج لدينا:

private static string ExtractTextFromHtml(string html)
{
 if (string.IsNullOrWhiteSpace(html))
 return string.Empty;

 var doc = new HtmlDocument();
 doc.LoadHtml(html);

 var nodesToRemove = doc.DocumentNode.SelectNodes("//script|//style|//nav|//footer|//header");
 if (nodesToRemove != null)
 {
 foreach (var node in nodesToRemove)
 {
 node.Remove();
 }
 }

 var text = doc.DocumentNode.InnerText;

 text = System.Text.RegularExpressions.Regex.Replace(text, @"\s+", " ");
 return text.Trim();
}

نقوم بتحميل HTML إلى مستند HtmlDocument، والذي يقوم بتوزيعه إلى بنية شجرة. ثم نستخدم XPath لتحديد جميع العقد التي نريد إزالتها. يحدد تعبير XPath //script|//style|//nav|//footer|//header جميع عناصر البرنامج النصي (لا نحتاج إلى كود JavaScript)، وعناصر النمط (لا نحتاج إلى CSS)، وعناصر التنقل (قوائم التنقل)، وعناصر التذييل، وعناصر الرأس.

بعد إزالة هذه العقد، نحصل على خاصية InnerText، التي تستخرج كل محتوى النص أثناء تجريد علامات HTML. وهذا يعطينا النص الواضح للمقالة.وأخيرا، نقوم بتنظيف المساحة البيضاء. غالبًا ما يحتوي HTML على الكثير من المسافات البيضاء الإضافية لأغراض التنسيق - مسافات متعددة وعلامات تبويب وأسطر جديدة. نستخدم التعبير العادي لاستبدال أي تسلسل من أحرف المسافات البيضاء بمسافة واحدة، ثم نقوم بقص النتيجة.

جلب المقالة كاملة

يقدم لنا موجز RSS ملخصات فقط، وليس محتوى المقالة بالكامل. للحصول على النص الكامل، نحتاج إلى جلب صفحة الويب الخاصة بالمقالة:

public static async Task<string> FetchArticleContentAsync(string url)
{
 using var httpClient = new HttpClient();
 httpClient.DefaultRequestHeaders.Add("User-Agent", "VsFeedLinkedin/1.0");

 try
 {
 return await httpClient.GetStringAsync(url);
 }
 catch (Exception ex)
 {
 Console.WriteLine($"⚠️ Failed to fetch article content: {ex.Message}");
 return string.Empty;
 }
}

هذا أمر واضح ومباشر – نقوم بإرسال طلب HTTP GET إلى عنوان URL للمقالة ونعيد استجابة HTML. نقوم بلفها في محاولة التقاط لأن طلبات الشبكة يمكن أن تفشل، ونفضل إرجاع سلسلة فارغة بدلاً من تعطل التطبيق بأكمله.

إنشاء وثائق دائمة

لماذا يتم إنشاء ملفات Markdown

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

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

ثانياً، توفر الشفافية. يمكنك أن ترى بالضبط ما تم إنشاؤه بواسطة الذكاء الاصطناعي لكل مقالة، بما في ذلك التحليل الكامل ومنشور LinkedIn.

ثالثًا، إنه مفيد لتصحيح الأخطاء. إذا حدث خطأ ما في إحدى المشاركات، فيمكنك إلقاء نظرة على ملف تخفيض السعر لفهم ما حدث.

فئة مولد تخفيض السعر

public class MarkdownGenerator
{
 private readonly string _outputDirectory;

 public MarkdownGenerator(string outputDirectory)
 {
 _outputDirectory = outputDirectory;

 if (!Directory.Exists(_outputDirectory))
 {
 Directory.CreateDirectory(_outputDirectory);
 }
 }

 public string GenerateMarkdownFile(ArticleAnalysis analysis)
 {
 var sb = new StringBuilder();

 var safeTitle = GenerateSafeFileName(analysis.Title);
 var fileName = $"{analysis.AnalyzedAt:yyyy-MM-dd}_{safeTitle}.md";
 var filePath = Path.Combine(_outputDirectory, fileName);

 sb.AppendLine($"# {analysis.Title}");
 sb.AppendLine();
 sb.AppendLine("## Article Information");
 sb.AppendLine();
 sb.AppendLine($"- **Author:** {analysis.Author}");
 sb.AppendLine($"- **URL:** [{analysis.Url}]({analysis.Url})");
 sb.AppendLine($"- **Published:** {analysis.PublishDate:yyyy-MM-dd}");
 sb.AppendLine($"- **Analyzed:** {analysis.AnalyzedAt:yyyy-MM-dd HH:mm:ss}");
 sb.AppendLine($"- **Tags:** {string.Join(", ", analysis.Tags)}");
 sb.AppendLine();
 sb.AppendLine("");
 sb.AppendLine();
 sb.AppendLine("## AI Analysis");
 sb.AppendLine();
 sb.AppendLine("### Summary");
 sb.AppendLine();
 sb.AppendLine(analysis.Summary);
 sb.AppendLine();
 sb.AppendLine("### Key Topics");
 sb.AppendLine();
 sb.AppendLine(analysis.KeyTopics);
 sb.AppendLine();
 sb.AppendLine("### Relevance for Developers");
 sb.AppendLine();
 sb.AppendLine(analysis.Relevance);
 sb.AppendLine();
 sb.AppendLine("");
 sb.AppendLine();
 sb.AppendLine("## Generated LinkedIn Post");
 sb.AppendLine();
 sb.AppendLine("```");
 sb.AppendLine(ana Analysis.LinkedInPost);
 sb.AppendLine("```");
 sb.AppendLine();
 sb.AppendLine("");
 sb.AppendLine();
 sb.AppendLine("*This analysis was generated using AI (Semantic Kernel with Azure OpenAI)*");

 File.WriteAllText(filePath, sb.ToString());
 return filePath;
 }

يأخذ المنشئ مسار دليل الإخراج ويقوم بإنشائه إذا لم يكن موجودًا. تأخذ طريقة GenerateMarkdownFile كائن ArticleAnalogy وتنتج مستند تخفيض السعر منسق بشكل جيد.

يتضمن اسم الملف التاريخ ونسخة منقحة من العنوان. وهذا يجعل من السهل فرز الملفات بترتيب زمني والتعرف عليها في لمحة.

التعامل مع أسماء الملفات غير الآمنة

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

private static string GenerateSafeFileName(string title)
{
 var invalidChars = Path.GetInvalidFileNameChars();
 var safeTitle = new string(title
 .Where(c => !invalidChars.Contains(c))
 .ToArray());

 safeTitle = safeTitle.Replace(" ", "-").Replace("--", "-");

 if (safeTitle.Length > 50)
 {
 safeTitle = safeTitle.Substring(0, 50);
 }

 return safeTitle.TrimEnd('-').ToLowerInvariant();
}

نستخدم Path.GetInvalidFileNameChars() للحصول على قائمة بالأحرف التي لا يمكن أن تظهر في أسماء الملفات على نظام التشغيل الحالي. نقوم بتصفية هذه العناصر، واستبدال المسافات بواصلات لتسهيل القراءة، وتحديد الطول بـ 50 حرفًا، وتحويلها إلى أحرف صغيرة لتحقيق الاتساق.

إعداد إشعارات تيليجرام

لماذا اخترت تيليجرام

بالنسبة لعنصر الإشعارات، فكرت في عدة خيارات – البريد الإلكتروني، والرسائل النصية القصيرة، وSlack، وDiscord، وTelegram. لقد اخترت Telegram في النهاية لعدة أسباب.

واجهة برمجة التطبيقات (API) مجانية تمامًا ولا توجد حدود للمعدلات للاستخدام المعقول. تفرض العديد من خدمات الإشعارات حدودًا على عدد الرسائل التي يمكنك إرسالها مجانًا، لكن Telegram لا يقيد رسائل الروبوت للمستخدمين الفرديين.

واجهة برمجة تطبيقات الروبوت بسيطة بشكل لا يصدق. إنها مجرد طلبات HTTP مع حمولات JSON. لا توجد تدفقات مصادقة معقدة، ولا يلزم وجود خطافات ويب للوظائف الأساسية.يعمل Telegram في كل مكان – على هاتفي، وعلى سطح المكتب، وفي متصفح الويب. يمكنني تلقي الإخطارات أينما كنت والرد عليها على الفور.

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

إنشاء بوت Telegram الخاص بك

يعد إعداد روبوت Telegram أمرًا سهلاً بشكل مدهش. افتح Telegram وابحث عن @BotFather – هذا هو روبوت Telegram الرسمي لإنشاء الروبوتات وإدارتها. ابدأ محادثة مع BotFather وأرسل الأمر /newbot. سيطلب منك BotFather اسمًا لروبوتك (هذا هو اسم العرض) واسم مستخدم (يجب أن يكون فريدًا وينتهي بـ “bot”). بمجرد تقديم هذه العناصر، سيقوم BotFather بإنشاء الروبوت الخاص بك ويمنحك رمزًا مميزًا لواجهة برمجة التطبيقات. هذا الرمز المميز يشبه كلمة المرور - احتفظ به سرًا ولا تضعه في المستودعات العامة.

للعثور على معرف الدردشة الخاص بك حتى يعرف الروبوت مكان إرسال الرسائل، ابدأ محادثة مع الروبوت الجديد الخاص بك عن طريق البحث عنه والضغط على ابدأ. ثم قم بالوصول إلى عنوان URL https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates في متصفحك أو باستخدام حليقة. ابحث عن كائن chat في الرد - الحقل id هو معرف الدردشة الخاص بك.

إرسال الرسائل عبر API

هذه هي وظيفتنا لإرسال رسائل Telegram:

static async Task SendToTelegramAsync(string botToken, string chatId, string message)
{
 using var httpClient = new HttpClient();

 var telegramApiUrl = $"https://api.telegram.org/bot{botToken}/sendMessage";

 var payload = new
 {
 chat_id = chatId,
 text = message,
 parse_mode = "HTML"
 };

 var jsonContent = JsonSerializer.Serialize(payload);
 var content = new StringContent(jsonContent, Encoding.UTF8, "application/json");

 var response = await httpClient.PostAsync(telegramApiUrl, content);

 if (!response.IsSuccessStatusCode)
 {
 var errorContent = await response.Content.ReadAsStringAsync();
 throw new Exception($"Telegram API error: {response.StatusCode} - {errorContent}");
 }
}

تعتمد Telegram Bot API على REST. نقوم بإجراء طلب POST إلى نقطة نهاية sendMessage باستخدام نص JSON يحتوي على معرف الدردشة (مكان الإرسال)، ونص الرسالة (ما يجب إرساله)، ووضع التحليل اختياريًا (للتنسيق).

يتيح لنا تعيين parse_mode على “HTML” استخدام علامات HTML الأساسية في رسائلنا - أشياء مثل <b>bold</b> و<i>italic</i>. وهذا يمكن أن يجعل الإشعارات أكثر قابلية للقراءة، على الرغم من أننا نرسل نصًا عاديًا في حالة الاستخدام الحالية لدينا.

إذا فشل الطلب، فإننا نطرح استثناءً يتضمن تفاصيل حول الخطأ الذي حدث. يساعد هذا في تصحيح الأخطاء إذا كان هناك شيء لا يعمل.

تكوين التطبيق

متغيرات البيئة

يحتاج تطبيقنا إلى عدة أجزاء من المعلومات الحساسة - مفاتيح واجهة برمجة التطبيقات، ورموز الروبوت، وعناوين URL لنقطة النهاية. لا ينبغي لنا أبدًا أن نبرمجها أو نلزمها بالتحكم في الإصدار. وبدلاً من ذلك، نستخدم متغيرات البيئة، والتي يمكن تعيينها بشكل آمن في كل بيئة يتم فيها تشغيل التطبيق.

بالنسبة إلى Telegram، نحتاج إلى TELEGRAM_BOT_TOKEN (الرمز المميز الذي قدمه لك BotFather) وTELEGRAM_CHAT_ID (معرف الدردشة الخاص بك حيث يجب إرسال الرسائل).

بالنسبة إلى Azure OpenAI، نحتاج إلى AZURE_OPENAI_ENDPOINT (عنوان URL لموردك)، وAZURE_OPENAI_API_KEY (مفتاح API الخاص بك)، وAZURE_OPENAI_DEPLOYMENT (اسم النموذج الذي تم نشره، مثل “gpt-4o”).

تحميل التكوين في التعليمات البرمجية

إليك كيفية تحميل هذه القيم عند بدء تشغيل التطبيق:

var telegramBotToken = Environment.GetEnvironmentVariable("TELEGRAM_BOT_TOKEN");
var telegramChatId = Environment.GetEnvironmentVariable("TELEGRAM_CHAT_ID");

var azureOpenAiEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
var azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY");
var azureOpenAiDeployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT") ?? "gpt-4o";

var aiAnalysisEnabled = !string.IsNullOrWhiteSpace(azureOpenAiEndpoint) &&
 !string.IsNullOrWhiteSpace(azureOpenAiKey);

نحن نستخدم Environment.GetEnvironmentVariable لقراءة كل قيمة. بالنسبة لاسم النشر، نقدم الإعداد الافتراضي “gpt-4o” إذا لم يتم تعيين أي قيمة.

نتحقق بعد ذلك مما إذا كان ينبغي تمكين تحليل الذكاء الاصطناعي من خلال التحقق من أن لدينا نقطة نهاية ومفتاح واجهة برمجة التطبيقات. يسمح هذا للتطبيق بالعمل في وضع منخفض إذا لم يتم تكوين Azure OpenAI - فسيستمر في جلب الخلاصات وتتبع المقالات، فقط بدون تحليل الذكاء الاصطناعي.### تدهور رشيق

مفهوم التدهور الرشيق هذا مهم. لا نريد أن يتعطل التطبيق لمجرد عدم تكوين ميزة اختيارية واحدة:

ArticleAnalyzer? articleAnalyzer = null;
MarkdownGenerator? markdownGenerator = null;

if (aiAnalysisEnabled)
{
 Console.WriteLine("🤖 AI Analysis enabled - Using Azure OpenAI with Semantic Kernel");
 articleAnalyzer = new ArticleAnalyzer(azureOpenAiEndpoint!, azureOpenAiKey!, azureOpenAiDeployment);
 markdownGenerator = new MarkdownGenerator(articlesOutputDir);
}
else
{
 Console.WriteLine("ℹ️ AI Analysis disabled - Set AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_API_KEY to enable");
}

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

الأتمتة باستخدام إجراءات GitHub

لماذا إجراءات جيثب

القوة الحقيقية لهذا الحل تأتي من الأتمتة. لا نريد تشغيل التطبيق يدويًا كل بضع ساعات، بل نريد تشغيله تلقائيًا في الخلفية.

إجراءات GitHub مثالية لهذا الغرض. إنه مدمج في GitHub، لذا لا توجد خدمة إضافية لإعدادها. إنه مجاني للمستودعات العامة ويتضمن دقائق مجانية سخية للمستودعات الخاصة. ويمكن تشغيله وفقًا لجدول زمني، مما يؤدي إلى تشغيل تطبيقنا على فترات منتظمة. يحتوي على إدارة أسرار مدمجة لتخزين مفاتيح API الخاصة بنا بشكل آمن. ويمكنه إجراء التغييرات مرة أخرى على المستودع، مما يحافظ على تحديث ملف التتبع الخاص بنا.

ملف سير العمل

قم بإنشاء ملف على .github/workflows/fetch-and-notify.yml بالمحتوى التالي:

name: Fetch DevBlogs and Notify

on:
 schedule:
 - cron: '0 */6 * * *'
 workflow_dispatch:

jobs:
 fetch-and-notify:
 runs-on: ubuntu-latest

 steps:
 - name: Checkout repository
 uses: actions/checkout@v4

 - name: Setup .NET
 uses: actions/setup-dotnet@v4
 with:
 dotnet-version: '9.0.x'

 - name: Restore dependencies
 run: dotnet restore src/VsFeedLinkedin.csproj

 - name: Build
 run: dotnet build src/VsFeedLinkedin.csproj --no-restore

 - name: Run application
 env:
 TELEGRAM_BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
 TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
 AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
 AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}
 AZURE_OPENAI_DEPLOYMENT: ${{ secrets.AZURE_OPENAI_DEPLOYMENT }}
 run: dotnet run --project src/VsFeedLinkedin.csproj

 - name: Commit and push changes
 run: |
 git config user.name "GitHub Actions Bot"
 git config user.email "actions@github.com"

 if [[ -n $(git status --porcelain posted-articles.md generated-posts/) ]]; then
 TIMESTAMP=$(date +%Y%m%d_%H%M%S)
 git add posted-articles.md generated-posts/
 git commit -m "chore($TIMESTAMP): processed new articles"
 git push
 else
 echo "No changes to commit"
 fi

اسمحوا لي أن أشرح كل جزء. يحدد القسم “وقت تشغيل سير العمل”. يستخدم مشغل الجدول الزمني صيغة cron - 0 */6 * * * تعني “في الدقيقة 0 من كل 6 ساعات.” لذلك يتم تشغيل سير العمل في منتصف الليل، والساعة 6 صباحًا، والظهيرة، والساعة 6 مساءً بالتوقيت العالمي المنسق. يسمح مشغل Workflow_dispatch بالتشغيل اليدوي من واجهة مستخدم GitHub، وهو أمر مفيد للاختبار.

تعمل المهمة على نظام التشغيل ubuntu-latest، وهو جهاز Linux افتراضي. نحن نتحقق من مستودعنا، ونقوم بإعداد .NET 9، ونستعيد حزم NuGet، ونبني المشروع.

خطوة تشغيل التطبيق هي المكان الذي يحدث فيه السحر. نقوم بتمرير أسرارنا كمتغيرات بيئة باستخدام بناء الجملة ${{ Secrets.SECRET_NAME }}. يتم تخزين هذه الأسرار بشكل آمن في GitHub ولا يتم كشفها أبدًا في السجلات.

وأخيرًا، نلتزم بأي تغييرات مرة أخرى في المستودع. نقوم بتكوين Git بهوية الروبوت، والتحقق مما إذا كانت هناك أي تغييرات على ملف التتبع الخاص بنا أو دليل المنشورات التي تم إنشاؤها، وإذا كان الأمر كذلك، فقم بإنشاء التزام ودفعه.

إعداد الأسرار

لإضافة أسرار إلى مستودع GitHub الخاص بك، انتقل إلى إعدادات المستودع الخاص بك، ثم الأسرار والمتغيرات، ثم الإجراءات. انقر فوق “سر المستودع الجديد” وأضف كل متغير من متغيرات البيئة الخاصة بك. يجب أن تتطابق الأسماء تمامًا مع ما نشير إليه في ملف سير العمل.

الختام

ما قمنا ببنائه

بالنظر إلى كل ما قمنا بتغطيته، قمنا ببناء مجمع موجز RSS شامل ومدعوم بالذكاء الاصطناعي والذي يعمل على أتمتة ما كان في السابق عملية يدوية شاقة. يراقب التطبيق سبعة خلاصات لـ Microsoft DevBlogs تلقائيًا، ويلتقط كل مقالة جديدة بمجرد نشرها. فهو يتعامل مع تعقيدات إلغاء البيانات المكررة، ويتعرف على وقت ظهور المقالة نفسها في خلاصات متعددة.يقوم تحليل الذكاء الاصطناعي المدعوم من Semantic Kernel وAzure OpenAI بقراءة محتوى المقالة وفهمه، وإنشاء ملخصات، وتحديد الموضوعات الرئيسية، وشرح مدى صلتها بالموضوع - كل ذلك تلقائيًا. والأهم من ذلك، أنه ينشئ منشورات جذابة على LinkedIn يمكنني مشاركتها مع الحد الأدنى من التحرير.

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

ولأنه يعمل على GitHub Actions وفقًا لجدول زمني، فلا يتعين علي أن أتذكر القيام بأي شيء. يعمل النظام في الخلفية، ولا أشارك إلا عندما يكون هناك شيء يستحق المشاركة.

التقنيات التي جعلت ذلك ممكنًا

جمع هذا المشروع بين العديد من التقنيات التي لعبت كل منها دورًا حاسمًا. قدم .NET 9 أساسًا متينًا بميزات اللغة الحديثة والأداء الممتاز. لقد جعل Semantic Kernel تكامل الذكاء الاصطناعي أمرًا مباشرًا، حيث تعامل مع كل تعقيدات استدعاءات واجهة برمجة التطبيقات وإدارة الاستجابة. لقد وفر Azure OpenAI الذكاء – القدرة على فهم المحتوى التقني وتحليله فعليًا. حل HtmlAgilityPack المشكلة الفوضوية المتمثلة في استخراج النص النظيف من صفحات الويب. System.ServiceModel.Syndicator جعل تحليل RSS أمرًا سهلاً. أعطتنا واجهة برمجة تطبيقات Telegram Bot إشعارات مجانية وموثوقة. وربطت إجراءات GitHub كل ذلك معًا من خلال التنفيذ الآلي المجدول.

التفكير في التكاليف

سؤال واحد قد يكون لديك: ما هي تكلفة تشغيل هذا؟ الجواب هو: ليس كثيرا على الاطلاق.

Telegram مجاني تمامًا – لا توجد رسوم لإرسال الرسائل من خلال برنامج الروبوت الخاص بك.

إجراءات GitHub مجانية للمستودعات العامة. بالنسبة للمستودعات الخاصة، تحصل على 2000 دقيقة شهريًا على المستوى المجاني، وهو أكثر من كافٍ لحالة الاستخدام الخاصة بنا.

Azure OpenAI هو المكون الوحيد المدفوع، والتكاليف ضئيلة. باستخدام GPT-4o، يتكلف تحليل مقال مدونة نموذجي ما بين سنت وثلاثة سنتات. حتى لو كنت تقوم بمعالجة عشرات المقالات شهريًا، فإنك تتوقع أقل من دولار واحد من تكاليف الذكاء الاصطناعي.

أين يمكنك أن تأخذ هذا بعد ذلك

على الرغم من أن هذا الحل يناسب احتياجاتي بشكل رائع، إلا أن هناك العديد من الطرق التي يمكنك من خلالها توسيع نطاقه. يمكنك إضافة دعم لمنصات اجتماعية متعددة - ربما النشر على Twitter/X أو Mastodon أو Bluesky بالإضافة إلى LinkedIn. يمكنك تنفيذ تحليل المشاعر لتتبع أسلوب المقالات بمرور الوقت وتحديد الاتجاهات. يمكنك السماح بنماذج مطالبات مختلفة لخلاصات مختلفة، وإنشاء أنماط مختلفة من المنشورات لموضوعات مختلفة. يمكنك إنشاء لوحة تحكم ويب لمراجعة المنشورات وإدارتها بدلاً من استخدام Telegram. يمكنك تتبع مقاييس التفاعل للمحتوى المنشور لمعرفة الموضوعات التي تلقى صدى أكبر لدى جمهورك.

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

من خلال الجمع بين قوة .NET وSemantic Kernel وAzure OpenAI، قمنا بإنشاء أداة توفر ساعات من العمل اليدوي كل أسبوع مع الحفاظ على الجودة والاتساق. إنه نوع من الأتمتة العملية التي تُحدث فرقًا حقيقيًا في الحياة اليومية.

إذا قمت ببناء شيء مماثل أو لديك أفكار للتحسينات، فأنا أحب أن أسمع عنها. لا تتردد في التواصل على LinkedIn!

برمجة سعيدة، وعيد ميلاد سعيد! 🎄

بناء أنظمة الذكاء الاصطناعي متعددة الوكلاء باستخدام Microsoft Agent Framework

Mon, 01 Dec 2025 00:00:00 +0000

مقدمة

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

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

يمنح Microsoft Agent Framework، وهو جزء من النظام البيئي Semantic Kernel الأوسع، لمطوري .NET مجموعة أدوات من الدرجة الأولى لبناء هذه الأنواع من الأنظمة بالضبط. في هذا المنشور، سننتقل من الصفر إلى مسار عمل متعدد الوكلاء يعمل بشكل كامل، ويغطي المفاهيم الأساسية وأنماط التنسيق والتعليمات البرمجية العملية التي تحتاجها للبدء.

ما هو إطار عمل وكيل Microsoft؟

يعد Agent Framework بمثابة إجابة Microsoft لبناء وتنسيق ونشر وكلاء الذكاء الاصطناعي والأنظمة متعددة الوكلاء في .NET. إنه يجلس جنبًا إلى جنب مع Semantic Kernel ويتكامل معه بشكل عميق، وهو عبارة عن SDK مفتوح المصدر من Microsoft لتنسيق الذكاء الاصطناعي منذ عام 2023.

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

يدعم إطار العمل العديد من موفري النماذج بما في ذلك Azure OpenAI وOpenAI والنماذج المستضافة على Azure AI Foundry. إنه لا يعتمد على النماذج في التصميم ولكنه متكامل بعمق مع نظام Azure البيئي، مما يجعله مقنعًا بشكل خاص لسيناريوهات المؤسسات.

تشمل القدرات الرئيسية ما يلي:

أنواع الوكلاء المتعددة: ChatCompletionAgent، وOpenAIAssistantAgent، وAzureAIAgent للواجهات الخلفية المختلفة
أنماط التنسيق: سير عمل الدردشة التسلسلية والمتزامنة والتسليم والجماعية
نظام المكونات الإضافية: توسيع الوكلاء باستخدام وظائف C# الأصلية، ومواصفات OpenAPI، وأدوات بروتوكول سياق النموذج (MCP)
إدارة المحادثة: الترابط المضمن وإدارة السجل واستراتيجيات الإنهاء
قابلية الملاحظة: التكامل مع OpenTelemetry لتتبع تفاعلات الوكيل

المفاهيم الأساسية

قبل أن نكتب أي كود، دعونا نحدد المفردات. يدور إطار عمل الوكيل حول بعض التجريدات الأساسية.

الوكلاء

الوكيل هو كيان مدعوم بنموذج الذكاء الاصطناعي، ويتم تكوينه بتعليمات محددة (موجه النظام)، واسم، واختياريًا مجموعة من المكونات الإضافية أو الأدوات. كل وكيل هو متخصص - أنت تحدد ما يعرفه، وما يمكنه فعله، وكيف يجب أن يتصرف.

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

ChatCompletionAgent agent = new()
{
 Name = "Reviewer",
 Instructions = "You are a senior code reviewer. Analyze the provided code for bugs, security issues, and style violations. Be concise and actionable.",
 Kernel = kernel
};

OpenAIAssistantAgent

يستفيد نوع الوكيل هذا من واجهة برمجة التطبيقات OpenAI Assistants API، التي توفر حالة المحادثة من جانب الخادم، ومعالجة الملفات، وتفسير التعليمات البرمجية. إنها ثقيلة الوزن ولكنها تمنحك سلاسل رسائل مستمرة وأدوات مدمجة مثل مترجم التعليمات البرمجية والبحث عن الملفات.

OpenAIAssistantAgent agent = await OpenAIAssistantAgent.CreateAsync(
 clientProvider: clientProvider,
 definition: new OpenAIAssistantDefinition("gpt-4o")
 {
 Name = "DataAnalyst",
 Instructions = "You analyze datasets and produce statistical summaries."
 }
);

وكيلGroupChat

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

أنماط التنسيق

يدعم إطار العمل أربعة أنماط تزامن أساسية، كل منها يناسب مشاكل مختلفة.

متسلسل

ينفذ الوكلاء واحدًا تلو الآخر بترتيب محدد. يتم تغذية مخرجات الوكيل A إلى الوكيل B، الذي يتم تغذية مخرجاته إلى الوكيل C. وهذا مثالي لخطوط الأنابيب: مسودة → مراجعة → تحرير → نشر.

// Conceptual flow
var draft = await writerAgent.InvokeAsync("Write a blog post about .NET 9");
var reviewed = await reviewerAgent.InvokeAsync($"Review this: {draft}");
var edited = await editorAgent.InvokeAsync($"Edit based on feedback: {reviewed}");

متزامنة

يعمل العديد من الوكلاء على نفس المدخلات في وقت واحد. تقوم بتوزيع العمل ومن ثم تجميع النتائج. يعد هذا أمرًا رائعًا للحصول على وجهات نظر متنوعة - مثل جعل ثلاثة مراجعين ينظرون إلى طلب السحب نفسه.

التسليم

يقرر الوكيل نقل التحكم إلى وكيل آخر استنادًا إلى سياق المحادثة. يحاكي هذا كيفية عمل فريق خدمة العملاء: يتعامل وكيل الخط الأمامي مع الاستفسارات الأساسية ويصعدها إلى المتخصصين عند الحاجة.

دردشة جماعية

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

بناء وكيلك الأول

دعونا نصبح عمليين. فيما يلي كيفية إنشاء وكيلك الأول خطوة بخطوة.

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

سوف تحتاج إلى:

.NET 9 SDK
مورد Azure OpenAI بنموذج منشور (على سبيل المثال، gpt-4o)
Visual Studio أو VS Code

إعداد المشروع

قم بإنشاء تطبيق وحدة تحكم جديد وقم بتثبيت الحزم المطلوبة:

dotnet new console -n AgentDemo
cd AgentDemo
dotnet add package Microsoft.SemanticKernel --prerelease
dotnet add package Microsoft.SemanticKernel.Agents.Core --prerelease
dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity

إنشاء وكيل بسيط

أولاً، قم بإعداد النواة باستخدام تكوين Azure OpenAI الخاص بك:

using Azure.Identity;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.ChatCompletion;

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 credentials: new DefaultAzureCredential()
);

Kernel kernel = builder.Build();

الآن قم بإنشاء وكيل واستدعائه:

ChatCompletionAgent agent = new()
{
 Name = "TechWriter",
 Instructions = """
 You are a technical writer specializing in software documentation.
 Write clear, concise content aimed at experienced developers.
 Use code examples when appropriate.
 Always structure your output with headings and bullet points.
 """,
 Kernel = kernel
};

ChatHistory history = new();
history.AddUserMessage("Explain dependency injection in .NET in 200 words.");

await foreach (ChatMessageContent response in agent.InvokeAsync(history))
{
 Console.WriteLine(response.Content);
}

هذا كل شيء. لديك وكيل العمل. لكن القوة الحقيقية تأتي عندما يعمل الوكلاء معًا.

تنسيق متعدد الوكلاء باستخدام AgentGroupChat

دعونا نبني شيئًا أكثر إثارة للاهتمام — دردشة جماعية يتعاون فيها العديد من الوكلاء. يدير الفصل AgentGroupChat تدفق المحادثة، بما في ذلك من يتحدث بعد ذلك ومتى يتوقف.

تعريف الوكلاء

سنقوم بإنشاء ثلاثة وكلاء: كاتب، ومراجع، ومحرر.

ChatCompletionAgent writer = new()
{
 Name = "Writer",
 Instructions = """
 You are a content writer. When given a topic, produce a well-structured
 draft. Focus on clarity and technical accuracy.
 When you receive feedback from the Reviewer, incorporate it into a
 revised draft.
 """,
 Kernel = kernel
};

ChatCompletionAgent reviewer = new()
{
 Name = "Reviewer",
 Instructions = """
 You are a content reviewer. Analyze drafts for technical accuracy,
 clarity, and completeness. Provide specific, actionable feedback.
 Do NOT rewrite the content — only provide feedback.
 When the content meets your standards, respond with: APPROVED
 """,
 Kernel = kernel
};

ChatCompletionAgent editor = new()
{
 Name = "Editor",
 Instructions = """
 You are an editor. Once content is approved by the Reviewer,
 polish it for grammar, tone, and formatting.
 Output only the final polished version.
 When you have produced the final version, respond with: COMPLETE
 """,
 Kernel = kernel
};

إعداد الدردشة الجماعية

يحتاج AgentGroupChat إلى تكوينين رئيسيين: استراتيجية الاختيار (من يتحدث بعد ذلك) و استراتيجية الإنهاء (متى يتوقف).

AgentGroupChat chat = new(writer, reviewer, editor)
{
 ExecutionSettings = new()
 {
 SelectionStrategy = new SequentialSelectionStrategy(),
 TerminationStrategy = new ApprovalTerminationStrategy()
 {
 Agents = [editor],
 MaximumIterations = 12
 }
 }
};

استراتيجية الإنهاء المخصصةتحدد استراتيجية الإنهاء متى تنتهي المحادثة. إليك كلمة مخصصة تبحث عن الكلمة الأساسية “مكتملة”:

class ApprovalTerminationStrategy : TerminationStrategy
{
 protected override Task<bool> ShouldAgentTerminateAsync(
 Agent agent,
 IReadOnlyList<ChatMessageContent> history,
 CancellationToken cancellationToken = default)
 {
 bool isComplete = history
 .Last()
 .Content?
 .Contains("COMPLETE", StringComparison.OrdinalIgnoreCase) ?? false;

 return Task.FromResult(isComplete);
 }
}

تشغيل المحادثة

ابدأ المحادثة برسالة مستخدم واسمح للوكلاء بالتعاون:

chat.AddChatMessage(
 new ChatMessageContent(AuthorRole.User,
 "Write a 300-word technical overview of gRPC vs REST for microservices.")
);

await foreach (ChatMessageContent message in chat.InvokeAsync())
{
 Console.WriteLine($"[{message.AuthorName}]: {message.Content}");
 Console.WriteLine("---");
}

سيبدو التدفق كما يلي:

الكاتب ينتج مسودة
المراجع يقدم الملاحظات
الكاتب يراجع بناءً على التعليقات
المراجع يقول “تمت الموافقة عليه”
المحرر يصقل ويقول “مكتمل”
تنتهي المحادثة

يستمر هذا ذهابًا وإيابًا تلقائيًا حتى يتم استيفاء شرط الإنهاء أو الوصول إلى MaximumIterations.

الإضافات والأدوات

يصبح الوكلاء أقوياء حقًا عندما يمكنهم التفاعل مع الأنظمة الخارجية. يدعم Agent Framework ثلاث آليات تمديد رئيسية.

الوظائف الأصلية (مكونات Kernel الإضافية)

يمكنك منح الوكلاء إمكانية الوصول إلى أساليب C# كأدوات. سوف يقوم الوكيل باستدعاء هذه الوظائف عندما يحدد أن هناك حاجة إليها:

public class ContentToolsPlugin
{
 [KernelFunction("word_count")]
 [Description("Counts the number of words in the provided text.")]
 public int WordCount([Description("The text to count words in")] string text)
 {
 return text.Split(' ', StringSplitOptions.RemoveEmptyEntries).Length;
 }

 [KernelFunction("check_readability")]
 [Description("Calculates a readability score for the given text.")]
 public string CheckReadability([Description("The text to analyze")] string text)
 {
 var words = text.Split(' ', StringSplitOptions.RemoveEmptyEntries).Length;
 var sentences = text.Split(['.', '!', '?'], StringSplitOptions.RemoveEmptyEntries).Length;

 if (sentences == 0) return "Unable to calculate — no sentences found.";

 double avgWordsPerSentence = (double)words / sentences;

 return avgWordsPerSentence switch
 {
 < 15 => $"Easy to read (avg {avgWordsPerSentence:F1} words/sentence)",
 < 25 => $"Moderate difficulty (avg {avgWordsPerSentence:F1} words/sentence)",
 _ => $"Difficult to read (avg {avgWordsPerSentence:F1} words/sentence). Consider shorter sentences."
 };
 }
}

قم بتسجيل الإضافة على النواة قبل إنشاء الوكيل:

kernel.Plugins.AddFromType<ContentToolsPlugin>();

ChatCompletionAgent analyst = new()
{
 Name = "ContentAnalyst",
 Instructions = "Analyze content using available tools. Report word count and readability.",
 Kernel = kernel,
 Arguments = new KernelArguments(
 new PromptExecutionSettings
 {
 FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
 })
};

بروتوكول السياق النموذجي (MCP)

يعد MCP معيارًا مفتوحًا لربط نماذج الذكاء الاصطناعي بالأدوات الخارجية ومصادر البيانات. يدعم Agent Framework MCP، مما يعني أن وكلاءك يمكنهم استخدام الأدوات التي يكشفها أي خادم متوافق مع MCP. وهذا يفتح الباب أمام أنظمة الملفات وقواعد البيانات وواجهات برمجة التطبيقات والمزيد — كل ذلك من خلال واجهة موحدة.

// Example: Adding an MCP server for file operations
kernel.Plugins.AddFromMcpServer("filesystem",
 new Uri("http://localhost:3000/mcp"));

يعد هذا أمرًا مثيرًا بشكل خاص لأنه يعني أن عملائك لا يقتصرون على ما تقوم بإنشائه - بل يمكنهم الاستفادة من النظام البيئي لأدوات MCP التي يطورها الآخرون ويشاركونها.

مثال من العالم الحقيقي: خط أنابيب مراجعة المحتوى

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

الباحث — يجمع المعلومات الفنية ذات الصلة
الكاتب — يُنتج مسودة بناءً على البحث
المراجع — يتحقق من الدقة والاكتمال
الناشر — يقوم بتنسيق المخرجات النهائية وإعدادها

وهنا تنفيذ مكثف:

using Azure.Identity;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.ChatCompletion;

// Build the kernel
var builder = Kernel.CreateBuilder();
builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 credentials: new DefaultAzureCredential()
);
Kernel kernel = builder.Build();

// Define specialized agents
ChatCompletionAgent researcher = new()
{
 Name = "Researcher",
 Instructions = """
 You are a technical researcher. Given a topic, identify the key
 concepts, recent developments, and important details that should
 be covered. Output a structured research brief.
 """,
 Kernel = kernel
};

ChatCompletionAgent writer = new()
{
 Name = "Writer",
 Instructions = """
 You are a technical writer. Using the research brief provided,
 write a comprehensive, well-structured article. Include code
 examples where relevant. Target audience: experienced developers.
 """,
 Kernel = kernel
};

ChatCompletionAgent reviewer = new()
{
 Name = "Reviewer",
 Instructions = """
 You are a senior technical reviewer. Check the article for:
 - Technical accuracy
 - Completeness relative to the research brief
 - Code correctness
 - Clarity and structure
 If everything looks good, respond with APPROVED.
 Otherwise, provide specific feedback for revision.
 """,
 Kernel = kernel
};

ChatCompletionAgent publisher = new()
{
 Name = "Publisher",
 Instructions = """
 You are a content publisher. Once the article is approved,
 format it with proper markdown, add a summary at the top,
 and ensure consistent formatting throughout.
 End your response with COMPLETE.
 """,
 Kernel = kernel
};

// Configure the group chat
AgentGroupChat chat = new(researcher, writer, reviewer, publisher)
{
 ExecutionSettings = new()
 {
 SelectionStrategy = new SequentialSelectionStrategy(),
 TerminationStrategy = new ApprovalTerminationStrategy()
 {
 Agents = [publisher],
 MaximumIterations = 15
 }
 }
};

// Start the pipeline
chat.AddChatMessage(new ChatMessageContent(
 AuthorRole.User,
 "Create a technical article about implementing health checks in ASP.NET Core microservices."
));

await foreach (ChatMessageContent message in chat.InvokeAsync())
{
 Console.ForegroundColor = message.AuthorName switch
 {
 "Researcher" => ConsoleColor.Cyan,
 "Writer" => ConsoleColor.Green,
 "Reviewer" => ConsoleColor.Yellow,
 "Publisher" => ConsoleColor.Magenta,
 _ => ConsoleColor.White
 };

 Console.WriteLine($"\n{'='new string('=', 60)}");
 Console.WriteLine($"[{message.AuthorName}]");
 Console.WriteLine(new string('=', 60));
 Console.WriteLine(message.Content);
}

Console.ResetColor();

ينتج هذا المسار مقالة مدروسة ومكتوبة ومراجعة ومنسقة بالكامل - كل ذلك من خلال تعاون الوكيل. يركز كل وكيل على ما يفعله بشكل أفضل، ويقوم AgentGroupChat بتنسيق سير العمل.

أفضل الممارسات

بعد إنشاء العديد من الأنظمة متعددة الوكلاء، إليك الأنماط والممارسات التي وجدتها الأكثر قيمة.

معالجة الأخطاء

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

TerminationStrategy = new ApprovalTerminationStrategy()
{
 MaximumIterations = 12 // Safety net
}

قم بلف استدعاءات وكيلك في كتل محاولة الالتقاط. حدود معدل واجهة برمجة التطبيقات (API)، ومشكلات الشبكة، وأخطاء النماذج كلها حقائق لأنظمة الإنتاج:

try
{
 await foreach (var message in chat.InvokeAsync(cancellationToken))
 {
 // Process messages
 }
}
catch (HttpOperationException ex) when (ex.StatusCode == System.Net.HttpStatusCode.TooManyRequests)
{
 // Implement retry with exponential backoff
 await Task.Delay(TimeSpan.FromSeconds(30), cancellationToken);
}

إمكانية الملاحظةيتكامل Agent Framework مع OpenTelemetry، مما يعني أنه يمكنك تتبع كل تفاعل للوكيل، واستدعاء أداة، واستخدام الرمز المميز. يعد هذا أمرًا ضروريًا لتصحيح أخطاء سير العمل متعدد الوكلاء حيث لا يكون من الواضح دائمًا الوكيل الذي تسبب في المشكلة.

قم بإعداد القياس عن بعد الأساسي عن طريق إضافة حزم القياس عن بعد Semantic Kernel وتكوين المصدر المفضل لديك (Application Insights، Jaeger، وما إلى ذلك):

builder.Services.AddOpenTelemetry()
 .WithTracing(tracing =>
 {
 tracing.AddSource("Microsoft.SemanticKernel*");
 tracing.AddOtlpExporter();
 });

إدارة التكاليف

تعمل الأنظمة متعددة الوكلاء على مضاعفة تكاليف واجهة برمجة التطبيقات (API) الخاصة بك - كل دور وكيل هو عبارة عن استدعاء لواجهة برمجة التطبيقات (API)، ويمكن أن تولد الدردشات الجماعية العديد من الأدوار. بعض الاستراتيجيات لإبقاء التكاليف تحت السيطرة:

استخدم نماذج أرخص للوكلاء الأبسط: لا يحتاج كل وكيل إلى GPT-4o. قد يعمل المراجع بشكل جيد مع نموذج أصغر، بينما يحتاج الكاتب فقط إلى الضارب الثقيل.
السجل الحدي: استخدم ReducedHistoryCount في إعدادات التنفيذ لديك لتحديد مقدار سياق المحادثة الذي يتلقاه كل وكيل.
تعيين حدود تكرار صارمة: منع المحادثات الهاربة ذات قيم MaximumIterations المعقولة.
التخزين المؤقت عندما يكون ذلك ممكنًا: إذا أجرى الوكيل نفس البحث بشكل متكرر، فقم بتخزين النتائج مؤقتًا في مكون إضافي.

تصميم الوكيل

حافظ على تركيز التعليمات: يجب أن يتحمل كل وكيل مسؤولية واحدة واضحة. تؤدي التعليمات الواسعة إلى أداء متواضع في جميع المهام.
كن واضحًا بشأن تنسيق المخرجات: أخبر الوكلاء بكيفية تنظيم ردودهم بالضبط. وهذا يجعل التحليل المصب موثوقًا به.
استخدام الكلمات الرئيسية للإنهاء: حدد الإشارات الواضحة (مثل “تمت الموافقة عليه” أو “مكتمل”) التي يستخدمها الوكلاء للإشارة إلى الانتهاء. وهذا يجعل استراتيجيات الإنهاء بسيطة ويمكن التنبؤ بها.

الخلاصة

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

يجعل Microsoft Agent Framework هذا الأمر عمليًا لمطوري .NET. التجريدات نظيفة - الوكلاء، والمحادثات الجماعية، واستراتيجيات الاختيار والإنهاء - وهي تتشكل بشكل طبيعي. بالاشتراك مع النظام البيئي الإضافي لـ Semantic Kernel واستضافة نماذج Azure، لديك مجموعة كاملة لبناء أنظمة متعددة الوكلاء على مستوى الإنتاج.

لا يزال إطار العمل يتطور (العديد من الحزم قيد المعاينة)، ولكن الأنماط الأساسية ثابتة والاتجاه واضح. إذا كنت تقوم بإنشاء تطبيقات مدعومة بالذكاء الاصطناعي في .NET، فهذا هو الوقت المناسب لبدء تجربة بنيات متعددة الوكلاء.

ابدأ صغيرًا - أنشئ وكيلين يتعاونان في مهمة بسيطة. بمجرد ملاحظة تحسن الجودة مقارنة بأساليب الوكيل الفردي، ستحتاج إلى تحليل كل شيء إلى فرق وكلاء.

ترميز سعيد!

عرض HTML الخام في Blazor باستخدام MarkupString

Sat, 22 Nov 2025 00:00:00 +0000

في أحد الأيام كنت أقوم ببناء مكون يحتاج إلى تقديم بعض HTML الذي يأتي من نظام إدارة المحتوى (CMS). كانت لدي سلسلة HTML في متغير وقمت بإسقاطها في القالب مثل @myHtml. وبالطبع، أفلت Blazor من كل شيء وقدم العلامات الفعلية كنص على الصفحة. ليس ما أردت.

#المشكلة

افتراضيًا، يقوم Blazor بتشفير أي سلسلة تعرضها في قالب. لذلك إذا كان لديك:

@code {
 private string content = "<strong>Hello</strong> <em>world</em>";
}

وأنت تفعل هذا:

<div>@content</div>

ستشاهد النص الحرفي <strong>Hello</strong> <em>world</em> على الصفحة بدلاً من Hello world. يقوم Blazor بهذا عن قصد لمنع هجمات XSS، وهو السلوك الافتراضي الصحيح.

الحل: MarkupString

إذا كنت تريد فعليًا تقديم HTML خام، فيمكنك لف السلسلة في MarkupString:

<div>@((MarkupString)content)</div>

وهذا كل شيء! الآن سوف يقوم Blazor بعرض HTML كعلامة فعلية. يمكنك أيضًا إسنادها إلى متغير:

@code {
 private string rawHtml = "<strong>Hello</strong> <em>world</em>";
 private MarkupString HtmlContent => (MarkupString)rawHtml;
}

<div>@HtmlContent</div>

#مثال من العالم الحقيقي

كنت أقوم بسحب محتوى المدونة من واجهة برمجة التطبيقات (API) وأحتاج إلى عرضه في مكون معاينة. يحتوي المحتوى على جميع أنواع HTML - العناوين، وكتل التعليمات البرمجية، والروابط، والصور. إليك ما بدا عليه الأمر تقريبًا:

@inject HttpClient Http

@if (article is not null)
{
 <article>
 <h1>@article.Title</h1>
 <div class="content">
 @((MarkupString)article.HtmlBody)
 </div>
 </article>
}

@code {
 [Parameter]
 public int ArticleId { get; set; }

 private ArticleDto? article;

 protected override async Task OnInitializedAsync()
 {
 article = await Http.GetFromJsonAsync<ArticleDto>($"api/articles/{ArticleId}");
 }
}

يعمل على أكمل وجه. يتم عرض HTML من واجهة برمجة التطبيقات (API) كعلامة فعلية.

كن حذرا مع المحتوى غير الموثوق به

هذا أمر مهم: MarkupString لا** يقوم بتطهير HTML. فهو يعرض كل ما تقدمه له، بما في ذلك علامات <script>. لذا، إذا كان المحتوى يأتي من مدخلات المستخدم أو من مصدر غير موثوق به، فأنت بحاجة إلى تطهيره أولاً.

لا يوجد مطهر HTML مدمج في Blazor، ولكن يمكنك استخدام مكتبة مثل HtmlSanitizer:

using Ganss.Xss;

@code {
 private HtmlSanitizer sanitizer = new();

 private MarkupString SafeHtml(string html)
 {
 var clean = sanitizer.Sanitize(html);
 return (MarkupString)clean;
 }
}

<div>@SafeHtml(untrustedContent)</div>

يؤدي هذا إلى استبعاد العناصر الخطيرة مثل معالجات <script> وonclick والأشياء الأخرى التي لا تريد عرضها من المحتوى المقدم من المستخدم.

#متى يتم استخدامه

أستخدم MarkupString من أجل:

محتوى CMS أو تخفيض السعر الذي تم تحويله إلى جانب خادم HTML
إخراج محرر النص الغني
معاينة قوالب البريد الإلكتروني
أي HTML تم إنشاؤه مسبقًا من مصادر موثوقة

بالنسبة لأي شيء يأتي من مدخلات المستخدم، قم دائمًا بالتعقيم أولاً. أفضل آمنة من آسف.

آمل أن تكونوا قد أحببت هذا المنصب! لا تتردد في الاتصال بي على أي وسائل التواصل الاجتماعي على **@emimontesdeoca **.

الموارد

ما الجديد في EF Core 9: الميزات التي تحتاج إلى معرفتها

Tue, 18 Nov 2025 00:00:00 +0000

تم شحن Entity Framework Core 9 جنبًا إلى جنب مع .NET 9 في نوفمبر 2024، وبعد قضاء قدر كبير من الوقت في العمل معه عبر العديد من المشاريع، يمكنني القول إنه أحد الإصدارات الأكثر أهمية منذ فترة. ليس لأنه يعيد اختراع العجلة، ولكن لأنه يصقل المجالات التي تسببت فيها EF Core تاريخيًا في أكبر قدر من الاحتكاك - ترجمة الاستعلامات والأداء والعمل باستخدام أنماط البيانات الحديثة.

في هذا المنشور، سأستعرض الميزات التي كان لها التأثير الأكبر على عملي اليومي. إذا كنت لا تزال تستخدم EF Core 8 (أو حتى 7)، فمن المفترض أن يمنحك هذا صورة واضحة عما ينتظرك على الجانب الآخر من الترقية.

EF Core 9 في النظام البيئي .NET 9

يستهدف EF Core 9 الإصدارين .NET 8 و.NET 9، مما يعني أنك لا تحتاج بالضرورة إلى ترقية تطبيقك بالكامل إلى .NET 9 للاستفادة من معظم هذه الميزات. ومع ذلك، فإن بعض AOT وتحسينات الأداء مقترنة بإحكام مع تغييرات وقت تشغيل .NET 9، لذلك ستحصل على أقصى استفادة منه من خلال المضي قدمًا.

يتبع الإصدار الإيقاع الفردي/الزوجي الذي أنشأته Microsoft: الإصدارات ذات الأرقام الفردية (مثل .NET 9) هي دعم قياسي على المدى (STS) مع 18 شهرًا من الدعم، في حين أن الإصدارات الزوجية (مثل .NET 8) هي دعم طويل الأجل (LTS). ضع ذلك في الاعتبار عند التخطيط للجدول الزمني للترقية.

تحسينات الترجمة في LINQ

هذا هو المكان الذي سيشعر فيه معظم المطورين بالفرق على الفور. لقد قطع EF Core 9 خطوات كبيرة في ترجمة تعبيرات LINQ إلى SQL وهو أمر منطقي بالفعل.

مجموعة أفضل بالترجمات

إذا سبق لك أن كتبت استعلام GroupBy في EF Core وانتهى الأمر بتحذيرات تقييم من جانب العميل أو SQL غريبة، فأنت تعرف الألم. يتعامل EF Core 9 مع مجموعة أوسع بكثير من سيناريوهات GroupBy مباشرة في SQL.

var salesByCategory = await context.Products
 .GroupBy(p => p.Category.Name)
 .Select(g => new
 {
 Category = g.Key,
 TotalRevenue = g.Sum(p => p.Price * p.UnitsSold),
 AveragePrice = g.Average(p => p.Price),
 ProductCount = g.Count()
 })
 .OrderByDescending(x => x.TotalRevenue)
 .ToListAsync();

في الإصدارات السابقة، كانت الاستعلامات التي تتضمن تجميعات عبر خصائص التنقل داخل GroupBy ترجع أحيانًا إلى تقييم العميل. يترجم EF Core 9 هذا الأمر بشكل واضح إلى استعلام SQL واحد باستخدام GROUP BY، SUM، AVG، و COUNT.

الإسقاطات المعقدة والاستعلامات الفرعية

حصلت الاستعلامات الفرعية المتداخلة والإسقاطات المعقدة أيضًا على ترقية جدية. النظر في شيء من هذا القبيل:

var orderSummaries = await context.Customers
 .Select(c => new CustomerSummaryDto
 {
 Name = c.FullName,
 TotalOrders = c.Orders.Count(),
 MostRecentOrder = c.Orders
 .OrderByDescending(o => o.OrderDate)
 .Select(o => new OrderBriefDto
 {
 Id = o.Id,
 Date = o.OrderDate,
 Total = o.LineItems.Sum(li => li.Quantity * li.UnitPrice)
 })
 .FirstOrDefault(),
 TopCategory = c.Orders
 .SelectMany(o => o.LineItems)
 .GroupBy(li => li.Product.Category.Name)
 .OrderByDescending(g => g.Count())
 .Select(g => g.Key)
 .FirstOrDefault()
 })
 .ToListAsync();

يمكن لـ EF Core 9 الآن ترجمة هذا التعبير بالكامل إلى SQL دون إجراء تقييم من جانب العميل. يستخدم الاستعلام الذي تم إنشاؤه استعلامات فرعية مترابطة وروابط جانبية حيثما يكون ذلك مناسبًا، كما أن خطة SQL أكثر كفاءة بكثير مما تنتجه الإصدارات السابقة.

المجموعات البدائية ذات المعلمات

أحد التحسينات البارزة في LINQ هو القدرة على تمرير مجموعات من القيم الأولية مباشرة إلى الاستعلامات:

var statusFilter = new List<string> { "Active", "Pending", "Review" };

var filteredOrders = await context.Orders
 .Where(o => statusFilter.Contains(o.Status))
 .ToListAsync();

في EF Core 8، تمت ترجمة ذلك باستخدام عبارات IN ذات القيم المضمنة، مما يعني أنه لا يمكن إعادة استخدام ذاكرة التخزين المؤقت لخطة الاستعلام عند تغيير القائمة. يقوم EF Core 9 بتحديد معلمات هذه المجموعات بشكل صحيح، وإرسالها كمعلمة منظمة. يعد هذا أمرًا مهمًا للتخزين المؤقت لخطة الاستعلام على SQL Server وPostgreSQL.## العمليات المجمعة - تنفيذ التحديث وتنفيذ الحذف

تم تقديم ExecuteUpdate وExecuteDelete في EF Core 7، لكن EF Core 9 يوسع ما يمكنك فعله بهما بطرق مفيدة.

عمليات الحذف المشروطة المجمعة باستخدام الاستعلامات الفرعية

أصبحت الآن عمليات الحذف المجمعة باستخدام مرشحات الاستعلام الفرعي مدعومة بشكل كامل:

await context.AuditLogs
 .Where(log => log.CreatedAt < DateTime.UtcNow.AddYears(-2))
 .Where(log => !context.ProtectedRecords
 .Any(pr => pr.AuditLogId == log.Id))
 .ExecuteDeleteAsync();

يُترجم هذا إلى DELETE مع استعلام فرعي NOT EXISTS، وهو بالضبط ما ستكتبه يدويًا. لم يتم تحميل أي كيانات، ولا توجد رحلات ذهابًا وإيابًا.

تحسينات عمود JSON

لقد كانت أعمدة JSON واحدة من أكثر الميزات إثارة في إصدارات EF Core الأخيرة، ويأخذها EF Core 9 إلى أبعد من ذلك.

الاستعلام داخل JSON

يمكنك الآن تصفية البيانات وعرضها من داخل أعمدة JSON مع دعم أفضل للترجمة:

public class Order
{
 public int Id { get; set; }
 public string CustomerName { get; set; }
 public ShippingAddress Address { get; set; } // Stored as JSON
 public List<OrderNote> Notes { get; set; } // Stored as JSON
}

public class ShippingAddress
{
 public string Street { get; set; }
 public string City { get; set; }
 public string State { get; set; }
 public string ZipCode { get; set; }
 public string Country { get; set; }
}

public class OrderNote
{
 public DateTime CreatedAt { get; set; }
 public string Text { get; set; }
 public string Author { get; set; }
}

التكوين في DbContext:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
 modelBuilder.Entity<Order>(builder =>
 {
 builder.OwnsOne(o => o.Address, ab =>
 {
 ab.ToJson();
 });

 builder.OwnsMany(o => o.Notes, nb =>
 {
 nb.ToJson();
 });
 });
}

يمكنك الآن الاستعلام مباشرة إلى JSON:

var newYorkOrders = await context.Orders
 .Where(o => o.Address.State == "NY")
 .OrderByDescending(o => o.Notes.Count)
 .Select(o => new
 {
 o.CustomerName,
 o.Address.City,
 LatestNote = o.Notes
 .OrderByDescending(n => n.CreatedAt)
 .Select(n => n.Text)
 .FirstOrDefault()
 })
 .ToListAsync();

يقوم EF Core 9 بإنشاء استدعاءات JSON_VALUE و JSON_QUERY مناسبة على SQL Server (أو ما يعادله على مقدمي الخدمات الآخرين)، وتغطي الترجمة نطاقًا أوسع بكثير من عمليات LINQ على عناصر JSON أكثر من ذي قبل.

تحديث خصائص JSON

كانت إحدى نقاط الاحتكاك في EF Core 8 هي أن تحديث خاصية واحدة داخل عمود JSON قد يؤدي إلى إعادة كتابة مستند JSON بالكامل. يعمل EF Core 9 على تحسين ذلك من خلال تتبع تغييرات أكثر دقة للأنواع المعينة بـ JSON، مما يؤدي إلى إنشاء المزيد من التحديثات المستهدفة عندما يكون ذلك ممكنًا.

var order = await context.Orders.FindAsync(orderId);
order.Address.ZipCode = "10001";
await context.SaveChangesAsync();

بالنسبة للموفرين المدعومين، يمكن أن يؤدي ذلك إلى إنشاء تعديل JSON أكثر استهدافًا بدلاً من إعادة كتابة الكائن الثنائي الكبير بالكامل.

الأنواع المعقدة — كائنات القيمة بدون هوية

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

[ComplexType]
public record Money(decimal Amount, string Currency);

[ComplexType]
public record DateRange(DateTime Start, DateTime End);

public class Project
{
 public int Id { get; set; }
 public string Name { get; set; }
 public Money Budget { get; set; }
 public DateRange Timeline { get; set; }
}

يتم تخزينها كأعمدة مسطحة في الجدول الأصلي - Budget_Amount، Budget_Currency، Timeline_Start، Timeline_End - دون الحاجة إلى جدول منفصل أو أي نوع من المفاتيح.

الفرق الرئيسي عن الأنواع المملوكة: تتم مقارنة الأنواع المعقدة من حيث القيمة، وليس من خلال المرجع. يعتبر مثيلان Money بنفس Amount و Currency متساويين، بغض النظر عن الكيان الذي ينتمون إليه.

var expensiveProjects = await context.Projects
 .Where(p => p.Budget.Amount > 100_000m && p.Budget.Currency == "USD")
 .OrderByDescending(p => p.Budget.Amount)
 .ToListAsync();

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

دعم التسلسل الهرمي لخادم SQL

إذا سبق لك التعامل مع البيانات الهرمية في SQL Server - المخططات التنظيمية وأشجار الفئات وأنظمة الملفات - فأنت تعلم أن HierarchyId هو النوع المضمن لهذا الغرض. يقدم EF Core 9 دعمًا من الدرجة الأولى له.

public class Employee
{
 public int Id { get; set; }
 public string Name { get; set; }
 public string Title { get; set; }
 public HierarchyId PathFromCeo { get; set; }
}

يمكنك الآن الاستعلام عن العلاقات الهرمية مباشرة:

var managerId = HierarchyId.Parse("/1/3/");

// All direct and indirect reports
var allReports = await context.Employees
 .Where(e => e.PathFromCeo.IsDescendantOf(managerId))
 .Where(e => e.PathFromCeo != managerId) // exclude the manager
 .OrderBy(e => e.PathFromCeo)
 .ToListAsync();

// Direct reports only (one level down)
var directReports = await context.Employees
 .Where(e => e.PathFromCeo.GetAncestor(1) == managerId)
 .ToListAsync();

// Get an employee's depth in the hierarchy
var employeesWithDepth = await context.Employees
 .Select(e => new
 {
 e.Name,
 e.Title,
 Level = e.PathFromCeo.GetLevel()
 })
 .OrderBy(e => e.Level)
 .ToListAsync();
```كل هذه تترجم إلى أساليب `HierarchyId` الأصلية لـ SQL Server. إذا كنت تقوم بتنفيذ هياكل شجرية ذات مرجعية ذاتية للمفاتيح الخارجية وCTEs العودية، فهذا نهج أكثر نظافة.

## النماذج المجمعة ودعم AOT

سيقدر المطورون المهتمون بالأداء الاستثمار المستمر في النماذج المجمعة ودعم التجميع المسبق (AOT).

### النماذج المجمعة

تقوم النماذج المجمعة بإنشاء البيانات التعريفية للنموذج مسبقًا والتي تقوم EF Core ببنائها عادةً عند بدء التشغيل. بالنسبة للنماذج الكبيرة (فكر في مئات الكيانات)، يمكن أن يؤدي ذلك إلى تقليل وقت البدء البارد بشكل كبير.

```bash
dotnet ef dbcontext optimize --output-dir CompiledModels --namespace MyApp.CompiledModels

ثم قم بتوصيله:

builder.Services.AddDbContext<AppDbContext>(options =>
 options
 .UseSqlServer(connectionString)
 .UseModel(MyApp.CompiledModels.AppDbContextModel.Instance));

في EF Core 9، تكون النماذج المجمعة أكثر اكتمالاً - فهي تدعم المزيد من ميزات رسم الخرائط وتنتج مخرجات أصغر. بالنسبة للنموذج الذي يحتوي على حوالي 400 كيان، يمكن أن ينخفض وقت بدء التشغيل من عدة ثوانٍ إلى شبه فوري.

تقدم تجميع AOT

لا يزال دعم AOT الأصلي الكامل لـ EF Core قيد التقدم، لكن EF Core 9 يحقق خطوات كبيرة. تمت إعادة هيكلة العديد من مسارات التعليمات البرمجية ذات الانعكاس الثقيل لتكون ملائمة للتشذيب، وتعد النماذج المجمعة جزءًا أساسيًا من قصة AOT. إذا كنت تستهدف سيناريوهات مثل وظائف Azure أو الخدمات الصغيرة حيث تكون البداية الباردة مهمة، فإن هذه التحسينات ذات صلة مباشرة.

تحديثات موفر قاعدة بيانات Cosmos

يستمر موفر Azure Cosmos DB في النضج باستخدام EF Core 9. بعض التحسينات الملحوظة:

التعامل مع مفتاح التقسيم

يدعم الموفر الآن مفاتيح الأقسام الهرمية ويتعامل مع عوامل تصفية مفاتيح الأقسام بشكل أكثر ذكاءً:

public class TenantDocument
{
 public string Id { get; set; }
 public string TenantId { get; set; } // Partition key
 public string Region { get; set; } // Sub-partition key
 public string Content { get; set; }
}

// This query now correctly uses the partition key for routing
var docs = await context.TenantDocuments
 .Where(d => d.TenantId == "tenant-42" && d.Region == "us-east")
 .Where(d => d.Content.Contains("important"))
 .ToListAsync();

تحسين ترجمة LINQ إلى NoSQL

يتم الآن ترجمة المزيد من عمليات LINQ إلى لهجة SQL الخاصة بـ Cosmos DB، بما في ذلك دعم أفضل لـ Contains، Any، وعمليات المصفوفة المتداخلة، والوظائف الرياضية. يتم الآن التعامل مع الاستعلامات التي كانت ترجع سابقًا إلى تقييم العميل من جانب الخادم.

دعم البحث عن المتجهات

يقدم EF Core 9 دعمًا مبكرًا للبحث عن تشابه المتجهات باستخدام Cosmos DB، وهو أمر مفيد إذا كنت تقوم بإنشاء تطبيقات تتكامل مع عمليات التضمين أو البحث المعتمد على الذكاء الاصطناعي:

var results = await context.Documents
 .OrderBy(d => EF.Functions.VectorDistance(d.Embedding, queryVector))
 .Take(10)
 .ToListAsync();

تحسينات الهجرة

حصلت عمليات الترحيل على بعض التحسينات في جودة الحياة مما يجعل العمل معهم أقل إيلامًا في بيئات الفريق.

الجداول الزمنية في الهجرات

تتعامل عمليات الترحيل الآن مع تكوين الجدول الزمني بشكل أكثر رشاقة، مع الدعم المناسب لأعمدة الفترة وتسمية جدول المحفوظات:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
 modelBuilder.Entity<Employee>()
 .ToTable("Employees", b => b.IsTemporal(t =>
 {
 t.HasPeriodStart("ValidFrom");
 t.HasPeriodEnd("ValidTo");
 t.UseHistoryTable("EmployeeHistory");
 }));
}

نصوص عاجزة

ينتج الأمر Script-Migration (ومكافئه لواجهة سطر الأوامر) نصوصًا برمجية أفضل بشكل افتراضي، مع معالجة محسنة لحالات الحافة حول تغييرات المخطط التي تعتمد على البيانات الموجودة في حالات معينة.

حزم الهجرة

تعد حزم الترحيل، التي تجمع عمليات الترحيل الخاصة بك في ملف مستقل قابل للتنفيذ للنشر، أكثر موثوقية في EF Core 9 مع الإبلاغ عن الأخطاء بشكل أفضل ومنطق إعادة المحاولة في حالات الفشل العابر.

dotnet ef migrations bundle --self-contained -r linux-x64

ينتج عن ذلك ملف ثنائي يمكنك تشغيله في مسار CI/CD الخاص بك دون الحاجة إلى تثبيت .NET SDK على هدف النشر الخاص بك.

معايير الأداءفيما يلي بعض المعايير التقريبية من الاختبار الخاص بي. هذه من مشروع يضم ما يقرب من 200 كيان، تعمل مقابل SQL Server 2022، ويتم قياسها باستخدام BenchmarkDotNet. ستختلف أرقامك، لكن التحسينات النسبية يجب أن تكون متشابهة.

السيناريو	إي أف كور 8	إي أف كور 9	تحسين
بناء النموذج (البداية الباردة)	1,850 مللي ثانية	320 مللي ثانية	~5.8x أسرع (مترجمة)
استعلام بسيط (كيان واحد بواسطة PK)	0.42 مللي ثانية	0.38 مللي ثانية	~10% أسرع
استعلام معقد (صلات + تجميع)	3.1 مللي ثانية	2.4 مللي ثانية	~23% أسرع
تحديث مجمع (10 آلاف صف)	145 مللي ثانية	118 مللي ثانية	~19% أسرع
استعلام عمود JSON	2.8 مللي ثانية	1.9 مللي ثانية	~32% أسرع
حفظ التغييرات (100 كيان)	48 مللي ثانية	41 مللي ثانية	~15% أسرع

يعد تحسين النموذج المجمّع هو الأكثر دراماتيكية، ولكن التحسينات الثابتة في جميع المجالات تضيف المزيد - خاصة في السيناريوهات عالية الإنتاجية حيث تقوم بتنفيذ آلاف الاستعلامات في الثانية.

الترقية من EF Core 8

إذا كنت تستخدم EF Core 8، فإن مسار الترقية يكون سلسًا نسبيًا. فيما يلي قائمة مرجعية:

**1. تحديث الحزم الخاصة بك: **

<PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="9.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="9.0.0" />

**2. تحقق من وجود تغييرات عاجلة. ** قائمة EF Core 9 قصيرة نسبيًا مقارنة ببعض الإصدارات السابقة. أبرزها:

تمت إزالة بعض واجهات برمجة التطبيقات (APIs) القديمة سابقًا
تغييرات في كيفية ترجمة استعلامات GroupBy معينة (تنتقل الآن إلى جانب الخادم، مما يغير السلوك إذا كنت تعتمد على تقييم العميل)
تغييرات طفيفة في مخرجات سقالات الهجرة

3. أعد إنشاء النماذج المجمعة إذا كنت تستخدمها. تم تغيير التنسيق، لذا لن تعمل النماذج القديمة المجمعة مع EF Core 9.

**4. قم بتشغيل مجموعة الاختبار الخاصة بك. ** انتبه بشكل خاص للاستعلامات التي تم تقييمها مسبقًا على العميل - ربما يتم تقييمها الآن على الخادم، وهو ما يكون عادةً أفضل ولكنه قد يؤدي إلى ظهور اختلافات في البيانات.

5. تحقق من استعلامات Cosmos DB إذا كنت تستخدم هذا الموفر. تعني الترجمات المحسنة أن بعض الاستعلامات سيتم تنفيذها بشكل مختلف (عادةً ما يكون أسرع)، ولكن من المفيد التحقق من تطابق النتائج.

يبدو الحد الأدنى من الترقية لمشروع نموذجي كما يلي:

dotnet add package Microsoft.EntityFrameworkCore --version 9.0.0
dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 9.0.0
dotnet add package Microsoft.EntityFrameworkCore.Design --version 9.0.0
dotnet build
dotnet test

إذا تم تجميع كل شيء واجتياز الاختبارات، فمن المحتمل أنك في حالة جيدة. إذا واجهت مشكلات، فإن وثائق التغييرات العاجلة في EF Core 9 تحتوي على إرشادات مفصلة للترحيل لكل تغيير.

الختام

إن EF Core 9 ليس إصدارًا ثوريًا، بل هو إصدار تطوري، وهذا بالضبط ما كان يجب أن يكون عليه. تحسينات LINQ وحدها تبرر الترقية لمعظم المشاريع، والميزات مثل تحسينات أعمدة JSON، والأنواع المعقدة، وHierarchyId تدعم الأنماط المفتوحة التي كانت في السابق غير ملائمة أو مستحيلة.

إذا اضطررت إلى اختيار الميزات الثلاثة التي كان لها التأثير الأكبر على مشاريعي:

المجموعات الأولية ذات المعلمات — لأن كفاءة ذاكرة التخزين المؤقت لخطة الاستعلام مهمة على نطاق واسع
تحسينات عمود JSON — لأن نمط المستند العلائقي المختلط مفيد بشكل لا يصدق
النماذج المجمعة — لأن وقت بدء التشغيل يؤثر بشكل مباشر على إنتاجية المطور وسرعة النشرلقد كان فريق EF Core يسير على مسار قوي منذ EF Core 5، ويواصل الإصدار 9 هذا الاتجاه. إذا كنت مشتركًا بالفعل في EF Core 8، فإن الترقية تكون منخفضة المخاطر ومكافأة عالية. إذا كنت تستخدم شيئًا أقدم، فليس هناك وقت أفضل للقيام بهذه القفزة.

برمجة سعيدة - واستعلام سعيد.

البدء باستخدام النواة الدلالية: تنسيق الذكاء الاصطناعي في لغة C#

Sun, 05 Oct 2025 00:00:00 +0000

إذا كنت تقوم ببناء تطبيقات .NET وتشاهد مشهد الذكاء الاصطناعي يتطور، فربما تساءلت: *ما هي أفضل طريقة لدمج نماذج اللغة الكبيرة في مشاريع C# الخاصة بي دون تحويل قاعدة التعليمات البرمجية الخاصة بي إلى معكرونة؟ * هذه هي بالضبط المشكلة التي تحلها Semantic Kernel من Microsoft، وبعد قضاء العام الماضي في بناء تطبيقات الإنتاج باستخدامها، يمكنني أن أخبرك أنها أصبحت واحدة من أهم الأدوات في مجموعة أدوات المطور الخاصة بي.

في هذا المنشور، سأرشدك إلى كل ما تحتاجه للبدء في استخدام Semantic Kernel - بدءًا من فهم المفاهيم الأساسية وحتى إنشاء مساعد الذكاء الاصطناعي في العالم الحقيقي. سواء كنت تغمس أصابع قدميك في تطوير الذكاء الاصطناعي أو تبحث عن طريقة منظمة لتنسيق مكالمات LLM في تطبيقات .NET الموجودة لديك، فإن هذا الدليل يلبي احتياجاتك.

ما هي النواة الدلالية؟

Semantic Kernel (SK) عبارة عن SDK مفتوح المصدر من Microsoft يعمل بمثابة طبقة تنسيق بين رمز التطبيق الخاص بك ونماذج اللغات الكبيرة مثل GPT-4o أو Azure OpenAI أو خدمات الذكاء الاصطناعي الأخرى. فكر في الأمر على أنه برنامج وسيط خفيف الوزن يتيح لك الجمع بين كود C# التقليدي وإمكانيات الذكاء الاصطناعي بطريقة نظيفة وقابلة للتركيب.

ولكن لماذا لا نتصل بـ OpenAI API مباشرة؟ يمكنك فعل ذلك بالتأكيد، ولا بأس بذلك بالنسبة لحالات الاستخدام البسيطة. لكن في اللحظة التي تحتاج فيها إلى:

دع الذكاء الاصطناعي يقرر الوظائف التي سيتم الاتصال بها بناءً على مدخلات المستخدم
ادمج مكالمات الذكاء الاصطناعي المتعددة مع التعليمات البرمجية التقليدية في مسار واحد
أضف الذاكرة والسياق حتى يتذكر الذكاء الاصطناعي التفاعلات السابقة
قم ببناء وكلاء متعددي الخطوات الذين يقومون بالتفكير من خلال المهام المعقدة

…ستجد نفسك تعيد اختراع العجلة. يمنحك Semantic Kernel كل هذا خارج الصندوق، مع دعم .NET من الدرجة الأولى، وتكامل حقن التبعية، وبنية المكونات الإضافية التي تبدو طبيعية لأي مطور C#.

يتواجد المشروع على GitHub ضمن مستودع microsoft/semantic-kernel ويحتوي على SDKs لـ C# وPython وJava. يعد C# SDK هو الأكثر نضجًا وهو الذي سنركز عليه هنا.

المفاهيم الأساسية

قبل أن نكتب أي كود، دعونا نفهم اللبنات الأساسية.

النواة

Kernel هو الكائن المركزي في Semantic Kernel. إنه المنسق - الشيء الذي يربط بين خدمات الذكاء الاصطناعي والمكونات الإضافية والتكوين. يمكنك إنشاء واحدة، وتسجيل خدماتك ومكوناتك الإضافية عليها، ثم استخدامها لتنفيذ المطالبات أو استدعاء الوظائف. إذا كنت معتادًا على حقن التبعية في ASP.NET Core، فستشعر أن Kernel مألوف جدًا - فهي في الأساس حاوية خدمة ذات قوى خارقة للذكاء الاصطناعي.

الإضافات والوظائف

المكون الإضافي عبارة عن مجموعة من الوظائف ذات الصلة التي يمكن أن يستدعيها Kernel. الوظائف تأتي في نكهتين:

الوظائف السريعة — يتم تعريفها على أنها قوالب لغة طبيعية يتم إرسالها إلى LLM
الوظائف الأصلية — أساليب C# العادية المزينة بالسمات التي يمكن لـ Kernel اكتشافها واستدعاءها

على سبيل المثال، قد يكون لديك WeatherPlugin مع وظيفة أصلية GetCurrentWeather(string city) ووظيفة سريعة تلخص بيانات الطقس بطريقة سهلة.### موصلات الذكاء الاصطناعي

الموصلات هي الطريقة التي تتحدث بها Semantic Kernel مع خدمات الذكاء الاصطناعي. الأكثر شيوعا هي:

AzureOpenAIChatCompletion — لخدمة Azure OpenAI
OpenAIChatCompletion — لواجهة برمجة تطبيقات OpenAI مباشرة
تضمين موصلات للبحث عن المتجهات والذاكرة

تقوم بتسجيلها على Kernel عند بدء التشغيل، وكل شيء آخر يعمل.

إعداد مشروعك

دعونا الحصول على أيدينا القذرة. ابدأ بإنشاء تطبيق وحدة تحكم جديد:

dotnet new console -n SemanticKernelDemo
cd SemanticKernelDemo

أضف الآن حزم Semantic Kernel NuGet:

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Connectors.AzureOpenAI

إذا كنت تستخدم OpenAI مباشرةً بدلاً من Azure OpenAI:

dotnet add package Microsoft.SemanticKernel.Connectors.OpenAI

لدعم الذاكرة والتضمينات (سنستخدم هذا لاحقًا):

dotnet add package Microsoft.SemanticKernel.Plugins.Memory
dotnet add package Microsoft.Extensions.VectorData.Abstractions

يجب أن يستهدف .csproj الإصدار .NET 8 أو الأحدث. تستفيد أحدث إصدارات Semantic Kernel استفادة كاملة من ميزات .NET الحديثة.

نواتك الأولى

لنبدأ بأبسط مثال ممكن - إنشاء Kernel، وربطه بخدمة الذكاء الاصطناعي، وطرح سؤال عليه.

using Microsoft.SemanticKernel;

// Build the kernel with Azure OpenAI
var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

var kernel = builder.Build();

// Invoke a simple prompt
var result = await kernel.InvokePromptAsync(
 "Explain dependency injection in C# in three sentences."
);

Console.WriteLine(result);

إذا كنت تستخدم OpenAI مباشرة، فقم بتبديل تسجيل الخدمة:

builder.AddOpenAIChatCompletion(
 modelId: "gpt-4o",
 apiKey: "your-openai-api-key"
);

هذا كل شيء. قم بتشغيله وستحصل على شرح موجز لحقن التبعية. ولكن هذا مجرد خدش السطح.

استخدام القوالب السريعة

تتيح لك قوالب الموجهات تحديد معلمات المطالبات الخاصة بك باستخدام المتغيرات باستخدام بناء جملة نمط Handlebars:

var prompt = """
 You are a technical writer. Write a brief summary of {{$topic}}
 aimed at developers with {{$experienceLevel}} experience.
 Keep it under 200 words.
 """;

var function = kernel.CreateFunctionFromPrompt(prompt);

var arguments = new KernelArguments
{
 ["topic"] = "gRPC in .NET",
 ["experienceLevel"] = "intermediate"
};

var result = await kernel.InvokeAsync(function, arguments);
Console.WriteLine(result);

هذا هو المكان الذي يبدأ فيه Semantic Kernel في التألق - يمكنك تحديد قوالب المطالبة القابلة لإعادة الاستخدام، وإصدارها، وتكوينها في مسارات عمل أكبر.

الإضافات والوظائف الأصلية

المكونات الإضافية هي المكان الذي يقوم فيه Semantic Kernel بسد الفجوة بين الذكاء الاصطناعي ورمز C# الموجود لديك. الوظيفة الأصلية هي مجرد طريقة عادية تعرضها لـ Kernel.

using Microsoft.SemanticKernel;
using System.ComponentModel;

public class TimePlugin
{
 [KernelFunction("get_current_time")]
 [Description("Gets the current date and time in UTC")]
 public string GetCurrentTime()
 {
 return DateTime.UtcNow.ToString("yyyy-MM-dd HH:mm:ss UTC");
 }

 [KernelFunction("get_time_in_timezone")]
 [Description("Gets the current time in a specific timezone")]
 public string GetTimeInTimezone(
 [Description("The IANA timezone identifier, e.g. 'America/New_York'")] string timezone)
 {
 var tz = TimeZoneInfo.FindSystemTimeZoneById(timezone);
 var time = TimeZoneInfo.ConvertTimeFromUtc(DateTime.UtcNow, tz);
 return time.ToString("yyyy-MM-dd HH:mm:ss");
 }
}

لاحظ سمات [KernelFunction] و [Description]. هذه الأمور بالغة الأهمية، فالأوصاف هي ما يقرأه الذكاء الاصطناعي لفهم متى وكيف يتم استدعاء وظائفك. الأوصاف الجيدة تُحدث فرقًا بين الذكاء الاصطناعي الذي يستخدم أدواتك بفعالية والذكاء الاصطناعي الذي يرتبك.

سجل البرنامج المساعد على النواة الخاصة بك:

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

builder.Plugins.AddFromType<TimePlugin>();

var kernel = builder.Build();

يمكنك أيضًا إنشاء مكونات إضافية أكثر تعقيدًا تعمل على إدخال الخدمات. نظرًا لأن Semantic Kernel يتكامل مع Microsoft.Extensions.DependencyInjection، فيمكن لمكوناتك الإضافية تلقي تبعيات المُنشئ تمامًا مثل أي خدمة أخرى:

public class OrderPlugin
{
 private readonly IOrderRepository _repository;

 public OrderPlugin(IOrderRepository repository)
 {
 _repository = repository;
 }

 [KernelFunction("get_order_status")]
 [Description("Retrieves the status of an order by its ID")]
 public async Task<string> GetOrderStatus(
 [Description("The order ID to look up")] string orderId)
 {
 var order = await _repository.GetByIdAsync(orderId);
 return order is null
 ? $"No order found with ID {orderId}"
 : $"Order {orderId}: {order.Status}, placed on {order.CreatedAt:d}";
 }
}

استدعاء الوظائف والاستدعاء التلقائي

هذا هو المكان الذي تصبح فيه الأمور مثيرة للاهتمام حقًا. من خلال استدعاء الوظائف (المعروف أيضًا باسم استدعاء الأدوات)، يمكنك السماح لنموذج الذكاء الاصطناعي بتحديد الوظائف المسجلة التي سيتم الاتصال بها بناءً على سياق المحادثة. لا ينفذ النموذج تعليمات برمجية — فهو يُرجع طلبًا منظمًا يقول “أريد استدعاء الوظيفة X باستخدام هذه الوسائط”، ويتولى Kernel التعامل مع الاستدعاء الفعلي.

فيما يلي كيفية تمكين استدعاء الوظائف التلقائي:

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

builder.Plugins.AddFromType<TimePlugin>();
builder.Plugins.AddFromType<WeatherPlugin>();

var kernel = builder.Build();

// Enable automatic function calling
var settings = new OpenAIPromptExecutionSettings
{
 FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
};

var result = await kernel.InvokePromptAsync(
 "What time is it in Tokyo and what's the weather like there?",
 new KernelArguments(settings)
);

Console.WriteLine(result);

باستخدام FunctionChoiceBehavior.Auto()، سيقوم النواة بما يلي:

أرسل مطالبتك إلى الذكاء الاصطناعي مع وصف جميع الوظائف المتاحة
يقرر الذكاء الاصطناعي أنه بحاجة إلى الاتصال بـ get_time_in_timezone وget_weather
يقوم Kernel تلقائيًا بتنفيذ هذه الوظائف
يتم إرسال النتائج مرة أخرى إلى الذكاء الاصطناعي
يقوم الذكاء الاصطناعي بتأليف استجابة لغة طبيعية باستخدام نتائج الوظيفةيمكن أن تحدث هذه الحلقة عدة مرات في استدعاء واحد - قد يستدعي الذكاء الاصطناعي عدة وظائف بالتسلسل لجمع كل المعلومات التي يحتاجها. يمكنك أيضًا استخدام FunctionChoiceBehavior.Required() لإجبار الذكاء الاصطناعي على استدعاء وظيفة واحدة على الأقل، أو تقديم قائمة محددة من الوظائف المسموح له باستخدامها.

استكمال الدردشة مع التاريخ

بالنسبة لتطبيقات المحادثة، ستحتاج إلى استخدام ChatCompletionService مباشرة مع كائن ChatHistory:

using Microsoft.SemanticKernel.ChatCompletion;

var chatService = kernel.GetRequiredService<IChatCompletionService>();
var history = new ChatHistory();

history.AddSystemMessage("""
 You are a helpful developer assistant. You have access to tools
 for checking the time and weather. Be concise and friendly.
 """);

while (true)
{
 Console.Write("You: ");
 var input = Console.ReadLine();
 if (string.IsNullOrWhiteSpace(input)) break;

 history.AddUserMessage(input);

 var response = await chatService.GetChatMessageContentAsync(
 history,
 executionSettings: settings,
 kernel: kernel
 );

 history.AddAssistantMessage(response.Content ?? "");
 Console.WriteLine($"Assistant: {response.Content}");
}

يمنحك هذا برنامج chatbot تفاعلي بالكامل يحافظ على سجل المحادثات ويمكنه استدعاء المكونات الإضافية حسب الحاجة.

الذاكرة والتضمينات

أحد أقوى الأنماط في تطبيقات الذكاء الاصطناعي هو الجيل المعزز للاسترجاع (RAG) — مما يتيح للذكاء الاصطناعي الوصول إلى بياناتك الخاصة عن طريق تضمينها في مساحة متجهة واسترداد الأجزاء ذات الصلة في وقت الاستعلام.

يوفر Semantic Kernel تجريدات للعمل مع مخازن المتجهات والتضمينات. فيما يلي كيفية إعداد متجر متجهات في الذاكرة للتطوير:

using Microsoft.Extensions.VectorData;
using Microsoft.SemanticKernel.Connectors.AzureOpenAI;
using Microsoft.SemanticKernel.Embeddings;

#pragma warning disable SKEXP0010

// Create an embedding generation service
var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAITextEmbeddingGeneration(
 deploymentName: "text-embedding-ada-002",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

var kernel = builder.Build();
var embeddingService = kernel.GetRequiredService<ITextEmbeddingGenerationService>();

// Generate embeddings for your documents
var documents = new[]
{
 "Semantic Kernel is an open-source SDK for AI orchestration.",
 "Azure OpenAI provides enterprise-grade AI models.",
 "Plugins in SK allow you to expose C# methods to AI models."
};

var embeddings = await embeddingService.GenerateEmbeddingsAsync(documents);

بالنسبة لسيناريوهات الإنتاج، يمكنك تخزين هذه التضمينات في قاعدة بيانات متجهة مخصصة مثل Azure AI Search أو Qdrant أو Pinecone. يحتوي Kernel الدلالي على موصلات لكل هذه الروابط من خلال تجريدات Microsoft.Extensions.VectorData.

يبدو تدفق RAG النموذجي كما يلي:

الاستيعاب: قم بتقطيع مستنداتك، وإنشاء التضمينات، وتخزينها في قاعدة بيانات متجهة
استرداد: عندما يطرح المستخدم سؤالاً، قم بتضمين الاستعلام وابحث عن المستندات الأكثر تشابهًا
إنشاء: قم بتمرير المستندات المستردة كسياق إلى LLM مع سؤال المستخدم

[KernelFunction("search_knowledge_base")]
[Description("Searches the internal knowledge base for relevant information")]
public async Task<string> SearchKnowledgeBase(
 [Description("The search query")] string query)
{
 var queryEmbedding = await _embeddingService.GenerateEmbeddingAsync(query);

 var results = await _vectorStore.SearchAsync(queryEmbedding, limit: 3);

 return string.Join("\n\n", results.Select(r => r.Text));
}

من خلال الكشف عن مسار RAG الخاص بك كوظيفة kernel، يمكن للذكاء الاصطناعي أن يقرر تلقائيًا متى يحتاج إلى البحث في قاعدة المعرفة الخاصة بك - مع الحفاظ على التنسيق نظيفًا والسماح للنموذج بالقيام بما يفعله على أفضل وجه.

المخططون والوكلاء

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

الأساسيات: وكيل إكمال الدردشة

أبسط نوع وكيل يغلف نموذج إكمال الدردشة مع التعليمات والمكونات الإضافية:

using Microsoft.SemanticKernel.Agents;

#pragma warning disable SKEXP0110

var agent = new ChatCompletionAgent
{
 Name = "DevAssistant",
 Instructions = """
 You are a senior .NET developer assistant. Help users with code
 reviews, architecture decisions, and debugging. Always provide
 code examples when relevant. Use your available tools to look up
 current information when needed.
 """,
 Kernel = kernel,
 Arguments = new KernelArguments(settings)
};

var history = new ChatHistory();

history.AddUserMessage("How should I structure a clean architecture project in .NET 8?");

await foreach (var message in agent.InvokeAsync(history))
{
 Console.WriteLine(message.Content);
 history.Add(message);
}

التعاون متعدد الوكلاء

تصبح الأمور قوية حقًا عندما يكون لديك وكلاء متعددون يعملون معًا. يدعم Semantic Kernel أنماط الدردشة الجماعية حيث يتعاون الوكلاء ذوو التخصصات المختلفة:

#pragma warning disable SKEXP0110

var codeReviewer = new ChatCompletionAgent
{
 Name = "CodeReviewer",
 Instructions = """
 You review C# code for bugs, performance issues, and best practices.
 Be specific about what you find and suggest concrete fixes.
 """,
 Kernel = kernel
};

var securityAuditor = new ChatCompletionAgent
{
 Name = "SecurityAuditor",
 Instructions = """
 You focus exclusively on security vulnerabilities in code.
 Look for injection attacks, authentication issues, data exposure,
 and OWASP Top 10 violations.
 """,
 Kernel = kernel
};

var groupChat = new AgentGroupChat(codeReviewer, securityAuditor)
{
 ExecutionSettings = new AgentGroupChatSettings
 {
 TerminationStrategy = new MaximumIterationTerminationStrategy(4)
 }
};

groupChat.AddChatMessage(
 new ChatMessageContent(AuthorRole.User, "Review this code: ...")
);

await foreach (var message in groupChat.InvokeAsync())
{
 Console.WriteLine($"[{message.AuthorName}]: {message.Content}");
}

يعد هذا النمط مفيدًا بشكل لا يصدق للمهام المعقدة التي تحتاج إلى مراعاة وجهات نظر أو مجالات خبرة مختلفة. يعمل كل وكيل بموجه النظام الخاص به ويمكن أن يكون لديه مجموعة خاصة به من المكونات الإضافية.

مثال من العالم الحقيقي: بناء مساعد توثيق المشروع

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

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;
using Microsoft.SemanticKernel.Connectors.OpenAI;
using System.ComponentModel;

// Define our plugins
public class FileSystemPlugin
{
 private readonly string _rootPath;

 public FileSystemPlugin(string rootPath)
 {
 _rootPath = rootPath;
 }

 [KernelFunction("read_file")]
 [Description("Reads the contents of a file from the project directory")]
 public async Task<string> ReadFile(
 [Description("Relative path to the file")] string path)
 {
 var fullPath = Path.Combine(_rootPath, path);

 if (!File.Exists(fullPath))
 return $"File not found: {path}";

 var content = await File.ReadAllTextAsync(fullPath);

 // Truncate very large files
 if (content.Length > 8000)
 content = content[..8000] + "\n... [truncated]";

 return content;
 }

 [KernelFunction("list_files")]
 [Description("Lists files in a directory, optionally filtered by extension")]
 public string ListFiles(
 [Description("Relative directory path")] string directory,
 [Description("File extension filter like '.cs' or '.json'")] string? extension = null)
 {
 var fullPath = Path.Combine(_rootPath, directory);

 if (!Directory.Exists(fullPath))
 return $"Directory not found: {directory}";

 var files = Directory.GetFiles(fullPath, "*.*", SearchOption.AllDirectories)
 .Select(f => Path.GetRelativePath(_rootPath, f))
 .Where(f => extension is null || f.EndsWith(extension))
 .Take(50);

 return string.Join("\n", files);
 }
}

public class DocumentationPlugin
{
 [KernelFunction("generate_summary")]
 [Description("Generates a structured markdown summary for documentation")]
 public string GenerateSummaryTemplate(
 [Description("Name of the component")] string componentName,
 [Description("Brief description")] string description,
 [Description("Key responsibilities as comma-separated values")] string responsibilities)
 {
 var items = responsibilities.Split(',', StringSplitOptions.TrimEntries);
 var bullets = string.Join("\n", items.Select(r => $"- {r}"));

 return $"""
 ## {componentName}

 {description}

 ### Responsibilities
 {bullets}

 ---
 *Generated documentation — review and expand as needed.*
 """;
 }
}

// Wire it all up
var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

builder.Plugins.AddFromObject(new FileSystemPlugin("./src"));
builder.Plugins.AddFromType<DocumentationPlugin>();

var kernel = builder.Build();

var chatService = kernel.GetRequiredService<IChatCompletionService>();
var history = new ChatHistory();

history.AddSystemMessage("""
 You are a codebase documentation assistant. You help developers understand
 projects by reading source files and explaining architecture, patterns,
 and design decisions.

 When asked about code, use your tools to read the actual files rather
 than guessing. Be specific and reference actual code when possible.
 Generate documentation artifacts when asked.
 """);

var settings = new OpenAIPromptExecutionSettings
{
 FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
};

Console.WriteLine("Documentation Assistant ready. Ask me about your codebase!");
Console.WriteLine("Type 'exit' to quit.\n");

while (true)
{
 Console.Write("You: ");
 var input = Console.ReadLine();

 if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
 break;

 history.AddUserMessage(input);

 var response = await chatService.GetChatMessageContentAsync(
 history,
 executionSettings: settings,
 kernel: kernel
 );

 Console.WriteLine($"\nAssistant: {response.Content}\n");
 history.AddAssistantMessage(response.Content ?? "");
}

يمكن لهذا المساعد:- إدراج الملفات وقراءتها من دليل مشروعك

أجب عن الأسئلة حول قاعدة التعليمات البرمجية من خلال قراءة ملفات المصدر الفعلية
إنشاء وثائق بتنسيق تخفيض السعر
حافظ على سياق المحادثة حتى تعمل أسئلة المتابعة بشكل طبيعي

يقرر الذكاء الاصطناعي تلقائيًا متى يتم الاتصال بـ read_file أو list_files أو generate_summary بناءً على ما تطلبه. اسأله “ماذا تفعل خدمة OrderService؟” وسوف يقرأ الملف ويحلله ويشرحه. اطلب منه “إنشاء وثائق لوحدة المصادقة” وسوف يستكشف الملفات ويفهم البنية وينتج ملخصًا منسقًا.

نصائح للإنتاج

قبل أن تقوم بشحن تطبيق Semantic Kernel الخاص بك، تعلمت بعض الأشياء بالطريقة الصعبة:

استخدم حقن التبعية بشكل صحيح. في تطبيقات ASP.NET Core، قم بتسجيل Kernel والخدمات في حاوية DI الخاصة بك بدلاً من إنشائها في السطر:

builder.Services.AddKernel()
 .AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: configuration["AzureOpenAI:Endpoint"]!,
 apiKey: configuration["AzureOpenAI:ApiKey"]!
 )
 .Plugins.AddFromType<TimePlugin>()
 .AddFromType<OrderPlugin>();

** التعامل مع الأخطاء بأمان. ** يمكن أن تفشل مكالمات LLM، أو تنقضي المهلة، أو ترجع نتائج غير متوقعة. قم بتجميع دعواتك في كتل محاولة الالتقاط وتنفيذ سياسات إعادة المحاولة باستخدام Polly أو ميزات المرونة المضمنة.

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

kernel.FunctionInvocationFilters.Add(new LoggingFilter());

حافظ على دقة أوصاف وظيفتك. تؤدي الأوصاف الغامضة إلى استدعاء وظائف الذكاء الاصطناعي بشكل غير صحيح. اختبر أوصافك عن طريق طرح السؤال التالي: “إذا قرأت الوصف فقط، فهل سأعرف بالضبط متى وكيف أستخدم هذه الوظيفة؟”

الخلاصة

Semantic Kernel هي إحدى تلك المكتبات التي تغير بشكل جذري طريقة تفكيرك في إنشاء التطبيقات. إنه ليس مجرد غلاف لواجهة برمجة التطبيقات - إنه إطار عمل للتنسيق يتيح لك إنشاء إمكانات الذكاء الاصطناعي باستخدام التعليمات البرمجية التقليدية بطريقة قابلة للصيانة والاختبار وجاهزة للإنتاج.

أكثر ما أحبه فيه هو أنه يحترم النظام البيئي .NET. فهو يستخدم الأنماط التي تعرفها بالفعل - حقن التبعية، والسمات، وعدم المزامنة/الانتظار، والواجهات - ويوسعها لتشمل عالم الذكاء الاصطناعي. ليس عليك أن تتعلم نموذجًا جديدًا تمامًا؛ ما عليك سوى إضافة الذكاء الاصطناعي كقدرة أخرى في مجموعة أدواتك.

إذا كنت تقوم بإنشاء تطبيقات .NET ولم تستكشف Semantic Kernel بعد، فهذا هو الوقت المناسب. تتميز مجموعة SDK بأنها مستقرة، والمجتمع نشط، والأنماط التي تتيحها - بدءًا من التنسيق السريع البسيط وحتى التعاون بين الوكلاء المتعددين - أصبحت مهارات أساسية للمطورين المعاصرين.

ابدأ صغيرًا. قم بإنشاء Kernel، وقم بتسجيل مكون إضافي، وشاهد الذكاء الاصطناعي وهو يتصل بالرمز الخاص بك. بمجرد النقر على ذلك، ستبدأ في رؤية فرص لإضافة الذكاء في كل مكان في تطبيقاتك.

تعد الوثائق الرسمية ومستودع GitHub من الموارد الممتازة لمواصلة رحلتك. بناء سعيد!

وراثة المكونات في Blazor

Thu, 04 Sep 2025 00:00:00 +0000

كنت أقوم بإنشاء مشروع يحتوي على مجموعة من صفحات النماذج، وكان لكل واحدة منها نفس منطق حالة التحميل، ونفس معالجة الأخطاء، ونفس إشعارات الخبز المحمص. بدا كل هذا خطأً في النسخ واللصق، لذلك بحثت في وراثة المكونات في Blazor. تبين أن الأمر بسيط جدًا نظرًا لأن مكونات Blazor هي مجرد فئات C#.

#الأساسيات

يرث كل مكون من مكونات Blazor من ComponentBase افتراضيًا. يمكنك إنشاء الفئة الأساسية الخاصة بك والتي تمتد ComponentBase ومن ثم ترث مكوناتك منها.

لنفترض أن معظم صفحاتنا تحتاج إلى حالة التحميل ومعالجة الأخطاء. يمكننا إنشاء فئة أساسية:

using Microsoft.AspNetCore.Components;

public abstract class PageBase : ComponentBase
{
 protected bool IsLoading { get; set; } = true;
 protected string? ErrorMessage { get; set; }

 protected async Task LoadDataAsync(Func<Task> action)
 {
 try
 {
 IsLoading = true;
 ErrorMessage = null;
 await action();
 }
 catch (Exception ex)
 {
 ErrorMessage = ex.Message;
 }
 finally
 {
 IsLoading = false;
 StateHasChanged();
 }
 }
}

استخدام الفئة الأساسية

الآن في أي مكون من مكونات الصفحة، بدلاً من الوراثة من ComponentBase، نرث من PageBase:

@page "/users"
@inherits PageBase

@if (IsLoading)
{
 <div class="spinner"></div>
}
else if (ErrorMessage is not null)
{
 <div class="alert alert-danger">@ErrorMessage</div>
}
else
{
 <ul>
 @foreach (var user in users)
 {
 <li>@user.Name</li>
 }
 </ul>
}

@code {
 private List<User> users = new();

 protected override async Task OnInitializedAsync()
 {
 await LoadDataAsync(async () =>
 {
 users = await Http.GetFromJsonAsync<List<User>>("api/users");
 });
 }
}

التوجيه @inherits PageBase هو المفتاح. يطلب من Blazor استخدام الفئة الأساسية لدينا بدلاً من الفئة الافتراضية ComponentBase. الآن نحصل على IsLoading و ErrorMessage و LoadDataAsync() مجانًا في كل صفحة ترث منه.

حقن الخدمات في الفئة الأساسية

يمكنك أيضًا إدخال الخدمات في الفئة الأساسية بحيث تكون متاحة لجميع المكونات الفرعية:

public abstract class PageBase : ComponentBase
{
 [Inject]
 protected NavigationManager Navigation { get; set; } = default!;

 [Inject]
 protected IToastService Toast { get; set; } = default!;

 protected bool IsLoading { get; set; } = true;
 protected string? ErrorMessage { get; set; }

 protected void NavigateBack() => Navigation.NavigateTo("javascript:history.back()");

 protected void ShowSuccess(string message) => Toast.ShowSuccess(message);
}

كل مكون يرث من PageBase لديه الآن إمكانية الوصول إلى Navigation، Toast، NavigateBack()، و ShowSuccess() دون الحاجة إلى حقن أي شيء.

التعمق أكثر مع الفئات الأساسية العامة

يمكنك أيضًا إنشاء فئات أساسية عامة لأنماط CRUD الشائعة:

public abstract class CrudPageBase<T> : PageBase
{
 protected List<T> Items { get; set; } = new();
 protected T? SelectedItem { get; set; }

 protected abstract Task<List<T>> FetchItems();
 protected abstract Task DeleteItem(T item);

 protected override async Task OnInitializedAsync()
 {
 await LoadDataAsync(async () =>
 {
 Items = await FetchItems();
 });
 }

 protected async Task OnDelete(T item)
 {
 await LoadDataAsync(async () =>
 {
 await DeleteItem(item);
 Items = await FetchItems();
 ShowSuccess("Item deleted.");
 });
 }
}

ثم تصبح صفحتك الفعلية نظيفة للغاية:

@page "/products"
@inherits CrudPageBase<Product>

@* just the markup, all logic lives in the base class *@

@code {
 protected override Task<List<Product>> FetchItems()
 => Http.GetFromJsonAsync<List<Product>>("api/products");

 protected override Task DeleteItem(Product item)
 => Http.DeleteAsync($"api/products/{item.Id}");
}

#متى تستخدمه ومتى لا تستخدمه

يعد وراثة المكونات أمرًا رائعًا للسلوك المشترك مثل حالات التحميل أو معالجة الأخطاء أو عمليات التحقق من المصادقة أو أنماط CRUD. لكن لا تبالغ في استخدام التسلسلات الهرمية العميقة للوراثة - إذا وجدت نفسك تتعمق أكثر من مستويين، فمن الأفضل أن تكون في وضع أفضل مع التركيب (مثل نهج LoadingComponent من منشور سابق).

عادةً ما أحتفظ بها في فئة أساسية واحدة لكل “نوع” من الصفحة: PageBase للصفحات العادية، FormPageBase للنماذج، وهذا كل ما في الأمر.

آمل أن تكونوا قد أحببت هذا المنصب! لا تتردد في الاتصال بي على أي وسائل التواصل الاجتماعي على **@emimontesdeoca **.

الموارد

وراثة مكون ASP.NET Core Razor

.NET Aspire: بناء التطبيقات السحابية الأصلية بالطريقة الصحيحة

Wed, 20 Aug 2025 00:00:00 +0000

إذا سبق لك إنشاء تطبيق موزع في .NET، فأنت تعرف التدريبات. يمكنك تشغيل واجهة برمجة تطبيقات الويب، وإضافة عامل في الخلفية، واستخدام Redis للتخزين المؤقت، وPostgreSQL للاستمرارية، وربما RabbitMQ للمراسلة - وفجأة تقضي وقتًا أطول في توصيل البنية التحتية بدلاً من كتابة منطق الأعمال. سلاسل الاتصال متناثرة عبر ملفات appsettings.json، والفحوصات الصحية التي نسيت تهيئتها، وإمكانية المراقبة التي تعد دائمًا “مشكلة السباق التالي.”

لقد كنت هناك. مرات أكثر مما أود أن أعترف به.

هذه هي بالضبط المشكلة التي تم تصميم .NET Aspire لحلها. بعد تشغيله في مرحلة الإنتاج لعدة أشهر، أريد أن أشارككم ما تعلمته - الأشياء الجيدة والعظيمة والصعبة.

ما هو .NET Aspire؟

إن .NET Aspire هو عبارة عن حزمة مدروسة لإنشاء تطبيقات يمكن ملاحظتها وجاهزة للإنتاج وموزعة باستخدام .NET. إنه ليس إطار عمل بالمعنى التقليدي — فهو لا يحل محل ASP.NET Core ولا يجبرك على اتباع نموذج برمجة جديد. وبدلاً من ذلك، فهو يرتكز على ما تعرفه بالفعل ويسد الفجوات التي كانت موجودة دائمًا عند إنشاء تطبيقات سحابية أصلية.

في جوهرها، أسباير يمنحك أربعة أشياء:

AppHost — مشروع يحدد هيكل التطبيق الموزع بالكامل. ما هي الخدمات الموجودة، وما الذي تعتمد عليه، وكيفية اتصالها.
افتراضيات الخدمة — مشروع مشترك يقوم بتكوين الاهتمامات الشاملة مثل فحوصات السلامة وسياسات المرونة وOpenTelemetry — مرة واحدة لجميع خدماتك.
المكونات — حزم NuGet التي توفر عمليات تكامل موحدة مع خدمات الدعم مثل Redis وPostgreSQL وRabbitMQ وAzure Storage والمزيد.
لوحة تحكم المطور — واجهة مستخدم في الوقت الفعلي تعرض السجلات والتتبعات والمقاييس لتطبيقك الموزع بالكامل أثناء التطوير المحلي.

الفلسفة بسيطة: إذا كان كل تطبيق سحابي .NET يحتاج إلى هذه الأشياء، فلماذا نقوم جميعًا بتنفيذها من الصفر في كل مرة؟

إعداد مشروعك الأول أسباير

البدء واضح ومباشر. ستحتاج إلى .NET 8 أو إصدار أحدث وتثبيت حمل عمل Aspire:

dotnet workload update
dotnet workload install aspire

الآن أنشئ مشروعًا جديدًا لـ Aspire:

dotnet new aspire-starter -n MyCloudApp

يؤدي هذا إلى إنشاء حل بأربعة مشاريع:

MyCloudApp.AppHost — المنسق
MyCloudApp.ServiceDefaults — التكوين المشترك
MyCloudApp.ApiService — نموذج لواجهة برمجة تطبيقات الويب
MyCloudApp.Web — واجهة Blazor الأمامية

قم بتشغيل AppHost وسترى على الفور لوحة تحكم Aspire مفتوحة في متصفحك، وتعرض جميع خدماتك وسجلاتها وحالتها الصحية. لا يوجد ملف Docker Compose. لا توجد إدارة يدوية للمنافذ. إنه يعمل فقط.

dotnet run --project MyCloudApp.AppHost

تلك التجربة الأولى هي ما أذهلتني. في أقل من دقيقة، سيكون لديك تطبيق موزع منسق بالكامل مع إمكانية المراقبة.

نمط AppHost

AppHost هو المكان الذي يعيش فيه السحر. إنه تطبيق وحدة تحكم صغير يستخدم نمط البناء لتحديد طوبولوجيا تطبيقك الموزع - ما هي الموارد الموجودة وكيفية اتصال الخدمات بها.

إليك ما يبدو عليه AppHost الواقعي:

var builder = DistributedApplication.CreateBuilder(args);

// Infrastructure resources
var postgres = builder.AddPostgres("postgres")
 .WithPgAdmin()
 .AddDatabase("catalogdb");

var redis = builder.AddRedis("cache");

var rabbitmq = builder.AddRabbitMQ("messaging")
 .WithManagementPlugin();

// Application services
var catalogApi = builder.AddProject<Projects.CatalogApi>("catalog-api")
 .WithReference(postgres)
 .WithReference(redis)
 .WithReference(rabbitmq);

var orderApi = builder.AddProject<Projects.OrderApi>("order-api")
 .WithReference(postgres)
 .WithReference(rabbitmq);

var frontend = builder.AddProject<Projects.WebFrontend>("frontend")
 .WithExternalHttpEndpoints()
 .WithReference(catalogApi)
 .WithReference(orderApi);

builder.Build().Run();
```اقرأ هذا الرمز بصوت عالٍ. إنه يوثق نفسه عمليا. "تشير واجهة برمجة تطبيقات الكتالوج إلى PostgreSQL وRedis وRabbitMQ. وتشير الواجهة الأمامية إلى واجهة برمجة تطبيقات الكتالوج وواجهة برمجة تطبيقات الطلب." هذه هي الهندسة المعمارية الخاصة بك، معبرًا عنها بالكود.

بعض الأشياء الجديرة بالملاحظة:

- **`WithReference`** يقوم برفع الأحمال الثقيلة. يقوم تلقائيًا بإدخال سلاسل الاتصال وعناوين URL الخاصة بالخدمة في المشروع المستهلك عبر متغيرات البيئة والتكوين. لا تحتاج خدماتك إلى معرفة *مكان* تشغيل Redis — حيث تتولى Aspire ذلك.
- **`WithPgAdmin()`** و **`WithManagementPlugin()`** يقومان بتدوير واجهات المستخدم الإدارية لـ PostgreSQL وRabbitMQ إلى جانب الخدمات الفعلية. أثناء التطوير، هذه لا تقدر بثمن.
- **`WithExternalHttpEndpoints()`** يضع علامة على الخدمة على أنها يمكن الوصول إليها خارجيًا، وهو أمر مهم في وقت النشر.

### تكوين الموارد

يمكنك تكوين الموارد من خلال التحكم الدقيق:

```csharp
var postgres = builder.AddPostgres("postgres")
 .WithEnvironment("POSTGRES_MAX_CONNECTIONS", "200")
 .WithDataVolume("postgres-data")
 .AddDatabase("catalogdb");

var redis = builder.AddRedis("cache")
 .WithDataVolume("redis-data");

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

افتراضيات الخدمة: البطل المجهول

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

إليك ما يبدو عليه Extensions.cs النموذجي في ServiceDefaults:

public static class Extensions
{
 public static IHostApplicationBuilder AddServiceDefaults(
 this IHostApplicationBuilder builder)
 {
 builder.ConfigureOpenTelemetry();
 builder.AddDefaultHealthChecks();
 builder.Services.AddServiceDiscovery();

 builder.Services.ConfigureHttpClientDefaults(http =>
 {
 http.AddStandardResilienceHandler();
 http.AddServiceDiscovery();
 });

 return builder;
 }

 public static IHostApplicationBuilder ConfigureOpenTelemetry(
 this IHostApplicationBuilder builder)
 {
 builder.Logging.AddOpenTelemetry(logging =>
 {
 logging.IncludeFormattedMessage = true;
 logging.IncludeScopes = true;
 });

 builder.Services.AddOpenTelemetry()
 .WithMetrics(metrics =>
 {
 metrics.AddAspNetCoreInstrumentation()
 .AddHttpClientInstrumentation()
 .AddRuntimeInstrumentation();
 })
 .WithTracing(tracing =>
 {
 tracing.AddAspNetCoreInstrumentation()
 .AddHttpClientInstrumentation()
 .AddGrpcClientInstrumentation();
 });

 builder.AddOpenTelemetryExporters();
 return builder;
 }

 public static IHostApplicationBuilder AddDefaultHealthChecks(
 this IHostApplicationBuilder builder)
 {
 builder.Services.AddHealthChecks()
 .AddCheck("self", () => HealthCheckResult.Healthy(),
 ["live"]);

 return builder;
 }
}

ثم في Program.cs لكل خدمة، سطر واحد يفعل كل شيء:

var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();

// Your service-specific configuration...

var app = builder.Build();
app.MapDefaultEndpoints();
app.Run();

تمنحك هذه المكالمة الفردية AddServiceDefaults() ما يلي:

OpenTelemetry مع التسجيل المنظم والمقاييس والتتبع الموزع
فحوصات السلامة مع نقاط النهاية الحيوية والاستعداد
اكتشاف الخدمة حتى تتمكن الخدمات من العثور على بعضها البعض بالاسم
سياسات المرونة في جميع مكالمات HTTP الصادرة (إعادة المحاولة، وقواطع الدائرة، والمهلات)

هذه هي الأشياء التي تفصل بين العرض التوضيحي “يعمل على جهازي” وبين النظام الجاهز للإنتاج. وأسباير تجعلها الخيار الافتراضي، وليس فكرة لاحقة.

مكونات أسباير

مكونات Aspire هي حزم NuGet التي تعمل على توحيد كيفية اتصال خدماتك بالبنية التحتية الداعمة. إنها أكثر من مجرد مكتبات عملاء - فهي تشمل عمليات التحقق من السلامة والتسجيل والتتبع والمرونة القابلة للتكوين خارج الصندوق.

ريديس

var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();
builder.AddRedisDistributedCache("cache");

هذا كل شيء. تأتي سلسلة الاتصال من AppHost عبر WithReference. يسجل المكون IDistributedCache مدعومًا بواسطة Redis، مع فحوصات السلامة وأجهزة OpenTelemetry التي تم توصيلها بالفعل.

يمكنك أيضًا استخدام Redis للتخزين المؤقت للمخرجات:

builder.AddRedisOutputCache("cache");

PostgreSQL مع Entity Framework Core

builder.AddNpgsqlDbContext<CatalogDbContext>("catalogdb", settings =>
{
 settings.DisableRetry = false;
});

يؤدي هذا إلى تسجيل DbContext الخاص بك من خلال اتصال بقاعدة بيانات catalogdb المحددة في AppHost. ويتضمن تجميع الاتصالات والفحوصات الصحية وسياسات إعادة المحاولة.

رابيتMQ

builder.AddRabbitMQClient("messaging");

تسجيل IConnection من مكتبة عملاء RabbitMQ، تم تكوينها بالكامل وفحص صحتها.

تكاملات أزور

تمتلك Aspire أيضًا مكونات من الدرجة الأولى لخدمات Azure:

// Azure Blob Storage
builder.AddAzureBlobClient("blobs");

// Azure Service Bus
builder.AddAzureServiceBusClient("servicebus");

// Azure Key Vault
builder.AddAzureKeyVaultClient("secrets");
```النمط دائمًا هو نفسه: سطر واحد في AppHost لتحديد المورد، وسطر واحد في الخدمة المستهلكة لاستخدامه. تتدفق تفاصيل الاتصال تلقائيًا.

## لوحة تحكم المطور

تعد لوحة معلومات Aspire واحدة من تلك الميزات التي تبدو وكأنها من الأشياء الرائعة حتى تستخدمها فعليًا - فلا يمكنك تخيل العمل بدونها.

عند تشغيل AppHost محليًا، يتم تشغيل لوحة المعلومات وتمنحك:

- **نظرة عامة على الموارد** — نظرة سريعة على جميع خدماتك وبنيتك التحتية، مع مؤشرات الحالة
- **السجلات المنظمة** — سجل يتدفق في الوقت الفعلي من كل خدمة، قابل للتصفية والبحث
- **الآثار الموزعة** — آثار الطلب الشاملة التي تغطي خدمات متعددة، والتي يتم تصورها على شكل مخططات توضيحية
- **المقاييس** — معدلات طلبات HTTP، ومعدلات الخطأ، وزمن الاستجابة، والمقاييس المخصصة في الوقت الفعلي
- **سجلات وحدة التحكم** — stdout/stderr الأولي من كل حاوية ومشروع

التتبع الموزع له قيمة خاصة. عندما يصل طلب إلى الواجهة الأمامية لديك، يتدفق عبر واجهة برمجة تطبيقات الكتالوج، ويلمس Redis وPostgreSQL - ترى السلسلة بأكملها مع توقيت كل قفزة. لا مزيد من التخمين أين هو عنق الزجاجة.

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

لوحة المعلومات متاحة أيضًا كحاوية مستقلة، مما يعني أنه يمكنك استخدامها في البيئات المرحلية أو خطوط أنابيب CI:

```bash
docker run --rm -p 18888:18888 \
 mcr.microsoft.com/dotnet/aspire-dashboard:latest

النشر

أسباير تساعد أثناء التطوير، لكن ماذا عن الإنتاج؟ هذا هو المكان الذي تصبح فيه الأمور عملية.

تطبيقات حاوية Azure

مسار النشر الأكثر وضوحًا هو Azure Container Apps (ACA)، الذي يتمتع بدعم Aspire من الدرجة الأولى. يمكنك النشر مباشرة باستخدام Azure Developer CLI:

azd init
azd up

يكتشف الأمر azd init Aspire AppHost الخاص بك ويقوم بإنشاء البنية التحتية الضرورية كرمز. azd up يوفر كل شيء — سجل الحاوية، وتطبيقات الحاوية، وقواعد البيانات، ومثيلات Redis — استنادًا إلى طوبولوجيا AppHost لديك.

يصبح AppHost الخاص بك بشكل أساسي بيان النشر الخاص بك. نفس الكود الذي يحدد “catalog-api يعتمد على PostgreSQL وRedis” هو الذي يحرك عملية توفير البنية التحتية.

كوبيرنيت

بالنسبة لعمليات نشر Kubernetes، لا تقوم Aspire بإنشاء البيانات مباشرة، ولكن طوبولوجيا AppHost الخاصة بك تتوافق بشكل واضح مع موارد Kubernetes. يمكن لأداة المجتمع aspirate (Aspir8) إنشاء مخططات Helm أو بيانات Kubernetes من AppHost الخاص بك:

dotnet tool install -g aspirate
aspirate generate
aspirate apply

اعتبارات النشر

بعض الأشياء التي يجب وضعها في الاعتبار:- تتغير سلاسل الاتصال بين البيئات. محليًا، يقوم Aspire بتدوير الحاويات وإدخال سلاسل الاتصال تلقائيًا. في الإنتاج، ستشير إلى الخدمات المُدارة. يستخدم Aspire تكوين .NET القياسي، لذا تعمل متغيرات البيئة وAzure Key Vault كما هو متوقع.

لا يعمل AppHost في مرحلة الإنتاج. إنه أداة تنسيق للتطوير والنشر. في مرحلة الإنتاج، تعمل خدماتك بشكل مستقل، ويتم تكوينها من خلال متغيرات البيئة والمنسقين.
تتحول موارد البنية التحتية إلى خدمات مُدارة. تصبح حاوية PostgreSQL المحلية الخاصة بك هي قاعدة بيانات Azure لـ PostgreSQL. تصبح حاوية Redis المحلية لديك عبارة عن Azure Cache لـ Redis. كود الاستهلاك لا يتغير

نصائح من العالم الحقيقي

بعد تشغيل Aspire في الإنتاج لفترة من الوقت، إليكم الدروس التي وفرت لنا الوقت:

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

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

var postgres = builder.AddPostgres("postgres")
 .AddDatabase("catalogdb")
 .WithHealthCheck();

يمكن لـ Aspire إجراء فحوصات صحية على الموارد والاحتفاظ بالخدمات التابعة حتى تصبح جاهزة بالفعل.

2. استخراج الأنماط الشائعة إلى الامتدادات

إذا كانت هناك خدمات متعددة تشترك في تكوينات مماثلة، فقم بإنشاء طرق ملحقة:

public static class AppHostExtensions
{
 public static IResourceBuilder<ProjectResource> AddWorkerService(
 this IDistributedApplicationBuilder builder,
 string name,
 IResourceBuilder<IResourceWithConnectionString> db,
 IResourceBuilder<IResourceWithConnectionString> messaging)
 {
 return builder.AddProject<Projects.WorkerService>(name)
 .WithReference(db)
 .WithReference(messaging)
 .WithReplicas(3);
 }
}

3. الاستفادة من النسخ المتماثلة لاختبار التحميل

var catalogApi = builder.AddProject<Projects.CatalogApi>("catalog-api")
 .WithReference(postgres)
 .WithReference(redis)
 .WithReplicas(5);

WithReplicas يقوم بتدوير مثيلات متعددة للخدمة محليًا. يعد هذا أمرًا رائعًا لاختبار موازنة التحميل وأخطاء التزامن وسلوك التخزين المؤقت الموزع دون النشر إلى مجموعة.

4. استخدم المعلمات للقيم الحساسة

لا تقم بتشفير بيانات الاعتماد، حتى بالنسبة للتنمية المحلية:

var dbPassword = builder.AddParameter("db-password", secret: true);

var postgres = builder.AddPostgres("postgres", password: dbPassword)
 .AddDatabase("catalogdb");

عند التشغيل محليًا، سيطالبك Aspire بالقيمة أو يقرأها من أسرار المستخدم. في CI/CD، يأتي من متغيرات البيئة.

5. اختبارات التكامل تصبح تافهة

تتضمن Aspire حزمة اختبار تجعل اختبار التكامل للتطبيقات الموزعة أمرًا سهلاً بشكل ملحوظ:

[Fact]
public async Task CatalogApiReturnsProducts()
{
 var appHost = await DistributedApplicationTestingBuilder
 .CreateAsync<Projects.MyCloudApp_AppHost>();

 await using var app = await appHost.BuildAsync();
 await app.StartAsync();

 var httpClient = app.CreateHttpClient("catalog-api");
 var response = await httpClient.GetAsync("/api/products");

 response.EnsureSuccessStatusCode();

 var products = await response.Content
 .ReadFromJsonAsync<List<Product>>();
 Assert.NotEmpty(products);
}

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

6. مراقبة استخدام الموارد محليًا

عند تشغيل حاويات متعددة محليًا، راقب استهلاك الموارد. يمكن لمثيل PostgreSQL وRedis وRabbitMQ المزود بواجهة مستخدم الإدارة أن يستهلك بسهولة 2-3 جيجابايت من ذاكرة الوصول العشوائي. إذا كنت تستخدم جهازًا مقيدًا، ففكر في استخدام تكوينات موارد أخف:

var redis = builder.AddRedis("cache")
 .WithContainerRuntimeArgs("--memory=256m");

الخلاصة

لقد غيّر .NET Aspire بشكل أساسي طريقة إنشاء التطبيقات الموزعة. ليس لأنه يقدم مفاهيم ثورية - فالفحوصات الصحية، وقياس OpenTelemetry، وتنسيق الحاويات ليست جديدة. ولكن لأنها تجعلها افتراضية. فهو يأخذ مئات القرارات الصغيرة التي يتعين عليك اتخاذها عادةً، وينفذها بافتراضيات معقولة، ويتيح لك تجاوزها عند الحاجة.نمط AppHost، في رأيي، هو أكبر فوز. إن التعبير عن طوبولوجيا التطبيق الموزعة على شكل تعليمات برمجية - غير متناثرة عبر ملفات Docker Compose، وبيانات Kubernetes، ومستندات README - يجعل النظام مفهومًا. يمكن لأعضاء الفريق الجدد فتح Program.cs في AppHost وفهم البنية بأكملها في دقائق.

إذا كنت تقوم بإنشاء تطبيقات موزعة باستخدام .NET، فامنح Aspire نظرة جادة. ابدأ بالقالب aspire-starter، واستكشف لوحة المعلومات، واستخدم المكونات تدريجيًا حسب حاجتك إليها. ليس عليك أن تبذل كل ما في وسعك في اليوم الأول، فشركة Aspire هي شركة إضافية من حيث تصميمها.

لقد ولت أيام قضاء أول سباق سريع في توصيل البنية الأساسية للبنية الأساسية. اسمح لشركة Aspire بالتعامل مع أعمال السباكة حتى تتمكن من التركيز على ما يهم فعليًا: تطبيقك.

المصادقة والترخيص في Blazor: دليل عملي

Sat, 12 Jul 2025 00:00:00 +0000

إذا كنت قد عملت مع ASP.NET MVC أو Razor Pages، فمن المحتمل أن يكون لديك نموذج عقلي لكيفية عمل المصادقة: تعترض البرامج الوسيطة الطلب، وتتحقق من ملف تعريف الارتباط أو الرمز المميز، وتملأ HttpContext.User، وأنت خارج السباقات. يقوم Blazor بتغيير هذا النموذج العقلي بطرق دقيقة ولكنها مهمة - وإذا لم تفهم هذه الاختلافات مبكرًا، فسوف ينتهي بك الأمر إلى تصحيح مشكلات المصادقة التي تبدو مستحيلة.

في هذا المنشور، أريد أن أتعرف على كيفية عمل المصادقة والتفويض فعليًا في Blazor، والذي يغطي نماذج استضافة الخادم وWebAssembly. سننتقل من الأساسيات إلى موفري الخدمات المخصصين وبروتوكول OAuth الخارجي والمزالق التي رأيتها حتى مطوري .NET ذوي الخبرة.

لماذا تختلف المصادقة في Blazor

في ASP.NET التقليدي، كل تفاعل للمستخدم هو طلب HTTP. يتحقق الخادم من صحة بيانات الاعتماد، ويعين ملف تعريف الارتباط، وكل طلب لاحق يحمل ملف تعريف الارتباط هذا. خط أنابيب المصادقة خطي ويمكن التنبؤ به.

يعمل Blazor Server عبر اتصال SignalR المستمر. بعد أن يقوم طلب HTTP الأولي بتحميل الصفحة، تحدث جميع التفاعلات اللاحقة عبر WebSockets. لا يوجد طلب HTTP جديد لكل نقرة على الزر، لذلك لا يتم إعادة تنفيذ البرامج الوسيطة في كل تفاعل. يتوفر HttpContext أثناء الاتصال الأولي، ولكن الاعتماد عليه طوال عمر الدائرة يعد بمثابة وصفة للأخطاء.

يعمل Blazor WebAssembly بالكامل في المتصفح. لا يوجد HttpContext من جانب الخادم على الإطلاق. يجب جلب حالة المصادقة من واجهة برمجة التطبيقات (API)، وتخزينها من جانب العميل، وإدارتها من خلال الرموز المميزة - عادةً JWTs. يثق الخادم بالعميل فقط فيما يتعلق بالتحقق من صحة الرمز المميز.

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

حالة المصادقة: المؤسسة

يقع AuthenticationStateProvider في قلب نظام مصادقة Blazor. هذه فئة مجردة تكشف عن طريقة حاسمة واحدة:

public abstract Task<AuthenticationState> GetAuthenticationStateAsync();

يلتف الكائن AuthenticationState بـ ClaimsPrincipal — وهو نفس نموذج الهوية المستخدم في .NET. لا تتصل المكونات بملفات تعريف الارتباط أو الرموز المميزة مباشرةً؛ يسألون AuthenticationStateProvider عن الحالة الحالية.

لجعل هذه الحالة متاحة لشجرة المكونات بأكملها، يوفر Blazor CascadingAuthenticationState. عادةً ما تقوم بتغليف جهاز التوجيه الخاص بك به في App.razor أو في تخطيطك:

<CascadingAuthenticationState>
 <Router AppAssembly="@typeof(App).Assembly">
 <Found Context="routeData">
 <AuthorizeRouteView RouteData="@routeData"
 DefaultLayout="@typeof(MainLayout)">
 <NotAuthorized>
 <p>You're not authorized to view this page.</p>
 </NotAuthorized>
 </AuthorizeRouteView>
 </Found>
 <NotFound>
 <LayoutView Layout="@typeof(MainLayout)">
 <p>Page not found.</p>
 </LayoutView>
 </NotFound>
 </Router>
</CascadingAuthenticationState>

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

في .NET 8 والإصدارات الأحدث مع نموذج Blazor الموحد، ستقوم بتكوين هذا في App.razor وسيتعامل إطار العمل مع المعلمة المتتالية تلقائيًا عند استخدام AddCascadingAuthenticationState() في تسجيل الخدمة الخاصة بك.

تكامل هوية ASP.NET

بالنسبة لمعظم المشاريع، لا تحتاج إلى إنشاء مصادقة من الصفر. تمنحك هوية ASP.NET إدارة المستخدم، وتجزئة كلمة المرور، والمصادقة الثنائية، وتأكيد الحساب خارج الصندوق.يبدأ إعداده باستخدام Blazor في Program.cs:

builder.Services.AddDbContext<ApplicationDbContext>(options =>
 options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));

builder.Services.AddDefaultIdentity<IdentityUser>(options =>
 {
 options.SignIn.RequireConfirmedAccount = true;
 options.Password.RequireDigit = true;
 options.Password.RequiredLength = 8;
 })
 .AddRoles<IdentityRole>()
 .AddEntityFrameworkStores<ApplicationDbContext>();

builder.Services.AddAuthentication(options =>
 {
 options.DefaultScheme = IdentityConstants.ApplicationScheme;
 options.DefaultSignInScheme = IdentityConstants.ExternalScheme;
 });

باستخدام قالب Blazor Web App في .NET 8+، تستخدم واجهة مستخدم الهوية المدعومة مكونات Razor مباشرةً. يمكنك الحصول على صفحات تسجيل الدخول والتسجيل وإدارة الحساب التي تتكامل بشكل طبيعي مع بقية تطبيق Blazor الخاص بك - لم يعد هناك مزيج غريب من صفحات Razor ومكونات Blazor.

يرث ApplicationDbContext من IdentityDbContext وستحتاج إلى تشغيل عمليات الترحيل لإنشاء جداول الهوية:

public class ApplicationDbContext : IdentityDbContext<IdentityUser>
{
 public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
 : base(options) { }
}

dotnet ef migrations add InitialIdentity
dotnet ef database update

مكون AuthorizeView

بمجرد تدفق حالة المصادقة عبر شجرة المكونات الخاصة بك، يتيح لك AuthorizeView عرض واجهة المستخدم بشكل مشروط:

<AuthorizeView>
 <Authorized>
 <p>Welcome, @context.User.Identity?.Name!</p>
 <a href="/account/manage">Manage Account</a>
 <form method="post" action="/account/logout">
 <button type="submit">Log Out</button>
 </form>
 </Authorized>
 <NotAuthorized>
 <a href="/account/login">Log In</a>
 <a href="/account/register">Register</a>
 </NotAuthorized>
</AuthorizeView>

تتيح لك المعلمة context داخل <Authorized> الوصول إلى AuthenticationState، حتى تتمكن من فحص المطالبات والأدوار وهوية المستخدم مباشرة في الترميز الخاص بك.

يمكنك أيضًا استخدام AuthorizeView مع الأدوار والسياسات:

<AuthorizeView Roles="Admin,Moderator">
 <Authorized>
 <button @onclick="DeletePost">Delete Post</button>
 </Authorized>
</AuthorizeView>

<AuthorizeView Policy="CanEditArticles">
 <Authorized>
 <button @onclick="EditArticle">Edit</button>
 </Authorized>
</AuthorizeView>

هناك شيء واحد يجب أخذه في الاعتبار: AuthorizeView هو أحد اهتمامات واجهة المستخدم. فهو يخفي العناصر أو يظهرها، لكنه لا يحمي المنطق الأساسي. إذا كان بإمكان شخص ما الاتصال بنقطة نهاية واجهة برمجة التطبيقات (API) الخاصة بك أو استدعاء طريقتك مباشرة، فسيتجاوز AuthorizeView بالكامل. قم دائمًا بفرض الترخيص على جانب الخادم أيضًا.

السمة [التفويض]

لحماية صفحة بأكملها، قم بتطبيق السمة [Authorize]:

@page "/admin/dashboard"
@attribute [Authorize(Roles = "Admin")]

<h1>Admin Dashboard</h1>
<p>Only administrators can see this page.</p>

عندما ينتقل مستخدم غير مصادق إلى هذه الصفحة، يبدأ AuthorizeRouteView ويعرض القالب <NotAuthorized> الذي حددته مسبقًا. يمكنك إعادة التوجيه إلى صفحة تسجيل الدخول بدلاً من ذلك عن طريق التعامل مع حالة NotAuthorized مع التنقل:

<NotAuthorized>
 @if (!context.User.Identity?.IsAuthenticated ?? true)
 {
 <RedirectToLogin />
 }
 else
 {
 <p>You don't have permission to access this page.</p>
 }
</NotAuthorized>

قد يبدو مكون RedirectToLogin البسيط كما يلي:

@inject NavigationManager Navigation

@code {
 protected override void OnInitialized()
 {
 var returnUrl = Uri.EscapeDataString(Navigation.Uri);
 Navigation.NavigateTo($"/account/login?returnUrl={returnUrl}", forceLoad: true);
 }
}

يعد forceLoad: true مهمًا هنا - فأنت تريد تنقلًا فعليًا عبر HTTP حتى تتمكن البرامج الوسيطة للمصادقة من جانب الخادم من التعامل مع تدفق تسجيل الدخول بشكل صحيح.

التفويض المستند إلى الدور والسياسة

الأدوار هي أبسط نموذج: قم بتعيين المستخدمين إلى مجموعات مثل “المسؤول” أو “المحرر”، ثم تحقق من العضوية. لكن السياسات تمنحك مرونة أكبر بكثير.

تسجيل السياسات في Program.cs:

builder.Services.AddAuthorizationCore(options =>
{
 options.AddPolicy("CanPublish", policy =>
 policy.RequireClaim("Permission", "Publish"));

 options.AddPolicy("MinimumAge", policy =>
 policy.Requirements.Add(new MinimumAgeRequirement(18)));

 options.AddPolicy("PremiumUser", policy =>
 policy.RequireRole("Premium")
 .RequireClaim("Subscription", "Active"));
});

المتطلبات المخصصة تحتاج إلى معالج:

public class MinimumAgeRequirement : IAuthorizationRequirement
{
 public int MinimumAge { get; }
 public MinimumAgeRequirement(int minimumAge) => MinimumAge = minimumAge;
}

public class MinimumAgeHandler : AuthorizationHandler<MinimumAgeRequirement>
{
 protected override Task HandleRequirementAsync(
 AuthorizationHandlerContext context,
 MinimumAgeRequirement requirement)
 {
 var dateOfBirthClaim = context.User.FindFirst("DateOfBirth");

 if (dateOfBirthClaim is null)
 return Task.CompletedTask;

 var dateOfBirth = DateOnly.Parse(dateOfBirthClaim.Value);
 var age = DateOnly.FromDateTime(DateTime.Today).Year - dateOfBirth.Year;

 if (age >= requirement.MinimumAge)
 context.Succeed(requirement);

 return Task.CompletedTask;
 }
}

تسجيل المعالج:

builder.Services.AddSingleton<IAuthorizationHandler, MinimumAgeHandler>();

في المكونات، يمكنك أيضًا التحقق من الترخيص برمجيًا عندما تحتاج إلى منطق ديناميكي:

@inject IAuthorizationService AuthorizationService
@inject AuthenticationStateProvider AuthStateProvider

@code {
 private bool canPublish;

 protected override async Task OnInitializedAsync()
 {
 var authState = await AuthStateProvider.GetAuthenticationStateAsync();
 var result = await AuthorizationService.AuthorizeAsync(
 authState.User, "CanPublish");
 canPublish = result.Succeeded;
 }
}

موفري OAuth الخارجيين

يعد دعم “تسجيل الدخول باستخدام Google” أو “تسجيل الدخول باستخدام GitHub” أمرًا مباشرًا باستخدام البرنامج الوسيط لمصادقة ASP.NET. تم تكوينها من جانب الخادم نظرًا لأن تدفق OAuth يتطلب عمليات إعادة توجيه HTTP.

builder.Services.AddAuthentication()
 .AddGoogle(options =>
 {
 options.ClientId = builder.Configuration["Auth:Google:ClientId"]!;
 options.ClientSecret = builder.Configuration["Auth:Google:ClientSecret"]!;
 options.Scope.Add("profile");
 })
 .AddMicrosoftAccount(options =>
 {
 options.ClientId = builder.Configuration["Auth:Microsoft:ClientId"]!;
 options.ClientSecret = builder.Configuration["Auth:Microsoft:ClientSecret"]!;
 })
 .AddGitHub(options =>
 {
 options.ClientId = builder.Configuration["Auth:GitHub:ClientId"]!;
 options.ClientSecret = builder.Configuration["Auth:GitHub:ClientSecret"]!;
 });

بالنسبة إلى GitHub، ستحتاج إلى حزمة AspNet.Security.OAuth.GitHub NuGet، لأنها غير مضمنة في مكتبات ASP.NET الافتراضية.

توفر واجهة مستخدم تسجيل الدخول بعد ذلك روابط تؤدي إلى التحدي الخارجي:

@page "/account/external-login"

<h2>Sign in with an external provider</h2>

<form method="post" action="/api/auth/external-login">
 <button type="submit" name="provider" value="Google">
 Sign in with Google
 </button>
 <button type="submit" name="provider" value="Microsoft">
 Sign in with Microsoft
 </button>
 <button type="submit" name="provider" value="GitHub">
 Sign in with GitHub
 </button>
</form>

تقوم نقطة نهاية واجهة برمجة التطبيقات (API) بتشغيل التحدي وتتعامل مع رد الاتصال:

app.MapPost("/api/auth/external-login", (string provider, HttpContext context) =>
{
 var properties = new AuthenticationProperties
 {
 RedirectUri = "/api/auth/external-callback"
 };
 return Results.Challenge(properties, [provider]);
});

تتطلب المصادقة الخارجية في Blazor دائمًا التنقل الكامل للصفحة - لا يمكنك إكمال إعادة توجيه OAuth داخل دائرة SignalR أو تطبيق WebAssembly دون المرور عبر الخادم.

المصادقة المستندة إلى الرمز المميز في Blazor WebAssemblyيتم تشغيل Blazor WebAssembly على العميل، لذا لا يتم تطبيق المصادقة المستندة إلى ملفات تعريف الارتباط بنفس الطريقة. بدلاً من ذلك، عادةً ما تستخدم JWTs المخزنة في الذاكرة والمرفقة بطلبات HTTP الصادرة.

يوفر إطار العمل AuthorizationMessageHandler لإرفاق الرموز المميزة تلقائيًا:

builder.Services.AddHttpClient("API",
 client => client.BaseAddress = new Uri("https://api.example.com"))
 .AddHttpMessageHandler<AuthorizationMessageHandler>();

builder.Services.AddScoped(sp =>
 sp.GetRequiredService<IHttpClientFactory>().CreateClient("API"));

بالنسبة لتطبيقات Blazor WASM المستقلة التي تقوم بالمصادقة مقابل واجهة برمجة التطبيقات الخاصة بها، فسوف تقوم بتنفيذ AuthenticationStateProvider المخصص الذي يوزع JWT:

public class JwtAuthenticationStateProvider : AuthenticationStateProvider
{
 private readonly ILocalStorageService _localStorage;
 private readonly HttpClient _httpClient;

 public JwtAuthenticationStateProvider(
 ILocalStorageService localStorage,
 HttpClient httpClient)
 {
 _localStorage = localStorage;
 _httpClient = httpClient;
 }

 public override async Task<AuthenticationState> GetAuthenticationStateAsync()
 {
 var token = await _localStorage.GetItemAsync<string>("authToken");

 if (string.IsNullOrWhiteSpace(token))
 return new AuthenticationState(new ClaimsPrincipal(new ClaimsIdentity()));

 _httpClient.DefaultRequestHeaders.Authorization =
 new AuthenticationHeaderValue("Bearer", token);

 var claims = ParseClaimsFromJwt(token);
 var identity = new ClaimsIdentity(claims, "jwt");

 return new AuthenticationState(new ClaimsPrincipal(identity));
 }

 public void NotifyAuthStateChanged()
 {
 NotifyAuthenticationStateChanged(GetAuthenticationStateAsync());
 }

 private IEnumerable<Claim> ParseClaimsFromJwt(string jwt)
 {
 var payload = jwt.Split('.')[1];

 var padded = payload.Length % 4 switch
 {
 2 => payload + "==",
 3 => payload + "=",
 _ => payload
 };

 var bytes = Convert.FromBase64String(padded);
 var json = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(bytes);

 return json?.Select(kvp => new Claim(kvp.Key, kvp.Value.ToString()))
 ?? Enumerable.Empty<Claim>();
 }
}

بعد تسجيل الدخول بنجاح، يمكنك تخزين الرمز المميز وإخطار حالة المصادقة:

public class AuthService
{
 private readonly HttpClient _httpClient;
 private readonly ILocalStorageService _localStorage;
 private readonly JwtAuthenticationStateProvider _authStateProvider;

 public AuthService(
 HttpClient httpClient,
 ILocalStorageService localStorage,
 AuthenticationStateProvider authStateProvider)
 {
 _httpClient = httpClient;
 _localStorage = localStorage;
 _authStateProvider = (JwtAuthenticationStateProvider)authStateProvider;
 }

 public async Task<bool> LoginAsync(string email, string password)
 {
 var response = await _httpClient.PostAsJsonAsync("/api/auth/login",
 new { Email = email, Password = password });

 if (!response.IsSuccessStatusCode)
 return false;

 var result = await response.Content
 .ReadFromJsonAsync<LoginResponse>();

 await _localStorage.SetItemAsync("authToken", result!.Token);
 _authStateProvider.NotifyAuthStateChanged();

 return true;
 }

 public async Task LogoutAsync()
 {
 await _localStorage.RemoveItemAsync("authToken");
 _authStateProvider.NotifyAuthStateChanged();
 }
}

كلمة تحذير: تخزين JWTs في localStorage يعرضهم لهجمات XSS. بالنسبة للتطبيقات ذات الأمان الأعلى، فكر في الاحتفاظ بالرموز المميزة في الذاكرة فقط واستخدام الرموز المميزة للتحديث، أو اعتماد نمط الواجهة الخلفية للواجهة (BFF) حيث يدير الخادم الرموز المميزة ويستخدم العميل ملفات تعريف ارتباط HTTP فقط.

خادم Blazor مقابل WebAssembly: الاعتبارات الأمنية

يغير نموذج الاستضافة وضع الأمان لديك بشكل أساسي.

**يحتفظ Blazor Server بكل منطق المكونات لديك على الخادم. يرى العميل فقط اختلافات HTML المقدمة عبر SignalR. هذا يعني:

المنطق الحساس لا يترك الخادم أبدًا
يمكنك الوصول إلى قواعد البيانات والخدمات الداخلية مباشرة من المكونات
تأتي حالة المصادقة من HttpContext للخادم عند الاتصال الأولي
يمكن للدائرة أن تعيش أكثر من ملف تعريف ارتباط المصادقة - إذا انتهت صلاحية ملف تعريف الارتباط الخاص بالمستخدم، تظل الدائرة حية حتى يتم قطع اتصالها
يجب عليك التعامل مع انقطاع الدائرة بأمان وإعادة التحقق من صحة حالة المصادقة عند إعادة الاتصال

Blazor WebAssembly يعمل بالكامل في المتصفح. هذا يعني:

كل كود المكون الخاص بك قابل للتنزيل والفحص
لا تضع أبدًا أسرارًا أو سلاسل اتصال أو منطق عمل حساس في مكونات WASM
يتم فرض المصادقة فقط على العميل لتجربة المستخدم؛ يجب أن يحدث التنفيذ الحقيقي في طبقة API الخاصة بك
إدارة الرمز المميز هي مسؤوليتك
فكر في استخدام النموذج المستضاف حيث يتعامل مشروع الخادم مع المصادقة ويخدم تطبيق WASM

أحد الأنماط التي أوصي بها لتطبيقات WebAssembly هو التعامل مع كل مكون كما لو كان “واجهة مستخدم غير موثوق بها” وكل نقطة نهاية لواجهة برمجة التطبيقات كما لو كان يتم استدعاؤها بواسطة عميل غير معروف. التحقق من صحة كل شيء من جانب الخادم بغض النظر عما يتحقق منه العميل.

إنشاء AuthenticationStateProvider مخصص

في بعض الأحيان لا يتناسب الموفرون المضمنون مع بنيتك. ربما تقوم بالتكامل مع نظام مصادقة قديم، أو تحتاج إلى استطلاع تغييرات حالة المصادقة. فيما يلي موفر مخصص أكثر اكتمالاً لخادم Blazor:

public class CustomAuthStateProvider : AuthenticationStateProvider
{
 private readonly IHttpContextAccessor _httpContextAccessor;
 private readonly IUserService _userService;

 public CustomAuthStateProvider(
 IHttpContextAccessor httpContextAccessor,
 IUserService userService)
 {
 _httpContextAccessor = httpContextAccessor;
 _userService = userService;
 }

 public override async Task<AuthenticationState> GetAuthenticationStateAsync()
 {
 var httpContext = _httpContextAccessor.HttpContext;

 if (httpContext?.User?.Identity?.IsAuthenticated != true)
 return new AuthenticationState(
 new ClaimsPrincipal(new ClaimsIdentity()));

 var userId = httpContext.User.FindFirstValue(ClaimTypes.NameIdentifier);

 if (userId is null)
 return new AuthenticationState(
 new ClaimsPrincipal(new ClaimsIdentity()));

 var user = await _userService.GetUserWithClaimsAsync(userId);

 if (user is null)
 return new AuthenticationState(
 new ClaimsPrincipal(new ClaimsIdentity()));

 var claims = new List<Claim>
 {
 new(ClaimTypes.NameIdentifier, user.Id),
 new(ClaimTypes.Name, user.DisplayName),
 new(ClaimTypes.Email, user.Email)
 };

 claims.AddRange(user.Roles.Select(r => new Claim(ClaimTypes.Role, r)));
 claims.AddRange(user.Permissions.Select(p => new Claim("Permission", p)));

 var identity = new ClaimsIdentity(claims, "Custom");
 return new AuthenticationState(new ClaimsPrincipal(identity));
 }

 public void MarkUserAsAuthenticated(string userId)
 {
 NotifyAuthenticationStateChanged(GetAuthenticationStateAsync());
 }

 public void MarkUserAsLoggedOut()
 {
 var anonymous = new ClaimsPrincipal(new ClaimsIdentity());
 var authState = Task.FromResult(new AuthenticationState(anonymous));
 NotifyAuthenticationStateChanged(authState);
 }
}

سجله في Program.cs:

builder.Services.AddScoped<AuthenticationStateProvider, CustomAuthStateProvider>();
builder.Services.AddScoped<CustomAuthStateProvider>();

الفكرة الأساسية هنا هي NotifyAuthenticationStateChanged — يؤدي استدعاؤها إلى تشغيل المعلمة المتتالية للتحديث، والتي تعيد تقييم كل AuthorizeView وAuthorizeRouteView في شجرة المكونات الخاصة بك. هذه هي الطريقة التي تجعل واجهة المستخدم تتفاعل مع أحداث تسجيل الدخول/الخروج دون تحديث كامل للصفحة.

المخاطر والحلول الشائعة

بعد العمل مع Blazor auth عبر العديد من المشاريع، إليك المشكلات التي أراها في أغلب الأحيان:

1. استخدام HttpContext في مكونات خادم Blazor`HttpContext` متاح أثناء طلب HTTP الأولي، ولكنه `null` أو قديم أثناء تفاعلات SignalR. لا تقم بإدخال `IHttpContextAccessor` في المكونات التي تعمل بعد العرض الأولي.

الحل: التقط ما تحتاجه من HttpContext أثناء التهيئة وقم بتخزينه في خدمة محددة النطاق:

public class UserContext
{
 public string? UserId { get; set; }
 public string? AccessToken { get; set; }
}

// In a component that renders during the initial HTTP request:
@inject IHttpContextAccessor HttpContextAccessor
@inject UserContext UserContext

@code {
 protected override void OnInitialized()
 {
 var context = HttpContextAccessor.HttpContext;
 UserContext.UserId = context?.User.FindFirstValue(ClaimTypes.NameIdentifier);
 UserContext.AccessToken = context?.Request.Headers.Authorization
 .ToString().Replace("Bearer ", "");
 }
}

2. عدم تحديث حالة المصادقة بعد تسجيل الدخول

يمكنك استدعاء واجهة برمجة تطبيقات تسجيل الدخول الخاصة بك، وقد نجحت، ولكن واجهة المستخدم لا تزال تعرض “تسجيل الدخول”.

الحل: يجب عليك الاتصال بـ NotifyAuthenticationStateChanged على AuthenticationStateProvider بعد تغيير حالة المصادقة. لا يكتشف إطار العمل بطريقة سحرية أنه تم تخزين الرمز المميز أو تعيين ملف تعريف الارتباط.

3. سمة الترخيص لا تعمل على المكونات

يمكنك إضافة [Authorize] إلى أحد المكونات ولكنه لا يمنع المستخدمين غير المصادقين.

الحل: تأكد من أنك تستخدم AuthorizeRouteView بدلاً من RouteView العادي في App.razor. يتجاهل المعيار RouteView سمات الترخيص بالكامل.

4. العرض المسبق يكسر حالة المصادقة

أثناء العرض المسبق من جانب الخادم في Blazor WebAssembly، لا يوجد رمز مصادقة متاح. يتم عرض المكونات على أنها غير مصادقة، ثم تومض إلى حالة المصادقة بعد تحميل WASM.

الحل: إما تعطيل العرض المسبق للصفحات الحساسة للمصادقة باستخدام @rendermode InteractiveWebAssembly (بدون العرض المسبق)، أو التعامل مع حالة التحميل بأمان:

<AuthorizeView>
 <Authorized>
 <p>Welcome back, @context.User.Identity?.Name</p>
 </Authorized>
 <Authorizing>
 <p>Loading...</p>
 </Authorizing>
 <NotAuthorized>
 <a href="/login">Sign in</a>
 </NotAuthorized>
</AuthorizeView>

5. انتهاء صلاحية الرمز المميز في الدوائر طويلة التشغيل

يمكن لدوائر Blazor Server البقاء على قيد الحياة لساعات. إذا انتهت صلاحية الرمز المميز أو الجلسة، فسيظل المستخدم “مصادقًا عليه” في واجهة المستخدم ولكن تبدأ استدعاءات واجهة برمجة التطبيقات بالفشل.

الحل: قم بإجراء فحص دوري أو استخدم RevalidatingServerAuthenticationStateProvider:

public class RevalidatingAuthStateProvider
 : RevalidatingServerAuthenticationStateProvider
{
 private readonly IServiceScopeFactory _scopeFactory;

 public RevalidatingAuthStateProvider(
 ILoggerFactory loggerFactory,
 IServiceScopeFactory scopeFactory)
 : base(loggerFactory)
 {
 _scopeFactory = scopeFactory;
 }

 protected override TimeSpan RevalidationInterval => TimeSpan.FromMinutes(30);

 protected override async Task<bool> ValidateAuthenticationStateAsync(
 AuthenticationState authenticationState, CancellationToken cancellationToken)
 {
 await using var scope = _scopeFactory.CreateAsyncScope();
 var userManager = scope.ServiceProvider
 .GetRequiredService<UserManager<IdentityUser>>();

 var user = await userManager.GetUserAsync(authenticationState.User);
 return user is not null;
 }
}

يؤدي هذا إلى التحقق من أن المستخدم لا يزال موجودًا (وأن ختم الأمان الخاص به لم يتغير) كل 30 دقيقة.

الخلاصة

تتطلب المصادقة والترخيص في Blazor تحولًا في التفكير من ASP.NET التقليدي للاستجابة للطلب. إن تجريد AuthenticationStateProvider هو المفتاح لفهم كيفية تناسب كل شيء معًا - بمجرد استيعاب ذلك، يتبع الباقي بشكل طبيعي.

بالنسبة لمعظم التطبيقات، ابدأ بهوية ASP.NET والقوالب المضمنة. إنهم يتعاملون مع الأعباء الثقيلة لإدارة المستخدم وتجزئة كلمة المرور وإنشاء الرمز المميز. طبقة من السياسات والتفويض المبني على المطالبات مع نمو متطلباتك. قم بإضافة موفري OAuth خارجيين عندما يتوقعهم المستخدمون.

نموذج الاستضافة مهم: يمنحك Blazor Server وضعًا أمنيًا أكثر تقليدية حيث يبقى الكود على الخادم، بينما يدفعك WebAssembly نحو التفكير بواجهة برمجة التطبيقات أولاً حيث يكون العميل غير موثوق به حسب التصميم. ولا يعتبر أي منهما أكثر أمانًا بطبيعته، بل لديهم فقط نماذج تهديد مختلفة.

أيًا كان النهج الذي تختاره، تذكر القاعدة الذهبية: التفويض في واجهة المستخدم مخصص لتجربة المستخدم، أما التفويض على الخادم فهو للأمان. قم دائمًا بتنفيذ كليهما.

JavaScript معزول في Blazor مع ملفات JS مجمعة

Wed, 18 Jun 2025 00:00:00 +0000

إذا كنت قد عملت مع Blazor وJS Interop من قبل، فمن المحتمل أن ينتهي بك الأمر مع ملف app.js ضخم مليء بالوظائف العشوائية لمكونات مختلفة. إنه يعمل، لكنه يصبح فوضويًا بسرعة. لحسن الحظ، هناك طريقة أكثر نظافة: ملفات JavaScript المجمعة.

#الفكرة

تمامًا مثل عزل CSS، يتيح لك Blazor وضع ملف .razor.js بجوار المكون الخاص بك. يتم تحميل وحدة JavaScript عند الطلب، فقط عندما يحتاجها المكون فعليًا. لا توجد نصوص عالمية، ولا تلوث.

إعداده

لنفترض أن لدينا مكون Clipboard.razor الذي ينسخ النص إلى الحافظة. قم بإنشاء ملف يسمى Clipboard.razor.js بجواره مباشرةً:

export function copyToClipboard(text) {
 navigator.clipboard.writeText(text).then(() => {
 console.log("Copied to clipboard!");
 });
}

لاحظ الكلمة الأساسية export — وهذا أمر مهم. يقوم Blazor بتحميله كوحدة ES قياسية.

تحميل الوحدة في Blazor

في المكون الخاص بك، يمكنك استخدام IJSRuntime لاستيراد الوحدة. يتبع المسار الاصطلاح: ./_content/{ASSEMBLY_NAME}/{COMPONENT_PATH}.razor.js للمكتبات، أو المسار النسبي للمشروع الحالي فقط.

@inject IJSRuntime JS
@implements IAsyncDisposable

<button @onclick="Copy">Copy to clipboard</button>

@code {
 [Parameter]
 public string Text { get; set; }

 private IJSObjectReference? module;

 protected override async Task OnAfterRenderAsync(bool firstRender)
 {
 if (firstRender)
 {
 module = await JS.InvokeAsync<IJSObjectReference>(
 "import", "./Components/Clipboard.razor.js");
 }
 }

 private async Task Copy()
 {
 if (module is not null)
 {
 await module.InvokeVoidAsync("copyToClipboard", Text);
 }
 }

 public async ValueTask DisposeAsync()
 {
 if (module is not null)
 {
 await module.DisposeAsync();
 }
 }
}

بعض الأشياء التي يجب ملاحظتها هنا:

نقوم بتحميل الوحدة في OnAfterRenderAsync لأن JS Interop غير متاح أثناء العرض المسبق من جانب الخادم
نحتفظ بمرجع للوحدة مع IJSObjectReference
نقوم بتنفيذ IAsyncDisposable لتنظيف الوحدة عند تدمير المكون

لماذا هذا أفضل

من قبل، كنت أجمع كل شيء في ملف واحد wwwroot/js/app.js. لقد نجح الأمر، ولكن العثور على الوظائف كان أمرًا صعبًا، وكل صفحة تحمل JavaScript لم تكن بحاجة إليها. مع ملفات JS المجمعة:

يمتلك كل مكون جافا سكريبت الخاص به
يتم تحميل الوحدات بتكاسل، فقط عند الحاجة إليها
لا يوجد تعارض في أسماء الوظائف العامة
سهولة الصيانة والحذف — عندما تحذف المكون، فإنك تحذف ملف JS معه

#مسكتك مع المسار

يعتمد المسار الذي تمر به إلى import على ما إذا كنت تستخدم تطبيق Blazor المستقل أو مكتبة Razor Class Library. بالنسبة لتطبيق Blazor العادي، يكون المسار متعلقًا بـ wwwroot. يتم نسخ الملف .razor.js هناك في وقت الإنشاء، لذا يمكنك الرجوع إليه من موقع المكون في المشروع.

إذا كنت تحصل على 404 عند تحميل الوحدة، فتحقق جيدًا من المسار وتأكد من أن الملف ينتهي بـ .razor.js، وليس فقط .js.

آمل أن تكونوا قد أحببت هذا المنصب! لا تتردد في الاتصال بي على أي وسائل التواصل الاجتماعي على **@emimontesdeoca **.

الموارد

ASP.NET Core Blazor JavaScript مع JS المجمع

تفاعل Blazor في .NET 9 و.NET 10: دليل كامل

Sun, 15 Jun 2025 00:00:00 +0000

إذا كنت تقوم بإنشاء تطبيقات الويب باستخدام Blazor على مدى السنوات القليلة الماضية، فأنت تعلم أن إطار العمل قد قطع شوطًا طويلًا. ما بدأ كاختيار بين Blazor Server وBlazor WebAssembly تطور إلى نموذج عرض موحد ومرن يتيح لك اختيار استراتيجية التفاعل الصحيحة لكل مكون في تطبيقك.

مع .NET 8 حصلنا على التحول الأساسي — تقديم أوضاع العرض والعرض الثابت من جانب الخادم (SSR) كوضع افتراضي. والآن، يعتمد الإصداران .NET 9 و.NET 10 على هذا الأساس من خلال التحسينات التي تجعل تجربة المطور أكثر سلاسة وتجربة المستخدم النهائي أسرع.

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

نظرة سريعة إلى الوراء: كيف وصلنا إلى هنا

قبل .NET 8، كان عليك الالتزام بنموذج استضافة على مستوى المشروع. يعني Blazor Server أن كل شيء يعمل على الخادم عبر اتصال SignalR. يعني Blazor WebAssembly أن كل شيء يعمل في المتصفح. وكان لكل منهما مقايضات، وكان الاختلاط بينها مؤلما.

لقد غير .NET 8 اللعبة من خلال تقديم قالب مشروع واحد — تطبيق Blazor Web App — الذي يوحد كلا النموذجين. المفهوم الأساسي هو أوضاع العرض: عليك أن تقرر لكل مكون كيفية عرضه ومكان حدوث التفاعل. أصبح الإعداد الافتراضي هو SSR الثابت، مما يعني عرض المكونات على الخادم وإرسال HTML عادي إلى المتصفح - بدون SignalR، ولا WebAssembly، فقط HTML سريع.

قام .NET 9 بصقل هذه المفاهيم وتحسين تجربة المطورين وتحسين الأداء. يأخذ .NET 10 الأمر إلى أبعد من ذلك من خلال معالجة أفضل لإعادة الاتصال، وحالة المكون المستمرة عبر أوضاع العرض، وتحسينات على كيفية تسليم البرنامج النصي Blazor نفسه.

دعونا كسر كل شيء إلى أسفل.

أوضاع العرض في .NET 9

في قلب Blazor الحديث يوجد مفهوم أوضاع العرض. هناك أربعة أوضاع يجب أن تعرفها:

1. SSR الثابت (الافتراضي)

عند إنشاء تطبيق Blazor Web App جديد، يتم عرض المكونات بشكل ثابت على الخادم بشكل افتراضي. يقوم الخادم بمعالجة مكون Razor، وإنشاء HTML، وإرساله إلى المتصفح. لا يوجد اتصال مستمر، ولا وقت تشغيل WebAssembly — مجرد طلب/استجابة تقليدية.

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

@page "/products"

<h1>Our Products</h1>

@foreach (var product in products)
{
 <div class="product-card">
 <h3>@product.Name</h3>
 <p>@product.Description</p>
 <span class="price">@product.Price.ToString("C")</span>
 </div>
}

@code {
 private List<Product> products = new();

 protected override async Task OnInitializedAsync()
 {
 products = await ProductService.GetAllAsync();
 }
}

يتم عرض هذا المكون على الخادم، وينتج HTML، وهذا كل شيء. لا يوجد اتصال مستمر. تحميل أولي سريع، رائع لتحسين محركات البحث، الحد الأدنى من استخدام موارد الخادم.

2. الخادم التفاعليعندما تحتاج إلى التفاعل في الوقت الفعلي - التعامل مع نقرات الأزرار، ومعالجة إدخالات المستخدم، وتحديث واجهة المستخدم ديناميكيًا - يمكنك الاشتراك في وضع الخادم التفاعلي. يؤدي هذا إلى إنشاء اتصال SignalR بين المتصفح والخادم، وتحدث تحديثات واجهة المستخدم عبر هذا الاتصال.

@page "/counter"
@rendermode InteractiveServer

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
 private int currentCount = 0;

 private void IncrementCount()
 {
 currentCount++;
 }
}

التوجيه @rendermode InteractiveServer هو كل ما يتطلبه الأمر. يتم عرض المكون في البداية على الخادم، ثم يتم إنشاء اتصال SignalR للتعامل مع التفاعلات اللاحقة. تعمل معالجات أحداث C# على الخادم، ويتم إرسال اختلافات واجهة المستخدم إلى المتصفح.

متى تستخدمه: عندما تحتاج إلى التفاعل، تحتاج مكوناتك إلى الوصول إلى الموارد من جانب الخادم (قواعد البيانات، وواجهات برمجة التطبيقات، وأنظمة الملفات)، وتريد تحميلًا أوليًا سريعًا دون انتظار تنزيل WebAssembly.

3. تجميع الويب التفاعلي

إذا كنت تريد التفاعل دون الحفاظ على اتصال الخادم، يقوم Interactive WebAssembly بتشغيل منطق المكون الخاص بك مباشرةً في المستعرض باستخدام وقت تشغيل .NET WebAssembly.

@page "/search"
@rendermode InteractiveWebAssembly

<h1>Product Search</h1>

<input @bind="searchTerm" @bind:event="oninput" placeholder="Search products..." />

@if (filteredProducts.Any())
{
 <ul>
 @foreach (var product in filteredProducts)
 {
 <li>@product.Name — @product.Price.ToString("C")</li>
 }
 </ul>
}

@code {
 private string searchTerm = string.Empty;
 private List<Product> allProducts = new();
 private IEnumerable<Product> filteredProducts => allProducts
 .Where(p => p.Name.Contains(searchTerm, StringComparison.OrdinalIgnoreCase));

 protected override async Task OnInitializedAsync()
 {
 allProducts = await Http.GetFromJsonAsync<List<Product>>("api/products") ?? new();
 }
}

المقايضة: هناك تكلفة تنزيل أولية لوقت تشغيل .NET وتجميعاتك. ولكن بمجرد تحميله، يعمل المكون بالكامل في المتصفح دون الحاجة إلى رحلات ذهابًا وإيابًا للخادم لتفاعلات واجهة المستخدم.

متى يتم استخدامه: بالنسبة للمكونات التفاعلية للغاية حيث يكون زمن الاستجابة مهمًا (مثل: برامج تحرير النصوص الغنية، وأدوات الرسم، والتصفية في الوقت الفعلي)، أو عندما تريد تقليل تحميل الخادم، أو عندما تقوم بإنشاء تطبيق ويب تقدمي (PWA).

4. السيارات التفاعلية

هذه هي الأرضية الوسطى العملية وواحدة من ميزاتي المفضلة. يبدأ Interactive Auto بالعرض من جانب الخادم عبر SignalR للتحميل الأول، ثم يقوم بتنزيل وقت تشغيل WebAssembly في الخلفية بصمت. وفي الزيارات اللاحقة، يتم تشغيل المكون على WebAssembly.

@page "/dashboard"
@rendermode InteractiveAuto

<h1>Dashboard</h1>

<DashboardWidget Title="Sales" Value="@salesTotal" />
<DashboardWidget Title="Users" Value="@activeUsers" />

<button @onclick="RefreshData">Refresh</button>

@code {
 private decimal salesTotal;
 private int activeUsers;

 protected override async Task OnInitializedAsync()
 {
 await RefreshData();
 }

 private async Task RefreshData()
 {
 var data = await DashboardService.GetSummaryAsync();
 salesTotal = data.SalesTotal;
 activeUsers = data.ActiveUsers;
 }
}

يمنحك هذا أفضل ما في كلا العالمين: العرض الأول السريع (بدون انتظار تنزيل WASM)، وفي النهاية يتم تشغيل المكون من جانب العميل. لا يلاحظ المستخدم الانتقال.

متى تستخدمه: عندما تريد التحميل الأولي السريع والتنفيذ النهائي من جانب العميل. إنه خيار افتراضي رائع للعديد من المكونات التفاعلية.

بث SSR: أفضل ما في العالمين

يعد Streaming SSR إحدى تلك الميزات التي تبدو بسيطة ولكنها تحدث فرقًا كبيرًا في الأداء المتصور. إليك الفكرة: بدلاً من انتظار تحميل جميع بياناتك قبل إرسال أي HTML، يرسل الخادم غلاف الصفحة على الفور ثم يبث تحديثات المحتوى عندما تصبح البيانات متاحة.

@page "/reports"
@attribute [StreamRendering]

<h1>Monthly Reports</h1>

@if (reports is null)
{
 <div class="loading-spinner">
 <p>Loading reports...</p>
 </div>
}
else
{
 <table class="table">
 <thead>
 <tr>
 <th>Month</th>
 <th>Revenue</th>
 <th>Growth</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var report in reports)
 {
 <tr>
 <td>@report.Month</td>
 <td>@report.Revenue.ToString("C")</td>
 <td class="@(report.Growth >= 0 ? "text-success" : "text-danger")">
 @report.Growth.ToString("P1")
 </td>
 </tr>
 }
 </tbody>
 </table>
}

@code {
 private List<MonthlyReport>? reports;

 protected override async Task OnInitializedAsync()
 {
 // This might take a couple of seconds
 reports = await ReportService.GetMonthlyReportsAsync();
 }
}

مع السمة [StreamRendering]، إليك ما يحدث:

يرسل الخادم على الفور HTML باستخدام أداة التحميل الدوارة.
OnInitializedAsync يقوم بتشغيل وجلب البيانات.
عند وصول البيانات، يقوم الخادم بتدفق HTML المحدث (الجدول) إلى المتصفح.
يقوم المتصفح بتصحيح DOM دون إعادة تحميل الصفحة بالكامل.

يرى المستخدم الصفحة على الفور مع مؤشر التحميل، ثم يملأ المحتوى. لا حاجة إلى إطار جافا سكريبت. لا يوجد اتصال WebSocket. مجرد استخدام ذكي لتدفق HTTP.متى يتم استخدامها: أي صفحة SSR ثابتة تقوم بجلب البيانات أثناء العرض. صفحات قائمة المنتجات ولوحات المعلومات والتقارير - في أي مكان قد يستغرق تحميل البيانات الأولية أكثر من بضع مئات من المللي ثانية.

متى لا تستخدمه: إذا تم تحميل البيانات بسرعة كبيرة (أقل من 100 مللي ثانية)، فإن الحمل الزائد للبث لا يستحق ذلك. كما أن دفق SSR لا يمنحك تفاعلًا مستمرًا - لذلك، لا تزال بحاجة إلى وضع عرض تفاعلي.

تحسين التنقل ومعالجة النماذج

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

وهذا يعني أن التنقل بين صفحات SSR الثابتة يبدو وكأنه منتجع صحي - لا يوجد فلاش كامل للصفحة، ويمكن الحفاظ على موضع التمرير، وتكون التجربة سلسة للغاية.

كيف يعمل

عند تحميل البرنامج النصي Blazor (blazor.web.js)، فإنه يعترض تلقائيًا النقرات على الروابط الداخلية. بدلاً من التنقل التقليدي في المتصفح، فإنه:

يقدم طلب fetch إلى عنوان URL المستهدف.
يتلقى استجابة HTML.
دمج المحتوى الجديد في DOM الحالي.
يقوم بتحديث عنوان URL للمتصفح والتاريخ.

ليس عليك القيام بأي شيء لتمكين هذا - فهو قيد التشغيل افتراضيًا. ولكن يمكنك التحكم فيه:

<!-- Disable enhanced navigation for a specific link -->
<a href="/legacy-page" data-enhance-nav="false">Legacy Page</a>

<!-- Force a full page reload for external-like behavior -->
<a href="/downloads/report.pdf" data-enhance-nav="false">Download Report</a>

معالجة محسنة للنماذج

النماذج تحصل على نفس المعاملة. عند استخدام EditForm أو عنصر <form> القياسي مع معالجة نموذج Blazor، يتم اعتراض عمليات الإرسال والتعامل معها عبر fetch:

@page "/contact"

<EditForm Model="contactModel" OnValidSubmit="HandleSubmit" FormName="contact" Enhance>
 <DataAnnotationsValidator />

 <div class="mb-3">
 <label for="name">Name</label>
 <InputText id="name" @bind-Value="contactModel.Name" class="form-control" />
 <ValidationMessage For="() => contactModel.Name" />
 </div>

 <div class="mb-3">
 <label for="email">Email</label>
 <InputText id="email" @bind-Value="contactModel.Email" class="form-control" />
 <ValidationMessage For="() => contactModel.Email" />
 </div>

 <div class="mb-3">
 <label for="message">Message</label>
 <InputTextArea id="message" @bind-Value="contactModel.Message" class="form-control" />
 <ValidationMessage For="() => contactModel.Message" />
 </div>

 <button type="submit" class="btn btn-primary">Send</button>
</EditForm>

@code {
 [SupplyParameterFromForm]
 private ContactModel contactModel { get; set; } = new();

 private async Task HandleSubmit()
 {
 await ContactService.SubmitAsync(contactModel);
 contactModel = new ContactModel();
 }
}

السمة Enhance الموجودة على EditForm تطلب من Blazor اعتراض إرسال النموذج. يتم نشر النموذج على الخادم، ويقوم الخادم بمعالجته وإعادة عرض الصفحة، ويتم بث HTML المحدث مرة أخرى - كل ذلك بدون التنقل الكامل للصفحة. إنها تبدو تفاعلية، ولكنها مقدمة بالكامل من خلال الخادم.

لاحظ السمة [SupplyParameterFromForm] - هذه هي الطريقة التي يربط بها Blazor بيانات النموذج المنشورة بالنموذج الخاص بك في سيناريوهات SSR الثابتة. إنه الجسر بين منشورات النماذج التقليدية ونموذج مكونات Blazor.

التفاعل لكل صفحة ولكل مكون

أحد أقوى جوانب النموذج الجديد هو أنه يمكنك مزج أوضاع العرض داخل تطبيق واحد. يمكن أن تكون صفحة قائمة منتجاتك عبارة عن SSR ثابت، ويمكن أن تكون عربة التسوق الخاصة بك خادمًا تفاعليًا، ويمكن أن تكون أداة تكوين منتجك عبارة عن Interactive WebAssembly - كل ذلك في نفس التطبيق.

ضبط أوضاع العرض على مستوى المكون

يمكنك ضبط وضع التجسيد مباشرةً على أحد المكونات باستخدام التوجيه @rendermode:

@* This component is interactive via Server *@
@rendermode InteractiveServer

<h3>Live Chat</h3>
<!-- chat UI here -->

أو يمكنك ضبطه عند استخدام مكون من أحد الوالدين:

@page "/product/{Id:int}"

<h1>@product?.Name</h1>
<p>@product?.Description</p>

<!-- This child component gets its own interactive render mode -->
<ProductConfigurator Product="product" @rendermode="InteractiveWebAssembly" />

<!-- This stays static -->
<ProductReviews ProductId="Id" />

@code {
 [Parameter] public int Id { get; set; }
 private Product? product;

 protected override async Task OnInitializedAsync()
 {
 product = await ProductService.GetByIdAsync(Id);
 }
}

في هذا المثال، الصفحة نفسها عبارة عن SSR ثابت. يعمل المكون ProductConfigurator على WebAssembly من أجل تفاعل غني من جانب العميل. يظل المكون ProductReviews ثابتًا لأنه يعرض البيانات فقط.

ضبط أوضاع العرض على مستوى العالم

إذا كنت تريد أن تكون جميع الصفحات تفاعلية بشكل افتراضي، فيمكنك ضبط وضع العرض على مستوى الجذر في App.razor:

<Routes @rendermode="InteractiveServer" />
```وهذا يجعل كل صفحة تفاعلية عبر عرض الخادم. لا يزال بإمكان المكونات الفردية تجاوز هذا إذا لزم الأمر.

### قواعد مهمة يجب تذكرها

هناك بعض القيود التي يجب وضعها في الاعتبار عند مزج أوضاع العرض:

- **لا يمكن أن يحتوي المكون الفرعي على وضع عرض "أكثر تفاعلية" من المكون الأصلي. ** إذا كان الأصل ثابتًا، فيمكن أن يكون الأطفال ثابتين أو متفاعلين. ولكن إذا كان أحد الوالدين هو Interactive Server، فلا يمكن أن يكون الطفل Interactive WebAssembly (يجب أن يكون Server أو Auto).
- **لا يمكن للمكونات التفاعلية استخدام الخدمات المحددة مباشرة من الأصول الثابتة.** إذا تم تشغيل أحد المكونات على WebAssembly، فلن يتمكن من الوصول إلى مثيلات `DbContext` من جانب الخادم مباشرةً — ستحتاج إلى طبقة واجهة برمجة التطبيقات (API).
- **لا تنتقل الحالة تلقائيًا بين أوضاع التجسيد.** إذا تم عرض أحد المكونات مسبقًا على الخادم ثم قام بالتبديل إلى WebAssembly، فستحتاج إلى التعامل مع استمرار الحالة بشكل صريح - المزيد عن هذا في قسم .NET 10.

## ما الجديد في .NET 10

يواصل .NET 10 نهج التحسين التدريجي، مع التركيز على الموثوقية وتجربة المطور. فيما يلي أبرز مميزات تفاعل Blazor:

### تجربة إعادة الاتصال المحسنة

إذا كنت قد استخدمت وضع الخادم التفاعلي في الإنتاج، فمن المحتمل أنك واجهت تراكب إعادة الاتصال - تلك اللحظة التي ينقطع فيها اتصال SignalR ويرى المستخدم رسالة "جارٍ إعادة الاتصال...". في .NET 10، أصبحت هذه التجربة أفضل بشكل ملحوظ.

أصبح منطق إعادة الاتصال الآن أكثر ذكاءً فيما يتعلق بإعادة المحاولة. بدلاً من الفاصل الزمني الثابت لإعادة المحاولة، فإنه يستخدم إستراتيجية التراجع التي تتكيف مع الموقف. واجهة المستخدم أثناء إعادة الاتصال أصبحت أيضًا أكثر صقلًا، ولديك روابط أفضل لتخصيص التجربة:

```razor
<!-- In your App.razor or layout -->
<div id="components-reconnect-modal">
 <div class="reconnect-visible">
 <p>Connection lost. Attempting to reconnect...</p>
 <div class="spinner"></div>
 </div>
 <div class="reconnect-failed">
 <p>Could not reconnect to the server.</p>
 <button onclick="location.reload()">Reload</button>
 </div>
 <div class="reconnect-rejected">
 <p>Your session has expired.</p>
 <a href="/">Return to Home</a>
 </div>
</div>

يحاول إطار العمل الآن أيضًا إعادة الاتصال بقوة أكبر في حالات الفشل العابر، ويمكنه استعادة حالة الدائرة بشكل أكثر موثوقية. وهذا يعني عددًا أقل من لحظات “الرجاء إعادة تحميل الصفحة” للمستخدمين.

حالة المكون الثابتة عبر أوضاع العرض

هذه واحدة كبيرة. في .NET 9، عندما يتم عرض أحد المكونات مسبقًا على الخادم ثم ينتقل إلى WebAssembly (أو يقوم بالتبديل بين أوضاع العرض)، يتم فقدان حالة المكون. تتم إعادة تهيئة المكون بشكل فعال، مما قد يؤدي إلى عمليات جلب بيانات مكررة ووميض واجهة المستخدم.

يعمل .NET 10 على تحسين خدمة PersistentComponentState للعمل بسلاسة أكبر عبر انتقالات وضع العرض:

@page "/weather"
@rendermode InteractiveWebAssembly
@inject PersistentComponentState ApplicationState

<h1>Weather Forecast</h1>

@if (forecasts is null)
{
 <p>Loading...</p>
}
else
{
 @foreach (var forecast in forecasts)
 {
 <div class="forecast-card">
 <h4>@forecast.Date.ToShortDateString()</h4>
 <p>@forecast.Summary — @forecast.TemperatureC°C</p>
 </div>
 }
}

@code {
 private List<WeatherForecast>? forecasts;
 private PersistingComponentStateSubscription persistingSubscription;

 protected override async Task OnInitializedAsync()
 {
 persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);

 if (!ApplicationState.TryTakeFromJson<List<WeatherForecast>>(
 "weather-forecasts", out var restored))
 {
 // Data wasn't persisted from prerendering — fetch it
 forecasts = await Http.GetFromJsonAsync<List<WeatherForecast>>("api/weather");
 }
 else
 {
 forecasts = restored;
 }
 }

 private Task PersistData()
 {
 ApplicationState.PersistAsJson("weather-forecasts", forecasts);
 return Task.CompletedTask;
 }

 public void Dispose()
 {
 persistingSubscription.Dispose();
 }
}

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

Blazor Script كأحد أصول الويب الثابتة

في الإصدارات السابقة، تم تقديم ملف Blazor JavaScript (blazor.web.js) من نقطة النهاية الداخلية لإطار العمل. في .NET 10، يتم تسليمه كأصل ويب ثابت. قد يبدو هذا تغييرًا بسيطًا، لكن له فوائد عملية:- تخزين مؤقت أفضل: تحصل أصول الويب الثابتة على رؤوس ذاكرة تخزين مؤقت مناسبة وعناوين URL ذات بصمات أصابع، بحيث تقوم المتصفحات بتخزينها بشكل أكثر فعالية.

متوافق مع CDN: نظرًا لأنه ملف ثابت عادي، يمكن لشبكات CDN تخزينه مؤقتًا وتقديمه من مواقع التخزين المؤقت.
الضغط: يتم تطبيق ضغط أصول الويب الثابت تلقائيًا، مما يؤدي إلى تقليل حجم البرنامج النصي على السلك.

لا تحتاج إلى تغيير كيفية الرجوع إليه — حيث يتعامل إطار العمل مع المسار المحدث تلقائيًا.

أفضل الممارسات: اختيار وضع العرض المناسب

بعد العمل مع كل هذه الأوضاع عبر العديد من المشاريع، إليك إطار القرار الخاص بي:

ابدأ بـ SSR الثابت

اجعل SSR الثابت هو الخيار الافتراضي. تتعلق معظم الصفحات في معظم التطبيقات بشكل أساسي بعرض البيانات. صفحات المنتج، ومنشورات المدونات، وملفات تعريف المستخدمين، وصفحات الإعدادات - لا تحتاج إلى تفاعل في الوقت الفعلي. يمنحك Static SSR أفضل أداء وأقل استخدام للموارد وأبسط نموذج عقلي.

أضف التفاعل عند الحاجة فقط

حدد المكونات المحددة التي تحتاج إلى الاستجابة لتفاعلات المستخدم في الوقت الفعلي. زر “أعجبني”، وأداة الدردشة، وواجهة السحب والإفلات - كلها تحتاج إلى التفاعل. لكن الصفحة المحيطة بهم ربما لا تفعل ذلك.

استخدم الوضع التلقائي التفاعلي باعتباره الوضع التفاعلي المفضل لديك

عندما تحتاج إلى التفاعل، غالبًا ما يكون Interactive Auto هو الخيار الافتراضي الأفضل. فهو يوفر لك تحميلات أولية سريعة (عرض الخادم) مع التنفيذ النهائي من جانب العميل (WebAssembly). يحصل المستخدم على أفضل ما في كلا العالمين، وتكتب الكود الخاص بك مرة واحدة.

حجز الخادم التفاعلي لحالات محددة

استخدم الخادم التفاعلي عندما:

يحتاج المكون الخاص بك إلى الوصول المباشر إلى موارد الخادم (قواعد البيانات ونظام الملفات وواجهات برمجة التطبيقات الداخلية).
يعد حجم تنزيل WebAssembly مصدر قلق ولا يمكنك استخدام Auto.
أنت بحاجة إلى تشغيل المكون دائمًا على الخادم لأسباب أمنية (على سبيل المثال، معالجة البيانات الحساسة).

استخدم بث SSR بسخاء

إذا كانت صفحات SSR الثابتة تجلب أي بيانات، أضف [StreamRendering]. التكلفة ضئيلة والتحسن الملحوظ في الأداء كبير. يرى المستخدمون المحتوى يظهر بشكل تدريجي بدلاً من التحديق في صفحة فارغة.

تعامل مع انتقالات الحالة بعناية

إذا كنت تستخدم Interactive Auto أو تخلط العرض المسبق مع WebAssembly، فاستخدم دائمًا PersistentComponentState لتجنب عمليات جلب البيانات المكررة. سوف يشكرك المستخدمون على عدم وجود محتوى وامض.

ضع شجرة المكونات في الاعتبار

تذكر قواعد التسلسل الهرمي لوضع التجسيد. قم بتخطيط شجرة المكونات الخاصة بك بحيث تكون الحدود التفاعلية منطقية. النمط الشائع هو أن يكون لديك تخطيط ثابت مع “جزر” تفاعلية مضمنة عند الحاجة:

@* Layout: Static SSR *@
<header>
 <NavMenu />
 <UserMenu @rendermode="InteractiveServer" /> @* Needs real-time auth state *@
</header>

<main>
 @Body
</main>

<footer>
 <ChatWidget @rendermode="InteractiveAuto" /> @* Rich interactivity *@
</footer>

الخلاصة

يمثل نموذج التفاعل الخاص بـ Blazor في .NET 9 و.NET 10 أسلوبًا ناضجًا ومدروسًا جيدًا لبناء تطبيقات الويب. إن القدرة على اختيار أوضاع العرض لكل مكون، والتنقل المحسّن السلس، وتدفق SSR، والتحسينات المستمرة في إعادة الاتصال وإدارة الحالة تجعله خيارًا مقنعًا لمجموعة واسعة من التطبيقات.الفكرة الأساسية هي أن التفاعل عبارة عن نطاق، وليس خيارًا ثنائيًا. يمكن أن يكون معظم تطبيقك ثابتًا. تحتاج بعض الأجزاء إلى تفاعل يحركه الخادم. قد يستفيد البعض من التشغيل في المتصفح. يتيح لك Blazor الآن اتخاذ هذا الاختيار بأدق التفاصيل - المكون الفردي - دون محاربة إطار العمل.

إذا كنت تبدأ مشروعًا جديدًا، فإن نصيحتي بسيطة: أنشئ تطبيق Blazor Web App، وابدأ بـ SSR الثابت، وأضف [StreamRendering] إلى الصفحات المليئة بالبيانات، وقم بترقية المكونات الفردية إلى الأوضاع التفاعلية فقط عندما تحتاج إليها. سينتهي بك الأمر بالحصول على تطبيق سريع وفعال وقابل للتوسع بشكل جيد.

أتمنى لك حظًا سعيدًا في البرمجة، وكما هو الحال دائمًا، لا تتردد في التواصل معنا إذا كانت لديك أسئلة!

الحد الأدنى من واجهات برمجة التطبيقات في .NET: إنشاء واجهات برمجة تطبيقات HTTP خفيفة الوزن

Thu, 10 Apr 2025 00:00:00 +0000

إذا كنت تقوم ببناء واجهات برمجة التطبيقات باستخدام ASP.NET Core لفترة من الوقت، فمن المحتمل أنك على دراية كبيرة بالنهج القائم على وحدة التحكم: قم بإنشاء فئة وحدة تحكم، وقم بتزيينها بالسمات، وإدخال خدماتك من خلال المنشئ، وربط مساراتك. إنه يعمل بشكل جيد - ولكن في بعض الأحيان يبدو الأمر وكأنك تكتب الكثير من الاحتفالات لما يرقى إلى “قبول هذا الطلب، القيام بشيء ما، الرد على الرد”.

هذه هي بالضبط المشكلة التي تم تصميم Minimal APIs لحلها. تم تقديم الحد الأدنى من واجهات برمجة التطبيقات (APIs) في .NET 6، مما يتيح لك تحديد نقاط نهاية HTTP مع القليل جدًا من القواعد النموذجية. لا توجد وحدات تحكم، ولا سمات، ولا تلاعب بفئة بدء التشغيل - ما عليك سوى توجيه تعيينات المسار إلى المعالج بأسلوب نظيف وعملي.

في هذا المنشور، أريد أن أطلعك على كل ما تحتاج إلى معرفته حول Minimal APIs: بدءًا من نقطة النهاية الأولى وحتى تنظيم التطبيقات الكبيرة، والتعامل مع المصادقة، والتحقق من الصحة، ومستندات OpenAPI، واعتبارات الأداء. دعونا نصل الى ذلك.

لماذا الحد الأدنى من واجهات برمجة التطبيقات؟

قبل أن نبدأ، دعونا نتحدث عن لماذا تختار الحد الأدنى من واجهات برمجة التطبيقات بدلاً من النهج التقليدي القائم على وحدة التحكم.

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

الحد الأدنى من واجهات برمجة التطبيقات، من ناحية أخرى، يمكنك التألق عندما تريد:

نموذج معياري أقل — لا توجد فئات لوحدات التحكم، ولا توجد سمات [ApiController]، ولا يوجد تكوين منفصل لبدء التشغيل.
بدء تشغيل أسرع — عدد أقل من العمليات المستندة إلى الانعكاس في وقت التمهيد.
نموذج عقلي أبسط — يتم تعيين المسار مباشرةً إلى المعالج. هذا كل شيء.
متوافق مع الخدمات الصغيرة — عندما تحتوي واجهة برمجة التطبيقات لديك على 5 إلى 10 نقاط نهاية، قد يبدو إعداد وحدة التحكم الكاملة أمرًا مبالغًا فيه.

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

البدء

لنقم بإنشاء Minimal API من البداية. إذا كان لديك .NET SDK مثبتًا، فالأمر بسيط مثل:

dotnet new web -n MyMinimalApi
cd MyMinimalApi

يمنحك هذا Program.cs الذي يبدو كما يلي:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

هذا كل شيء. هذه واجهة برمجة تطبيقات عاملة. لا Startup.cs، ولا فئة وحدة التحكم، ولا تكوين التوجيه. تقوم بتشغيل dotnet run، ثم تضغط على http://localhost:5000، وستحصل على “Hello World!” خلف. البساطة هنا هي بيت القصيد.

لنجعلها أكثر فائدة قليلًا باستخدام واجهة برمجة تطبيقات المهام الكلاسيكية:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var todos = new List<Todo>();

app.MapGet("/todos", () => todos);

app.MapGet("/todos/{id:int}", (int id) =>
 todos.FirstOrDefault(t => t.Id == id) is { } todo
 ? Results.Ok(todo)
 : Results.NotFound());

app.MapPost("/todos", (Todo todo) =>
{
 todos.Add(todo);
 return Results.Created($"/todos/{todo.Id}", todo);
});

app.MapDelete("/todos/{id:int}", (int id) =>
{
 var todo = todos.FirstOrDefault(t => t.Id == id);
 if (todo is null) return Results.NotFound();
 todos.Remove(todo);
 return Results.NoContent();
});

app.Run();

record Todo(int Id, string Title, bool IsComplete);

لدينا CRUD كامل في أقل من 30 سطرًا. هذه هي قوة النهج البسيط.

معالجات الطريق

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

تعبيرات لامدا

النهج الأكثر شيوعًا، وما ستراه في معظم الأمثلة:

app.MapGet("/hello", () => "Hello!");
app.MapGet("/hello/{name}", (string name) => $"Hello, {name}!");

مجموعات الطريقة

للحصول على منطق أكثر تعقيدًا، يمكنك الإشارة إلى طريقة مُسمّاة:

app.MapGet("/products", GetProducts);
app.MapPost("/products", CreateProduct);

static IResult GetProducts(AppDbContext db)
 => Results.Ok(db.Products.ToList());

static IResult CreateProduct(Product product, AppDbContext db)
{
 db.Products.Add(product);
 db.SaveChanges();
 return Results.Created($"/products/{product.Id}", product);
}
```هذا هو النهج المفضل لدي لأي شيء يتجاوز الخطوط الفردية. فهو يحافظ على قسم تعيين المسار الخاص بك نظيفًا وقابلاً للقراءة - يمكنك رؤية نقاط النهاية الموجودة بنظرة سريعة دون الخوض في تفاصيل التنفيذ.

### الوظائف المحلية

يمكنك أيضًا استخدام الدوال المحلية، وهو أمر مفيد عندما تريد إبقاء المعالجات قريبة من تعريفات المسار الخاصة بها:

```csharp
app.MapGet("/health", CheckHealth);

IResult CheckHealth()
{
 // Some health check logic
 return Results.Ok(new { Status = "Healthy", Timestamp = DateTime.UtcNow });
}

ربط المعلمة

أحد الأشياء التي أقدرها حقًا بشأن Minimal APIs هو مدى سهولة ربط المعلمات. يحدد إطار العمل مكان سحب القيم بناءً على السياق والنوع.

معلمات الطريق

app.MapGet("/users/{id:int}", (int id) => $"User {id}");
app.MapGet("/files/{*path}", (string path) => $"File: {path}"); // catch-all

معلمات سلسلة الاستعلام

app.MapGet("/search", (string? query, int page = 1, int pageSize = 20) =>
 Results.Ok(new { query, page, pageSize }));

تصبح الأنواع الخالية معلمات اختيارية. تعمل القيم الافتراضية تمامًا كما تتوقع.

نص الطلب

app.MapPost("/orders", (Order order) =>
{
 // 'order' is automatically deserialized from the JSON body
 return Results.Created($"/orders/{order.Id}", order);
});

ربط الرأس والخدمة

app.MapGet("/protected", (
 [FromHeader(Name = "X-Api-Key")] string apiKey,
 [FromServices] ILogger<Program> logger) =>
{
 logger.LogInformation("Request with API key: {Key}", apiKey[..4] + "****");
 return Results.Ok("Authorized");
});

HttpContext وHttpRequest

عندما تحتاج إلى الوصول إلى المستوى الأدنى:

app.MapGet("/info", (HttpContext context) =>
{
 var userAgent = context.Request.Headers.UserAgent.ToString();
 var ip = context.Connection.RemoteIpAddress?.ToString();
 return Results.Ok(new { userAgent, ip });
});

ربط مخصص باستخدام BindAsync

بالنسبة للأنواع المعقدة، يمكنك تنفيذ طريقة ثابتة BindAsync:

public record PaginationParams(int Page, int PageSize)
{
 public static ValueTask<PaginationParams?> BindAsync(HttpContext context)
 {
 int.TryParse(context.Request.Query["page"], out var page);
 int.TryParse(context.Request.Query["pageSize"], out var pageSize);

 var result = new PaginationParams(
 Page: page > 0 ? page : 1,
 PageSize: pageSize > 0 ? Math.Min(pageSize, 100) : 20
 );

 return ValueTask.FromResult<PaginationParams?>(result);
 }
}

app.MapGet("/items", (PaginationParams pagination, AppDbContext db) =>
{
 var items = db.Items
 .Skip((pagination.Page - 1) * pagination.PageSize)
 .Take(pagination.PageSize)
 .ToList();

 return Results.Ok(items);
});

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

التحقق من الصحة

أحد المجالات التي لا يمنحك فيها الحد الأدنى من واجهات برمجة التطبيقات (APIs) قدرًا كبيرًا من خارج الصندوق مقارنةً بوحدات التحكم هو التحقق من صحة النموذج. لا يوجد تنفيذ تلقائي لـ [Required] أو [StringLength]. ولكن هناك أنماط نظيفة للتعامل معها.

التحقق اليدوي

أبسط طريقة — فقط قم بالتحقق من صحة المعالج:

app.MapPost("/users", (CreateUserRequest request) =>
{
 if (string.IsNullOrWhiteSpace(request.Email))
 return Results.BadRequest(new { Error = "Email is required" });

 if (request.Name?.Length > 100)
 return Results.BadRequest(new { Error = "Name must be 100 characters or less" });

 // Create user...
 return Results.Created($"/users/{request.Email}", request);
});

استخدام مكتبة التحقق من الصحة

بالنسبة لأي شيء غير تافه، أنصحك بالوصول إلى FluentValidation أو مكتبة مشابهة:

public class CreateUserValidator : AbstractValidator<CreateUserRequest>
{
 public CreateUserValidator()
 {
 RuleFor(x => x.Email).NotEmpty().EmailAddress();
 RuleFor(x => x.Name).NotEmpty().MaximumLength(100);
 RuleFor(x => x.Age).InclusiveBetween(0, 150);
 }
}

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

مرشحات نقطة النهاية

تعد مرشحات نقطة النهاية واحدة من أفضل ميزات Minimal APIs. فكر فيها كبرامج وسيطة، ولكنها تستهدف نقاط نهاية محددة بدلاً من خط الأنابيب بأكمله. لقد تم تقديمها في .NET 7 وهي رائعة للاهتمامات الشاملة.

الفلتر الأساسي

app.MapPost("/todos", (Todo todo) =>
{
 // Handle the request
 return Results.Created($"/todos/{todo.Id}", todo);
})
.AddEndpointFilter(async (context, next) =>
{
 var todo = context.GetArgument<Todo>(0);

 if (string.IsNullOrEmpty(todo.Title))
 {
 return Results.BadRequest(new { Error = "Title is required" });
 }

 return await next(context);
});

مرشح التحقق من الصحة باستخدام FluentValidation

هنا يصبح الأمر قويًا حقًا - مرشح التحقق من الصحة القابل لإعادة الاستخدام:

public class ValidationFilter<T> : IEndpointFilter where T : class
{
 private readonly IValidator<T> _validator;

 public ValidationFilter(IValidator<T> validator)
 {
 _validator = validator;
 }

 public async ValueTask<object?> InvokeAsync(
 EndpointFilterInvocationContext context,
 EndpointFilterDelegate next)
 {
 var model = context.Arguments
 .OfType<T>()
 .FirstOrDefault();

 if (model is null)
 return Results.BadRequest(new { Error = "Request body is required" });

 var result = await _validator.ValidateAsync(model);

 if (!result.IsValid)
 {
 var errors = result.Errors
 .GroupBy(e => e.PropertyName)
 .ToDictionary(g => g.Key, g => g.Select(e => e.ErrorMessage).ToArray());

 return Results.ValidationProblem(errors);
 }

 return await next(context);
 }
}

// Usage
app.MapPost("/users", (CreateUserRequest request) =>
{
 // Only reached if validation passes
 return Results.Created($"/users/{request.Email}", request);
})
.AddEndpointFilter<ValidationFilter<CreateUserRequest>>();

مرشح التسجيل

app.MapGet("/products", (AppDbContext db) => db.Products.ToList())
 .AddEndpointFilter(async (context, next) =>
 {
 var logger = context.HttpContext
 .RequestServices.GetRequiredService<ILogger<Program>>();

 var sw = Stopwatch.StartNew();
 var result = await next(context);
 sw.Stop();

 logger.LogInformation("Endpoint executed in {Elapsed}ms", sw.ElapsedMilliseconds);

 return result;
 });

يمكنك ربط مرشحات متعددة، ويتم تنفيذها بالترتيب الذي تمت إضافتها به - تمامًا مثل البرامج الوسيطة.

تكامل OpenAPI/Swagger

لم تعد وثائق API الجيدة اختيارية بعد الآن. لحسن الحظ، تتمتع Minimal APIs بدعم من الدرجة الأولى لـ OpenAPI من خلال الحزمة Microsoft.AspNetCore.OpenApi.

الإعداد الأساسي

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/todos", () => new List<Todo>())
 .WithName("GetTodos")
 .WithDescription("Retrieves all todo items")
 .WithTags("Todos");

app.Run();

بيانات تعريف نقطة النهاية الغنية

يمكنك تقديم معلومات مفصلة حول نقاط النهاية الخاصة بك:

app.MapPost("/todos", (Todo todo) =>
{
 return Results.Created($"/todos/{todo.Id}", todo);
})
.WithName("CreateTodo")
.WithDescription("Creates a new todo item")
.WithTags("Todos")
.Accepts<Todo>("application/json")
.Produces<Todo>(StatusCodes.Status201Created)
.Produces(StatusCodes.Status400BadRequest)
.ProducesValidationProblem();

استخدام WithOpenApi للتخصيص

للتحكم الدقيق في مستند OpenAPI الذي تم إنشاؤه:

app.MapGet("/todos/{id:int}", (int id) => Results.Ok(new Todo(id, "Sample", false)))
 .WithOpenApi(operation =>
 {
 operation.Summary = "Get a specific todo";
 operation.Description = "Retrieves a single todo item by its unique identifier.";
 operation.Parameters[0].Description = "The unique identifier of the todo item";
 return operation;
 });

يمنحك هذا نفس مستوى التحكم في التوثيق الذي تحصل عليه مع تعليقات Swashbuckle XML على وحدات التحكم، ولكن بطريقة أكثر وضوحًا، تعتمد على الكود أولاً.

المصادقة والترخيص

يتبع تأمين نقاط نهاية Minimal API نفس الأنماط مثل بقية ASP.NET Core - ما عليك سوى تطبيقها بشكل مختلف.

الإعداد الأساسي```csharp

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options => { options.Authority = “https://your-identity-provider.com”; options.Audience = “your-api”; });

builder.Services.AddAuthorizationBuilder() .AddPolicy(“AdminOnly”, policy => policy.RequireRole(“Admin”)) .AddPolicy(“PremiumUser”, policy => policy.RequireClaim(“subscription”, “premium”));

var app = builder.Build();

app.UseAuthentication(); app.UseAuthorization();


### تطبيق التفويض على نقاط النهاية

```csharp
// Require any authenticated user
app.MapGet("/profile", (ClaimsPrincipal user) =>
{
 return Results.Ok(new
 {
 Name = user.FindFirstValue(ClaimTypes.Name),
 Email = user.FindFirstValue(ClaimTypes.Email)
 });
}).RequireAuthorization();

// Require a specific policy
app.MapDelete("/admin/users/{id}", (int id) =>
{
 // Delete user logic
 return Results.NoContent();
}).RequireAuthorization("AdminOnly");

// Allow anonymous access
app.MapGet("/public/health", () => Results.Ok(new { Status = "Healthy" }))
 .AllowAnonymous();

لاحظ كيف يمكنك إدخال ClaimsPrincipal مباشرة في معلمات المعالج الخاص بك - يعتني إطار العمل بالباقي. هذا هو أحد الأشياء الصغيرة التي تجعل Minimal APIs تبدو أنيقة حقًا.

تنظيم واجهات برمجة التطبيقات الكبيرة

إن أهم ما يميز الغرفة مع الحد الأدنى من واجهات برمجة التطبيقات (APIs) هو التنظيم. عندما يحتوي Program.cs على 50 نقطة نهاية، يصبح الأمر في حالة من الفوضى. فيما يلي الأنماط التي أستخدمها لإبقاء الأمور قابلة للإدارة.

مجموعات الطريق

تتيح لك مجموعات المسار (المقدمة في .NET 7) مشاركة التكوين عبر نقاط النهاية ذات الصلة:

var todos = app.MapGroup("/todos")
 .WithTags("Todos")
 .RequireAuthorization();

todos.MapGet("/", (AppDbContext db) => db.Todos.ToListAsync());
todos.MapGet("/{id:int}", (int id, AppDbContext db) => db.Todos.FindAsync(id));
todos.MapPost("/", (Todo todo, AppDbContext db) =>
{
 db.Todos.Add(todo);
 db.SaveChangesAsync();
 return Results.Created($"/todos/{todo.Id}", todo);
});

تشترك جميع نقاط النهاية في المجموعة في البادئة /todos والعلامة Todos ومتطلبات الترخيص. ينظف.

طرق التمديد

هذا هو النمط الذي يقاس حقًا. انقل كل مجموعة من نقاط النهاية إلى فئتها الثابتة الخاصة بها:

// Endpoints/TodoEndpoints.cs
public static class TodoEndpoints
{
 public static RouteGroupBuilder MapTodoEndpoints(this WebApplication app)
 {
 var group = app.MapGroup("/todos").WithTags("Todos");

 group.MapGet("/", GetAll);
 group.MapGet("/{id:int}", GetById);
 group.MapPost("/", Create);
 group.MapPut("/{id:int}", Update);
 group.MapDelete("/{id:int}", Delete);

 return group;
 }

 private static async Task<IResult> GetAll(AppDbContext db)
 => Results.Ok(await db.Todos.ToListAsync());

 private static async Task<IResult> GetById(int id, AppDbContext db)
 => await db.Todos.FindAsync(id) is { } todo
 ? Results.Ok(todo)
 : Results.NotFound();

 private static async Task<IResult> Create(Todo todo, AppDbContext db)
 {
 db.Todos.Add(todo);
 await db.SaveChangesAsync();
 return Results.Created($"/todos/{todo.Id}", todo);
 }

 private static async Task<IResult> Update(int id, Todo updated, AppDbContext db)
 {
 var todo = await db.Todos.FindAsync(id);
 if (todo is null) return Results.NotFound();

 todo.Title = updated.Title;
 todo.IsComplete = updated.IsComplete;
 await db.SaveChangesAsync();

 return Results.Ok(todo);
 }

 private static async Task<IResult> Delete(int id, AppDbContext db)
 {
 var todo = await db.Todos.FindAsync(id);
 if (todo is null) return Results.NotFound();

 db.Todos.Remove(todo);
 await db.SaveChangesAsync();

 return Results.NoContent();
 }
}

// Program.cs — stays clean
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapTodoEndpoints();
app.MapUserEndpoints();
app.MapOrderEndpoints();

app.Run();

يصبح Program.cs الخاص بك جدول محتويات لواجهة برمجة التطبيقات (API) الخاصة بك. تعيش كل مجموعة نقاط نهاية في ملف خاص بها. هذا هو النهج الذي أوصي به لتطبيقات الإنتاج.

مكتبة كارتر

إذا كنت تريد المزيد من البنية، فإن مكتبة كارتر توفر منهجًا يعتمد على الوحدة:

public class TodoModule : ICarterModule
{
 public void AddRoutes(IEndpointRouteBuilder app)
 {
 app.MapGet("/todos", async (AppDbContext db) =>
 await db.Todos.ToListAsync());

 app.MapPost("/todos", async (Todo todo, AppDbContext db) =>
 {
 db.Todos.Add(todo);
 await db.SaveChangesAsync();
 return Results.Created($"/todos/{todo.Id}", todo);
 });
 }
}

يكتشف كارتر جميع الوحدات ويسجلها تلقائيًا. إنها حل وسط لطيف بين نهج Minimal API الخام ووحدات التحكم الكاملة.

النتائج المكتوبة وأنواع الاستجابات

بدءًا من .NET 7، يمكنك استخدام TypedResults بدلاً من Results للاستجابات الآمنة. قد يبدو هذا تغييرًا بسيطًا، لكن له فوائد حقيقية لتوثيق OpenAPI وقابلية الاختبار.

app.MapGet("/todos/{id:int}", async Task<Results<Ok<Todo>, NotFound>> (int id, AppDbContext db) =>
{
 var todo = await db.Todos.FindAsync(id);
 return todo is not null
 ? TypedResults.Ok(todo)
 : TypedResults.NotFound();
});

يخبر نوع الإرجاع Results<Ok<Todo>, NotFound> بوضوح إطار العمل (ومستندات OpenAPI الخاصة بك) بأنواع الاستجابة التي يمكن أن تنتجها نقطة النهاية هذه بالضبط. لا مزيد من التخمين، ولا مزيد من الاستدعاءات اليدوية Produces<>() للحالات الأساسية.

للحصول على نتائج محتملة متعددة:

app.MapPost("/todos",
 async Task<Results<Created<Todo>, ValidationProblem, Conflict>>
 (Todo todo, AppDbContext db) =>
{
 if (string.IsNullOrEmpty(todo.Title))
 return TypedResults.ValidationProblem(
 new Dictionary<string, string[]>
 {
 { "Title", new[] { "Title is required" } }
 });

 if (await db.Todos.AnyAsync(t => t.Title == todo.Title))
 return TypedResults.Conflict();

 db.Todos.Add(todo);
 await db.SaveChangesAsync();

 return TypedResults.Created($"/todos/{todo.Id}", todo);
});

لقد بدأت باستخدام TypedResults في جميع المشاريع الجديدة. يلتقط المترجم عدم التطابق بين أنواع الإرجاع المعلنة وما تقوم بإرجاعه بالفعل، مما يلغي فئة كاملة من مفاجآت وقت التشغيل.

اعتبارات الأداء

يعد الأداء إحدى نقاط البيع لواجهات برمجة التطبيقات البسيطة (Minimal APIs)، ومن الجدير أن نفهم لماذا تكون أسرع.

خفض تكاليف بدء التشغيل. تعتمد وحدات التحكم بشكل كبير على الانعكاس لاكتشاف نقاط النهاية وربط النماذج وتطبيق عوامل التصفية. يستخدم الحد الأدنى من واجهات برمجة التطبيقات مولدات المصدر (تبدأ في .NET 7) لإنشاء تعليمات برمجية ملزمة في وقت الترجمة. وهذا يعني عملاً أقل عند بدء التشغيل وتخصيصًا أقل للذاكرة لكل طلب.

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

تجميع RequestDelegate. يقوم إطار العمل بتجميع تعبيرات lambda الخاصة بك في مثيلات RequestDelegate المحسنة. الكود الناتج قريب جدًا مما كنت ستكتبه يدويًا إذا كنت تعمل مباشرة مع HttpContext.

فيما يلي بعض النصائح العملية لتحقيق أقصى قدر من الأداء:

// Use AsNoTracking for read-only queries
app.MapGet("/products", async (AppDbContext db) =>
 await db.Products.AsNoTracking().ToListAsync());

// Return results directly — avoid unnecessary allocations
app.MapGet("/count", async (AppDbContext db) =>
 await db.Products.CountAsync());

// Use cancellation tokens for long-running operations
app.MapGet("/report", async (AppDbContext db, CancellationToken ct) =>
 await db.Orders
 .AsNoTracking()
 .GroupBy(o => o.Status)
 .Select(g => new { Status = g.Key, Count = g.Count() })
 .ToListAsync(ct));
```ومن الجدير بالذكر أيضًا أن فجوة الأداء بين وحدات التحكم وواجهات برمجة التطبيقات البسيطة تستمر في التضييق مع كل إصدار .NET. بالنسبة لمعظم التطبيقات، لن يكون الاختلاف هو عنق الزجاجة لديك، بل سيكون ذلك من خلال استعلامات قاعدة البيانات واستدعاءات الخدمة الخارجية. اختر بناءً على خبرة المطور واحتياجات المشروع، وليس المعايير.

## الخلاصة

لقد قطع الحد الأدنى من واجهات برمجة التطبيقات (APIs) شوطًا طويلًا منذ تقديمها في .NET 6. وما بدأ كميزة تجريبية "hello World" قد تطور ليصبح خيارًا مشروعًا لواجهات برمجة تطبيقات الإنتاج. باستخدام عوامل تصفية نقطة النهاية ومجموعات المسارات والنتائج المكتوبة ودعم OpenAPI القوي، لديك كل ما تحتاجه لإنشاء خدمات جيدة التنظيم وقابلة للصيانة.

توصيتي؟ إذا كنت تبدأ مشروعًا جديدًا لواجهة برمجة التطبيقات (API) - خاصةً خدمة صغيرة أو واجهة برمجة تطبيقات داخلية مركزة - فجرّب Minimal APIs بجدية. استخدم نمط أسلوب الامتداد للتنظيم، واعتمد على مرشحات نقطة النهاية للاهتمامات الشاملة، واستفد من `TypedResults` لسلامة النوع.

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

ترميز سعيد!

استخدام CSS المعزول في مكونات Blazor

Wed, 12 Mar 2025 00:00:00 +0000

الشيء الوحيد الذي كان يزعجني دائمًا عند العمل مع Blazor هو مدى سهولة كسر الأنماط عبر المكونات عن طريق الخطأ. يمكنك إضافة فصل دراسي في مكون واحد وفجأة يبدو شيء آخر في صفحة مختلفة تمامًا. اتضح أن Blazor لديه حل مدمج لهذا: عزل CSS.

ما هو عزل CSS؟

يتيح لك عزل CSS نطاق الأنماط لمكون معين. يقوم Blazor بذلك عن طريق إنشاء سمة فريدة لكل مكون في وقت الإنشاء وإلحاقها بمحددات CSS. لذلك تنطبق أنماطك فقط على المكون الذي تنتمي إليه.

لا حاجة لتسمية BEM، ولا حاجة لاختراقات خصوصية مجنونة. فقط CSS نظيف ومحدد النطاق.

#طريقة استخدامه

لنفترض أن لديك مكونًا يسمى Card.razor:

<div class="card">
 <h3 class="card-title">@Title</h3>
 <p class="card-body">@ChildContent</p>
</div>

@code {
 [Parameter]
 public string Title { get; set; }

 [Parameter]
 public RenderFragment ChildContent { get; set; }
}

لإضافة أنماط معزولة، ما عليك سوى إنشاء ملف بنفس الاسم ولكن بامتداد .razor.css. في هذه الحالة: Card.razor.css.

.card {
 border: 1px solid var(--color-border);
 border-radius: 8px;
 padding: 1rem;
 background: var(--color-bg-secondary);
}

.card-title {
 font-size: 1.1rem;
 font-weight: 600;
 margin-bottom: 0.5rem;
}

.card-body {
 color: var(--color-text-secondary);
 font-size: 0.9rem;
}

وهذا كل شيء! سوف يلتقطه Blazor تلقائيًا ويوسع نطاق هذه الأنماط إلى مكون Card فقط. إذا كان لديك فصل .card آخر في مكان آخر، فلن يتأثر.

#كيف يعمل تحت غطاء محرك السيارة

عندما تقوم بإنشاء مشروعك، يقوم Blazor بإعادة كتابة HTML وCSS. يحصل المكون الخاص بك على سمة فريدة مثل b-3x8qz7k2f1، ويتم إلحاق محددات CSS بهذه السمة:

.card[b-3x8qz7k2f1] {
 border: 1px solid var(--color-border);
 /* ... */
}

يتم تقديم حزمة CSS التي تم إنشاؤها كـ {ProjectName}.styles.css. تأكد من وجود هذا في index.html أو _Host.cshtml:

<link href="YourApp.styles.css" rel="stylesheet" />

إذا كنت تفتقد هذا الرابط، فلن تظهر أنماطك المعزولة وستقضي 30 دقيقة تتساءل عما يحدث. ثق بي، لقد كنت هناك.

استهداف العناصر الفرعية

شيء واحد يجب أخذه في الاعتبار هو أنه افتراضيًا، ينطبق CSS المعزول فقط على عناصر المكون الحالي. إذا كنت تريد تصميم العناصر داخل مكون فرعي، فأنت بحاجة إلى أداة الدمج ::deep:

::deep .child-element {
 color: red;
}

هذا يخبر Blazor بتطبيق النمط على العناصر المطابقة داخل المكونات الفرعية أيضًا. مفيد جدًا عندما يكون لديك مكون مجمع يحتاج إلى تصميم أبنائه.

#متى يتم استخدامه

أستخدم عزل CSS لكل مكون تقريبًا الآن. إنها تحافظ على الأشياء نظيفة ويمكن التنبؤ بها. المرة الوحيدة التي لا أستخدمها فيها هي للأنماط العالمية مثل عمليات إعادة التعيين أو الطباعة أو متغيرات السمات - تلك التي تدخل في ملف CSS مشترك.

آمل أن تكونوا قد أحببت هذا المنصب! لا تتردد في الاتصال بي على أي وسائل التواصل الاجتماعي على **@emimontesdeoca **.

الموارد

عزل ASP.NET Core Blazor CSS

التحكم في إنفاق عيد الميلاد باستخدام Semantic Kernel

Sat, 28 Dec 2024 00:00:00 +0000

## مقدمة

مع اقتراب موسم العطلات، يمكن أن تصبح إدارة النفقات تحديًا، خاصة مع موجة التسوق وشراء الهدايا. في منشور المدونة هذا، سنستكشف كيفية الاستفادة من الذكاء الاصطناعي للمساعدة في تتبع إنفاقك في عيد الميلاد باستخدام تقنيات .NET. من خلال تحليل الإيصالات بقوة Semantic Kernel والذكاء الاصطناعي، يمكننا استخراج التفاصيل الأساسية بكفاءة مثل أسماء المتاجر والتواريخ وقوائم العناصر والمبالغ الإجمالية. يتيح لك هذا الحل مراقبة إنفاقك في عيد الميلاد وإدارته بسهولة، مما يضمن لك البقاء على اطلاع بميزانيتك دون الحاجة إلى مراجعة الإيصالات يدويًا.

Calendario de Adviento de Inteligencia Artificial 2024 en Español

استلهم هذا المشروع من مشاركتي في Calendario de Adviento de Inteligencia Artificial 2024 en Español، وهو حدث عبر الإنترنت مخصص للذكاء الاصطناعي. يمكنك العثور على المزيد حول الحدث على رابط Dev.to هذا.

##المشروع

في هذا المشروع، سنستخدم Azure OpenAI، وهي خدمة تتيح لنا استخدام نماذج الذكاء الاصطناعي القوية مثل GPT-4 لمعالجة الصور وتحليلها. تتضمن العملية عدة خطوات، بدءًا من إعداد خدمة واجهة برمجة التطبيقات الخلفية وحتى التكامل مع الواجهة الأمامية لـ Blazor لتحميل الصور. سنستخدم أيضًا .NET Aspire، وهو مكون يساعد على ربط كل شيء بسلاسة.

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

قبل أن نتعمق في الكود، تأكد من أن لديك المتطلبات الأساسية التالية:

-.نت 9

الوصول إلى Azure OpenAI (مفتاح API)
Visual Studio أو Visual Studio Code
المعرفة الأساسية بـ Blazor وعملاء HTTP وتطوير واجهة برمجة التطبيقات

حل Visual Studio

سينتهي بنا الأمر بالحصول على شيء كهذا، أحب أن أبقي الأشياء منفصلة وبأسماء رائعة، فإليك كيف يبدو الأمر:

ولكن دعونا نمضي قدمًا في إنشاء الأشياء خطوة بخطوة!

الخطوة 0: النماذج

يعتمد جوهر تطبيق Receipt Scanner على العديد من النماذج الرئيسية التي تسهل التفاعل بين خدمات الواجهة الأمامية وواجهة برمجة التطبيقات (API) وخدمات الذكاء الاصطناعي (AI). وفيما يلي النماذج الرئيسية المستخدمة في هذا المشروع:

طلب تحليل الإيصال
يمثل هذا النموذج بنية الطلب لتحليل الإيصال. يحتوي على خاصية ImageBytes، التي تحتوي على مصفوفة البايت لصورة الإيصال التي ستتم معالجتها.
```
public class AnalyzeReceiptRequest
{
 public byte[] ImageBytes { get; set; }
}
```
نتيجة تحليل الإيصال
يلتقط هذا النموذج النتيجة بعد معالجة الإيصال. ويحتفظ بالبيانات المنظمة المستخرجة من الإيصال، مثل اسم المتجر والتاريخ والأصناف والمبلغ الإجمالي.
```
public class ReceiptAnalyzeResult
{
 public DateTime CreatedAt { get; set; }
 public ReceiptData Result { get; set; }
}
```
بيانات الاستلام
هذا هو النموذج الذي يحمل بيانات الاستلام المنظمة. ويتضمن خصائص اسم المتجر، والتاريخ، وقائمة العناصر (مع اسم كل عنصر وسعره)، والمبلغ الإجمالي في الإيصال.
```
public class ReceiptData
{
 public string Store { get; set; }
 public DateTime? Date { get; set; }
 public List<ReceiptItem> Items { get; set; }
 public decimal? Total { get; set; }
}
```

عنصر الإيصال
يتم تمثيل كل عنصر في الإيصال بواسطة هذا النموذج. يحمل اسم السلعة وسعرها.

public class ReceiptItem
{
 public string Name { get; set; }
 public decimal? Price { get; set; }
}
```تعمل هذه النماذج كأساس لتمرير البيانات بين العميل والخادم، مما يضمن التدفق السلس للمعلومات. تتلقى واجهة برمجة التطبيقات (API) صورة الإيصال، وفي المقابل، تقوم بمعالجة وإرجاع كائن JSON منظم يمكن استهلاكه بسهولة بواسطة الواجهة الأمامية.

الخطوة 1: إعداد خدمة Backend API

الخطوة الأولى في بناء هذا التطبيق هي إعداد خدمة API لتحليل صور الإيصالات. سنستخدم Azure OpenAI API لاستخراج المعلومات من صور الإيصال. فيما يلي تفصيل لكيفية تناسب كل شيء معًا:

خدمة الذكاء الاصطناعي - نظرة عميقة

تقع خدمة الذكاء الاصطناعي في قلب نظام تحليل الإيصالات الخاص بنا. إنها مسؤولة عن التواصل مع واجهة برمجة تطبيقات Azure OpenAI لمعالجة بيانات الصورة وإرجاع رؤى ذات معنى. فئة AiApiClient هي العميل الذي سيتعامل مع كافة التفاعلات مع Azure OpenAI API.

تنفيذ عميل الذكاء الاصطناعي

AiApiClient هو المكون الرئيسي المسؤول عن إرسال صورة الإيصال (بتنسيق صفيف البايت) إلى Azure OpenAI API. يتعامل مع الاتصالات وتسجيل الأخطاء وتحليل البيانات:

public class AiApiClient
{
 private readonly HttpClient _httpClient;
 private readonly ILogger<AiApiClient> _logger;

 public AiApiClient(HttpClient httpClient, ILogger<AiApiClient> logger)
 {
 _httpClient = httpClient;
 _logger = logger;
 }

 public async Task<ReceiptAnalyzeResult?> AnalyzeAsync(byte[] imageBytes, CancellationToken cancellationToken = default)
 {
 if (imageBytes == null || imageBytes.Length == 0)
 {
 _logger.LogWarning("ImageBytes is null or empty.");
 return null;
 }

 _logger.LogInformation("Sending analyze request with image bytes of length: {Length}", imageBytes.Length);

 var request = new AnalyzeReceiptRequest
 {
 ImageBytes = imageBytes
 };

 try
 {
 var response = await _httpClient.PostAsJsonAsync("/analyze-receipt", request, cancellationToken);

 if (!response.IsSuccessStatusCode)
 {
 _logger.LogWarning("Failed to analyze receipt. StatusCode: {StatusCode}", response.StatusCode);
 return null;
 }

 var analyzeResult = await response.Content.ReadFromJsonAsync<ReceiptAnalyzeResult>(cancellationToken: cancellationToken);

 if (analyzeResult == null)
 {
 _logger.LogWarning("No content received from AI API service.");
 return null;
 }

 _logger.LogInformation("Analysis result received: {AnalyzeResult}", analyzeResult);

 return analyzeResult;
 }
 catch (Exception ex)
 {
 _logger.LogError(ex, "An error occurred while analyzing the receipt.");
 return null;
 }
 }
}

في هذا الجزء من الكود، قمنا بتعريف الطريقة AnalyzeAsync، وهي المسؤولة عن:

إرسال مصفوفة بايت الصورة إلى Azure OpenAI API.
التعامل مع أي أخطاء أو استجابات غير ناجحة من API.
تحليل بيانات JSON التي تم إرجاعها إلى نتيجة منظمة (ReceiptAnalyzeResult).

تتضمن فوائد فصل هذه الوظيفة إلى خدمة مخصصة (AiApiClient) ما يلي:

معالجة الأخطاء: معالجة مركزية للأخطاء مثل مشكلات الشبكة أو الاستجابات غير الصالحة.
التسجيل: التسجيل الصحيح للطلبات والاستجابات لمراقبة سلوك النظام.

خدمة API - التعامل مع الطلبات والردود

تعمل خدمة API كوسيط بين تطبيق Blazor للواجهة الأمامية وخدمة الذكاء الاصطناعي. هذه الخدمة مسؤولة عن قبول بيانات الصورة وتمريرها إلى خدمة الذكاء الاصطناعي وإرجاع نتائج التحليل إلى العميل.

نقطة نهاية واجهة برمجة التطبيقات

في هذه الخطوة، نحدد نقطة نهاية بسيطة لواجهة برمجة التطبيقات (API) لقبول صور الإيصالات، وإعادة توجيهها إلى خدمة الذكاء الاصطناعي للمعالجة، وإرجاع النتائج إلى العميل:

using ReceiptScanner.Shared.Clients;
using ReceiptScanner.Shared.Models;

var builder = WebApplication.CreateBuilder(args);

// Add service defaults & Aspire client integrations.
builder.AddServiceDefaults();

// Add services to the container.
builder.Services.AddProblemDetails();

// Register AiApiClient with HttpClient
builder.Services.AddHttpClient<AiApiClient>(client =>
{
 client.BaseAddress = new Uri("https+http://aiservice");
});

// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.UseExceptionHandler();

if (app.Environment.IsDevelopment())
{
 app.MapOpenApi();
}

// POST endpoint to analyze receipt
app.MapPost("/api/analyze-receipt", async (AnalyzeReceiptRequest request, AiApiClient aiApiClient, ILogger<Program> logger) =>
{
 if (request.ImageBytes == null || request.ImageBytes.Length == 0)
 {
 logger.LogWarning("ImageBytes is null or empty.");
 return Results.BadRequest("ImageBytes is required.");
 }

 logger.LogInformation("Received analyze receipt request with image bytes of length: {Length}", request.ImageBytes.Length);

 try
 {
 var result = await aiApiClient.AnalyzeAsync(request.ImageBytes);

 if (result == null)
 {
 logger.LogWarning("Failed to analyze the receipt.");
 return Results.Problem("Unable to process the receipt at this time. Please try again later.");
 }

 logger.LogInformation("Analysis completed successfully. Result: {Result}", result);

 return Results.Ok(result);
 }
 catch (Exception ex)
 {
 logger.LogError(ex, "An error occurred while processing the receipt.");
 return Results.Problem("An error occurred while processing the receipt. Please try again later.");
 }
});

app.MapDefaultEndpoints();

app.Run();

نقطة النهاية هذه:

قبول صورة الإيصال كجزء من نص الطلب.
يستدعي أسلوب النقطة الداخلية AiService لإرسال الصورة إلى Azure OpenAI للمعالجة.
إرجاع نتيجة التحليل إلى العميل.

الخطوة الثانية: إعداد واجهة Blazor الأمامية

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

تنفيذ صفحة Blazor

توفر صفحة Blazor واجهة بسيطة حيث يمكن للمستخدمين تحميل صور إيصالات متعددة ثم رؤية نتائج التحليل معروضة في جدول. وهذا هو الكود الخاص بالصفحة:

@page "/analyzer"
@using ReceiptScanner.Shared.Clients
@using ReceiptScanner.Shared.Models
@using System.Globalization
@inject ApiServiceClient ApiClient
@inject ILogger<Program> Logger

@attribute [StreamRendering]
@rendermode InteractiveServer

<PageTitle>Receipt Analyzer</PageTitle>

<h1 class="text-center my-4">Receipt Analyzer</h1>

<div class="container">
 <p class="lead text-center mb-4">Upload receipt images below to extract their data.</p>

 <!-- File Upload Section -->
 <div class="card mb-4">
 <div class="card-body">
 <InputFile OnChange="HandleFileSelected" multiple class="form-control mb-3" />
 <button class="btn btn-primary w-100" @onclick="ProcessReceipts" disabled="@(!hasFiles)" type="button">
 <span class="@(!processing ? "d-none" : "") spinner-border spinner-border-sm" role="status" aria-hidden="true"></span>
 @if (processing)
 {
 <span>Processing...</span>
 }
 else
 {
 <span>Process Receipts</span>
 }
 </button>
 </div>
 </div>

 <!-- Uploaded Images Preview -->
 @if (fileBytesList.Any())
 {
 <div class="card mb-4">
 <div class="card-header">
 <h5 class="mb-0">Uploaded Receipt Images</h5>
 </div>
 <div class="card-body">
 <div class="row">
 @foreach (var fileBytes in fileBytesList)
 {
 <div class="col-12 col-md-4 mb-3">
 <img src="@($"data:image/jpeg;base64,{Convert.ToBase64String(fileBytes)}")" class="img-fluid rounded" alt="Uploaded receipt" />
 </div>
 }
 </div>
 </div>
 </div>
 }

 <!-- Processing Indicator -->
 @if (processing)
 {
 <div class="alert alert-info text-center" role="alert">
 <strong>Processing receipts...</strong> Please wait while we analyze the uploaded files.
 </div>
 }

 <!-- Analysis Results Section -->
 @if (analyzedReceipts != null && analyzedReceipts.Any())
 {
 <div class="card">
 <div class="card-header">
 <h5 class="mb-0">Analysis Results</h5>
 </div>
 <div class="card-body">
 <table class="table table-striped table-bordered">
 <thead>
 <tr>
 <th>Store</th>
 <th>Date</th>
 <th>Total</th>
 <th>Items</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var receipt in analyzedReceipts)
 {
 <tr>
 <td>@(receipt.Result?.Store ?? "Unknown")</td>
 <td>@(receipt.Result?.Date?.ToString() ?? "Unknown")</td>
 <td>@(receipt.Result?.Total?.ToString("C", ci) ?? "Unknown")</td>
 <td>
 <ul class="list-unstyled">
 @if (receipt.Result?.Items is not null)
 {
 @foreach (var item in receipt.Result?.Items!)
 {
 <li><strong>@item.Name</strong> - @item.Price?.ToString("C", ci)</li>
 }
 }
 </ul>
 </td>
 </tr>
 }
 </tbody>
 </table>
 </div>
 </div>
 }
 else if (processed && (analyzedReceipts == null || !analyzedReceipts.Any()))
 {
 <div class="alert alert-warning text-center" role="alert">
 <strong>No results found.</strong> Please try again with different images or ensure they are clear and legible.
 </div>
 }
</div>

@code {
 private bool hasFiles;
 private bool processing;
 private bool processed;
 private List<byte[]> fileBytesList = new();
 private List<ReceiptAnalyzeResult> analyzedReceipts = new();
 CultureInfo ci = new CultureInfo("es-es");

 private async Task HandleFileSelected(InputFileChangeEventArgs e)
 {
 try
 {
 fileBytesList.Clear();

 foreach (var file in e.GetMultipleFiles())
 {
 var memoryStream = new MemoryStream();
 await file.OpenReadStream().CopyToAsync(memoryStream);
 fileBytesList.Add(memoryStream.ToArray());
 }

 hasFiles = fileBytesList.Any();
 }
 catch (Exception ex)
 {
 Logger.LogError(ex, "Error while handling file upload.");
 }
 }

 private async Task ProcessReceipts()
 {
 if (!hasFiles)
 return;

 processing = true;
 analyzedReceipts.Clear();

 try
 {
 foreach (var fileBytes in fileBytesList)
 {
 var result = await ApiClient.AnalyzeReceiptAsync(fileBytes);
 if (result != null)
 {
 analyzedReceipts.Add(result);
 }
 }
 }
 catch (Exception ex)
 {
 Logger.LogError(ex, "Error while processing receipts.");
 }
 finally
 {
 processing = false;
 processed = true;
 }
 }
}

```تسمح هذه الصفحة للمستخدمين بتحميل الإيصالات وإظهار نتائج التحليل في جدول يحتوي على أسماء المتاجر والتواريخ والمبالغ الإجمالية وقائمة العناصر.

<p align="center">
<img src="https://imgur.com/BLswKhm.png">
</ص>

## الخطوة 3: .NET Aspire

<p align="center">
<img src="https://imgur.com/ja56RWN.png">
</ص>

### ما هو .NET Aspire؟

.NET Aspire عبارة عن مجموعة من الأدوات والقوالب والحزم القوية لإنشاء تطبيقات يمكن ملاحظتها وجاهزة للإنتاج. يتم تسليم .NET Aspire من خلال مجموعة من حزم NuGet التي تتعامل مع اهتمامات محددة تتعلق بالسحابة الأصلية. غالبًا ما تتكون التطبيقات السحابية الأصلية من أجزاء صغيرة مترابطة أو خدمات صغيرة بدلاً من قاعدة تعليمات برمجية واحدة متجانسة. تستهلك التطبيقات السحابية بشكل عام عددًا كبيرًا من الخدمات، مثل قواعد البيانات والمراسلة والتخزين المؤقت. للحصول على معلومات حول الدعم، راجع سياسة دعم .NET Aspire.

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

يوفر استخدام **.NET Aspire** لهذا المشروع العديد من الفوائد التي تعمل على تحسين جودة النظام بشكل عام، مثل:

### 1. **التسجيل المركزي**

يقوم .NET Aspire بدمج التسجيل تلقائيًا عبر التطبيق بأكمله، مما يعني أنك لن تضطر إلى تكوين التسجيل يدويًا لكل خدمة. ويضمن ذلك اتساق السجلات وتخزينها في موقع مركزي، مما يجعل تصحيح الأخطاء والمراقبة أسهل بكثير.

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

```csharp
_logger.LogInformation("Sending analyze request with image bytes of length: {Length}",

 imageBytes.Length);

2. جمع المقاييس تلقائيًا

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

3. تحسين الأداء

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

4. التكامل السلس

يعمل .NET Aspire على تبسيط تكامل الخدمات المتنوعة (مثل خدمات الذكاء الاصطناعي وواجهة برمجة التطبيقات في هذا المشروع) وتبسيط عملية النشر. لا داعي للقلق بشأن التكوينات ذات المستوى المنخفض، حيث تتولى Aspire المهام المتعلقة بالبنية التحتية نيابةً عنك.

الخلاصةلم يعد الذكاء الاصطناعي مجرد كلمة طنانة أو شيء نراه في أفلام الخيال العلمي. إنها تعمل بنشاط على حل مشكلات العالم الحقيقي اليوم، مثل تلك التي عالجناها في هذا المشروع، وهي استخراج البيانات المنظمة من الإيصالات. بمساعدة Azure OpenAI و.NET Aspire وBlazor، يمكننا أتمتة المهمة اليدوية التي قد تستغرق وقتًا طويلاً وعرضة للأخطاء. لا يقوم الذكاء الاصطناعي فقط بالدردشة أو الاستجابة للمطالبات مثل ChatGPT؛ فهو يفسر الصور ويستخرج معلومات قيمة ويعطينا رؤى قابلة للتنفيذ في ثوانٍ.

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

يعد هذا المنشور جزءًا من Calendario de Adviento de Inteligencia Artificial 2024 en Español، وهو حدث يعرض تطبيقات الذكاء الاصطناعي في العالم الحقيقي ويقوم بتثقيف مجتمع التكنولوجيا الناطق بالإسبانية حول أحدث الاتجاهات. إذا كنت تتطلع إلى التعمق أكثر في الذكاء الاصطناعي وإمكانياته، فإن هذا الحدث يعد مكانًا رائعًا للبدء.

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

كود المصدر

كود المصدر الكامل لهذا المشروع متاح على GitHub. لا تتردد في تنزيله، واستكشاف كيفية عمل خدمات الذكاء الاصطناعي وواجهة برمجة التطبيقات معًا، وتكييفه ليناسب حالات الاستخدام الخاصة بك. إذا واجهت أية مشكلات، أو إذا كانت لديك أفكار للتحسينات، فلا تتردد في إنشاء مشكلة أو إرسال طلب سحب. المساهمات مرحب بها دائمًا، وستساعد تعليقاتك في جعل هذا المشروع أفضل!

ترميز سعيد!

هل تستخدم الحاويات... لتتبع أسعار هدايا عيد الميلاد؟

Thu, 12 Dec 2024 00:00:00 +0000

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

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

لماذا يتم أتمتة مراقبة الأسعار؟

تشبه أتمتة مراقبة الأسعار وجود فريق خاص بك من أقزام سانتا يعمل على مدار الساعة لضمان حصولك على أفضل الصفقات دون أن تحرك ساكنًا. إليك سبب إعجابك به:

العناصر باهظة الثمن: نعلم جميعًا أن هدايا عيد الميلاد يمكن أن تصبح باهظة الثمن، خاصة عندما تكون الأدوات والألعاب مدرجة في قائمتك. يمكن أن يكون توفير المال على هذه المنتجات مرضيًا تمامًا مثل العثور على آخر قطعة علوية للشجرة في المخزون.
الفحوصات اليومية: من لديه الوقت (أو الصبر) للتحقق من الأسعار كل يوم؟ ليس أنا!
الأتمتة: احتضن روح العطاء في العطلة، وامنح نفسك هدية الكفاءة.
الدقة: تضمن الأتمتة أن تكون عمليات التحقق من الأسعار دقيقة بقدر سطوع أنف رودولف.

التقنيات الأساسية

لبناء مساعد سانتا الصغير الخاص بي، قررت استخدام العديد من التقنيات الأساسية:

###حاويات

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

###بلازور

يعد Blazor إطارًا رائعًا لبناء تطبيقات الويب التفاعلية باستخدام .NET. يشبه الأمر استبدال ترانيم عيد الميلاد العامة بقائمة التشغيل الخاصة بك في العطلات، والتي تكون مصممة خصيصًا وفعالة وممتعة للغاية.

عامل الميناء يؤلف

Docker-Compose هو مدير عملياتنا في القطب الشمالي. فهو يساعدنا في الحفاظ على تشغيل جميع خدماتنا - مثل واجهة برمجة التطبيقات (API) والواجهة الأمامية لـ Blazor - معًا في وئام تام. فكر في الأمر كقائد لسيمفونية عطلتنا.

دليل خطوة بخطوة

الآن، دعونا نتعمق في ورشة عمل سانتا ونجعل هذا المشروع ينبض بالحياة!

الخطوة 1: إنشاء واجهة برمجة التطبيقات

1.1 إعداد المشروع

ارتدي قبعة سانتا للبرمجة وقم بإعداد مشروع ASP.NET Core Web API جديد. افتح جهازك الطرفي (يشبه إلى حد ما فتح تقويم المجيء الخاص بك) وقم بتشغيل:

dotnet new webapi -o PriceMonitorApi
cd PriceMonitorApi

يقوم هذا الأمر بإنشاء دليل جديد باسم PriceMonitorApi وإعداد مشروع Web API أساسي. تخيل أن الأمر يشبه إنشاء قاعدة متينة لمنزل خبز الزنجبيل الخاص بك.

1.2 إضافة HttpClient وحذف المكتباتبعد ذلك، أضف `HttpClient` ومكتبة لتحليل HTML. وستكون هذه مزلقتنا الموثوقة لجلب بيانات الأسعار وقراءتها.

dotnet add package HtmlAgilityPack

HtmlAgilityPack هو القزم الذي يساعدنا في تحليل مستندات HTML.

1.3 إنشاء النماذج

النماذج تشبه مخطط ألعابنا. لنقم بإنشاء نموذج لتمثيل معلومات المنتج:

namespace PriceMonitorApi.Models
{
 public class ProductInfo
 {
 public string Title { get; set; }
 public decimal Price { get; set; }
 public DateTime Date { get; set; }
 }
}

لقد أنشأنا للتو القالب المثالي لبياناتنا.

1.4 تنفيذ خدمة الكاشطة

تشبه خدمة الكشط لدينا مساعد سانتا الصغير، حيث تقوم بجلب المعلومات ومعالجتها لنا:

using HtmlAgilityPack;
using PriceMonitorApi.Models;
using System.Globalization;

namespace PriceMonitorApi.Services
{
 public class ScraperService
 {
 private readonly HttpClient _httpClient;

 public ScraperService(HttpClient httpClient)
 {
 _httpClient = httpClient;
 }

 public async Task<ProductInfo> ScrapeProductInfoAsync(string url)
 {
 var response = await _httpClient.GetStringAsync(url);

 var htmlDoc = new HtmlDocument();
 htmlDoc.LoadHtml(response);

 var title = htmlDoc.DocumentNode.SelectSingleNode("//h1[@class='product-title']").InnerText.Trim();
 var priceString = htmlDoc.DocumentNode.SelectSingleNode("//span[@class='product-price']").InnerText.Trim();

 if (decimal.TryParse(priceString, NumberStyles.Currency, CultureInfo.InvariantCulture, out var price))
 {
 return new ProductInfo
 {
 Title = title,
 Price = price,
 Date = DateTime.UtcNow
 };
 }

 throw new Exception("Unable to parse price");
 }
 }
}

يحول هذا المقتطف HtmlAgilityPack إلى عصا سحرية للعطلات.

1.5 إنشاء وحدة تحكم API

لنقم بإنشاء وحدة تحكم تعمل كحارس البوابة لبياناتنا:

using Microsoft.AspNetCore.Mvc;
using PriceMonitorApi.Models;
using PriceMonitorApi.Services;

namespace PriceMonitorApi.Controllers
{
 [ApiController]
 [Route("api/[controller]")]
 public class ScraperController : ControllerBase
 {
 private readonly ScraperService _scraperService;

 public ScraperController(ScraperService scraperService)
 {
 _scraperService = scraperService;
 }

 [HttpGet("productinfo")]
 public async Task<ActionResult<ProductInfo>> GetProductInfo(string url)
 {
 try
 {
 var productInfo = await _scraperService.ScrapeProductInfoAsync(url);
 return Ok(productInfo);
 }
 catch (Exception ex)
 {
 return BadRequest(new { Message = ex.Message });
 }
 }
 }
}

تضمن وحدة التحكم لدينا تسليم البيانات بشكل أسرع من تسليم سانتا أسفل المدخنة.

1.6 تسجيل الخدمات في حاوية DI

وأخيرًا، قم بتسجيل ScraperService للتأكد من أنه متاح عند الحاجة.

services.AddHttpClient<ScraperService>();

الآن أصبحت واجهة برمجة التطبيقات الخاصة بك جاهزة - مثل مزلقة سانتا عشية عيد الميلاد!

الخطوة الثانية: إنشاء تطبيق Blazor

يساعدنا Blazor في تزيين مشروعنا مثل شجرة عيد الميلاد، مما يجعله جذابًا بصريًا وتفاعليًا.

2.1 إعداد مشروع Blazor

بعد ذلك، سنقوم بإنشاء مشروع Blazor الذي يعمل كواجهة لركوب مزلقة لمراقبة الأسعار.

dotnet new blazor -o PriceMonitorBlazor
cd PriceMonitorBlazor

يُضفي هذا الأمر بعض سحر العطلة لإعداد مشروع Blazor WebAssembly الأساسي.

2.2 إضافة النماذج

تمامًا مثل إعداد الزخارف، قم بإضافة نموذج ProductInfo في مشروع Blazor:

namespace PriceMonitorBlazor.Models
{
 public class ProductInfo
 {
 public string Title { get; set; }
 public decimal Price { get; set; }
 public DateTime Date { get; set; }
 }
}

2.3 إنشاء الخدمة لاستدعاءات API

قم بإنشاء خدمة لجلب البيانات من واجهة برمجة التطبيقات (API) الخاصة بنا - فكر في الأمر على أنه صديقنا للتسوق عبر الإنترنت:

using PriceMonitorBlazor.Models;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace PriceMonitorBlazor.Services
{
 public class ScraperService
 {
 private readonly HttpClient _httpClient;

 public ScraperService(HttpClient httpClient)
 {
 _httpClient = httpClient;
 }

 public async Task<ProductInfo> GetProductInfoAsync(string url)
 {
 var response = await _httpClient.GetFromJsonAsync<ProductInfo>($"https://localhost:5001/api/scraper/productinfo?url={url}");
 return response;
 }
 }
}

2.4 تسجيل الخدمات في حاوية DI

تأكد من تسجيل ScraperService حتى نتمكن من إدخاله في مكوناتنا.

builder.Services.AddScoped<ScraperService>();

2.5 إنشاء مكون Blazor

قم بتحديث Pages/Index.razor ليشمل واجهة ممتعة وتفاعلية:

@page "/"
@using PriceMonitorBlazor.Models
@using PriceMonitorBlazor.Services
@inject ScraperService ScraperService

<h3>Price Monitor</h3>

<p>
 <label for="urlInput">Product URL:</label>
 <input id="urlInput" @bind="productUrl" />
 <button @onclick="FetchProductInfo">Fetch Price</button>
</p>

@if (productInfos.Any())
{
 <table class="table">
 <thead>
 <tr>
 <th>Title</th>
 <th>Price</th>
 <th>Date</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var product in productInfos)
 {
 <tr>
 <td>@product.Title</td>
 <td>@product.Price</td>
 <td>@product.Date</td>
 </tr>
 }
 </tbody>
 </table>
}

@code {
 private string productUrl;
 private List<ProductInfo> productInfos = new List<ProductInfo>();

 private async Task FetchProductInfo()
 {
 if (!string.IsNullOrEmpty(productUrl))
 {
 var productInfo = await ScraperService.GetProductInfoAsync(productUrl);
 productInfos.Add(productInfo);
 }
 }
}

إنه مثل إعداد عرض احتفالي للعطلات — مما يجعل تطبيقنا تفاعليًا ومبهجًا.

الخطوة 3: توصيل كل شيء باستخدام Docker-Compose

الآن دعونا نربط كل شيء باستخدام Docker-Compose، لنحول مشروعنا إلى رحلة مزلقة جيدة التزييت.

3.1 إنشاء ملفات Dockerfiles

قم بإنشاء Dockerfiles لكل من مشاريع API وBlazor:

PriceMonitorApi/Dockerfile:

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY ["PriceMonitorApi/PriceMonitorApi.csproj", "PriceMonitorApi/"]
RUN dotnet restore "PriceMonitorApi/PriceMonitorApi.csproj"
COPY . .
WORKDIR "/src/PriceMonitorApi"
RUN dotnet build "PriceMonitorApi.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "PriceMonitorApi.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "PriceMonitorApi.dll"]

PriceMonitorBlazor/Dockerfile:

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY ["PriceMonitorBlazor/PriceMonitorBlazor.csproj", "PriceMonitorBlazor/"]
RUN dotnet restore "PriceMonitorBlazor/PriceMonitorBlazor.csproj"
COPY . .
WORKDIR "/src/PriceMonitorBlazor"
RUN dotnet build "PriceMonitorBlazor.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "PriceMonitorBlazor.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "PriceMonitorBlazor.dll"]

3.2 إنشاء docker-compose.yml

قم بتوصيل جميع النقاط (أضواء عيد الميلاد) بملف docker-compose.yml واحد:

version: '3.4'

services:
 api:
 image: pricemonitorapi
 build:
 context: ./PriceMonitorApi
 dockerfile: Dockerfile
 ports:
 - "5000:80"
 networks:
 - price-monitor-network

 blazor:
 image: pricemonitorblazor
 build:
 context: ./PriceMonitorBlazor
 dockerfile: Dockerfile
 ports:
 - "5001:80"
 depends_on:
 - api
 networks:
 - price-monitor-network

networks:
 price-monitor-network:
 driver: bridge

المخططات

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

مخطط معمارية النظام

مخطط تدفق البيانات

مخطط التسلسل

مخطط المكونات لإعداد Docker

الخطوة 4: إدارة URL، والتحديث، والتحديث الدوري الآليفي هذا العرض التوضيحي، سنقوم فقط بتخزينه في الذاكرة، ولكن في التطبيق الحقيقي، يمكنك استخدام قاعدة بيانات. بالنسبة لهذا المشروع الممتع، دعونا نلتزم بالتخزين في الذاكرة.

4.1 تعديل الخدمة لإدارة عناوين URL

أولاً، سوف نتأكد من أن خدمتنا يمكنها التعامل مع إضافة عناوين URL واستردادها، بالإضافة إلى جلب معلومات المنتج:

تحديث Services/ScraperService.cs:

using PriceMonitorBlazor.Models;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace PriceMonitorBlazor.Services
{
 public class ScraperService
 {
 private readonly HttpClient _httpClient;
 private List<string> urls = new List<string>();

 public ScraperService(HttpClient httpClient)
 {
 _httpClient = httpClient;
 }

 public async Task<ProductInfo> GetProductInfoAsync(string url)
 {
 var response = await _httpClient.GetFromJsonAsync<ProductInfo>($"http://localhost:5000/api/scraper/productinfo?url={url}");
 return response;
 }

 public void AddUrl(string url)
 {
 if (!urls.Contains(url))
 {
 urls.Add(url);
 }
 }

 public List<string> GetUrls()
 {
 return urls;
 }

 public void ClearUrls()
 {
 urls.Clear();
 }
 }
}

4.2 تحديث مكون Blazor لإدارة URL وتحديثه

بعد ذلك، قم بتحديث Pages/Index.razor لإضافة إدارة URL والتحديث والتحديث الدوري التلقائي:

@page "/"
@using PriceMonitorBlazor.Models
@using PriceMonitorBlazor.Services
@inject ScraperService ScraperService

<h3>Price Monitor</h3>

<p>
 <label for="urlInput">Product URL:</label>
 <input id="urlInput" @bind="productUrl" />
 <button @onclick="AddUrl">Add URL</button>
</p>

<p>
 <button @onclick="RefreshPrices">Refresh All Prices</button>
</p>

@if (productInfos.Any())
{
 <table class="table">
 <thead>
 <tr>
 <th>Title</th>
 <th>Price</th>
 <th>Date</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var product in productInfos)
 {
 <tr>
 <td>@product.Title</td>
 <td>@product.Price</td>
 <td>@product.Date</td>
 </tr>
 }
 </tbody>
 </table>
}

@code {
 private string productUrl;
 private List<ProductInfo> productInfos = new List<ProductInfo>();
 private Timer _timer;

 protected override void OnInitialized()
 {
 StartTimer();
 }

 private void StartTimer()
 {
 // Set up the timer to call RefreshPrices every minute (60000 ms)
 _timer = new Timer(async _ => await InvokeAsync(RefreshPrices), null, TimeSpan.Zero, TimeSpan.FromMinutes(1));
 }

 private void AddUrl()
 {
 if (!string.IsNullOrEmpty(productUrl))
 {
 ScraperService.AddUrl(productUrl);
 productUrl = string.Empty;
 }
 }

 private async Task RefreshPrices()
 {
 productInfos.Clear();
 var urls = ScraperService.GetUrls();

 foreach (var url in urls)
 {
 var productInfo = await ScraperService.GetProductInfoAsync(url);
 productInfos.Add(productInfo);
 }
 StateHasChanged();
 }
}

في هذا المكون المحدث:

نستخدم Timer للاتصال بطريقة RefreshPrices بشكل دوري كل دقيقة.
تعمل طريقة StartTimer على تهيئة المؤقت ليبدأ على الفور ثم يتم تشغيله كل 60 ثانية.
يستدعي أسلوب دورة الحياة OnInitialized StartTimer عند تهيئة المكون لبدء التحديث الدوري.

4.3 تشغيل الحل

لتشغيل تطبيق Blazor المحدث بالميزات الجديدة، قم بإعادة بناء حاويات Docker وإعادة تشغيلها:

docker-compose build
docker-compose up

بعد تحميل http://localhost:5001 في متصفحك، يجب الآن على تطبيق Blazor تحديث أسعار المنتجات تلقائيًا كل دقيقة بالإضافة إلى السماح بالتحديثات اليدوية وإدارة عناوين URL.

الخلاصة

لقد كان بناء نظام مراقبة الأسعار هذا بمثابة انفجار احتفالي! لم ينقذني ذلك من ضغوط التحقق اليومي من الأسعار فحسب، بل أظهر أيضًا سحر تقنيات الويب الحديثة.

التقويم التقني الاحتفالي 2024

لقد أنشأت هذا المنشور كجزء من حدث Festive Tech Calendar 2024، الذي يجمع عشاق التكنولوجيا والمبتكرين والحالمين الرقميين لمشاركة المعرفة والاحتفال بدمج الروح الاحتفالية والعجائب التكنولوجية. لا تقتصر هذه المبادرة على التعلم والتواصل فحسب، بل تتعلق أيضًا بتقديم العطاء.

يدعم تقويم التكنولوجيا الاحتفالي 2024 مؤسسة Beatson Cancer الخيرية هذا العام. جمعية بيتسون لمكافحة السرطان مكرسة لدعم الأشخاص المصابين بالسرطان وأسرهم ومتخصصي الرعاية الصحية الذين يعتنون بهم. يمكن العثور على مزيد من المعلومات حول عملهم المذهل على https://www.beatsoncancercharity.org/.

قم بزيارة موقع ويب Festive Tech Calendar على https://festivetechcalendar.com للحصول على الأسئلة الشائعة ومزيد من التفاصيل حول الحدث.

هو هو هو!

لقد كان إنشاء هذا المشروع طريقة رائعة للمساهمة في مجتمع التكنولوجيا الاحتفالي ودعم قضية عظيمة في نفس الوقت.

أتمنى أن تجد هذا الدليل مفيدًا وأن يلهمك لاستكشاف المزيد من الطرق لاستخدام التكنولوجيا لتبسيط المهام اليومية.

إذا كانت لديك أي أسئلة أو كنت بحاجة إلى مزيد من المساعدة، فلا تتردد في التواصل معنا.

ترميز سعيد!

سمة التحقق المخصصة والتحقق من صحة Blazor

Fri, 29 Mar 2024 00:00:00 +0000

#تخصيص كل شيء

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

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

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

نعم إنه أمر مضحك، بعد كل هذه السنوات…

سمات التحقق المخصصة

في الواقع، جاءت الفكرة من العمل، فنحن نقوم دائمًا بالتحقق من الصحة في جميع الأماكن ولكن كان لدي بعض الحقول التي تتطلب نفس عملية التحقق من الصحة، لذلك اعتقدت أنه قد يكون هناك شيء ما هناك…. مثل سمات التحقق المخصصة!

لذلك قمت بتشغيل وثائق Microsoft لذلك واكتشفت أنه نعم، يمكنك إنشاء سمات تحقق مخصصة وتعيينها للخصائص، تمامًا مثل هذا:

public class StringLengthRangeAttribute : ValidationAttribute
{
 public int Minimum { get; set; }
 public int Maximum { get; set; }

 public StringLengthRangeAttribute()
 {
 this.Minimum = 0;
 this.Maximum = int.MaxValue;
 }

 public override bool IsValid(object value)
 {
 string strValue = value as string;
 if (!string.IsNullOrEmpty(strValue))
 {
 int len = strValue.Length;
 return len >= this.Minimum && len <= this.Maximum;
 }
 return true;
 }
}

واستخدامها في فئة بسيطة مثل هذا:

[Required]
[StringLengthRange(Minimum = 10, ErrorMessage = "Must be >10 characters.")]

[StringLengthRange(Maximum = 20)]

[Required]
[StringLengthRange(Minimum = 10, Maximum = 20)]

مدقق مخصص

لذا، لدي أداة التحقق هذه التي أحتاجها لبعض حالات العمل المحددة التي ستحتوي على 20 حرفًا أولًا تستبدل 9 أرقام وواصلة، وتنتهي بحرفين يمثلان عادةً رمز البلد، لذلك شيء من هذا القبيل: 123456789-123456789-ES

انتهى بي الأمر بشيء مثل هذا، إنه بسيط حقًا ولكنه يعمل:

using System;
using System.ComponentModel.DataAnnotations;
using System.Text.RegularExpressions;

public class SpecialStringValidatorAttribute : ValidationAttribute
{
 private const int TotalLength = 22;
 private const string Pattern = @"^(\d{10})-(\d{10})-([A-Za-z]{2})$";

 protected override ValidationResult IsValid(object value, ValidationContext validationContext)
 {
 string strValue = value as string;

 if (!string.IsNullOrEmpty(strValue))
 {
 if (strValue.Length != TotalLength)
 {
 return new ValidationResult($"The string must be {TotalLength} characters long.");
 }

 if (!Regex.IsMatch(strValue, Pattern))
 {
 return new ValidationResult("The string must follow the pattern: 1234567890-1234567890-AB");
 }

 return ValidationResult.Success;
 }

 return new ValidationResult("The string cannot be null or empty.");
 }
}

الاختبارات

لقد كتبت بعض الاختبارات لهم أيضًا، فقط في حالة:

public class SpecialStringValidatorTests
{
 [Theory]
 [InlineData("1234567890-1234567890-AB", true)]
 [InlineData("1234567890-1234567890-XY", true)]
 [InlineData("1234567890-1234567890-A1", false)]
 [InlineData("1234567890-1234567890-A", false)]
 [InlineData("1234567890-123456789-AB", false)]
 [InlineData("1234567890-1234567890", false)]
 [InlineData("1234567890-1234567890-ABCDE", false)]
 public void SpecialStringValidatorTest(string input, bool expectedResult)
 {
 // Arrange
 var validator = new SpecialStringValidatorAttribute();

 // Act
 var result = validator.IsValid(input);

 // Assert
 Assert.Equal(expectedResult, result);
 }
}

وعندما ركضت حصلت على هذه النتائج:

Microsoft (R) Test Execution Command Line Tool Version 16.9.1
Copyright (c) Microsoft Corporation. All rights reserved.

Starting test execution, please wait...

A total of 1 test files matched the specified pattern.

Test run in progress...

Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-AB", expectedResult: True)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-XY", expectedResult: True)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-A1", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-A", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-123456789-AB", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-ABCDE", expectedResult: False)

Test Run Successful.
Total tests: 7
 Passed: 7
 Total time: 1.7296 Seconds

التحقق المخصص وBlazor

والآن بعد أن علمت أنه يمكن استخدامه، من الواضح أنه من الجيد تنفيذه في Blazor، أليس كذلك؟

لنفترض أن لدي هذا النموذج، والذي سيستخدم النموذج Person الذي عرضته من قبل:

@using Models
@page "/"

<PageTitle>Home</PageTitle>

<h1>Hello, world!</h1>

<EditForm Model=@Person FormName="PersonForm">
 <DataAnnotationsValidator/>
 <ValidationSummary/>
 <div class="form-group">
 <label for="Name">Name</label>
 <InputText @bind-Value=Person.Name class="form-control" id="Name" />
 <ValidationMessage For="() => Person.Name"/>
 </div>
 <div class="form-group">
 <label for="MySpecialString">My special string</label>
 <InputText @bind-Value=Person.MySpecialString class="form-control" id="Name" />
 <ValidationMessage For="() => Person.MySpecialString"/>
 </div>
 <div class="form-group">
 <label for="Age">Age</label>
 <InputNumber @bind-Value=Person.Age class="form-control" id="Age" />
 <ValidationMessage For=@(() => Person.Age) />
 </div>
 <input type="submit" class="btn btn-primary" value="Save"/>
</EditForm>

@code {
 Person Person = new Person();
}

بمجرد تشغيل هذا، نحصل على الأخطاء التالية:

وإذا وضعنا ما نريد فقط، نحصل على الأمر التالي، كل شيء واضح:

لأكون صادقًا بالنسبة لي، من الواضح تمامًا أننا يجب أن ننقل المنطق على الأقل للتحقق من صحة هذه النماذج إلى سمات التحقق المخصصة، فهذا يمنحنا حرية تخزين الكود الخاص بتسجيل الدخول هذا في مكان واحد، ويمكننا استخدامه لاحقًا لواجهة برمجة التطبيقات (API) أو تطبيق آخر.

آمل أن تكون قد نالت إعجابك، إذا كان لديك أي أسئلة أو كنت ترغب في التواصل معي، فلا تتردد واتصل بي!

معالجة الاستثناءات المخصصة على .NET API

Sun, 01 Oct 2023 00:00:00 +0000

الاستثناءات سيئة، ونحن نعلم أليس كذلك؟ ولكن ماذا لو كان علينا التعامل معهم؟

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

بالنسبة للعرض التوضيحي، قمت بإنشاء واجهة برمجة تطبيقات dotnet وأضفت طريقة من شأنها طرح استثناء:

[HttpGet]
[Route("GetWithoutExceptionHandler")]
public Task GetWithoutExceptionHandler()
{
 throw new Exception("This is a custom exception!");
}

إذا قمنا بطرح استثناء، فسيبدو كما يلي:

System.Exception: This is a custom exception!
 at CustomExceptionHandleDemo.Controllers.WeatherForecastController.GetWithoutExceptionHandler()
 at lambda_method16(Closure , Object , Object[] )
 at Microsoft.AspNetCore.Mvc.Infrastructure.ActionMethodExecutor.AwaitableResultExecutor.Execute(IActionResultTypeMapper mapper, ObjectMethodExecutor executor, Object controller, Object[] arguments)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeActionMethodAsync>g__Logged|12_1(ControllerActionInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeNextActionFilterAsync>g__Awaited|10_0(ControllerActionInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Rethrow(ActionExecutedContextSealed context)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Next(State& next, Scope& scope, Object& state, Boolean& isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.InvokeInnerFilterAsync()
--- End of stack trace from previous location ---
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeFilterPipelineAsync>g__Awaited|20_0(ResourceInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Routing.EndpointMiddleware.<Invoke>g__AwaitRequestTask|6_0(Endpoint endpoint, Task requestTask, ILogger logger)
 at Microsoft.AspNetCore.Authorization.AuthorizationMiddleware.Invoke(HttpContext context)
 at Swashbuckle.AspNetCore.SwaggerUI.SwaggerUIMiddleware.Invoke(HttpContext httpContext)
 at Swashbuckle.AspNetCore.Swagger.SwaggerMiddleware.Invoke(HttpContext httpContext, ISwaggerProvider swaggerProvider)
 at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware.Invoke(HttpContext context)

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

وهذا ما يبدو على Swagger:

إنشاء استثناء مخصص

يمكن تجنب هذه الخطوة، لأننا نعرف ما هو الاستثناء الذي سيتم طرحه، في هذه الحالة Exception، ولكن بالنسبة لي، فإن الحصول على استثناءاتك المخصصة هو الأفضل نظرًا لأن لديك المزيد من التحكم في ما ترميه.

في هذه الحالة، قمت للتو بإنشاء كائن CustomException يرث من Exception:

namespace CustomExceptionHandleDemo.Exceptions
{
 public class CustomException : Exception
 {
 /// <summary>
 /// Constructor for <see cref="CustomException"/>
 /// </summary>
 public CustomException() { }

 /// <summary>
 /// Constructor for <see cref="CustomException"/>
 /// </summary>
 /// <param cref="string" name="message">Parameter for message</param>
 public CustomException(string message) : base(message) { }

 /// <summary>
 /// Constructor for <see cref="CustomException"/>
 /// </summary>
 /// <param cref="string" name="message">Parameter for message</param>
 /// <param cref="Exception" name="inner">Parameter for inner</param>
 public CustomException(string message, Exception inner) : base(message, inner) { }
 }
}

بعد أن قمنا بإنشاء الاستثناء المخصص، فلنقم بتحديث طريقتنا لرمي CustomException بدلاً من Exception:

[HttpGet]
[Route("GetWithoutExceptionHandler")]
public Task GetWithoutExceptionHandler()
{
 throw new CustomException("This is a custom exception!");
}

لن يغير هذا أي شيء في الوقت الحالي ولكن تتبع المكدس سيُظهر أن الكائن الذي تم طرحه هو CustomException بدلاً من Exception، ألقِ نظرة على بداية تتبع المكدس:

CustomExceptionHandleDemo.Exceptions.CustomException: This is a custom exception!
 at CustomExceptionHandleDemo.Controllers.WeatherForecastController.GetWithoutExceptionHandler()
 at lambda_method24(Closure , Object , Object[] )
 at Microsoft.AspNetCore.Mvc.Infrastructure.ActionMethodExecutor.AwaitableResultExecutor.Execute(IActionResultTypeMapper mapper, ObjectMethodExecutor executor, Object controller, Object[] arguments)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeActionMethodAsync>g__Logged|12_1(ControllerActionInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeNextActionFilterAsync>g__Awaited|10_0(ControllerActionInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Rethrow(ActionExecutedContextSealed context)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Next(State& next, Scope& scope, Object& state, Boolean& isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.InvokeInnerFilterAsync()
--- End of stack trace from previous location ---
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeFilterPipelineAsync>g__Awaited|20_0(ResourceInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Routing.EndpointMiddleware.<Invoke>g__AwaitRequestTask|6_0(Endpoint endpoint, Task requestTask, ILogger logger)
 at Microsoft.AspNetCore.Authorization.AuthorizationMiddleware.Invoke(HttpContext context)
 at Swashbuckle.AspNetCore.SwaggerUI.SwaggerUIMiddleware.Invoke(HttpContext httpContext)
 at Swashbuckle.AspNetCore.Swagger.SwaggerMiddleware.Invoke(HttpContext httpContext, ISwaggerProvider swaggerProvider)
 at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware.Invoke(HttpContext context)

إنشاء ExceptionFilterAttribute

لقد منحتنا Microsoft طريقة للتعامل مع الاستثناءات بعد طرحها، ويمكنك التحقق من مزيد من المعلومات هنا.

لكن الوثائق التي قدموها لنا حتى الآن هي:

عامل تصفية مجردة يتم تشغيله بشكل غير متزامن بعد قيام الإجراء بطرح استثناء. يجب أن تتجاوز الفئات الفرعية OnException(ExceptionContext) أو OnExceptionAsync(ExceptionContext) ولكن ليس كليهما.

لذا فلنقم بإنشاء واحد، سنقوم بإنشاء CustomExceptionFilterAttribute حيث سنقوم بتجاوز OnException:

using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.AspNetCore.Mvc;
using CustomExceptionHandleDemo.Exceptions;

namespace CustomExceptionHandleDemo.ExceptionFilterAttributes
{
 public class CustomExceptionFilterAttribute : ExceptionFilterAttribute
 {
 /// <summary>
 /// OnException
 /// </summary>
 /// <param cref="ExceptionContext" name="context">Parameter for context</param>
 public override void OnException(ExceptionContext context)
 {
 if (context.Exception is CustomException)
 {
 context.HttpContext.Response.StatusCode = 500;
 context.Result = new ObjectResult(context.Exception.Message);
 }
 }
 }
}

كما ترون، نحن نلقي نظرة على ExceptionContext، عندما يكون الاستثناء نوعًا من CustomException، فإننا نفعل شيئًا ما.

يقوم هذا الشيء بتحديث الاستجابة ورمز الحالة لما سنعود إليه.

من أجل تحديث رمز الحالة، يجب علينا تحديث context.HttpContext.Response.StatusCode ومن أجل إرجاع النتيجة، علينا تحديث context.Result عن طريق إعطائه كائنًا موروثًا من ActionResult.

هذا مرشح، لذا فهذا يعني أنه يتعين علينا إضافته بشيء ما عن طريق إضافة [CustomExceptionFilter].

استخدام الفلتر

الآن، دعونا نكرر الطريقة التي لدينا ونضيف هذا الفلتر حتى يتم اتخاذ الإجراء اللازم، وستنتهي نقطة نهاية واجهة برمجة التطبيقات الخاصة بنا على النحو التالي:

using CustomExceptionHandleDemo.ExceptionFilterAttributes;
using CustomExceptionHandleDemo.Exceptions;
using Microsoft.AspNetCore.Mvc;

namespace CustomExceptionHandleDemo.Controllers
{
 [ApiController]
 [Route("[controller]")]
 public class WeatherForecastController : ControllerBase
 {
 public WeatherForecastController()
 {
 }

 [HttpGet]
 [Route("GetWithoutExceptionHandler")]
 public Task GetWithoutExceptionHandler()
 {
 throw new CustomException("This is a custom exception!");
 }

 [HttpGet]
 [Route("GetWithExceptionHandler")]
 [CustomExceptionFilter]
 public Task GetWithExceptionHandler()
 {
 throw new CustomException("This is a custom exception!");
 }
 }
}

كما ترون، لدينا طريقة جديدة تسمى GetWithExceptionHandler، لها نفس المنطق الذي يمتلكه GetWithoutExceptionHandler، ولكن في هذه الحالة، أضفنا عامل التصفية [CustomExceptionFilter] إلى الطريقة.

والنتيجة هي التالية بعد تشغيل الطريقة، سأعرض صورة، لأنها لم تعد تظهر تتبع المكدس:

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

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

طريقة أجمل لحقن الأشياء

Mon, 04 Sep 2023 00:00:00 +0000

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

هذا هو نفسه دائمًا، تذهب إلى Program.cs، ثم تنتقل إلى جزء ما من الملف لإضافة builder.Services.AddScoped<MyService>(); من أجل إدخال الخدمة.

شيء من هذا القبيل:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

// Repositories
builder.Services.AddScoped<ARepository>(); // 👀
builder.Services.AddScoped<BRepository>(); // 👀

// Services
builder.Services.AddScoped<AService>(); // 👀
builder.Services.AddScoped<BService>(); // 👀
builder.Services.AddScoped<CService>(); // 👀
builder.Services.AddScoped<DService>(); // 👀

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
 app.UseExceptionHandler("/Error");
 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
 app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

أعني أنه يعمل، لكني صعب الإرضاء، ولا أحبه حقًا.

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

في هذه الحالة، هل يمكنك تخيل عدد الأسطر التي يتعين علينا إضافتها إلى Program.cs.

لنفترض أن لدينا مكتبة تحتوي على بعض الخدمات، إذا أردنا تضمين جميع خدماتنا، علينا العمل مع IServiceCollection.

لذلك سنقوم بإنشاء static class الذي سيكون له طريقة static تسمى AddServices والتي تُرجع IServiceCollection.

في هذه الحالة سيتم تسميته IServiceCollectionServicesExtensions.

/// <summary>
/// IServiceCollectionServicesExtensions class
/// </summary>
public static class IServiceCollectionServicesExtensions
{
 /// <summary>
 /// AddCoreServices
 /// </summary>
 /// <param cref="IServiceCollection" name="services">Parameter for <see cref="IServiceCollection"/></param>
 /// <returns>An object of type <see cref="IServiceCollection"/></returns>
 public static IServiceCollection AddServices(this IServiceCollection services)
 {
 services
 .AddScoped<AService>()
 .AddScoped<BService>()
 .AddScoped<CService>()
 .AddScoped<DService>();

 return services;
 }
}

ليس هذا فحسب، لدينا أيضًا مكتبة أخرى تتضمن بعض المستودعات التي تستخدمها هذه الخدمات، لذلك دعونا نفعل الشيء نفسه.

/// <summary>
/// IServiceCollectionServicesExtensions class
/// </summary>
public static class IServiceCollectionServicesExtensions
{
 /// <summary>
 /// AddCoreServices
 /// </summary>
 /// <param cref="IServiceCollection" name="services">Parameter for <see cref="IServiceCollection"/></param>
 /// <returns>An object of type <see cref="IServiceCollection"/></returns>
 public static IServiceCollection AddRepositories(this IServiceCollection services)
 {
 services
 .AddScoped<ARepository>()
 .AddScoped<BRepository>();

 return services;
 }
}

الآن، لدينا مستودعاتنا وطرق تقديم الخدمات التي تم إنشاؤها، ولكن كيف نستخدمها؟

دعنا نعود إلى Program.cs ونضيف ما يلي:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

// Repositories
builder.Services.AddRepositories(); // 👀

// Services
builder.Services.AddServices(); // 👀

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
 app.UseExceptionHandler("/Error");
 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
 app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

هذا يبدو أنظف بكثير، أليس كذلك؟ حسنًا، لقد نجحنا في إدخال بعض الخدمات والمستودعات، لكنها الآن تبدو أجمل ولدينا بالفعل ما نقوم بإدخاله في المكتبة الخارجية.

حقن التبعية مع السمات على .NET API

Tue, 22 Aug 2023 00:00:00 +0000

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

المرشحات، وفقًا لـ [وثائق] Microsoft الرسمية(https://learn.microsoft.com/en-us/aspnet/core/mvc/controllers/filters?view=aspnetcore-3.1):

تسمح عوامل التصفية في ASP.NET Core بتشغيل التعليمات البرمجية قبل أو بعد مراحل محددة في مسار معالجة الطلب.

تتعامل المرشحات المضمنة مع مهام مثل:

التفويض، منع الوصول إلى الموارد غير المصرح للمستخدم بها.

التخزين المؤقت للاستجابة، مما يؤدي إلى تقصير مسار الطلب لإرجاع استجابة مخبأة.

يمكن إنشاء مرشحات مخصصة للتعامل مع الاهتمامات الشاملة. تتضمن أمثلة الاهتمامات الشاملة معالجة الأخطاء والتخزين المؤقت والتكوين والترخيص والتسجيل. تتجنب المرشحات تكرار التعليمات البرمجية.

أنا أعمل كثيرًا مع واجهات برمجة التطبيقات (APIs) وهناك بعض الأشياء التي يجب أن تقوم بتشغيل كل طلب على حدة، أو جميعها تقريبًا، لذا، من الأفضل أن ما نريد القيام به هو العمل معها بالإضافة إلى…. حقن التبعية!

لكنها خدعة بعض الشيء في بعض الأحيان، فهي لا تعمل كما نريد إذا أردنا أن نرث من ActionAttribute لذلك نحتاج إلى العمل مع TypeFilterAttribute، مما يتيح لنا القيام بالأشياء عند تجاوز OnActionExecutionAsync.

عادةً ما أقوم بإنشاء هذه المرشحات لإجراء بعض التسجيل، لذلك سنستخدم ذلك كمثال:

/// <summary>
/// LoggedQueryAttribute class
/// </summary>
public class LoggedQueryTypeFilterAttribute : TypeFilterAttribute
{
 /// <summary>
 /// Constructor for <see cref="LoggedQueryTypeFilterAttribute"/>
 /// </summary>
 public LoggedQueryTypeFilterAttribute() : base(typeof(LoggedQueryFilter))
 {
 }

 /// <summary>
 /// LoggedQueryFilter class
 /// </summary>
 private class LoggedQueryFilter : IAsyncActionFilter
 {
 /// <summary>
 /// <see cref="_loggingService"/> object
 /// </summary>
 private readonly LoggingService _loggingService;

 /// <summary>
 /// Constructor for <see cref="LoggedQueryFilter"/>
 /// </summary>
 /// <param cref="LoggingService" name="loggingService">Parameter for loggingService</param>
 public LoggedQueryFilter(LoggingService loggingService)
 {
 _loggingService = loggingService;
 }

 /// <summary>
 /// OnActionExecutionAsync
 /// </summary>
 /// <param cref="ActionExecutingContext" name="context">Parameter for context</param>
 /// <param cref="ActionExecutionDelegate" name="next">Parameter for next</param>
 public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
 {
 // Get properties
 var properties = (Request)context.ActionArguments.First().Value!;

 // Get call from context
 var call = context.HttpContext.Request.Path.Value!;

 // Logging
 _loggingService.LogCustomEvent(call);

 // Continue call
 await next();
 }
 }
}

المنطق بسيط جدًا، نحصل على النص عن طريق الوصول إلى كائن context باستخدام context.ActionArguments.First().Value، كما نستخدم استدعاء الأسلوب باستخدام context.HttpContext.Request.Path.Value.

ثم نقوم فقط باستدعاء طريقتنا من خدمتنا، في هذه الحالة هي _loggingService.LogCustomEvent(call).

بعد ذلك، يجب علينا الاتصال بـ await next();، لأن خط الأنابيب يجب أن يستمر.

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

[LoggedQueryTypeFilterAttribute]
public ActionResult<string> TestFilter()
{
 return Ok("Hello world!");
}

آمل أن تكون قد نالت إعجابك، إذا كان لديك أي أسئلة أو كنت ترغب في التواصل معي، فلا تتردد واتصل بي!

التوثيق مع المكتبات الخارجية

Fri, 17 Feb 2023 00:00:00 +0000

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

بالنسبة لي على الأقل، من الضروري تقسيم نماذج البيانات، التي تتضمن Entity Framework، بحيث يمكن الرجوع إليها واستخدامها في Console application، أو Blazor application أو API.

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

هذا مثال على فصل قمت بنقله من مشروع API مع وثائق تحتوي على summary لكل خاصية وفئة.

namespace CustomLibrariesDocumentation.Models
{
 /// <summary>
 /// WeatherForecast class
 /// </summary>
 public class WeatherForecast
 {
 /// <summary>
 /// Gets or sets the Date
 /// </summary>
 public DateOnly Date { get; set; }

 /// <summary>
 /// Gets or sets the TemperatureC
 /// </summary>
 public int TemperatureC { get; set; }

 /// <summary>
 /// Gets or sets the TemperatureF
 /// </summary>
 public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

 /// <summary>
 /// Gets or sets the Summary
 /// </summary>
 public string? Summary { get; set; }
 }
}

إذا أشرنا إلى Console application وبدأنا في استخدام النموذج، فيمكننا رؤية الوثائق، وهي ميزة قياسية في Visual Studio لذا فهي تعمل بشكل جيد، كما ترون هنا:

ولكن بعد ذلك، إذا أشرنا إلى API وانتقلنا إلى Swagger، فلن يكون هناك توثيق موجز.

كيف نصلح هذا؟

أولاً، علينا تمكين تعليقات XML على المكتبة، وللقيام بذلك، تحتاج إلى تحديث إعدادات المشاريع وتمكين ``:

سيؤدي هذا إلى إنشاء بعض الملفات في مجلد البناء والتي تنتهي بامتداد الملف xml، كما ترون هنا:

الآن بعد أن انتهينا من ذلك، يتعين علينا إضافة بعض العناصر على Program.cs، من أجل التبختر في قراءة تلك الملفات، وذلك لأنه بشكل افتراضي يقوم فقط بتحميل تعريف XML للمشروع الذي يعمل عليه.

يستخدم طريقة موجودة داخل AddSwaggerGen تسمى IncludeXmlComments.

الفكرة هي أنه إذا كان لدينا جميع ملفات xml، فسنضطر إلى تحميلها على Swagger.

builder.Services.AddSwaggerGen(s =>
{
 // Comments
 var allXmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml");

 foreach (string xmlFiles in allXmlFiles)
 {
 s.IncludeXmlComments(xmlFiles);
 }
});

لقد تم توجيهها مباشرة، نحصل على ملفات xml من دليل البناء ونضيفها باستخدام طريقة IncludeXmlComments.

الآن نقوم بتحميل API مرة أخرى ونتحقق مما إذا كان بإمكاننا رؤية الوثائق.

ويمكنك أن ترى أنه يمكننا رؤية الوثائق!

آمل أن يكون قد ساعدك، إذا كان لديك أي سؤال فلا تتردد في الاتصال بي!

تنظيف الفروع المحلية في جيت

Mon, 30 Jan 2023 00:00:00 +0000

هل وصلت إلى مرحلة أصبح لديك فيها عدد كبير جدًا من الفروع المحلية؟ يحدث هذا لي كثيرًا، لأننا نستخدم الفروع لكل ميزة أو خطأ أو عمل روتيني.

انتهى بي الأمر بشيء كهذا ويصبح قذرًا للغاية بعد فترة

إنه يزعجني حقًا، لذا سأشارككم أمرًا سريعًا يمكنك تشغيله على وحدة التحكم الخاصة بك للقيام بعملية التنظيف هذه!

لقد وجدت هذا الأمر في Stack Overflow في الإجابة التالية بواسطة Robert Corvus، وهو إصدار يعمل على Powerhsell.

يرجى توخي الحذر عند تشغيل هذا الأمر لأنك قد تفقد تغييراتك

قبل تشغيله، تذكر تحديث MY_MASTER_BRANCH_NAME إلى فرعك الرئيسي، والذي يمكن أن يكون master كما أستخدمه أو الفروع الجديدة التي تأتي افتراضيًا والتي تسمى main.

git branch | %{ $_.Trim() } | ?{ $_ -ne 'MY_MASTER_BRANCH_NAME' } | %{ git branch -D $_ }

بعد تشغيل هذا الأمر، سوف تحصل على نتيجة مثل هذا

نأمل أن يكون مفيدا لك!

تحديث مسارات الهوية في ASP.NET Core 7

Mon, 23 Jan 2023 00:00:00 +0000

هل تتساءل كيف تسمي Microsoft الأشياء النادرة جدًا؟ لقد اعتقدت دائمًا أنهم لا يفعلون ذلك بشكل رائع حقًا، لكن هذا ما هو عليه الأمر!

والشيء الجيد في هذا هو أنه يمكنك تغيير كل شيء إلى حد كبير أثناء تطويرك!

هل سبق لك أن دخلت إلى إحدى الصفحات وأدركت على الفور أن هذا هو مشروع ويب ASP.NET بمجرد القيام بعملية التسجيل أو تسجيل الدخول؟

لقد حدث لي ذلك كثيرًا لأنه افتراضيًا في المشروع الذي تقوم بإنشائه، لديك عناوين URL هذه للقيام بعملية تسجيل الدخول والتسجيل (لديك أيضًا الكثير من الصفحات الأخرى أيضًا).

لذلك يوضح هذا البرنامج التعليمي طريقة لتحديث عناوين URL هذه حتى يبدو مشروعك أجمل!!

السلوك الافتراضي

عندما نقوم بإنشاء مشروع Blazor ونقرر استخدامه مع الهوية، فإنه يعرض شيئًا مثل هذا:

وعندما نحاول القيام بعملية تسجيل الدخول أو التسجيل، فإننا ننتقل إما /Identity/Account/Login أو /Identity/Account/Register.

ولكن ماذا لو أخبرتك أنه يمكنك تحديث عناوين URL هذه بشكل كامل لتكون مختلفة؟

سقالات صفحات `Login` و `Register`

ومن أجل تحديث هذه الصفحات، تقوم Microsoft بإخفائها، ولكن يمكنك دعمها بسرعة وإجراء التغييرات التي تريدها!

للقيام بذلك، عليك الانتقال إلى Add Scaffolded Item في قائمة السياق الخاصة بالمشروع، تمامًا مثل هذا:

بعد ذلك سينبثق شكل مشروط وعليك تحديد Identity مرتين والنقر على Add:

بعد ذلك، سينبثق نموذج آخر، حيث يمكنك تحديد الصفحات من الهوية بأكملها التي تريد تحديثها. هناك الكثير من الصفحات التي يمكنك تحديثها، لكننا سنركز على Account/Login وAccount/Register:

الآن دع الأمر يعمل قليلاً ثم تحقق من Solution Explorer، ستجد بعض الملفات الجديدة:

هذه الملفات الجديدة هي صفحة تسجيل الدخول والتسجيل التي يضيفها ASP.NET إلى مشروعك عندما تحدده لإضافة الهوية!

تحديث عناوين URL

كما لاحظت على الأرجح، هذه الملفات هي ملفات razor، نظرًا لأن امتدادها هو cshtml، لذلك سنستخدم توجيهًا لتحديث عنوان url للصفحة:

@page "/login"
@model LoginModel

@{
 ViewData["Title"] = "Log in";
}

<h1>@ViewData["Title"]</h1>
<div class="row">
 <div class="col-md-4">
 <section>
 <form id="account" method="post">
 <h2>Use a local account to log in.</h2>
 <hr />
 <div asp-validation-summary="ModelOnly" class="text-danger" role="alert"></div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Email" class="form-control" autocomplete="username" aria-required="true" placeholder="name@example.com" />
 <label asp-for="Input.Email" class="form-label">Email</label>
 <span asp-validation-for="Input.Email" class="text-danger"></span>
 </div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Password" class="form-control" autocomplete="current-password" aria-required="true" placeholder="password" />
 <label asp-for="Input.Password" class="form-label">Password</label>
 <span asp-validation-for="Input.Password" class="text-danger"></span>
 </div>
 <div class="checkbox mb-3">
 <label asp-for="Input.RememberMe" class="form-label">
 <input class="form-check-input" asp-for="Input.RememberMe" />
 @Html.DisplayNameFor(m => m.Input.RememberMe)
 </label>
 </div>
 <div>
 <button id="login-submit" type="submit" class="w-100 btn btn-lg btn-primary">Log in</button>
 </div>
 <div>
 <p>
 <a id="forgot-password" asp-page="./ForgotPassword">Forgot your password?</a>
 </p>
 <p>
 <a asp-page="./Register" asp-route-returnUrl="@Model.ReturnUrl">Register as a new user</a>
 </p>
 <p>
 <a id="resend-confirmation" asp-page="./ResendEmailConfirmation">Resend email confirmation</a>
 </p>
 </div>
 </form>
 </section>
 </div>
 <div class="col-md-6 col-md-offset-2">
 <section>
 <h3>Use another service to log in.</h3>
 <hr />
 @{
 if ((Model.ExternalLogins?.Count ?? 0) == 0)
 {
 <div>
 <p>
 There are no external authentication services configured. See this <a href="https://go.microsoft.com/fwlink/?LinkID=532715">article
 about setting up this ASP.NET application to support logging in via external services</a>.
 </p>
 </div>
 }
 else
 {
 <form id="external-account" asp-page="./ExternalLogin" asp-route-returnUrl="@Model.ReturnUrl" method="post" class="form-horizontal">
 <div>
 <p>
 @foreach (var provider in Model.ExternalLogins!)
 {
 <button type="submit" class="btn btn-primary" name="provider" value="@provider.Name" title="Log in using your @provider.DisplayName account">@provider.DisplayName</button>
 }
 </p>
 </div>
 </form>
 }
 }
 </section>
 </div>
</div>

@section Scripts {
 <partial name="_ValidationScriptsPartial" />
}

كما ترون معظم الأشياء هي نفسها، ولكن إذا ألقيت نظرة على السطر الأول في الفصل، فقد قمت بتحديث ما كان لدينا من قبل من:

@page

@page "/login"

حسناً، كان ذلك سهلاً، أليس كذلك؟ الآن دعونا نجري اختبارًا سريعًا لمعرفة ما إذا كان يعمل أم لا.

أولاً، دعنا نذهب إلى الصفحة الافتراضية التي كانت لدينا في البداية، للتحقق مما إذا كانت لا تزال تعمل:

وهو ما لا! فلنبدأ الآن ونختبر عنوان URL الجديد وهو /login:

ويعمل!!

الآن دعونا نفعل الشيء نفسه بالنسبة للسجل، نقوم بتحديث صفحته وإضافة المسار الذي نريده في التوجيه @page ودعنا نجري اختبارًا!

@page "/register"
@model RegisterModel
@{
 ViewData["Title"] = "Register";
}

<h1>@ViewData["Title"]</h1>

<div class="row">
 <div class="col-md-4">
 <form id="registerForm" asp-route-returnUrl="@Model.ReturnUrl" method="post">
 <h2>Create a new account.</h2>
 <hr />
 <div asp-validation-summary="ModelOnly" class="text-danger" role="alert"></div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Email" class="form-control" autocomplete="username" aria-required="true" placeholder="name@example.com" />
 <label asp-for="Input.Email">Email</label>
 <span asp-validation-for="Input.Email" class="text-danger"></span>
 </div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Password" class="form-control" autocomplete="new-password" aria-required="true" placeholder="password" />
 <label asp-for="Input.Password">Password</label>
 <span asp-validation-for="Input.Password" class="text-danger"></span>
 </div>
 <div class="form-floating mb-3">
 <input asp-for="Input.ConfirmPassword" class="form-control" autocomplete="new-password" aria-required="true" placeholder="password" />
 <label asp-for="Input.ConfirmPassword">Confirm Password</label>
 <span asp-validation-for="Input.ConfirmPassword" class="text-danger"></span>
 </div>
 <button id="registerSubmit" type="submit" class="w-100 btn btn-lg btn-primary">Register</button>
 </form>
 </div>
 <div class="col-md-6 col-md-offset-2">
 <section>
 <h3>Use another service to register.</h3>
 <hr />
 @{
 if ((Model.ExternalLogins?.Count ?? 0) == 0)
 {
 <div>
 <p>
 There are no external authentication services configured. See this <a href="https://go.microsoft.com/fwlink/?LinkID=532715">article
 about setting up this ASP.NET application to support logging in via external services</a>.
 </p>
 </div>
 }
 else
 {
 <form id="external-account" asp-page="./ExternalLogin" asp-route-returnUrl="@Model.ReturnUrl" method="post" class="form-horizontal">
 <div>
 <p>
 @foreach (var provider in Model.ExternalLogins!)
 {
 <button type="submit" class="btn btn-primary" name="provider" value="@provider.Name" title="Log in using your @provider.DisplayName account">@provider.DisplayName</button>
 }
 </p>
 </div>
 </form>
 }
 }
 </section>
 </div>
</div>

@section Scripts {
 <partial name="_ValidationScriptsPartial" />
}

لقد قمت بتحديث الجزء العلوي بـ @page "/login" والآن نختبر ما إذا كان يعمل:

يعمل أيضا!!

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

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

السمات المخصصة على .NET 6 Core API

Fri, 09 Dec 2022 00:00:00 +0000

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

إنها تساعد حقًا عندما تريد القيام ببعض الأشياء الأمنية مثل التحقق من الرؤوس، أو التحقق من قيمة المعلمة التي تحتاجها بالتأكيد.

في حالتي، سنستخدمه في مشروع .NET Core API، حيث سنتحقق مما إذا كان كل الطلب يحتوي على رأس معين.

سمة التحقق من الرأس

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

وبعد ذلك سنقوم بإضافة المنطق إلى فئة HeaderCheckAttribute الخاصة بنا.

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;

namespace DotNet6CustomAttribute.Attributes
{
 public class HeaderCheckAttribute : ActionFilterAttribute
 {
 public override void OnActionExecuting(ActionExecutingContext context)
 {
 // Get all headers
 var headers = context.HttpContext.Request.Headers;

 // Check if headers has x-dotnet-6-custom-attribute
 if (!headers.ContainsKey("x-dotnet-6-custom-attribute"))
 {
 context.Result = new BadRequestObjectResult("The header x-dotnet-6-custom-attribute is missing");
 }
 else if (string.IsNullOrEmpty(headers["x-dotnet-6-custom-attribute"]))
 {
 context.Result = new BadRequestObjectResult("The header x-dotnet-6-custom-attribute can't be null or empty");
 }

 base.OnActionExecuting(context);
 }
 }
}

المنطق الأساسي هو، أولاً يتحقق من وجود رأس باستخدام المفتاح x-dotnet-6-custom-attribute وإذا كان موجودًا، فإنه يتحقق مما إذا كان يحتوي على قيم.

إذا كان كلا التعبيرين صحيحين، فسيتم إعادة BadRequestObjectResult برسالة معينة.

إضافته إلى وحدة التحكم

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

لذلك دعونا نزين الفصل WeatherForecastController معهم.

using DotNet6CustomAttribute.Attributes;
using Microsoft.AspNetCore.Mvc;

namespace DotNet6CustomAttribute.Controllers
{
 [ApiController]
 [Route("[controller]")]
 public class WeatherForecastController : ControllerBase
 {
 private static readonly string[] Summaries = new[]
 {
 "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
 };

 private readonly ILogger<WeatherForecastController> _logger;

 public WeatherForecastController(ILogger<WeatherForecastController> logger)
 {
 _logger = logger;
 }

 [HttpGet]
 [Route("GetWeatherForecastWithCheck")]
 [HeaderCheckAttribute]
 public IEnumerable<WeatherForecast> GetWithCheck()
 {
 return Enumerable.Range(1, 5).Select(index => new WeatherForecast
 {
 Date = DateTime.Now.AddDays(index),
 TemperatureC = Random.Shared.Next(-20, 55),
 Summary = Summaries[Random.Shared.Next(Summaries.Length)]
 })
 .ToArray();
 }

 [HttpGet]
 [Route("GetWeatherForecastWithoutCheck")]
 public IEnumerable<WeatherForecast> GetWithoutCheck()
 {
 return Enumerable.Range(1, 5).Select(index => new WeatherForecast
 {
 Date = DateTime.Now.AddDays(index),
 TemperatureC = Random.Shared.Next(-20, 55),
 Summary = Summaries[Random.Shared.Next(Summaries.Length)]
 })
 .ToArray();
 }
 }
}

دعونا تشغيل المشروع!

لدينا وظيفتان هناك: GetWeatherForecastWithCheck وGetWeatherForecastWithoutCheck، إحداهما ستفشل والبعض الآخر لن يفشل، ولكن دعونا نتحقق من ذلك على Swagger!

كما ترون، تقوم إحدى الإرجاعات بإرجاع خطأ 400 في رسالتنا، بينما تقوم الأخرى بإرجاع القيم، والآن لاختبار ذلك بشكل كامل، فلنقم بتشغيل Postman وإضافة رأس حتى نتمكن أيضًا من رؤية البيانات باستخدام GetWeatherForecastWithCheck.

ساعي البريد

الآن قيد التشغيل على Postman، نضيف الرأس ونرى أن رسالة الخطأ قد تغيرت، منذ الآن نقوم بتوفير الرأس ولكن ليس هناك قيمة له

إذا أضفنا قيمة إليها، فسنحصل في النهاية على القيم!

هذا كل شيء

حسنا هذا كل شيء! حق بسيط جدا؟ حسنًا، أنت تعرف الآن كيفية إنشاء سمة وتخصيصها للطرق ووحدات التحكم!

استمتع معهم!

الكود

هذا المشروع بأكمله موجود على Github ويمكنك العثور عليه هنا!

إذا كانت لديك أي مشاكل أو أسئلة، فلا تتردد في الاتصال بي على أي من وسائل التواصل الاجتماعي على @emimontesdeoca (في تويتر هو في الواقع @emimontesdeocaa مع اثنين من aa في النهاية). يمكنك أيضًا العثور على معظم وسائل التواصل الاجتماعي الخاصة بي على رأس المدونة.

آمل أن تكونوا قد أحببت هذا المنصب! سيا!

التعامل مع مكونات التحميل في Blazor

Tue, 19 Jul 2022 00:00:00 +0000

Blazor رائع، رائع حقًا، خاصة عندما نقوم بأشياء غير متزامنة مثل صناديق التحميل ويبدو الأمر جيدًا.

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

#فكرة

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

رمز تحميل المكون

الكود بسيط جدًا، ليس هناك الكثير مما يجب فعله، if أساسي مع خاصية التحميل، ووظيفة تبديل بالداخل، وقد انتهى الأمر!

@if (_loaded)
{
 <div class="text-center">
 <div class="spinner-border" role="status">
 <span class="sr-only"></span>
 </div>
 </div>
}
else
{
 @ChildContent
}

@code {
 private bool _loaded = true;

 [Parameter]
 public RenderFragment? ChildContent { get; set; }

 public void ToggleLoad(bool state)
 {
 _loaded = state;
 }
}

الاستخدام

الاستخدام بسيط جدًا، ومن أجل الاختبار، سنستخدم صفحة جديدة ونضع المحتوى الخاص بنا داخل مكون LoadingComponent الذي أنشأناه للتو.

@page "/loading"
@using LoadingBoxes.Components

<LoadingBoxes.Components.LoadingComponent @ref=loadingComponent>
 This is some content
</LoadingBoxes.Components.LoadingComponent>

@code {
 private LoadingComponent loadingComponent;


 protected override async Task OnInitializedAsync()
 {
 // We are going to simulate some load
 await Task.Delay(5000);

 loadingComponent.ToggleLoad(false);
 }

}

هذه هي الطريقة التي تبدو

الحصول على تاريخ انتهاء الصلاحية من الشهادة

Fri, 27 May 2022 00:00:00 +0000

هناك عدد قليل من تطبيقات الويب التي تساعدك على التحقق من الحالة الحالية للشهادات من النطاقات التي نستخدمها، ولدينا عدد قليل منها.

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

لن يتم عرض المنطق نفسه لكيفية عمل الوظيفة، أود أن أعرض الوظيفة التي تقوم بالفحص الأساسي للشهادة والبيانات التي نحصل عليها.

الوظيفة

static async Task<X509Certificate2> CheckCertificateAsync(string urlPath)
{
 var certificate = new X509Certificate2();
 var httpClientHandler = new HttpClientHandler
 {
 ServerCertificateCustomValidationCallback = (request, cert, chain, policyErrors) =>
 {
 certificate = new X509Certificate2(cert);
 return true;
 }
 };

 using HttpClient httpClient = new HttpClient(httpClientHandler);
 await httpClient.SendAsync(new HttpRequestMessage(HttpMethod.Head, urlPath));

 return certificate;
}

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

نتيجة متسلسلة

هذه هي القيمة التسلسلية للكائن certificate:

{
 "Archived":false,
 "Extensions":[
 {
 "KeyUsages":160,
 "Critical":true,
 "Oid":{
 "Value":"2.5.29.15",
 "FriendlyName":"Key Usage"
 },
 "RawData":"AwIFoA=="
 },
 {
 "EnhancedKeyUsages":[
 {
 "Value":"1.3.6.1.5.5.7.3.1",
 "FriendlyName":"Server Authentication"
 },
 {
 "Value":"1.3.6.1.5.5.7.3.2",
 "FriendlyName":"Client Authentication"
 }
 ],
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.37",
 "FriendlyName":"Enhanced Key Usage"
 },
 "RawData":"MBQGCCsGAQUFBwMBBggrBgEFBQcDAg=="
 },
 {
 "CertificateAuthority":false,
 "HasPathLengthConstraint":false,
 "PathLengthConstraint":0,
 "Critical":true,
 "Oid":{
 "Value":"2.5.29.19",
 "FriendlyName":"Basic Constraints"
 },
 "RawData":"MAA="
 },
 {
 "SubjectKeyIdentifier":"634E1585565AA49402C21642A4A5979A38025797",
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.14",
 "FriendlyName":"Subject Key Identifier"
 },
 "RawData":"BBRjThWFVlqklALCFkKkpZeaOAJXlw=="
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.35",
 "FriendlyName":"Authority Key Identifier"
 },
 "RawData":"MBaAFBQusxe3WFbLrlAJQOYfr52LFMLG"
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"1.3.6.1.5.5.7.1.1",
 "FriendlyName":"Authority Information Access"
 },
 "RawData":"MEcwIQYIKwYBBQUHMAGGFWh0dHA6Ly9yMy5vLmxlbmNyLm9yZzAiBggrBgEFBQcwAoYWaHR0cDovL3IzLmkubGVuY3Iub3JnLw=="
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.17",
 "FriendlyName":"Subject Alternative Name"
 },
 "RawData":"MB6CHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20="
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.32",
 "FriendlyName":"Certificate Policies"
 },
 "RawData":"MEMwCAYGZ4EMAQIBMDcGCysGAQQBgt8TAQEBMCgwJgYIKwYBBQUHAgEWGmh0dHA6Ly9jcHMubGV0c2VuY3J5cHQub3Jn"
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"1.3.6.1.4.1.11129.2.4.2",
 "FriendlyName":"SCT List"
 },
 "RawData":"BIH0APIAdwBByMqx3yJGShDGoToJQodeTjGLGwPr60vHaPCQYpYG9gAAAYCeJIwYAAAEAwBIMEYCIQCG8sf4iBitUjNCc1dsxVd5mdRQCKapRqqnTHKxSKHjHgIhAJFGNXEZkCHKygT1T7bE4orpd6p2l1+GmifMEIuRsgHbAHcARqVV63X6kSAwtaKJafTzfREsQXS+/Um4havy/HD+bUcAAAGAniSMNgAABAMASDBGAiEAoxv1LBn/vfyR7s67kRLB/n1tq3eicuA/8/V0S2YzQCYCIQDXaS3FZbdIVNxQvKxPFxM1awBO/sGxBXafz0lspOoWSA=="
 }
 ],
 "FriendlyName":"",
 "HasPrivateKey":false,
 "PrivateKey":null,
 "IssuerName":{
 "Name":"CN=R3, O=Let's Encrypt, C=US",
 "Oid":{
 "Value":null,
 "FriendlyName":null
 },
 "RawData":"MDIxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQDEwJSMw=="
 },
 "NotAfter":"2022-08-05T10:50:35+01:00",
 "NotBefore":"2022-05-07T10:50:36+01:00",
 "PublicKey":{
 "EncodedKeyValue":{
 "Oid":{
 "Value":"1.2.840.113549.1.1.1",
 "FriendlyName":"RSA"
 },
 "RawData":"MIIBCgKCAQEAq8cbDO3GAfjqqbPPCBdPost8NMRmEubv85gXecll7mZMH5qSfTPuB/ouFWL3tPMf1U8usWeoSUK/48yatzBGwmj1KKlkaW9MS2QkydztRp+kH8LvbzbQvGknuOLWGHBALLT17o/3DYxuA5LnXdY+vLvJWygQoFr2N/XhnhUjcm6OaQEJpIykydfbBQGQSEuQIIw4egpgdHkYJjCOYAsXuSSggN8/FADTCec0RzVjfFTSoJ3hV9HLE9M8MCSXjuo0AJ/MbAxq91S8XmDcRjHCCd7Zw+NjHo8cxZCQ6NqGvn3xwx8ahmmbC+CyDEcIyJJZK2Yv+qE4oS8QZfaX/RaHMwIDAQAB"
 },
 "EncodedParameters":{
 "Oid":{
 "Value":"1.2.840.113549.1.1.1",
 "FriendlyName":"RSA"
 },
 "RawData":"BQA="
 },
 "Key":{
 "Key":{
 "Algorithm":{
 "Algorithm":"RSA"
 },
 "AlgorithmGroup":{
 "AlgorithmGroup":"RSA"
 },
 "ExportPolicy":0,
 "Handle":{
 "IsInvalid":false,
 "IsClosed":false
 },
 "IsEphemeral":true,
 "IsMachineKey":false,
 "KeyName":null,
 "KeySize":2048,
 "KeyUsage":16777215,
 "ParentWindowHandle":{
 "value":0
 },
 "Provider":{
 "Provider":"Microsoft Software Key Storage Provider"
 },
 "ProviderHandle":{
 "IsInvalid":false,
 "IsClosed":false
 },
 "UIPolicy":{
 "ProtectionLevel":0,
 "FriendlyName":null,
 "Description":null,
 "UseContext":null,
 "CreationTitle":null
 },
 "UniqueName":null
 },
 "LegalKeySizes":[
 {
 "MinSize":512,
 "MaxSize":16384,
 "SkipSize":64
 }
 ],
 "KeyExchangeAlgorithm":"RSA",
 "SignatureAlgorithm":"RSA",
 "KeySize":2048
 },
 "Oid":{
 "Value":"1.2.840.113549.1.1.1",
 "FriendlyName":"RSA"
 }
 },
 "RawData":"MIIFQDCCBCigAwIBAgISBNwTmwP/RTcrEeIgAdMrpaFtMA0GCSqGSIb3DQEBCwUAMDIxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQDEwJSMzAeFw0yMjA1MDcwOTUwMzZaFw0yMjA4MDUwOTUwMzVaMCcxJTAjBgNVBAMTHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCrxxsM7cYB+Oqps88IF0+iy3w0xGYS5u/zmBd5yWXuZkwfmpJ9M+4H+i4VYve08x/VTy6xZ6hJQr/jzJq3MEbCaPUoqWRpb0xLZCTJ3O1Gn6Qfwu9vNtC8aSe44tYYcEAstPXuj/cNjG4Dkudd1j68u8lbKBCgWvY39eGeFSNybo5pAQmkjKTJ19sFAZBIS5AgjDh6CmB0eRgmMI5gCxe5JKCA3z8UANMJ5zRHNWN8VNKgneFX0csT0zwwJJeO6jQAn8xsDGr3VLxeYNxGMcIJ3tnD42MejxzFkJDo2oa+ffHDHxqGaZsL4LIMRwjIklkrZi/6oTihLxBl9pf9FoczAgMBAAGjggJZMIICVTAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFGNOFYVWWqSUAsIWQqSll5o4AleXMB8GA1UdIwQYMBaAFBQusxe3WFbLrlAJQOYfr52LFMLGMFUGCCsGAQUFBwEBBEkwRzAhBggrBgEFBQcwAYYVaHR0cDovL3IzLm8ubGVuY3Iub3JnMCIGCCsGAQUFBzAChhZodHRwOi8vcjMuaS5sZW5jci5vcmcvMCcGA1UdEQQgMB6CHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20wTAYDVR0gBEUwQzAIBgZngQwBAgEwNwYLKwYBBAGC3xMBAQEwKDAmBggrBgEFBQcCARYaaHR0cDovL2Nwcy5sZXRzZW5jcnlwdC5vcmcwggEGBgorBgEEAdZ5AgQCBIH3BIH0APIAdwBByMqx3yJGShDGoToJQodeTjGLGwPr60vHaPCQYpYG9gAAAYCeJIwYAAAEAwBIMEYCIQCG8sf4iBitUjNCc1dsxVd5mdRQCKapRqqnTHKxSKHjHgIhAJFGNXEZkCHKygT1T7bE4orpd6p2l1+GmifMEIuRsgHbAHcARqVV63X6kSAwtaKJafTzfREsQXS+/Um4havy/HD+bUcAAAGAniSMNgAABAMASDBGAiEAoxv1LBn/vfyR7s67kRLB/n1tq3eicuA/8/V0S2YzQCYCIQDXaS3FZbdIVNxQvKxPFxM1awBO/sGxBXafz0lspOoWSDANBgkqhkiG9w0BAQsFAAOCAQEAjSEID5MWonbSiyHbmPYWO8ImCCOjkLGxgY8WJODbrWxFy+xU44UwrWOCkqYZUlv2LRmPqSyZDrIeeHK9VMbGh71oXX+XovikgAr6PpI0Mp897nPWj0XvOBaSYG0s+f+CXMtyt0tWCsQOcl+iT82+Ja71f8gbVL6l7xESewEE78pTKEH8EqD22r8VSD7FNICD8EYQr13v3AuVWObSU/R8Td6SrSVEknw1HgJS4e9nvmrMxBGKOJ+aWrAGiUydehg8M9o2gbGckMhz6D7cwB5l618cYaXKkW1dEOYZHl++qUj1/VPK+FNkiDZOPVNN//PbZuOLwAUIlZvhqGWX5/9PBg==",
 "SerialNumber":"04DC139B03FF45372B11E22001D32BA5A16D",
 "SignatureAlgorithm":{
 "Value":"1.2.840.113549.1.1.11",
 "FriendlyName":"sha256RSA"
 },
 "SubjectName":{
 "Name":"CN=blog.emilianomontesdeoca.com",
 "Oid":{
 "Value":null,
 "FriendlyName":null
 },
 "RawData":"MCcxJTAjBgNVBAMTHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20="
 },
 "Thumbprint":"28CF960F772ABFF22AA193C291492C27F8E13D4D",
 "Version":3,
 "Handle":{
 "value":2658150705632
 },
 "Issuer":"CN=R3, O=Let's Encrypt, C=US",
 "Subject":"CN=blog.emilianomontesdeoca.com"
}

تاريخ انتهاء الصلاحية

لمعرفة وقت انتهاء الصلاحية، نحتاج إلى إلقاء نظرة على NotAfter و NotBefore، الموجودين داخل هذا الكائن:

 "NotAfter":"2022-08-05T10:50:35+01:00",
 "NotBefore":"2022-05-07T10:50:36+01:00",

تطبيق وحدة التحكم

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

using Newtonsoft.Json;
using System.Net;
using System.Security.Cryptography.X509Certificates;
using System.Text.Json;

var url = "https://blog.emilianomontesdeoca.com/";

static async Task<X509Certificate2> CheckCertificateAsync(string urlPath)
{
 var certificate = new X509Certificate2();
 var httpClientHandler = new HttpClientHandler
 {
 ServerCertificateCustomValidationCallback = (request, cert, chain, policyErrors) =>
 {
 certificate = new X509Certificate2(cert);
 return true;
 }
 };

 using HttpClient httpClient = new HttpClient(httpClientHandler);
 await httpClient.SendAsync(new HttpRequestMessage(HttpMethod.Head, urlPath));

 return certificate;
}

var cert = await CheckCertificateAsync(url);

var serializedValue = JsonConvert.SerializeObject(cert);

Console.WriteLine(serializedValue);

Console.ReadLine();

المشروع التجريبي

يمكنك العثور على تطبيق وحدة التحكم في موقع Github الخاص بي، في المستودع المسمى شهادة تاريخ انتهاء الصلاحية.

تركيز عنصر في Blazor

Thu, 05 May 2022 00:00:00 +0000

بعد العمل على لعبة Wordlzor التي قمت بها مؤخرًا، كنت بحاجة إلى إضافة وظيفة بسيطة جدًا: التركيز على اللعبة بأكملها عند الدخول.

يجب القيام بذلك لأنه يمكن للمستخدم الكتابة فعليًا في اللعبة وليس فقط استخدام لوحة المفاتيح التي تظهر على الشاشة.

ملف جافا سكريبت

من أجل القيام بذلك، علينا إنشاء ملف جافا سكريبت يسمى app.js الذي سيحتوي على وظيفة

window.FocusElement = (element) => {
 element.focus();
};

بعد أن قمنا بذلك، نحتاج إلى تضمين البرنامج النصي في ملف index.html:

<script src="js/app.js"></script>

مكون البلازور

بمجرد تهيئة البرنامج النصي، نحتاج إلى العثور على عنصر للتركيز عليه، لذلك في أي من مكوناتنا، نحتاج إلى إحالة هذا العنصر إلى كائن.

لذلك، في مكون blazor الخاص بنا، دعنا نضيف div مع خاصية @ref:

<div @ref=@elementToFocus tabindex="0" >
 This is my focus component
</div>

بعد ذلك، في منطق المكون، يمكنك الحصول على الخاصية كـ ElementReference:

/// <summary>
/// Reference to element
/// </summary>
private ElementReference elementToFocus;

حقن JSInterop

الآن، من أجل استدعاء الوظيفة الموجودة في ملف Javascript لدينا، نحتاج إلى استخدام JSInterop.

بادئ ذي بدء، يجب علينا حقنه في المكون بالصيغة التالية:

[Inject]
public IJSRuntime JSRuntime { get; set; }

بعد إدخال الخدمة، أصبحنا الآن قادرين على استدعاء أي من التوابع الموجودة بها، مثل InvokeVoidAsync، والتي ستستدعي الدالة:

public async Task Focus()
{
 // Focus when initializing
 await JSRuntime.InvokeVoidAsync("window.FocusElement", elementToFocus);
}

وعندما تستدعي funciton Focus()، فإنه سيركز على العناصر التي أنشأناها، ومن الواضح أنه يمكنك إعادة بناء العنصر نفسه وتمريره كمعلمة.

إذا كنت تريد إلقاء نظرة على كيفية تنفيذ ذلك، فقم بإلقاء نظرة على كود المصدر Wordlzor، الذي استخدمته للتنبيهات والتركيز عند إغلاق نموذج التعليمات.

قم بإنشاء ملفات *.dacpac من مشروع قاعدة بيانات VS في إجراءات GitHub

Mon, 18 Apr 2022 00:00:00 +0000

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

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

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

#مشروع قاعدة البيانات

عندما نقوم بإنشاء مشروع قاعدة البيانات الخاص بنا على Visual Studio ونقوم باستيراد قاعدة بيانات، فسوف ينتهي الأمر بهذا الشكل

عندما نقوم بتشغيل تجميع في هذا المشروع، فإنه سيتم إنشاء ملف dacpac الذي سيتضمن كل بنيتنا

خط أنابيب جيثب

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

name: DacpacGithubActions project build

on:
 push:
 branches: main

jobs:
 build:
 runs-on: windows-latest

 steps:
 - uses: actions/checkout@v2

 - name: Setup MSBuild
 uses: microsoft/setup-msbuild@v1

 - name: Navigate to Workspace
 run: cd $GITHUB_WORKSPACE

 - name: Create Build Directory
 run: mkdir artifacts

 - name: Build Solution
 run: |
 msbuild.exe /t:DacpacGithubActions /p:DebugSymbols=false /p:DebugType=None /p:DeployOnBuild=true /p:WebPublishMethod=FileSystem /p:OutDir="../artifacts"
 
 - name: Upload artifact
 uses: actions/upload-artifact@v1.0.0
 with:
 name: DacpacGithubActionsArtifacts
 path: "../artifacts"

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

تشغيل خط الأنابيب

الآن قم ببدء البناء، يجب أن تكون النتيجة ما يلي

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

الكود

هذا المشروع بأكمله موجود على Github ويمكنك العثور عليه هنا!

آمل أن تكونوا قد أحببت هذا المنصب! سيا!

تبديل السمات باستخدام Javascript Interop في Blazor

Fri, 01 Apr 2022 00:00:00 +0000

بالنسبة للأشخاص مثلي الذين يعانون من ذكريات الماضي في كل مرة أفتح فيها صفحة ويب، فقد توصلت إلى حل بسيط للغاية حول كيفية التبديل بين الوضع الفاتح والوضع الداكن باستخدام Javascript واستدعائه من Blazor باستخدام Javascript Interop.

تحديد السمة الأصل

بادئ ذي بدء، يتعين علينا تحديد العنصر الأصلي بمعرف، وذلك لأننا نغير الألوان اعتمادًا على قيمة ذلك المعرف.

وللقيام بذلك في Javascript، سيتعين علينا تشغيل هذا الأمر

document.documentElement.setAttribute('data-theme', 'YOUR_IDFENTIFIER');

في حالتنا، نريد أن يكون لدينا معرفان لكل نوع من الأنماط، وهما light و dark.

إنشاء ملف جافا سكريبت للتعامل مع المنطق

لدينا الآن وظيفة تحديث المعرف، والآن لنقم بإنشاء ملف Javascript بوظيفة تقوم بتشغيل هذا المنطق. سيتم استدعاء ملفنا app.js

في هذا الملف، سيكون لدينا وظيفة تستدعي الكود الذي ذكرناه سابقًا.

var toggleTheme = function (identifier) {
 document.documentElement.setAttribute('data-theme', identifier);
}

إضافة ملف جافا سكريبت إلى Blazor

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

<script src="~/js/app.js"></script>

#إنشاء الخدمة

الآن بعد أن حصلنا على كود Javascript، نحتاج إلى إنشاء خدمة تسمى ThemeToggleService.

ستتعامل هذه الخدمة مع منطق التبديل بين السمة light و dark.

حقن JSInterop

من أجل استدعاء أي Javascipt، علينا استدعاء JSInterop، لذلك يتعين علينا إنشاء خاصية سيتم حقنها.

using Microsoft.AspNetCore.Components;
using Microsoft.JSInterop;

namespace BlazorDarkmodeToggle.Data
{
 private readonly IJSRuntime jSRuntime;

 public ThemeToggleService(IJSRuntime jSRuntime)
 {
 this.jSRuntime = jSRuntime;
 }
}

وظيفة لتعيين المعرف

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

using Microsoft.AspNetCore.Components;
using Microsoft.JSInterop;

namespace BlazorDarkmodeToggle.Data
{
 public class ThemeToggleService
 {
 private readonly IJSRuntime jSRuntime;

 public ThemeToggleService(IJSRuntime jSRuntime)
 {
 this.jSRuntime = jSRuntime;
 }

 public bool IsLightTheme { get; set; } = true;
 public string GetIdentifier => IsLightTheme ? "light" : "dark";

 public async Task ToggleTheme() {
 IsLightTheme = !IsLightTheme;
 await jSRuntime.InvokeVoidAsync("toggleTheme", GetIdentifier);
 }
 }
}

إضافة خدمة لبدء التشغيل

ولإتاحة الخدمة لجميع المكونات والصفحات، علينا إضافتها إلى ملف Program.cs.

builder.Services.AddSingleton<ThemeToggleService>();

وبذلك سينتهي الملف بهذا الشكل

using BlazorDarkmodeToggle.Data;
using Microsoft.AspNetCore.Components;
using Microsoft.AspNetCore.Components.Web;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();
builder.Services.AddSingleton<WeatherForecastService>();
builder.Services.AddSingleton<ThemeToggleService>();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
 app.UseExceptionHandler("/Error");
 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
 app.UseHsts();
}

app.UseHttpsRedirection();

app.UseStaticFiles();

app.UseRouting();

app.MapBlazorHub();
app.MapFallbackToPage("/_Host");

app.Run();

ضع في اعتبارك أن هذا يمكن أن يتغير اعتمادًا على ما إذا كنت تستخدم Blazor Server أو Blazor WebAssembly.

خبز CSS

الآن بعد أن أصبح لدينا جزء من الكود جاهزًا، علينا أن نبدأ العمل على CSS. ما يتعين علينا القيام به هو تعيين جميع خصائص CSS التي تتعامل مع ألوان CSS والخلفية وما إلى ذلك إلى متغير.

:root {
 --background-color:#ffffff;
 --text-color:#000000;
}

بمجرد القيام بذلك، باستخدام المعرف، يمكننا التغيير بسهولة بين المعرفات، وسوف يستخدم أيًا منهما بقيمة أخرى.

[data-theme="dark"] {
 --background-color: #000000;
 --text-color: #ffffff;
}

لتلاشي الرسوم المتحركة الرائعة، سنضيف فقط خاصية transition إلى الكل، حتى تبدو جيدة.

* {
 transition: all 250ms;
}

الآن سنقوم بتعيين هذه المتغيرات لبعض فئات CSS، حتى نتمكن من رؤيتها على صفحة Blazor.

.app-background {
 background-color: var(--background-color);
 width: 200px;
 height: 200px;
}

.app-text {
 color: var(--text-color);
}

تذكر إضافة الملف إلى تطبيق Blazor عن طريق إضافته على head.

<link href="css/app.css" rel="stylesheet" />

اتصال من بليزر

إذن كيف سنختبر هذا؟ لتبسيط الأمر، سنقوم فقط بإضافة div مع فئة app-background، وبداخله سيكون هناك p مع فئة app-text.لذلك دعونا ننشئ صفحة تسمى Theme.razor ضمن المجلد Pages ونضيف بعض التعليمات البرمجية لذلك

@page "/theme"
@using BlazorDarkmodeToggle.Data
@inject ThemeToggleService ThemeToggleService

<button class="btn btn-primary" @onclick=Toggle>Toggle theme</button>

<br />

<div class="app-background">
 <p class="app-text">Hello world!</p>
</div>

@code{
 public async Task Toggle()
 {
 await this.ThemeToggleService.ToggleTheme();
 }
}

يمكننا اختبار ذلك بالانتقال إلى /theme، ولكن دعونا نضيفه أيضًا إلى شريط التنقل

<div class="nav-item px-3">
 <NavLink class="nav-link" href="theme">
 <span class="oi oi-list-rich" aria-hidden="true"></span> Theme togle
 </NavLink>
</div>

الاختبار

كما ترون، بمجرد تبديلنا لتغييرات السمة والخلفية ولون الخط، يمكنك الآن معرفة مدى قوة ذلك، إذا قمت بالفعل بتطوير الصفحة بأكملها باستخدام هذه المتغيرات في CSS، فيمكن أن يكون لديك سمات مختلفة وتبديلها فقط!

كم هو رائع!!

الكود

هذا المشروع بأكمله موجود على Github ويمكنك العثور عليه هنا!

آمل أن تكونوا قد أحببت هذا المنصب!

الموارد

استدعاء وظائف JavaScript من أساليب .NET في ASP.NET Core Blazor

تحميل الملفات إلى Azure Blob Storage في Blazor

Wed, 23 Mar 2022 00:00:00 +0000

تعد خدمة تخزين Azure Blob واحدة من الخدمات الأكثر استخدامًا على نظام Azure البيئي، فهي تتيح لك تحميل الكثير من الملفات إلى السحابة بينما تكون رخيصة للغاية. كما أن لديها شبكة ويب بديهية يمكنك الوصول إليها أو تنزيلها عبر رابط مباشر.

بشكل عام، خدمة جيدة جدًا، لقد كنت أستخدمها في كل من مشاريع العمل والمشاريع الشخصية وبصراحة أفضل شيء هو بساطة كيفية إنجاحها.

معظم الحالات التي استخدمت فيها Azure Blob Storage تكون في الواجهة الخلفية، حيث يتم تحميل شيء ما مباشرة نتيجة لعملية أو شيء من هذا القبيل. لذلك لم أقم حقًا بأي نوع من تحميل ملف من موقع ويب أو نحو ذلك. سيئ الحظ!

نظرًا لأنني معجب بـ Blazor، فأنا أقدم لك طريقة لتحميل الملفات إلى Azure Blob Storage باستخدام إدخال الملف الأصلي من HTML5.

#المتطلبات

حساب Azure (إذا لم يكن لديك، فانتقل هنا إلى مجموعة من $$$).
IDE (VS، Code، أي شيء سيعمل)
.NET Core 3.0 أو أعلى

إنشاء وحدة تخزين Azure Blob

انتقل إلى بوابة Azure الخاصة بك ودعنا نتابع إنشاء حساب تخزين.

ابحث أولاً عن Storage accounts وانقر على النتيجة.

بعد التحميل، انقر على Create.

سيظهر نموذج يحتوي على مجموعة من الخطوات، لذا قم بملئها.

بعد ملء كل شيء بالإعدادات التي تريدها، قم بتمرير التحقق من الصحة وإنشاء المورد.

بعد إنشائه، انقر على Go to resource. سنحصل على سلسلة اتصال تتيح لنا اللعب باستخدام واجهة برمجة التطبيقات (API).

احصل على مفاتيح الموارد

بعد أن وصلنا إلى المورد الذي تم إنشاؤه حديثًا، انتقل إلى Acccess keys ضمن Security + networking. بعد التحميل سترى Connection string و Key، انسخهما لأننا سنحتاج إليهما لاحقًا!

إنشاء مشروع رائع لخادم Blazor

سأستخدم Visual Studio 2022 لهذا البرنامج التعليمي، ولكن كما قلت من قبل، يمكنك استخدام أي بيئة تطوير متكاملة (IDE) أخرى وإنشاء المشروع باستخدام dotnet CLI.

ثم دعونا نمضي قدمًا وننشئ مشروع Blazor بسرعة كبيرة باستخدام Visual Studio في مجموعة من الخطوات فقط.

إذا قمنا بتشغيل ما أنشأناه للتو، فسيبدو هكذا، مجرد تطبيق Blazor عادي.

الآن بعد أن أنشأنا المشروع، فلنقم ببعض عناصر واجهة المستخدم حتى يكون لدينا صفحة جديدة تحتوي على مجموعة من المدخلات حتى نتمكن من ملئها بالمفاتيح من المورد، وInputFile للملف (الملفات)، وزر للقيام بشيء ما، ورسالة ستنتج عن الإجراء.

إنشاء النموذج

سنحتاج إلى بعض النماذج للقيام بذلك بشكل صحيح. أولاً سيكون لدينا فئة BlobRequest التي ستتعامل مع سلسلة الاتصال واسم الحاوية والملفات.

أيضًا، للحفاظ على كل شيء بشكل مرتب، سنقوم بإنشاء فصل يسمى BlobFile حيث سنقوم بتخزين Name و Data.

لقد قمت بإنشاء مجلد باسم Models لذلك تم فصل كل شيء.

الطبقات بسيطة جدا.```csharp using System.ComponentModel.DataAnnotations;

namespace UploadingFilesAzBlobBlazor.Models { public class BlobRequest { [Required(ErrorMessage = “Connection string is required”)] public string? ConnectionString { get; set; } [Required(ErrorMessage = “Container name is required”)] public string? Container { get; set; } public List? Files { get; set; } } }


```csharp
namespace UploadingFilesAzBlobBlazor.Models
{
 public class BlobFile
 {
 public string? Name { get; set; }
 public byte[]? Data { get; set; }
 }
}

تعديل واجهة المستخدم

الآن بعد أن قمنا بإنشاء نموذجنا، فلنمضي قدمًا ونقوم ببعض السحر على واجهة المستخدم باستخدامه!

أولاً، قم بإنشاء صفحة ضمن المجلد Pages المسمى Upload.razor.

في هذه الصفحة، سنضيف نموذجًا صغيرًا يملأ فئة BlobRequest، لذلك يتعين علينا إضافة مدخلات لـ ConnectionString، وContainer، وFiles.

@page "/upload"
@using UploadingFilesAzBlobBlazor.Models
@inject IJSRuntime JsRuntime
<PageTitle> Upload</PageTitle>

<h1> Azure blob storage uploader!</h1>

<EditForm Model="@modal" OnValidSubmit="@HandleValidSubmit">
<DataAnnotationsValidator />
<ValidationSummary />

<div class="mb-3">
<label for="connectionString" class="form-label"> Connection string</label>
<InputText class="form-control" id="connectionString" @bind-Value="modal.ConnectionString" />
</div>

<div class="mb-3">
<label for="container" class="form-label"> Container name</label>
<InputText class="form-control" id="container" @bind-Value="modal.Container" />
</div>

<div class="mb-3">
<label for="formFileMultiple" class="form-label"> Files</label>
<InputFile OnChange="OnInputFileChange" class="form-control" id="formFileMultiple" multiple />
</div>

<div class="mb-3">
<button type="submit" class="btn btn-primary"> Submit</button>
</div>
</EditForm>

@code {
 private BlobRequest modal = new();
 private EditContext editContext;
 IReadOnlyList <IBrowserFile> selectedFiles;
 private void OnInputFileChange(InputFileChangeEventArgs e)
 {
 selectedFiles = e.GetMultipleFiles();
 this .StateHasChanged();
 }

 private async Task HandleValidSubmit() {
 // This is where we are going to upload stuff ! 
 await JsRuntime.InvokeVoidAsync("alert", "Files uploaded!");
 }
}

إنه جزء من التعليمات البرمجية ولكنه في الأساس سيعرض النموذج ويتعامل مع التحقق من الصحة.

إذا ضغطت على الزر للتحميل وكان كل شيء على ما يرام، فسيتم عرض تنبيه.

التحميل إلى مساحة تخزين Azure Blob

الآن بعد أن انتهينا من معظم واجهة المستخدم، فلنثبت الآن الحزمة التي ستتعامل مع واجهة برمجة تطبيقات Azure Blob Storage وستسمح لنا بتحميل الملفات. بسيطة جدا.

أضف حزمة NuGet

دعونا ندير حزم NuGet من المشروع ونضيف Azure.Storage.Blob.

التحميل إلى Azure Blob Stoare

الآن دعونا نقوم بالمنطق الخاص بتحميل الملف فعليًا، عادةً ما نستخدم سلسلة الاتصال والمفتاح من app.config ولكن من أجل هذا البرنامج التعليمي، نستخدم المدخلات ونوفر البيانات هناك.

أولاً، دعونا نضيف using لفئة تخزين Azure Blob

@using Azure.Storage.Blobs
@using Azure.Storage.Blobs.Models

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

private async Task HandleValidSubmit()
{
 try
 {
 // Instantiate container
 var container = new BlobContainerClient(modal.ConnectionString, modal.Container);
 // Create container if not exists
 var createResponse = await container.CreateIfNotExistsAsync();
 // Set access policy
 if (createResponse != null && createResponse.GetRawResponse().Status == 201)
 {
 await container.SetAccessPolicyAsync(Azure.Storage.Blobs.Models.PublicAccessType.Blob);
 }

 // For each file that we have uploaded
 foreach (var file in selectedFiles)
 {
 // New blob
 var blob = container.GetBlobClient(file.Name);
 // Delete any blob with the same name
 await blob.DeleteIfExistsAsync(Azure.Storage.Blobs.Models.DeleteSnapshotsOption.IncludeSnapshots);
 // Create a file stream and use the UploadSync method to upload the Blob.
 using (var fileStream = file.OpenReadStream())
 {
 await blob.UploadAsync(fileStream, new BlobHttpHeaders { ContentType = file.ContentType });
 }
 }

 // Display success message
 await JsRuntime.InvokeVoidAsync("alert", "Files uploaded!");
 }
 catch (Exception e)
 {
 // Display error message
 await JsRuntime.InvokeVoidAsync("alert", "An error ocurred!");
 }
}

اختبار الكود

حان الوقت الآن لاختبار الكود، وللقيام بذلك، ما عليك سوى ملء النموذج والنقر على “إرسال”.

سنعرض تنبيهًا ويجب تحميل الملف إلى Azure Blob Storage، وانتقل إلى Azure Portal وألقِ نظرة.

كما ترون، تم إنشاء الحاوية أيضًا، والآن إذا دخلنا إلى الحاوية، نرى الملف الذي قمنا بتحميله.

عمل جيد!

إعادة البناء

الآن بعد أن تم كل شيء، دعنا ننقل الكود من صفحة .razor إلى فئة .razor.cs بحيث يبدو أفضل.

إذا كنت تستخدم Visual Studio 2022، فهناك مصباح كهربائي عند التمرير مباشرة في @code، وسيُظهر لك خيارًا لـ Extract block to code behind، وسيفعل كما هو مذكور!

الآن سوف يتم فصل كل شيء وإنجازه!

الكود

هذا المشروع بأكمله موجود على Github ويمكنك العثور عليه هنا!

آمل أن تكونوا قد أحببت هذا المنصب! سيا!

الموارد

تجاوز وحدة التحكم الأساسية في Pimcore

Thu, 10 Dec 2020 00:00:00 +0000

لقد كنت أعمل في مشروع Pimcore منذ بعض الوقت، ولم أتطرق مطلقًا إلى PHP وSymfony في حياتي، لذلك كان ذلك تحديًا كبيرًا.

التوثيق رائع، أعني، إنه رائع حقًا، ولكن يبدو أنه ليس مخصصًا للمبتدئين في اللغة/إطار العمل، لذا كل ما قمت به كان علي أن أقوم بتدوين ملاحظات عنه.

بعد أن تعلمت أنه يمكنك توسيع Pimcore باستخدام الحزم، قضيت ساعات وساعات في محاولة لتجاوز وحدات التحكم وطرق جافا سكريبت والمزيد من الأشياء.

لذا سأشرح في هذا المنشور كيف تمكنت من تجاوز وحدة التحكم. كيفية تجاوز ملفات جافا سكريبت ستأتي لاحقًا 😉.

إنشاء الحزمة

أولاً، نحتاج إلى إنشاء حزمة لها، الأمر بسيط جدًا كما هو موثق في وثائق Pimcore، نحتاج فقط إلى تشغيل bin/console pimcore:generate:bundle --namespace=EmiDemo/EmiDemoBundle في مجلد المشروع.

سوف يطرح بعض الأسئلة ولكن لا شيء يدعو للقلق.

سيتم إنشاء مجلد جديد ضمن المجلد src بمساحة الاسم التي أعلناها من قبل، وفي الداخل سيكون لدينا جميع الملفات الضرورية للحزمة.

أيضًا، سيتم اكتشاف المكون الإضافي من خلال موقع إدارة Pimcore، ولكن سيتم تعطيله، يجب عليك تمكينه لبدء استخدامه.

تجاوز الطريقة من وحدة التحكم

لتجاوز طريقة ما في وحدة التحكم، من الواضح أنك تحتاج أولاً إلى العثور على الإجراء الذي تريد تحديثه، يبدو هذا سهلاً ولكني سأعطيك الطريقة التي أفعلها عادةً (تعلمت من زميلي في الفريق سيزار).

انتقل أولاً إلى الصفحة التي تعتقد أن وحدة التحكم تتخذ إجراءً، وفي حالتي أريد التحقق من الصفحة التي يتم تحميلها عندما نفتح أحد الأصول

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

باستخدام هذه المعلومات، يمكنك أن ترى أن الإجراء الذي يقوم بتحميل الأصل هو http://localhost/admin/asset/get-data-by-id?_dc=1607601778450&id=2&type=image. من ذلك يمكننا أن نرى أن إجراء وحدة التحكم هو get-data-by-id.

ابحث عن الإجراء في وحدة التحكم الأساسية

بالنسبة لي، فإن أبسط طريقة للقيام بذلك هي العثور على جميع الملفات في Visual Studio Code

من المحتمل أن تجد أكثر من واحد لذا يجب عليك إلقاء نظرة وتحديد أي منها هو، في حالتنا نحن نعمل مع الأصول لذا فمن الواضح أننا نريد استخدام AssetController.php.

تعديل وحدة التحكم الأساسية

يعتمد الأمر على المطور، وأنا لا أفعل ذلك عادةً لأنه من الأسرع تجاوز وحدة التحكم والتطور من هناك. لكنني أوصي أولاً بتحديث وحدة التحكم في الحزمة الأساسية لمعرفة ما إذا كانت التغييرات التي أجريتها تعمل أم لا.

في حالتنا، سأقوم فقط بإرجاع رسالة في بداية الطريقة للتأكد من أنها تعمل.

return $this->adminJson(['success' => false, 'message' => "Overriding the getDataByIdAction in the core!!"]);

ثم دعونا نعيد تحميل أصولنا ونتحقق من علامة تبويب الشبكة

دعونا نحتفظ بما لدينا هناك، حتى نعلم لاحقًا أننا نستخدم رسالة الحزمة بدلاً من الرسالة الأساسية.

الآن دعنا ننسخ ذلك إلى ملف مؤقت لتتبع ما فعلناه.

انقل هذه التغييرات إلى الحزمة

الآن، لنتمكن من نقل هذه التغييرات إلى مجموعتنا، لكننا نحتاج أولاً إلى بعض العناصر من وحدة التحكم الأساسية لدينا:

مساحة الاسم
الواردات
اسم وحدة التحكم

ومن الواضح أن الطريقة getDataByIdAction هي الطريقة التي نريد تجاوزها.

فضح وحدة التحكم

نحتاج إلى الكشف عن وحدة التحكم، وللقيام بذلك، عليك الانتقال إلى الملف /src/EmiDemo/EmiDemoBundle/Resources/config/pimcore/routing.yml وإضافة

options:
 expose: true

نحتاج أيضًا إلى تغيير prefix إلى الذي سنتجاوزه، في حالتنا، وحدة التحكم admin.

لذلك في النهاية سوف تبدو مثل هذا

emi_demo_emi_demo:
 resource: "@EmiDemoEmiDemoBundle/Controller/"
 type: annotation
 prefix: /admin
 options:
 expose: true

DefaultController.php

في ملفنا، سنقوم بإضافة الواردات وتوسيع وحدة التحكم مع تلك التي سنتجاوزها

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

إذا كنت تتذكر، لدينا رسالة في وحدة التحكم الأساسية بالفعل: Overriding the getDataByIdAction in the core!! والآن يجب أن نرى Overriding the getDataByIdAction in the bundle!!

دعونا لا نعيد أي شيء ونرى أنه يمكننا الآن رؤية الصفحة كما كانت من قبل

قم بالتعليق على بيان الإرجاع وأعد التحميل

هذا كل شيء

ومن خلال هذا العرض التوضيحي الصغير، يمكنك معرفة مدى سهولة تجاوز وحدة التحكم الأساسية الموجودة في Pimcore. هناك بعض الخطوات التي عليك اتباعها ولكنها ليست صعبة. فقط تأكد من كشف وحدة التحكم ومسح ذاكرة التخزين المؤقت من وقت لآخر أثناء إجراء التغييرات، وفي بعض الأحيان يتم تخزينها مؤقتًا وتظل عالقًا معتقدًا أنها لا تعمل وأنها مخزنة مؤقتًا فقط.

إذا كنت تتساءل عن كيفية تجاوز ملفات جافا سكريبت، فسوف يأتي في برنامج تعليمي آخر 😁.

قم بتكوين Apple Magic Keyboard 2 على نظام التشغيل Windows 10

Wed, 11 Nov 2020 00:00:00 +0000

بالأمس فقط اشتريت Apple Magic Keyboard 2، حتى لو كان لدي 5 لوحات مفاتيح ميكانيكية، لأنني أردت تجربتها وكانت لاسلكية.

نظام التشغيل الرئيسي لدي هو Windows 10، وأنا أحبه ولا أريد تغييره، لذا مع أخذ ذلك في الاعتبار، علمت أنه سيكون من الضروري القيام ببعض الأشياء لجعل لوحة المفاتيح تعمل بشكل مثالي. أعرف كيف تعمل شركة Apple وكيف ترغب في الحفاظ على أجهزتها في نظامها البيئي.

القضايا

إذا قمت بإقران لوحة المفاتيح، فسوف تتعرف على بعض الأشياء:

مفاتيح الوظائف لا تعمل
تم تعيين بعض المفاتيح بشكل خاطئ (حدث هذا لي في النسخة الإسبانية)

التوثيق

لكي أجعله يعمل، كان علي أن أقرأ الكثير من الويب، ولكن هذين الرابطين هما اللذان ساعداني على إنجاحه:

تثبيت برنامج تشغيل لوحة مفاتيح Apple

بعض هذه الخطوات مأخوذة من الوثائق المذكورة من قبل:

قم بتثبيت 7zip على جهاز الكمبيوتر الخاص بك إذا لم يكن لديك.
قم بتثبيت Python (الإصدار 2.x) على جهاز الكمبيوتر الخاص بك إذا لم يكن لديك.
- هام: أحدث إصدار من لغة Python هو 3.x. لكنك تحتاج إلى الإصدار 2.x لأن البرنامج النصي العميد غير متوافق مع الإصدار 3.x.
- (اختياري) لا يضيف برنامج التثبيت، افتراضيًا، python.exe إلى المسار الخاص بك. إذا كنت تريد، تحتاج إلى تمكين هذا الخيار. (انظر لقطة الشاشة على اليمين)
- إذا كان لديك بالفعل إصدار آخر من Python، فمن المحتمل أنك لا تريد تمكين هذا الخيار.
قم بتنزيل العميد (برنامج نصي بلغة Python يساعدك على تنزيل أحدث إصدار من Boot Camp).
يرجى النقر بزر الماوس الأيمن على الرابط التالي وحفظ الملف باستخدام “حفظ الرابط باسم…”. https://raw.githubusercontent.com/timsutton/brigadier/master/brigadier
افتح نافذة موجه الأوامر (ويعرف أيضًا باسم مربع DOS) وقم بتغيير الدليل إلى المكان الذي قمت بتنزيل البرنامج النصي العميد فيه.
بافتراض أنه تم حفظ البرنامج النصي العميد باسم “brigadier.txt”، يرجى تشغيل الأمر التالي:
- إذا كان إصدار Python 2.x موجودًا في المسار الخاص بك: python brigadier.txt –model=MacBook13,2
- بخلاف ذلك: [المسار إلى إصدار Python 2.x]\python.exe brigadier.txt –model=MacBook13,2
سيتم تنزيل حزمة كبيرة تحتوي على جميع برامج التشغيل من Bootcamp
قم بإنشاء مجلد يسمى BootCamp وانسخ BootCamp-xxx-yyyyyy\BootCamp\Drivers\Apple\BootCamp.msi و BootCamp-xxx-yyyyyy\BootCamp\Drivers\Apple\AppleKeyboardMagic2 فيه.
قم بتشغيل Powershell المسؤول وقم بتنفيذ BootCamp.msi، وسيقوم بتثبيت بعض الأشياء ولكننا بحاجة إلى تحديث برنامج التشغيل باستخدام محتويات المجلد AppleKeyboardMagic2
ابدأ تشغيل إدارة الأجهزة (devmgmt.msc)
قم بتوسيع العقدة Human Interface Devices
ابحث عن Bluetooth HID Device
قم بتحديث برنامج التشغيل باستخدام محتويات المجلد AppleKeyboardMagic2.
إعادة تشغيل الكمبيوتر

من المفترض أن تشاهد الآن لوحة مفاتيح البلوتوث التي تم اكتشافها على أنها لوحة مفاتيح Apple

تحديث سلوك مفاتيح FNإذا قمت بتثبيت كل شيء بشكل صحيح ستلاحظ أن مفاتيح FN ممكّنة افتراضيًا، فهذا يعني أنك بحاجة إلى الضغط على `fn` + `F5` للضغط فعليًا على الزر `F5`.

لإصلاح ذلك، وجدت حلاً، مذكورًا في قسم الوثائق، يعمل عن طريق تغيير بعض الإدخالات في regedit.

افتح رجديت
انتقل إلى HKEY_CURRENT_USER\SOFTWARE\Apple Inc.\Apple Keyboard Support
قم بإنشاء أو تحديث OSXFnBehavior وتعيينه على 0
إعادة تشغيل الكمبيوتر

تحديث تعيين المفاتيح

إذا كانت لديك مشكلة في التعيينات، فيمكنك استخدام SharpKeys وتحديثها.

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

بالنسبة لحالتي، كان علي تحديث المفاتيح Windows، alt، º و <>.

إضافة المكتبات المترجمة إلى حزمة NuGet

Thu, 01 Oct 2020 00:00:00 +0000

منذ بضعة أيام وجدت خطأً بشأن NullReferenceException في مكتبة مفقودة كان من المفترض أن يكون موجودًا لأنه يأتي من حزمة nuget التي قمنا بتحميلها.

في الأساس، قمت بتجميع فصل مكتبة يشير إلى بعض المشاريع. في مرحلة الإنشاء، سيتم إضافة ملفات dll إلى المجلد bin ولكن عندما يكون packaging كحزمة nuget وتثبيتها في حل آخر، فإن ملفات dll التي أشرت إليها والتي يجب نسخها إلى مجلد bin، ليست موجودة.

كيفية حلها

حل هذه المشكلة بسيط جدًا، يجب عليك تحديث ملف nuspec ولكل مكتبة تريد نسخها، أضف file في الجزء files.

<?xml version="1.0" encoding="utf-8"?>
<package >
 <metadata>
 <id>$id$</id>
 <version>$version$</version>
 <title>$title$</title>
 <authors>$author$</authors>
 <owners>$author$</owners>
 <requireLicenseAcceptance>false</requireLicenseAcceptance>
 <license type="expression">MIT</license>
 <projectUrl>$projectUrl$</projectUrl>
 <iconUrl>$projectIconUrl$</iconUrl>
 <description>$description$</description>
 <releaseNotes></releaseNotes>
 <copyright>$copyright$</copyright>
 <tags></tags>
 </metadata>
 <files>
 <file src="bin\Release\MyFile1.dll" target="lib\net47" />
 <file src="bin\Release\MyFile2.dll" target="lib\net47" />
 <file src="bin\Release\MyFile3.dll" target="lib\net47" />
 <file src="bin\Release\MyFile4.dll" target="lib\net47" />
 </files>
</package>

قم بإجراء bash تحميل المحطة الطرفية على الدليل الرئيسي لـ WSL

Tue, 22 Sep 2020 00:00:00 +0000

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

سيكون من الغباء عدم استخدامه مع توزيعة WSL بدلاً من استخدام وحدة التحكم التي تمنحك.

من الواضح أن وحدة التحكم هذه جيدة، ولكن بعد استخدام الوحدة الطرفية، لن يكون هناك مجال للتراجع. إنه أفضل بكثير، وكذلك c o l o r s.

الآن، إذا قمت بتشغيل الجهاز وفتح علامة تبويب جديدة لتحميل توزيعة WSL الخاصة بك، فسيتم تحميل مجلد المستخدم المثبت لديك.

هذه ليست مشكلة حقًا، لأنه إذا قمت فقط بـ cd ~، فسيتم فقط تحميل مجلد مستخدم التوزيعة.

الأمر هو أنني لا أريد القيام بذلك مرارًا وتكرارًا، لذا دعونا نقوم بتحديث الملف للقيام بذلك بنفسه.

.باشرك

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

أضف cd ~ في نهاية الملف قبل التعليمات الأخيرة.

احفظ وأعد فتح وحدة تحكم WSL باستخدام الجهاز ويجب أن تكون في مجلد الملفات الشخصية.

ضع في اعتبارك أنه سيتعين عليك القيام بذلك لجميع عمليات تثبيت WSL الخاصة بك، نظرًا لأننا نقوم بتحديث ملف bashrc لملف واحد.

إنشاء كائن ديناميكي باستخدام ExpandoObject

Fri, 06 Mar 2020 00:00:00 +0000

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

توصلت إلى برنامج تعليمي يمكنك العثور عليه هنا يستخدم .NET ExpandoObject والذي يتيح لك إلى حد كبير إنشاء كائن وإضافة أعضاء ديناميكيين.

كائن اكسباندو

تعريف مايكروسوفت هو:

يمثل كائنًا يمكن إضافة أعضائه وإزالتهم ديناميكيًا في وقت التشغيل.

وله بعض الملاحظات:

تمكنك فئة ExpandoObject من إضافة وحذف أعضاء مثيلاتها في وقت التشغيل وأيضًا تعيين قيم هؤلاء الأعضاء والحصول عليها. تدعم هذه الفئة الربط الديناميكي، والذي يمكّنك من استخدام بناء الجملة القياسي مثل SampleObject.sampleMember بدلاً من بناء الجملة الأكثر تعقيدًا مثل SampleObject.GetAttribute(“sampleMember”).

السلوك الحالي

لدينا ExcelExportService والذي، من خلال تمرير List<T>، في هذه الحالة ExcelItem، سيستخدم Reflection لإنشاء ملف xlsx.

حتى الآن، يبدو الكود الخاص بنا كما يلي:

class ExcelItem
 {
 public int Id { get; set; }
 public string Name { get; set; }
 public string Surname { get; set; }
 public string Age { get; set; }
 public string CreatedAt { get; set; }
 public string UpdatedAt { get; set; }
 }

ExcelItem هو الكائن الذي يحتوي على جميع الخصائص المستخدمة لإنشاء ملف Excel.

public static byte[] GetExcelBytes() {
 List<ExcelItem> excelItems = new List<ExcelItem>();
 ExcelExportService exportService = new ExcelExportService();

 foreach (var items in itemsToExcel)
 {
 excelItems.Add(new ExcelItem()
 {
 Id = item.Id,
 Name = item.Name,
 Surname = item.Surname,
 Age = item.Age,
 CreatedAt = item.CreatedAt
 UpdatedAt = item.UpdatedAt
 });
 }

 return exportService.ExportToExcel(excelItems);
}

يعمل هذا الأسلوب بشكل مثالي، حيث يتم إنشاء الملف xlsx دون مشاكل حيث يكون كل عمود هو كل خاصية، يمكنك استخدام طريقة GetExcelBytes مثل هذا، على سبيل المثال، لحفظه في ملف:

File.WriteAllBytes("path-to-somewhere/my-file.xlsx", GetExcelBytes());

المشكلة

نظرًا لأن ما نفعله بشكل صحيح هو استخدام جميع خصائص الكائن ExcelItem، فكل ما أريده هو عدم استخدام كل هذه الخصائص، فقط ربما استخدم 2 أو 3 منها.

من المتطلبات أيضًا أنني لا أريد تغيير الكود، يجب أن يتم كل شيء بواسطة administrator، الذي سيقرر الأعمدة التي يجب أن تظهر، وقد يعرف أو لا يعرف الخصائص الموجودة في الكود.

TLDR: يجب أن يكون كل شيء ديناميكيًا، ولدينا كائن ذو خصائص ويجب علينا التأكد من أن الملف الذي تم إنشاؤه يحتوي على خصائص N لذلك الكائن، ولكن من الواضح أنه ليس مشفرًا.

الأعمدة الديناميكية

سيكون التغيير هو استخدام كائن dynamic، لأننا نرغب في تعيين خصائص الكائن التي سيتم استخدامها لإنشاء قائمة الأعمدة.

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

هيكل قاعدة البيانات

نحفظ هذا التعريف في قاعدة البيانات الخاصة بنا بشيء من هذا القبيل:

Id PropertyName
---------------------
1 Name
2 Surname
3 Age

لاحظ أن لدينا قيمًا أقل من الخصائص الموجودة لكائن ExcelItem، حيث يحتوي على خصائص 6 ولدينا فقط 3 مدرج في قاعدة البيانات.

لاحظ أيضًا أن PropertyName يجب أن يتطابق مع اسم خاصية الكائن الذي سأستخدمه للمهمة الديناميكية.

بناء الكائن

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

public static byte[] GetExcelBytes(List<string> columns) {
 List<ExcelItem> excelItems = new List<ExcelItem>();
 List<dynamic> objectsToExcel = new List<dynamic>();
 ExcelExportService exportService = new ExcelExportService();

 foreach (var item in itemsToExcel)
 {
 dynamic newObject = new ExpandoObject();
 foreach (var col in columns)
 {
 this.AddProperty(newObject, col, product.GetType().GetProperty(col).GetValue(item, null));
 }

 objectsToExcel.Add(newObject);
 }

 return exportService.ExportToExcel(objectsToExcel);
}

سنقوم الآن بإنشاء كائن يحتوي على بعض خصائص ExcelItem، ولكنه ديناميكي تمامًا. بدلاً من استخدام جميع الخصائص الستة، نستخدم فقط ثلاثة منها، وهي الخاصية التي نريد إرسالها فقط.

الآن لنفترض أن هذا الكائن ExcelItem يحتوي على 200 خاصية، مجنون، ولكن من الممكن أن يحدث ذلك.

الشيء الوحيد الذي يجب علي فعله هو إدراج تلك الخصائص التي أريد عرضها في ملف Excel إلى جدول ColumnExcelItem وهذا كل شيء.

##حالات

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

ReportingTemplates

Id PropertyName
---------------------
1 Admin
2 Users

ReportingTemplateItems

Id TemplateId PropertyName
---------------------
1 1 Id
2 1 Name
3 1 Surname
4 1 Age
5 1 CreatedAt
6 1 UpdatedAt
7 2 Name
8 2 Surname
9 2 Age

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

إذا كان لدينا مستخدم بالدور Admins، فسيحتوي الملف على أعمدة Id، Name، Surname، Age، CreatedAt، UpdatedAt.

في حالة إنشائه باستخدام الدور Users، سيكون له Name، Age. Surname.

الخلاصة

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

التسليم المستمر لحزمة NuGet باستخدام TravisCI

Tue, 21 Jan 2020 00:00:00 +0000

لقد قمت مؤخرًا بعمل برنامج تعليمي حول كيفية استخدام Travis CI كأداة لاختبار الكود الذي دفعته للتو أو حاولت دفعه إلى فرع master تلقائيًا. مما يجعل تجميعه واختباره وإبلاغك أخيرًا بحالة هذا التغيير.

ولكن يمكننا الاستمرار في تحسينها **على سبيل المثال، المكتبة الأساسية التي تم إنشاؤها في هذا البرنامج التعليمي الأخير، أريد أن أجعلها عامة باستخدام موجز NuGet، حتى يتمكن الجميع من إجراء عملية سهلة في مكتباتهم!

ولكن كيف؟ كيف سنقوم بتجميع هذه الحزمة واختبارها ثم نشرها في الموجز ليتمكن الجميع من تنزيلها في مشاريعهم؟

حسنًا، هذا هذا البرنامج التعليمي لـ 😁!

ما الجديد؟

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

.NET CLI الأساسية

سنستخدم .NET Core CLI، الذي استخدمناه في البرنامج التعليمي السابق مع أوامر مثل dotnet restore، dotnet build و dotnet test.

الآن سوف نستخدم مجموعة جديدة من الأوامر!

`dotnet nuget`

يمكنك التحقق من الوثائق الخاصة بمجموعة الأدوات هذه هنا، ولكن مع شرح مختصر:

dotnet nuget عبارة عن مجموعة من الأدوات الأساسية التي تتضمن تثبيت الحزم واستعادتها وإزالتها ونشرها.

تغذية نوجيت

NuGet هو مدير الحزم لـ .NET. توفر أدوات عميل NuGet القدرة على إنتاج الحزم واستهلاكها. يعد NuGet Gallery مستودع الحزم المركزي الذي يستخدمه جميع مؤلفي الحزم والمستهلكين.

NuGet مجاني، لذا يمكنك التسجيل والتقاط مفتاح API الخاص بك والبدء في تحميل الحزم. سيتم تحميلها والتحقق منها ثم إدراجها في الجميع.

احصل على مفتاح API

لتحميل الحزمة الخاصة بك، ستحتاج إلى الحصول على مفتاح واجهة برمجة التطبيقات (API) بعد التسجيل، لذا انتقل إلى صفحة مفاتيح واجهة برمجة التطبيقات وأنشئ واحدة جديدة.

ضع في اعتبارك أن مفتاح واجهة برمجة التطبيقات (API) تنتهي صلاحيته لمدة 365 يومًا.

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

إنشاء حزمة NuGet

الآن بعد أن حصلنا على المفتاح API، فإن خطوتنا التالية هي إنشاء حزمة NuGet من الحل، لذا تابع وافتح الحل حيث توجد مكتبة الفصل الخاصة بك.

سأستخدم الحل من البرنامج التعليمي الأخير، والذي يحتوي على فئة مكتبة .NET Core تسمى CalculatorCLI.Core.

انتقل الآن إلى خصائص المشروع ثم الحزمة، وسترى الكثير من المعلومات المتعلقة بالحزمة مثل إصدار الحزمة والمؤلفين والأوصاف والمزيد.

التالي هو ملء هذا، ليس عليك حقًا ملء كل شيء، ولكن العناصر المهمة والإلزامية هي Package id، Package version، Authors و Description. وأيضًا إذا حاولت تحميل الملف بنفسك، فسوف يطلب License، وسنحتاج إلى إضافته أيضًا.

ثم يمكنك الحفظ، انقر بزر الماوس الأيمن في المشروع وحدد Pack.

1>------ Build started: Project: CalculatorCLI.Core, Configuration: Debug Any CPU ------
1>CalculatorCLI.Core -> D:\Development\Personal\CalculatorCLI-demo\CalculatorCLI\CalculatorCLI.Core\bin\Debug\netstandard2.1\CalculatorCLI.Core.dll
1>Successfully created package 'D:\Development\Personal\CalculatorCLI-demo\CalculatorCLI\CalculatorCLI.Core\bin\Debug\CalculatorCLI.Core.1.0.0.1.nupkg'.
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

سيُظهر الإخراج أنه إذا كان كل شيء على ما يرام، فسيتم طباعة Successfully created package.

استخدام `dotnet`

كما في البرنامج التعليمي السابق، استخدمنا أوامر مختلفة لبناء الحل واختباره. الآن، سنقوم بإضافة المزيد من الأوامر لحزم الحزم ونشرها.

تلك الأوامر هي:

dotnet pack -c <configuration>
dotnet nuget push <package> <k <apikey> -s <source>

البرامج النصية للنشر

نظرًا لأننا سنقوم بتغيير الطريقة التي سيكون بها البناء، فأنا أعتقد أن وجود ملفات مختلفة، كل منها يحتوي على تعريف بناء اعتمادًا على البيئة، سيكون أفضل فكرة.

لذلك دعونا ننشئ مجلدًا يسمى scripts بثلاثة نصوص bash في جذر المستودع.

scripts\compile.sh

#!/bin/sh

echo "Restoring..."
dotnet restore ".\CalculatorCLI\CalculatorCLI.sln"

echo "Building..."
dotnet build ".\CalculatorCLI\CalculatorCLI.sln" -c Release

scripts\test.sh

#!/bin/sh

echo "Testing..."
dotnet test ".\CalculatorCLI\CalculatorCLI.sln" -c Release -v n

scripts\push.sh

#!/bin/sh

echo "Packing..."
dotnet pack ./CalculatorCLI/CalculatorCLI.Core/CalculatorCLI.Core.csproj -c Release

echo "Pushing..."
dotnet nuget push ./CalculatorCLI/CalculatorCLI.Core/bin/Release/*.nupkg -s "https://nuget.org" -k $NUGET_API_KEY

تحسين ملف `.travis.yml`

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

ما سنفعله الآن بالملف .travis.yml هو ما يلي:

أضف stages مختلفًا
كل stage يعتمد على الفرع
إذا كان الإصدار الخاص بك هو الإصدار الرئيسي، فهذا يعني أنه يجب تحديث الحزمة، لذلك سنقوم بدفع الحزمة الخاصة بنا إلى خلاصات NuGet
إذا كان البناء عبارة عن طلب سحب، فمازلنا سنتحقق مما إذا كان البناء قد تم تجميعه واختباره، ولكننا لن ننشره.

المراحل

من وثائقهم:

يمكنك تصفية ورفض الإصدارات والمراحل والوظائف عن طريق تحديد الشروط في تكوين الإصدار الخاص بك (ملف .travis.yml الخاص بك).

يمكنك العثور على مزيد من المعلومات بخصوص TravisCI stages في صفحة الوثائق الخاصة بهم.

لذلك سنقوم بتغيير الملف وإضافة المراحل التي تنتهي بهذا الشكل:

language:
 csharp
sudo: required
mono: none 
dotnet: 3.0

os:
 - linux

jobs:
 include:
 - stage: compile
 script: bash scripts/compile.sh

 - stage: test
 script: bash scripts/test.sh

 - stage: deploy-prod
 if: branch = master AND type = push
 name: "Deploy to NuGet"
 script: bash scripts/push.sh

كما ترون لدينا ثلاث مراحل مختلفة compile، test و push، والتي سيتم تشغيل المرحلة الأخيرة فقط عندما يكون branch هو master وليس pull request لها، فقط push.

إذا لم تفهم هذا الأمر، فما عليك سوى الانتقال إلى الوثائق وسيتم شرحه بسهولة تامة.

مع أخذ ذلك في الاعتبار، لن يقوم كل pull request بدفع أي شيء إلى موجز NuGet.

تعيين مفتاح API كمتغير بيئة

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

إنشاء `pull request`

الآن بعد أن تم إعداد كل شيء، حان الوقت لإجراء pull request والتحقق مما إذا كان التجميع لطلب السحب هذا يتجاهل آخر stage.

التحقق من البنيات

بمجرد قيامك بتقديم طلب السحب، سيتم وضع البنية في قائمة الانتظار في لوحة معلومات TravisCI، وكما ترى أن لدينا نسختين مختلفتين هناك وليس ثلاثة.

الآن دعونا نقبل pull request ونتحقق من البناء مرة أخرى لنرى أن لدينا الآن ثلاث وظائف بدلاً من اثنتين.

وبمجرد أن ترى البناء في قائمة الانتظار، يمكنك رؤية المهام الثلاث بما في ذلك Deploy-prod في النهاية.

بمجرد اكتمال هذا البناء بالكامل، يمكنك أن ترى في السجلات أنه تم دفع الحزمة إلى المصادر.

ومن الواضح أنه يمكنك رؤيته في صفحة NuGet

هذا كل شيء

اكتشفنا في هذا البرنامج التعليمي كيفية أتمتة تسليم حزم NuGet الخاصة بنا. استخدمنا بعض الأدوات مثل TravisCI، stages و dotnet nuget.

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

يمكنك العثور على الكود المصدري، مع ملف .travis.yml مباشرة هنا، إذا كانت لديك أي أسئلة فلا تتردد في الاتصال بي على twitter!

التكامل المستمر لمشروع .NET Core 3.0 باستخدام TravisCI

Tue, 14 Jan 2020 00:00:00 +0000

قررت في نهاية الأسبوع الماضي أنني أريد أن أبدأ بشكل صحيح مشروع أداة تنزيل الكاشطة والمدقق الذي كنت أقوم به في مستودعات مختلفة.

بعد البدء بمشروع آخر، يجب أن يكون هذا رائعًا، مثل الرائع الحقيقي، باستخدام CI/CD، وطلب السحب، والوثائق، والشارات في الملف التمهيدي، وكل ما رأيته رائعًا وهو بالفعل أفضل الممارسات.

وبعد عطلة نهاية أسبوع جيدة، انتهيت من إنشاء Dramarr، وهي مجموعة من الأدوات التي تقوم بإلغاء العروض وتنزيلها من مصادر مختلفة.

يحتوي على مستودعات مختلفة في المؤسسة ومعظمها عبارة عن مكتبات يتم تجميعها واختبارها ونشرها في طلب السحب وعند دمجها في الفرع الرئيسي.

وهذا ما يطلق عليه CI/CD أو التكامل المستمر/التسليم المستمر.

ولكن في هذا البرنامج التعليمي سنتحدث فقط عن CI.

التكامل المستمر

ما هو؟

مأخوذة من [مدونة] مارتن فاولر(https://martinfowler.com/articles/continuousIntegration.html)، وهو أفضل شرح قرأته:

التكامل المستمر هو ممارسة لتطوير البرمجيات حيث يقوم أعضاء الفريق بدمج عملهم بشكل متكرر، وعادةً ما يتكامل كل شخص يوميًا على الأقل - مما يؤدي إلى عمليات تكامل متعددة يوميًا. يتم التحقق من كل تكامل من خلال إنشاء تلقائي (بما في ذلك الاختبار) لاكتشاف أخطاء التكامل في أسرع وقت ممكن.

الأدوات

هناك العديد من الأدوات لدمج سير العمل الخاص بك مع CI/CD، ولكن في هذا البرنامج التعليمي سنستخدم Github لتخزين التعليمات البرمجية الخاصة بنا وأدوات TravisCI لإعداد CI. فيما يتعلق باللغة والأطر، سوف نستخدم C# وnew.NET Core 3.0.

#المتطلبات

لإنجاز هذا العمل، تحتاج إلى ثلاثة أشياء بسيطة:

أحدث إصدار من فيجوال ستوديو 2019
حساب جيثب
حساب Travis-CI مرتبط بحساب Github الخاص بك

#مشروع

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

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

إنشاء مستودع جيثب

أولاً، سنقوم بإنشاء مستودع Github، لذا تواصل مع Github وقم بإنشاء المستودع واستنساخه في بيئتك المحلية. قررت استدعاء هذا المستودع الجديد CalculatorCLI-demo.

خلق الحل

لنقم الآن بإنشاء حل فارغ يسمى CalculatorCLI، في المجلد الجذر للمستودع المستنسخ

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

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

اذهب وأنشئ Class Library (.NET Standard) وقم بتسميته CalculatorCLI.Core

نسخة NET الأساسيةبمجرد إنشاء المشروع، انتقل إلى خصائص المشروع وقم بتغيير `Target framework` إلى `.NET Standard 2.1`، لجعله متوافقًا مع المشاريع المضمنة في `.NET Core 3.0`.

الكود

من أجل البرنامج التعليمي، دعونا ننشئ فصلًا بسيطًا يتعامل مع العمليات.

using System;

namespace ConsoleCalculator.Core
{
 public enum OperatorsEnum
 {
 ADD,
 SUBSTRACT,
 MULTIPLY,
 DIVIDE
 }

 public class Operation
 {
 public OperatorsEnum OperatorEnum { get; set; }
 public int LeftValue { get; set; }
 public int RightValue { get; set; }

 public Operation(string operatorString, int leftValue, int rightValue)
 {
 switch (operatorString)
 {
 case "+":
 OperatorEnum = OperatorsEnum.ADD;
 break;
 case "-":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;
 case "*":
 OperatorEnum = OperatorsEnum.MULTIPLY;
 break;
 case "/":
 OperatorEnum = OperatorsEnum.DIVIDE;
 break;
 default:
 throw new Exception("Operator invalid");
 }

 LeftValue = leftValue;
 RightValue = rightValue;
 }

 public int DoOperation()
 {
 switch (OperatorEnum)
 {
 case OperatorsEnum.ADD:
 return LeftValue + RightValue;
 case OperatorsEnum.SUBSTRACT:
 return LeftValue - RightValue;
 case OperatorsEnum.MULTIPLY:
 return LeftValue * RightValue;
 case OperatorsEnum.DIVIDE:
 return LeftValue / RightValue;
 default:
 throw new Exception("Operator is not valid");
 }
 }
 }
}

كلي

الآن بعد أن أصبح لدينا المشروع الأساسي، فلنقم بإنشاء التطبيق. في هذه الحالة، سيكون تطبيق وحدة تحكم بسيطًا يقبل الوسائط ويظهر نتيجة.

لذلك دعونا نمضي قدمًا وننشئ Console App (.NET Core) جديدًا، لقد أسميته CalculatorCLI.CLI.

نسخة NET الأساسية

كما فعلنا من قبل، بمجرد إنشاء المشروع، انتقل إلى خصائص المشروع وقم بتغيير Target framework إلى .NET Core 3.0، إذا لم يكن الأمر كذلك بالفعل.

ثم أضف المرجع إلى ConsoleCLI.Core إلى مشروعنا الذي تم إنشاؤه حديثًا.

الكود

الآن بالنسبة للكود، أصبح هذا أبسط من ذي قبل.

using ConsoleCalculator.Core;
using System;
using System.Text.RegularExpressions;

namespace ConsoleCalculator.CLI
{
 public class Program
 {
 public static void Main(string[] args)
 {
 if (args.Length == 0)
 {
 PrintUsage();
 }
 else
 {
 var joinedArgs = string.Join(" ", args);
 var regex = @"-op [\+\-\*\/] -l [-0-9]+ -r [-0-9]+";

 if (Regex.IsMatch(joinedArgs, regex))
 {
 int _left = Int32.Parse(args[3]);
 int _right = Int32.Parse(args[5]);
 string _operator = args[1];

 var _operation = new Operation(_operator, _left, _right);
 var _result = _operation.DoOperation();

 Console.WriteLine($"Result is: {_result}");
 }
 else
 {
 PrintUsage();
 }
 }
 }

 public static void PrintUsage()
 {
 Console.WriteLine($"Welcome to ConsoleCalculator!");
 Console.WriteLine($"");
 Console.WriteLine($"-op Operator, it must be +,-,*,/");
 Console.WriteLine($"-l Left number");
 Console.WriteLine($"-r Left number");
 Console.WriteLine($"");
 Console.WriteLine($"Example usage: -op + -l 5 -r 6");
 }
 }
}

سوف نستخدم هذا التطبيق من أمر مثل، لذا لكي نجعله يعمل، علينا أن نسميه تمرير بعض المعلمات. على سبيل المثال:

ConsoleCalculator.CLI.exe -op + -l 10 -r 20

والذي يترجم إلى:

ConsoleCalculator.CLI.exe -operator + -leftValue 10 -rightValue 20

رمز ذلك بسيط جدًا، إذا لم يتطابق مع نمط regex معين، فهو استدعاء خاطئ ويستدعي PrintUsage(). هذا يعني أننا إذا أدخلنا شيئًا مختلفًا عن الرقم، نظرًا لأنه تم ضبطه على التعبير العادي، فلن يحاول حتى إجراء عملية حسابية.

يعني لو سميناها هكذا:

ConsoleCalculator.CLI.exe -operator + -leftValue asdfg -rightValue ghjk

لن يتم إدخاله أبدًا داخل منطق العمليات ونحن نقوم بحفظ عمليات التحقق المستقبلية مثل TryParse من القيم.

اختبار

لدينا المكتبة الأساسية وسطر الأوامر، لكننا نحتاج الآن إلى الاختبار، لأن هذا ما نريد القيام به في CI.

لذلك دعونا نمضي قدمًا وننشئ MSTest Test Project (.NET Core) جديدًا ونسميه CalculatorCLI.Tests.

نسخة NET الأساسية

ثم أضف المرجع إلى ConsoleCLI.Core و ConsoleCLI.Core إلى مشروعنا الاختباري الذي تم إنشاؤه حديثًا.

الكود

سنقوم بتقسيم الاختبار إلى ملفين مختلفين: CoreTests.cs و CLITests.cs

using CalculatorCLI.Core;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using System;
using System.Collections.Generic;
using System.Text;

namespace CalculatorCLI.Tests
{
 [TestClass]
 public class CoreTests
 {
 public int _left = 2;
 public int _right = 2;

 [TestMethod]
 public void ShouldAdd()
 {
 var expectedResult = 4;
 var operation = new Operation("+", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 public void ShouldSubstract()
 {
 var expectedResult = 0;
 var operation = new Operation("-", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 public void ShouldMultiply()
 {
 var expectedResult = 4;
 var operation = new Operation("*", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 public void ShouldDivide()
 {
 var expectedResult = 1;
 var operation = new Operation("/", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 [ExpectedException(typeof(System.DivideByZeroException))]
 public void ShouldThrowExceptionForDivideByZero()
 {
 var operation = new Operation("/", _left, 0);
 operation.DoOperation();
 }

 [TestMethod]
 [ExpectedException(typeof(System.Exception), "Operator invalid")]
 public void ShouldThrowExceptionForWrongOperator()
 {
 var operation = new Operation("text", _left, 0);
 operation.DoOperation();
 }
 }
}

using Microsoft.VisualStudio.TestTools.UnitTesting;
using System;
using System.Collections.Generic;
using System.Text;

namespace CalculatorCLI.Tests
{
 [TestClass]
 public class CLITests
 {
 public string _left = "2";
 public string _right = "2";

 [TestMethod]
 public void ShouldAdd()
 {
 var args = new string[] { "-op", "+", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }

 [TestMethod]
 public void ShouldSubstract()
 {
 var args = new string[] { "-op", "-", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }

 [TestMethod]
 public void ShouldMultiply()
 {
 var args = new string[] { "-op", "*", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }

 [TestMethod]
 public void ShouldDivide()
 {
 var args = new string[] { "-op", "/", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }
 }
}

مع كل شيء تم إنشاؤه سننتهي بحل مثل هذا:

وبهذا يمكننا الآن إجراء الاختبارات، لذا انتقل إلى Test Explorer في Visual Studio وقم بتشغيلها!

#ترافيس سي.آي

إذا لم تقم بذلك بالفعل، فإن TravisCI هو نظام مستضاف للتكامل والنشر المستمر.

هناك بعض الخطوات التي يتعين علينا القيام بها هنا، ولكن أولاً سنقوم بربط مستودع Github الخاص بنا ليستمع إليه وكلاء TravisCI من أجل بناء مشروعنا واختباره.

تمكين المستودع

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

إنشاء .travis.ymlنحتاج إلى إنشاء ملف يسمى `.travis.yml` في جذر مشروعك، وذلك بسبب كما هو مذكور في الوثائق:

يقوم Travis فقط بتشغيل الإصدارات بناءً على الالتزامات التي تدفعها بعد إضافة ملف .travis.yml.

لذا اذهب وأنشئ ملف .travis.yml في جذر المستودع باستخدام الأسطر التالية:

language:
 csharp
sudo: required
mono: none 
dotnet: 3.0

os:
 - linux

before_script:
 - dotnet restore ".\CalculatorCLI\CalculatorCLI.sln"

script:
 - dotnet build ".\CalculatorCLI\CalculatorCLI.sln" -c Release
 - dotnet test ".\CalculatorCLI\CalculatorCLI.sln" -c Release -v n

لن أخوض في صياغة كيفية عمل الملف .travis.yml، ولكن دعنا نراجع ما يفعله:

قمنا بإعداد أن اللغة ستكون csharp.
لن نستخدم mono لأن .NET Core 3.0 سيتم تشغيله بشكل أصلي في Linux.
قمنا بتعيين إصدار dotnet على 3.0.
قمنا بتعيين os، افتراضيًا هو linux ولكنني أضفته على أي حال.
الآن لدينا before_script والذي سيتم تشغيله قبل المنطق الرئيسي .هنا، لذلك ما وضعته هو تشغيل dotnet restore إلى الحل بحيث يتم تحميل كل شيء بشكل مثالي لاحقًا.
الآن في script، سنقوم بإجراء dotnet builld و dotnet test للحل الخاص بنا، وهذا سيتحقق من تجميعه ثم تشغيل الاختبارات.

لقد انتهينا!

تحميل إلى الماجستير

الآن نحتاج فقط إلى دفع كل شيء لإتقانه.

git add --all
git commit -m "Initial files"
git push

التحقق من التكامل المستمر

يمكننا التحقق من حالة CI للدفع إلى master التي قمنا بها في كل من صفحة المستودع أو لوحة معلومات TravisCI.

في التقدم

##انتهى

#دعونا نكسرها

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

تغييرات الكود

لذا انتقل إلى Operation.cs وقم بتغيير شيء من شأنه أن يؤدي إلى كسر بعض الاختبارات.

using System;

namespace CalculatorCLI.Core
{
 public enum OperatorsEnum
 {
 ADD,
 SUBSTRACT,
 MULTIPLY,
 DIVIDE
 }

 public class Operation
 {
 public OperatorsEnum OperatorEnum { get; set; }
 public int LeftValue { get; set; }
 public int RightValue { get; set; }

 public Operation(string operatorString, int leftValue, int rightValue)
 {
 switch (operatorString)
 {
 case "+":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;
 case "-":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;
 case "*":
 OperatorEnum = OperatorsEnum.MULTIPLY;
 break;
 case "/":
 OperatorEnum = OperatorsEnum.DIVIDE;
 break;
 default:
 throw new Exception("Operator invalid");
 }

 LeftValue = leftValue;
 RightValue = rightValue;
 }

 public int DoOperation()
 {
 switch (OperatorEnum)
 {
 case OperatorsEnum.ADD:
 return LeftValue + RightValue;
 case OperatorsEnum.SUBSTRACT:
 return LeftValue - RightValue;
 case OperatorsEnum.MULTIPLY:
 return LeftValue * RightValue;
 case OperatorsEnum.DIVIDE:
 return LeftValue / RightValue;
 default:
 throw new Exception("Operator is not valid");
 }
 }
 }
}

وإذا قمنا بإجراء الاختبار مرة أخرى، لأننا قمنا بإرجاع الحالة إلى عملية الجمع، فسوف تفشل:

case "+":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;

كما هو متوقع، فشل الأمر بالنسبة لحالة ShouldAdd:

الآن قم بالالتزام بهذا التغيير وادفعه لإتقانه، وانتظر النتائج من وكيل TravisCI.

git add --all
git commit -m "Breaking changes"
git push

بناء

لننتقل الآن إلى سجلات TravisCI وسنرى أننا نجحنا في كسر المشروع، لأن اختبار التكامل فشل وكانت حالة البناء خاطئة.

في نهاية السجل يمكننا رؤية الخطأ نفسه:

دعونا نصلح الأمر مرة أخرى!

الآن ارجع عما فعلناه وادفع الكود لإتقانه، وتحقق من حالة البناء الجديد.

الاختبارات تمر بنجاح:

والبناء أيضًا ناجح:

#الخلاصة

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

هذا كل شيء

يتعلق الأمر بكيفية إنشاء حل .NET Core 3.0 الذي يتمتع بتكامل مستمر في كل بنية باستخدام TravisCI وتخزين التعليمات البرمجية في Github.

يمكنك العثور على الكود المصدري لهذا المشروع هنا.

رأيي في ذاكرة التخزين المؤقت في الذاكرة

Tue, 03 Sep 2019 00:00:00 +0000

لقد كنت أعمل على بعض الأشياء التي تعاملت مع كمية كبيرة من البيانات. أثناء القيام بذلك، أدركت أن جزءًا كبيرًا منه لا يتغير أبدًا، أو على الأقل لبعض الوقت المحدد، لا يتغير.

لذلك اعتقدت أنه سيكون من المفيد إنشاء مستودع ذاكرة تخزين مؤقت شخصي، بالطبع هذا ليس جديدًا، قبل بضعة أسابيع قرأت عن هذا في منشور في StackOverflow الذي كتبه Nick Craver حول كيفية إدارة ذاكرة التخزين المؤقت للتطبيق.

كما كنت أرغب دائمًا في العمل مع ذاكرة التخزين المؤقت، وكيف تعمل، والمنطق، وكيف يمكنني تشغيلها، ف… لماذا لا!

التدفق

فيما يلي تدفق سريع لكيفية تصرف الفئة التي تتحكم في ذاكرة التخزين المؤقت عندما يطلب المستخدم قيمة.

التنفيذ

قبل أن نبدأ

أعرف، أعرف. يوجد System.Runtime.Caching الذي يتعامل مع ذاكرة التخزين المؤقت للذاكرة. لكنني قررت أن أقوم ببنائه بنفسي، إذا كنت تريد استخدام هذا الفصل، فراجع هنا لمعرفة الطريقة.

عنصر ذاكرة التخزين المؤقت

الخطوة الأولى هي أن يكون لديك فئة تخزن قيمة الكائن وتاريخ انتهاء الصلاحية. ربما هناك طريقة أفضل للقيام بذلك، ولكن هذا ما فكرت به، لذا إليك ما يلي:

public class CacheItem
{
 public string Identifier { get; set; }
 public object Value { get; set; }
 public DateTime ValidUntil { get; set; }

 public CacheItem(string identifier, object value, TimeSpan valid)
 {
 Identifier = identifier;
 Value = value;
 ValidUntil = DateTime.UtcNow.Add(valid);
 }
}

مستودع التخزين المؤقت

ثم نحتاج إلى فئة تتعامل مع الكائنات وتحفظها في مكان ما (مثل CacheItem). أحب التعامل مع جميع البيانات/النماذج في الفئات التي تحتوي على اللاحقة Repository، ولكن ليس عليك القيام بذلك، لذلك دعونا نبني واحدًا للتخزين المؤقت.

public class CacheRepository
{
 private static Dictionary<string, string> Cache = new Dictionary<string, string>();
 private static T Set<T>(string key, Func<T> lookup, TimeSpan durationMinutes)
 {
 var item = new Models.Item(key, lookup(), durationMinutes);
 return Save<T>(key, item);
 }
 private static T Save<T>(string key, Item item)
 {
 Cache[key] = JsonConvert.SerializeObject(item);
 return (T)item.Value;
 }
 private static T Get<T>(string key)
 {
 var cached = Cache.FirstOrDefault(x => x.Key == key).Value;
 var item = string.IsNullOrEmpty(cached) ? null : JsonConvert.DeserializeObject<Item>(cached);
 return (item == null)
 ? default : (item.ValidUntil > DateTime.UtcNow)
 ? JsonConvert.DeserializeObject<T>(JsonConvert.SerializeObject(item.Value)) : default;
 }
 public static T GetOrSet<T>(string key, Func<T> lookup, TimeSpan durationMinutes)
 {
 var cache = Get<T>(key);
 return cache == null ? Set(key, lookup, durationMinutes) : cache;
 }
}

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

ضع في اعتبارك أنه سيتم تهيئة العنصر Cache بمجرد تحميل فئة CacheRepository.

الطريقة الوحيدة المتاحة عند استدعاء فئة CacheRepository هي GetOrSet(string key, Func<T> lookup, TimeSpan durationMinutes) التي تحتاج إلى ثلاث معلمات:

key: معرف الكائن المراد حفظه.
lookup: وظيفة رد الاتصال في حالة انتهاء صلاحية ذاكرة التخزين المؤقت أو أنها فارغة.
durationMinutes: المدة بالدقائق والتي سيتم إضافتها إلى الوقت الحالي (بالتوقيت العالمي).

حان الوقت للتخزين المؤقت

الآن، استخدم مستودع التخزين المؤقت الخاص بنا للحصول على بعض البيانات من مكان ما.

لكي يكون كل هذا منطقيًا، فلنقم بإنشاء كائن مثال مع بعض الخصائص، ثم مستودعًا لجلب قائمة بهذا الكائن وملؤها.

public class User
{
 public Guid Id { get; set; }
 public string Name { get; set; }
 public string Email { get; set; }
}
public class UserRepository
{
 public List<User> Get()
 {
 // Code to get users
 }
}

نظرًا لأن لدينا طريقة لملء قائمة User، فلنستخدم فئة CacheRepository.

private UserRepository _userRepository = new UserRepository();
private List<User> _user;
public List<User> User
{
 get
 {
 _user = CacheRepository.GetOrSet($"users", usersRepo.Get, TimeSpan.FromMinutes(10));
 return _user;
 }
}

وهكذا، في كل مرة تقوم فيها بالوصول إلى المتغير User، سيطلب من CacheRepository قيمة الكائن الذي يحتوي على المفتاح users.

إذا كان هذا المفتاح موجودًا، فسوف يتحقق من تاريخ انتهاء الصلاحية. إذا كان أي من هذه الشروط خاطئًا، فسيتم استخدام رد الاتصال لتعيين قيمة الكائن (باستخدام usersRepo.Get) وحفظه في ذاكرة التخزين المؤقت مع تعيين تاريخ انتهاء الصلاحية على DateTime.UtcNow + TimeSpan.FromMinutes(10) وإعادته.

التقط لقطات شاشة للصفحة باستخدام Devtools

Thu, 09 May 2019 00:00:00 +0000

كانت هناك أوقات كنت بحاجة فيها إلى عرض لقطة شاشة كاملة للعميل أو زميل الفريق للحالة الحالية لموقع الويب أو حتى جزء منه، لذلك كنت أستخدم Full Page Screen Capture، ولأي نوع آخر من لقطات الشاشة، أداة Snippet الخاصة بنظام Windows أو Snaggit. إذا كنت أرغب في استضافته عبر الإنترنت كما هو موضح في هذا المنشور Gyazo، والذي يحتوي أيضًا على أداة إنشاء صور GIF.

اكتشفت مؤخرًا أن Devtools يحتوي على أداة يمكنها التقاط لقطة شاشة للصفحة بأكملها، دون الحاجة إلى أي إضافات!

هذه ليست فكرة جديدة، فقد تم تضمينها في تحديث Devtools في أبريل 2017، ولكن يبدو أنني أعيش تحت صخرة ولم أعرف ذلك حتى الآن…

أدوات التطوير

كما هو مذكور في صفحة Devtools الرسمية:

Chrome DevTools عبارة عن مجموعة من أدوات مطوري الويب المضمنة مباشرة في متصفح Google Chrome. يمكن أن تساعدك أدوات DevTools على تحرير الصفحات بسرعة وتشخيص المشكلات بسرعة، مما يساعدك في النهاية على إنشاء مواقع ويب أفضل وبشكل أسرع.

تشغيل الأوامر في Devtools

أنت تعرف بالفعل كيفية فتح Devtools ولكن في حالة نسيانك للتو و من أجل هذا المنشور، افتحه باستخدام المفتاح F12 أو الاختصار Ctrl + Shift + I. ثم يتعين عليك فتح Run command في القائمة داخل Devtools أو استخدام Ctrl + Shift + P.

أداة لقطة الشاشة

إذا كتبت screenshot فسيتم تصفية الأوامر، وسيكون هناك 4 أنواع من طرق لقطات الشاشة التي يمكنك استخدامها:

لقطة شاشة للمنطقة
لقطة الشاشة بالحجم الكامل
لقطة شاشة للعقدة
التقاط لقطة للشاشة

قبل التحقق من جميع طرق لقطات الشاشة، وبعد انتهاء أدوات التطوير من معالجة الصورة، سيتم تنزيلها تلقائيًا باسم صفحة الويب.

لقطة شاشة للمنطقة

سيتيح لك area screenshot تحديد جزء من موقع الويب والتقاط لقطة شاشة.

النتيجة:

لقطة شاشة بالحجم الكامل

سيقوم full size screenshot بالتقاط لقطة شاشة لصفحة الويب بأكملها، من البداية إلى الأسفل.

النتيجة:

لقطة شاشة للعقدة

سيسمح لك node screenshot بعمل لقطة شاشة للعقدة المحددة في عنصر الفحص.

النتيجة:

التقاط لقطة للشاشة

سيقوم capture screenshot بالتقاط لقطة شاشة للصفحة الحالية دون التمرير وحجم المتصفح.

النتيجة:

لغات مخصصة باستخدام الموارد المضمنة والخارجية في .NET Framework

Mon, 06 May 2019 00:00:00 +0000

مقدمة

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

على سبيل المثال، لنفترض أن اللغة الأساسية تستخدم لغة غير رسمية وأن العميل يريد لغة رسمية لأن عملائه هم من كبار السن.

لاحظ أيضًا أن هذه الحلول مخصصة لعدة لغات، وسنستخدم الإنجليزية والإسبانية.

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

الموارد

الموارد هي ملفات XML ذات الامتداد .resx والتي تحتوي على بنية مفتاح/قيمة وتبدو كما يلي:

<?xml version="1.0" encoding="utf-8"?>
<root>
 <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
 <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
 <xsd:element name="root" msdata:IsDataSet="true">
 <xsd:complexType>
 <xsd:choice maxOccurs="unbounded">
 <xsd:element name="metadata">
 <xsd:complexType>
 <xsd:sequence>
 <xsd:element name="value" type="xsd:string" minOccurs="0" />
 </xsd:sequence>
 <xsd:attribute name="name" use="required" type="xsd:string" />
 <xsd:attribute name="type" type="xsd:string" />
 <xsd:attribute name="mimetype" type="xsd:string" />
 <xsd:attribute ref="xml:space" />
 </xsd:complexType>
 </xsd:element>
 <xsd:element name="assembly">
 <xsd:complexType>
 <xsd:attribute name="alias" type="xsd:string" />
 <xsd:attribute name="name" type="xsd:string" />
 </xsd:complexType>
 </xsd:element>
 <xsd:element name="data">
 <xsd:complexType>
 <xsd:sequence>
 <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
 <xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
 </xsd:sequence>
 <xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
 <xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
 <xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
 <xsd:attribute ref="xml:space" />
 </xsd:complexType>
 </xsd:element>
 <xsd:element name="resheader">
 <xsd:complexType>
 <xsd:sequence>
 <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
 </xsd:sequence>
 <xsd:attribute name="name" type="xsd:string" use="required" />
 </xsd:complexType>
 </xsd:element>
 </xsd:choice>
 </xsd:complexType>
 </xsd:element>
 </xsd:schema>
 <resheader name="resmimetype">
 <value>text/microsoft-resx</value>
 </resheader>
 <resheader name="version">
 <value>2.0</value>
 </resheader>
 <resheader name="reader">
 <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
 </resheader>
 <resheader name="writer">
 <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
 </resheader>
 <data name="Action_cancel" xml:space="preserve">
 <value>Finish</value>
 </data>
 <data name="Action_greeting" xml:space="preserve">
 <value>Hello</value>
 </data>
</root>

سنقوم بإنشاء موارد للغتين مختلفتين: الإنجليزية و الإسبانية، وبالتالي فإن تسميات الملفات ستكون: resources.ISOLANGUAGECODE.resx، على سبيل المثال: resource.es.resx للغة الإسبانية وresource.resx للغة الإنجليزية، وفي حالة أردنا إضافة اللغة الألمانية لاحقًا، فسيتم تسمية الملف resource.de.resx.

الموارد المضمنة

الموارد المضمنة، عند تجميع المشروع، ستتم إضافتها داخل dll.

فيما يلي صورة تحتوي على مورد مضمن، كما ترون، لا يمكن رؤية الملف Resource.resx في التجميع.

موارد خارجية

على الجانب الآخر، الموارد الخارجية أو غير المضمنة هي الموارد التي سيتم إضافتها إلى المجلد بعد التجميع.

ستكون ملفات الموارد (.resx) داخل المجلد Properties

بناء المشروع

لنبدأ بمشروع وحدة التحكم في .NET Framework.

إنشاء ملف المورد المضمن

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

إنشاء ملف الموارد الخارجية

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

نصيحة: لإضافة مجلد داخل مجلد الخصائص، قم بإنشائه بالخارج ونقله إلى الداخل، لا يسمح لك Visual Studio بإنشائه

افعل نفس ما فعلناه مع المورد المضمن، ثم انتقل إلى properties من الملف وداخل Advanced، Build action وقم بتغييره إلى: Content وقم بتغيير Copy to Output Dictionary إلى Copy if newer.

هذه هي الطريقة التي ينبغي أن تبدو وكأنها:

إضافة مفتاح إلى app.config

نظرًا لأننا مطورون رائعون ونحب إنجاز كل شيء بشكل جيد وعدم تغيير الكود لكل عميل، فلنضيف مفتاحًا إلى appconfig الذي سيكون له اسم المجلد الذي سنبحث فيه عن ملفات الموارد

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
 <startup>
 <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
 </startup>
 <appSettings>
 <add key="CustomResources.Folder" value="John" />
 </appSettings>
</configuration>
```لذلك، لاحقًا، عندما نبحث عن الموارد، سنبحث في `Properties.John` بدلاً من `Properties.Doe`.

وهذا أيضًا يجعل من السهل التغيير عندما يتم نشر التطبيق بالفعل حيث يمكنك تغيير app.config بسهولة.

## الوصول إلى ملفات الموارد المضمنة

يعد استخدام .NET Framework أمرًا سهلاً إلى حد ما، لذلك من أجل الوصول إلى الخصائص المضمنة، علينا فقط استخدام كائن `Properties`، الذي سيحتوي على ملفات الموارد كخاصية، وداخل هذا الكائن سيكون هناك كل المفتاح/القيمة الموجودة في ملف `resx`.

```csharp
static void Main(string[] args)
{
 var hello = Properties.Resource.Action_greeting;
 var bye = Properties.Resource.Action_cancel;

 Console.WriteLine($"Action_greeting value: {hello}, Action_cancel value: {bye}");

 Console.Read();
}

تشغيل ذلك يجب أن يظهر لنا شيئًا مثل هذا:

Action_greeting value: Hello, Action_cancel value: Cancel

الوصول إلى ملفات الموارد الخارجية

هذا الجزء هو نفسه إلى حد كبير، يمكنك الوصول إلى ملفات الموارد عن طريق كائن Properties.

var hello = Properties.Resource.Action_greeting;
var bye = Properties.Resource.Action_cancel;

var johnhello = Properties.John.Resource.Action_greeting;
var johnbye = Properties.John.Resource.Action_cancel;

var doehello = Properties.Doe.Resource.Action_greeting;
var doebye = Properties.Doe.Resource.Action_cancel;

مشكلة

المشكلة الرئيسية في استخدام هذه الطريقة هي أن كل مفتاح هو خاصية داخل الكائن، لذلك علينا أن نسميه كما رأينا من قبل. إذا كنت تريد استدعاء المفتاح Action_greeting من ملف الموارد الخاص بـ John فعلينا استخدام Properties.John التالي ثم Resource.Action_greeting.

هنا المشكلة.

وذلك لأنه إذا كنا نقوم بتطوير تطبيق لعدد كبير من العملاء، فمن السيئ أن نغير طريقة استدعاء ملفات الموارد لكل منهم.

هل يمكنك تخيل ذلك؟ تجميع التطبيق لكل عميل وتغيير John إلى Doe ثم إلى شيء آخر. هذا جنون!

الحل

فكر قائد فريقنا في طريقة جيدة جدًا، مثل نظام احتياطي، يجب أن يكون لدينا نموذج أساسي للموارد، وبعد ذلك يكون لكل عميل ملف مورد يقوم بتحديث الملف بموارده، وينتهي بنا الأمر بقائمة واحدة من الموارد.

إذا كان العميل لا يريد موارد مخصصة، فإننا نستخدم الموارد الأساسية، وإذا أرادها، نستخدم موارده.

لوضع هذا في قائمة التحقق، علينا القيام بما يلي:

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

رسم بياني

دعونا نرمز

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

هذا ما يبدو:

 class CustomResources
 {

 private static Dictionary<string, string> _ResourcesEnglish;
 private static Dictionary<string, string> ResourcesEnglish;

 private static Dictionary<string, string> _ResourcesSpanish;
 private static Dictionary<string, string> ResourcesSpanish;


 private static Dictionary<string, string> OverwriteDictionary(Dictionary<string, string> currentDictionary, Dictionary<string, string> newDictionary, bool addIfDoesntExist = false)
 {
 ...
 }

 private static Dictionary<string, string> GetDictionaryFromEmbedded(string embedded, string cultureInfoCode)
 {
 ...
 }

 private static Dictionary<string, string> GetDictionaryFromFile(string file)
 {
 ...
 }

 public static string GetText(string key)
 {
 ...
 }

 public static string GetText(string key, string language)
 {
 ...
 }
 }

لاحظ أننا نقوم بتطبيق التحميل البطيء للخصائص مما يساعد على زيادة الأداء ويجعل تحميل القاموس مرة واحدة.

GetDictionaryFromEmbedded: يُرجع قاموسًا من الموارد المضمنة.
GetDictionaryFromFile: يُرجع قاموسًا من مصادر خارجية.
OverwriteDictionary: خلط قاموسين وإرجاع قاموس واحد.
GetText: تُرجع قيمة معينة بمفتاح

من المورد المضمن إلى القاموس

يتعين علينا الحصول على جميع الخصائص من ملف xml وإرجاع القاموس:

private static Dictionary<string, string> GetDictionaryFromEmbedded(string embedded, string cultureInfoCode)
{
 Dictionary<string, string> res = new Dictionary<string, string>();

 try
 {
 ResourceManager rm = new ResourceManager(embedded, Assembly.GetExecutingAssembly());
 var resourceSet = rm.GetResourceSet(new CultureInfo(cultureInfoCode), true, true);

 var resourceDictionary = resourceSet.Cast<DictionaryEntry>()
 .ToDictionary(r => r.Key.ToString(),
 r => r.Value.ToString());
 res = resourceDictionary;
 }
 catch (Exception e)
 {
 string a = e.Message;
 // Error getting resource file
 }

 return res;
}

شيئين:- لاحظ أنه يحتاج إلى معامل يسمى embedded، وهو اسم الملف الذي يمكنك رؤيته في المصمم، في حالتنا هو: resources-demo.Properties.Resource.

لدينا أيضًا معلمة تسمى CultureInfoCode، وهي رمز اللغة التي سيتم اختيارها. لحسن الحظ بالنسبة لنا، يقوم .NET Framework بالمهمة نيابةً عنا وليس علينا القيام بأي شيء، فقط قم بتعيين ما نريده إما باللغة الإنجليزية أو الإسبانية، وسيختار بين resource.es.resx أو resource.resx

من الموارد الخارجية إلى القاموس

يعد الحصول على الملف أمرًا صعبًا بعض الشيء ولكن ليس صعبًا، يتعين علينا الحصول على الموقع الحالي للملف القابل للتنفيذ، وربط موقع ملف المورد ثم تحليله إلى القاموس.

لكن عليك أولاً إضافة المرجع إلى System.Windows.Forms، من أجل الوصول إلى ResXResourceReader.

الآن إلى طريقة GetDictionaryFromFile الخاصة بنا:

private static Dictionary<string, string> GetDictionaryFromFile(string file)
{
 Dictionary<string, string> res = new Dictionary<string, string>();
 string currentPath = (System.IO.Path.GetDirectoryName(System.Reflection.Assembly.GetExecutingAssembly().GetName().CodeBase) + file).Replace("file:\\", "");

 try
 {
 using (ResXResourceReader resxReader = new ResXResourceReader(currentPath))
 {
 foreach (DictionaryEntry entry in resxReader)
 {
 res.Add((string)entry.Key, (string)entry.Value);
 }
 }
 }
 catch (Exception e)
 {
 string a = e.Message;
 }

 return res;
}

يجب ملء معلمات الملف بالموقع من الملف القابل للتنفيذ إلى ملف المورد، في حالتنا هو: "\\Properties\\John\\Resource.resx".

خلط القواميس

لقد انتهينا تقريبًا، أولاً، تذكر إضافة System.Configuration إلى المراجع حتى تتمكن من الوصول إلى app.settings.

 private static Dictionary<string, string> OverwriteDictionary(Dictionary<string, string> currentDictionary, Dictionary<string, string> newDictionary, bool addIfDoesntExist = false)
{
 var identifier = ConfigurationManager.AppSettings["CustomResources.Folder"];
 if (String.IsNullOrEmpty(identifier))
 return currentDictionary;

 foreach (var item in newDictionary)
 {
 try
 {
 currentDictionary[item.Key] = item.Value;
 }
 catch (Exception)
 {
 if(addIfDoesntExist)
 currentDictionary.Add(item.Key, item.Value);
 }
 }

 return currentDictionary;
}

الحصول على نص من القاموس

قم بإنشاء طريقة عامة تستدعي طريقة خاصة تحدد لغة:

private static string GetText(string key, string language)
{
 try
 {
 switch (language)
 {
 case "es":
 return ResourceSpanish[key];
 case "en":
 default:
 return ResourceEnglish[key];
 }
 }
 catch (Exception)
 {
 return $"No value with key: {key} and language: {language}";
 }
}

public static string GetText(string key)
{
 try
 {
 return GetText(key, Thread.CurrentThread.CurrentCulture.TwoLetterISOLanguageName);
 }
 catch (Exception)
 {
 return $"No value with key: {key}";
 }
}

لاحظ أنه يتعين عليك تعديل المفتاح إذا كنت تريد إضافة المزيد من اللغات.

إضافة التعليمات البرمجية إلى getter الخصائص

نظرًا لأن لدينا جميع الطرق في الوقت الحالي، فيمكننا تعديل مُحضر الخاصية العامة للحصول على القيم.

private static Dictionary<string, string> _ResourcesEnglish;
private static Dictionary<string, string> ResourcesEnglish
{
 get
 {
 if (_ResourcesEnglish == null)
 {
 var folderIndentifier = ConfigurationManager.AppSettings["CustomResources.Folder"]; ;
 var baseResources = GetDictionaryFromEmbedded("resources-demo.Properties.Resource");
 var customResources = GetDictionaryFromFile($"\\Properties\\{folderIndentifier}\\Resource.resx", "en");
 _ResourcesEnglish = OverwriteDictionary(baseResources, customResources);
 }

 return _ResourcesEnglish;
 }
}

private static Dictionary<string, string> _ResourcesSpanish;
private static Dictionary<string, string> ResourcesSpanish
{
 get
 {
 if (_ResourcesSpanish == null)
 {
 var folderIndentifier = ConfigurationManager.AppSettings["CustomResources.Folder"]; ;
 var baseResources = GetDictionaryFromEmbedded("resources-demo.Properties.Resources");
 var customResources = GetDictionaryFromFile($"\\Properties\\{folderIndentifier}\\Resources.es.resx", "es");
 _ResourcesSpanish = OverwriteDictionary(baseResources, customResources);
 }

 return _ResourcesSpanish;
 }
}

أولاً نحصل على المُعرف من app.settings.
ثم نحصل على الموارد الأساسية، تلك المدمجة.
بعد ذلك نحصل على الموارد المخصصة ولهذا نحتاج إلى اسم المجلد (وهو المعرف).
ثم نخلطهم ونعيد القيمة.

سيتم كل هذا مرة واحدة، وبالتالي التحميل البطيء.

الاختبار

تم الانتهاء من كل ما يتعلق بالكود، فلنختبره الآن، ومن أجل الحصول على قيمة من القاموس علينا استدعاء الأسلوب CustomResources.GetText(string key) الذي يُرجع القيمة.

تحديث ملفات الموارد بأكملها

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

سنقوم باختبار John، ومن أجل ضبط ذلك، سيتم تعيين app.config على <add key="CustomResources.Folder" value="John" />.

الآن دعونا نتحقق من ملف المورد الأساسي الخاص بنا (Properties/Resource.es.resx):

ثم ملف الموارد الخارجية الخاص بنا (Properties/John/Resource.es.resx):

حسنًا، بعد أن تم ضبط كل شيء، نقوم بتشغيل تطبيق وحدة التحكم، فلنتوقف عند الجزء get من الخصائص ونتحقق من كل شيء

folderIdentifier له قيمة إعداد التطبيقات:

baseResources له قيمة الموارد الأساسية، تلك المضمنة:

customResources لديه قيم الموارد الخارجية داخل المجلد John:

وأخيرًا، _ResourcesSpanish له قيمة مختلطة من الموارد الأساسية إلى الموارد الخارجية.

تحديث واحد فقط

الآن دعونا نختبر نفس السيناريو ولكن مع وجود سيناريو مختلف، ما عليك سوى تحديث مفتاح واحد وترك الآخر كما هو.

كما ترون، الملفات لها نفس معنى القيمة لـ Action_greeting ولكن بقيمة مختلفة لـ Action_cancel، لذلك يجب تحديث Action_cancel فقط.

ملف المورد مفقود

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

زوج مفقود في المورد المضمن

إذا كان لديك زوج في ملف المورد الخارجي، فلن يضيفه افتراضيًا إلى القاموس النهائي، يمكنك تغيير ذلك عن طريق استدعاء الطريقة OverwriteDictionary() عند خلط كلا القواميس وتعيين المعلمة addIfDoesntExist على true.

لغات مختلفة

كما ترون لم نحدد أي لغة، لأن كل ذلك يتم بواسطة الوظيفة GetText(string key) التي تستدعي GetText(string key, string language)، ويتم ملء المعلمة language بواسطة TwoLetterISOLanguageName التي تُرجع اللغة الحالية لموضوعنا.

في حالتي، لدي اللغة الإسبانية كلغة افتراضية ولهذا السبب تظهر دائمًا باللغة الإسبانية، ولكن يمكننا تجربة استخدام اللغة الإنجليزية أيضًا.

دعونا نبرمج قليلاً ونبني شيئًا للتحقق من اللغتين الإسبانية والإنجليزية.

static void Main(string[] args)
{

 // System.Threading.Thread.CurrentThread.CurrentUICulture = new CultureInfo("en-US");
 System.Threading.Thread.CurrentThread.CurrentCulture = new CultureInfo("en-US");
 WriteText("Action_greeting");
 WriteText("Action_cancel");

 // System.Threading.Thread.CurrentThread.CurrentUICulture = new CultureInfo("es-ES");
 System.Threading.Thread.CurrentThread.CurrentCulture = new CultureInfo("es-ES");
 WriteText("Action_greeting");
 WriteText("Action_cancel");

 Console.Read();
}

private static void WriteText(string key) {
 Console.WriteLine($"[Culture: {System.Threading.Thread.CurrentThread.CurrentCulture}] Key: {key} -> value: {CustomResources.GetText(key)}");
}

عند تشغيل هذا، يجب أن يكون الإخراج شيء من هذا القبيل:

[Culture: en-US] Key: Action_greeting -> value: Hello
[Culture: en-US] Key: Action_cancel -> value: Finish
[Culture: es-ES] Key: Action_greeting -> value: Hola
[Culture: es-ES] Key: Action_cancel -> value: Terminar

أول قيمتين من resources.resx وهي باللغة الإنجليزية والأخيرة كلاهما باللغة الإسبانية ويتم استرداد القيم من resources.es.resx.

هذا كل شيء

وجدنا في هذا البرنامج التعليمي طريقة لدمج كل من الموارد المضمنة والخارجية للغات، وكان هذا حلاً لمشكلة واجهناها في الفريق، وهي تعمل منذ ذلك الحين دون أي مشاكل.

يمكنك التحقق من الكود المصدري هنا.

إذا كان لديك أي سؤال فلا تتردد في إرسال تغريدة لي على @emimontesdeocaa وسأعود إليك عندما يتوفر لدي الوقت.

اختبار التكامل باستخدام Bot Framework وDirectLine لحالات التدفق

Wed, 25 Apr 2018 00:00:00 +0000

مقدمة

في منشورات المدونة السابقة، أجرينا بعض اختبارات التكامل لحالات فردية. “الحالات الفردية” هي تلك الحالات التي بعد سؤال الروبوت عن شيء ما، سوف يرد مرة واحدة فقط ثم نقوم بمقارنة النتائج.

لن يشرح هذا الدليل كيفية إجراء المصادقة واستدعاءات واجهة برمجة التطبيقات (API)، إذا كنت تريد التحقق من ذلك، فيرجى مراجعة دليل الحالات الفردية.

ماذا عن محادثات التدفق؟

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

فيما يلي رسم تخطيطي لكيفية عمل اختبار التكامل للحالات الفردية.

!https://gyazo.com/8915f2653033c1143947ef59196403f4](https://gyazo.com/8915f2653033c1143947ef59196403f4)

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

لن يغطي الشرح التالي جميع المعلومات الأساسية حول كيفية عمل Bot Framework، إذا لم تكن تفهم ذلك، فيرجى الانتقال والتحقق من الوثائق الرسمية.

حالة مثال

بالنسبة للدليل التالي، سأستخدم روبوتًا يتضمن محادثة سلسة قمت بإنشائها، والتي تطلب المساعدة ثم تحديد خيارات مختلفة.

بنية JSON جديدة

الآن بعد أن أصبح لدينا أكثر من request عند التحدث إلى الروبوت، نحتاج إلى تعديل بنية json لإضافة جميع request التي سنقوم بها.

{
 "secret": "direct-line-secret",
 "directlineGenerateTokenEndpoint":
 "https://directline.botframework.com/v3/directline/tokens/generate",
 "directlineConversationEndpoint":
 "https://directline.botframework.com/v3/directline/conversations/",
 "entries": [
 {
 "name": "PedirAyuda",
 "requests": [
 {
 "type": "message",
 "text": "Ayuda",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 {
 "type": "message",
 "text": "Telefono",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 {
 "type": "message",
 "text": "Oficina",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 {
 "type": "message",
 "text": "Tenerife",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 }
 ],
 "response": {
 "type": "message",
 "timestamp": "2018-04-09T08:04:37.901Z",
 "localTimestamp": "2018-04-09T09:04:37+01:00",
 "serviceUrl": "http://localhost:50629",
 "channelId": "emulator",
 "from": {
 "id": "j98bbdf097a",
 "name": "Bot"
 },
 "conversation": {
 "id": "eabcie4be8ak"
 },
 "recipient": {
 "id": "default-user"
 },
 "locale": "es",
 "text": "922920252",
 "attachments": [],
 "entities": [],
 "replyToId": "61hacck8j6jg",
 "id": "47me557ikbf7"
 },
 "assert": "Request.Text == Response.Text"
 }
 ]
}

كما ترون، هناك تغيير مهم، request أصبح الآن requests. وهذا يعني أن لدينا الآن List<Activity> بدلاً من activity واحد.

كائنات جديدة

في السابق، قمنا بتعيين كائناتنا لحالات فردية: TestEntry وTestEntryCollection. بالنسبة لحالات التدفق، سنقوم بإنشاء كائنات جديدة: TestEntryFlow وTestEntryFlowCollection.

`TestEntryFlow`

هذا الكائن مخصص لكل إدخال لدينا في المجموعة، انظر إلى أن كائن Requests أصبح الآن List<Activity> بدلاً من Activity كما ذكرت من قبل.

نظرًا لأننا سنطلب من الروبوت عدة مرات، فنحن بحاجة إلى عدة activities سيتم إرسالها إلى المحادثة.

public class TestEntryFlow
{
 /// <summary>
 /// Entry name
 /// </summary>
 [JsonProperty("name")]
 public string Name { get; set; }
 /// <summary>
 /// Activity requested by the entry
 /// </summary>
 [JsonProperty("requests")]
 public List<Activity> Requests { get; set; }
 /// <summary>
 /// Activity response expected by the entry
 /// </summary>
 [JsonProperty("response")]
 public Activity Response { get; set; }
 /// <summary>
 /// Assert value in string
 /// </summary>
 [JsonProperty("assert")]
 public string Assert { get; set; }
}

`TestEntiresCollection`

سيحتوي هذا الكائن على المعلومات ذات الصلة بـ DirectLine مثل secret ونقاط النهاية، بالإضافة إلى قائمة Entries التي سنختبرها.

لاحظ أن Entries الآن عبارة عن قائمة بـ TestEntryFlow وليس TestEntry.

public class TestEntryFlowCollection
{
 /// <summary>
 /// DirectLine Secret
 /// </summary>
 [JsonProperty("secret")]
 public string Secret { get; set; }
 /// <summary>
 /// Endpoint to get the token using the secret for DirectLine
 /// </summary>
 [JsonProperty("directlineGenerateTokenEndpoint")]
 public string DirectLineGenerateTokenEndpoint { get; set; }
 /// <summary>
 /// Endpoint for a conversation in DirectLine
 /// </summary>
 [JsonProperty("directlineConversationEndpoint")]
 public string DirectLineConversationEndpoint { get; set; }
 /// <summary>
 /// Entries list
 /// </summary>
 [JsonProperty("entries")]
 public List<TestEntryFlow> Entries { get; set; }
}

إنشاء `TestMethod` لحالات التدفق

التدفق الجديد

أولاً، قم بإلقاء نظرة مرة أخرى على الرسم البياني مرة أخرى (وهو نفس الرسم البياني الذي نشرته أعلاه).

!https://gyazo.com/ef77fa168d3b5f8b4a116ff38b5edd83](https://gyazo.com/ef77fa168d3b5f8b4a116ff38b5edd83)

كما ترون، فإن بنية التدفق لإجراء الاختبار هي نفسها تقريبًا:

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

الكود

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

// Load entries from file
var path = System.IO.File.ReadAllText(@"C:\dataFlow.json");

// Deserialize to object
var data = JsonConvert.DeserializeObject<TestEntryFlowCollection>(path);

الآن علينا إجراء حلقة لكل TestEntryFlow، من data.entries، وبهذا يمكننا اتباع نفس التدفق الذي فعلناه في الحالات الفردية حتى الجزء الجديد، حيث نقوم بالتكرار في requests.

/// Arrange with current requested values
string token, newToken, conversationId;
Activity latestResponse = new Activity();

/// Act for step

/// 1 - Get token using secret from DirectLine in BotFramework panel
token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

/// 2 - Create a new conversation
var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

// This returns a new token and a conversationId
newToken = createdConversation.token;
conversationId = createdConversation.conversationId;

/// 3 - Send an activity to the conversation with new token and conversationId
string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";

الخطوة التالية بسيطة جدًا، علينا تكرار entry.requests وإرسال كل activity إلى المحادثة.

foreach (Activity step in entry.Requests)
{
 if (step.Type == ActivityTypes.Message)
 {
 /// Step
 Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(step));

 /// 4 - Get all activities, we get a List<activity> and a watermark
 var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

 /// 5 - Get the latest activity which is the response we should be expecting
 latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];
 }
}

نستخدم watermark للحصول على أحدث رسالة، watermark هي القيمة التي ترجعها واجهة برمجة تطبيقات DirectLine عند طلب معلومات المحادثة.

بعد ذلك، علينا فقط ملء globals بـ latestReponse و expectedResponse.

/// Arrange with new values
var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

ولإنهاء الحالة، نقوم بتقييم السلسلة assert في entry.

/// Assert
Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));

الكود النهائي

[TestMethod]
public async Task ShouldTestFlowCases()
{
 // Load entries from file
 var path = System.IO.File.ReadAllText(@"C:\dataFlow.json");

 // Deserialize to object
 var data = JsonConvert.DeserializeObject<TestEntryFlowCollection>(path);

 /// Flow: Arrange -> Act -> arrange -> assert
 foreach (TestEntryFlow entry in data.Entries)
 {
 /// Arrange with current requested values
 string token, newToken, conversationId;
 Activity latestResponse = new Activity();

 /// Act for step

 /// 1 - Get token using secret from DirectLine in BotFramework panel
 token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

 /// 2 -Create a new conversation
 var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

 // This returns a new token and a conversationId
 newToken = createdConversation.token;
 conversationId = createdConversation.conversationId;

 /// 3 - Send an activity to the conversation with new token and conversationId
 string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";

 foreach (Activity step in entry.Requests)
 {
 if (step.Type == ActivityTypes.Message)
 {
 /// Step
 Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(step));

 /// 4 - Get all activities, we get a List<activity> and a watermark
 var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

 /// 5 - Get the latest activity which is the response we should be expecting
 latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];
 }
 }

 /// Arrange with new values
 var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

 /// Assert
 Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));
 }

 await Task.CompletedTask;
}

التحسينات

أعتقد أن التدفق الأفضل قد يكون ممكنًا، ولكن هذا التحسين سيعني أنه يجب تغيير بنية JSON أيضًا. أيضًا، لتحقيق ذلك، يجب ملء ملف json بشكل أكبر.

من أجل تحسين هذا الاختبار، يجب أن يكون لدينا response لكل request، ويجب التأكيد في كل مرة نرسل فيها رسالة. الطريقة التي نقوم بها الآن هي من خلال تخزين كل requests و النهائي response .

لقد قمت بعمل رسم تخطيطي لإظهار كيف سيبدو هذا.

!https://gyazo.com/dfd4e9f87ff69159f02a0bcc70ae1edc](https://gyazo.com/dfd4e9f87ff69159f02a0bcc70ae1edc)

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

حسنًا، هذا كل ما في هذا الدليل، يرجى تذكر أن هذا الدليل يهدف إلى أن يكون استمرارًا لدليل الحالات الفردية، إذا شعرت بالضياع، فراجع هذا الدليل الأطول والذي يحتوي على المزيد من الشرح لكل شيء.

تذكر أنه تم تخزين كافة التعليمات البرمجية في جيثب الخاص بي في مستودع هذا.

اتمنى لك يوم جيد!

اختبار التكامل باستخدام Bot Framework و DirectLine (2)

Tue, 24 Apr 2018 00:00:00 +0000

في هذا الجزء، سنقوم بترخيص DirectLine والحصول على القيم من استجابة الروبوت.

الآن بعد أن قمنا بإلغاء التسلسل، حان الوقت للحصول على المعلومات من المجموعة والأجزاء الكاملة التي سنستخدمها للحصول على الترخيص، وإجراء مكالمات API وتأكيد النتيجة.

إجراء مكالمات API باستخدام WebClient

لتسهيل الاتصال بواجهة برمجة التطبيقات، قمت بإنشاء فئة utils، حيث نحفظ الوظائف التي سنستخدمها عدة مرات، تتضمن هذه الفئة uploadString لـ POST و downloadString لـ GET.

 public class Utils
 {
 /// <summary>
 /// Uploads to an URL and gets result
 /// </summary>
 /// <typeparam name="T">Type of object you are receiving</typeparam>
 /// <param name="bearer">Token</param>
 /// <param name="url">Url</param>
 /// <param name="serializedJson">Serialized JSON to send</param>
 /// <returns></returns>
 public static T uploadString<T>(string bearer, string url, string serializedJson)
 {
 string serializedResult = "";

 /// Webclient
 using (var client = new WebClient())
 {
 /// Add headers
 client.Headers.Add("Content-Type", "application/json");
 client.Headers.Add("Authorization", $"Bearer {bearer}");

 /// Upload string
 serializedResult = client.UploadString(url, serializedJson);
 }

 /// Get result and return it as an object
 return JsonConvert.DeserializeObject<T>(serializedResult);
 }

 /// <summary>
 /// Downloads from URL
 /// </summary>
 /// <typeparam name="T">Type of object you are receiving</typeparam>
 /// <param name="bearer">Token</param>
 /// <param name="url">Url</param>
 /// <returns></returns>
 public static T downloadString<T>(string bearer, string url)
 {
 string serializedResult = "";

 /// Webclient
 using (var client = new WebClient())
 {
 /// Add headers
 client.Headers.Add("Content-Type", "application/json");
 client.Headers.Add("Authorization", $"Bearer {bearer}");

 /// Download string
 serializedResult = client.DownloadString(url);
 }

 /// Get result and return it as an object
 return JsonConvert.DeserializeObject<T>(serializedResult);
 }
 }

ترخيص الخط المباشر

إذا قرأت الوثائق الرسمية، يمكنك العثور على كيفية القيام بذلك، وهو أمر سهل للغاية، باستخدام وظائفنا يصبح الأمر أسهل. أولًا، تذكر أننا داخل عبارة foreach، نظرًا لأننا نقوم بالمصادقة لكل حالة، في حالة نفاد الوقت، مما يعني فشل الاختبار.

/// Arrange with current requested values
string token, newToken, conversationId;
/// Act

/// 1 - Get token using secret from DirectLine in BotFramework panel
token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

الآن لدينا الرمز المميز، والذي سيتم استخدامه لإجراء جميع الاستدعاءات التالية إلى نقطة نهاية المحادثة.

إنشاء محادثة.

من أجل التحدث إلى الروبوت، نحتاج أولاً إلى إنشاء محادثة، وستعيد هذه المحادثة رمزًا مميزًا جديدًا يتضمن معرف المحادثة.

/// 2 -Create a new conversation
var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

// This returns a new token and a conversationId
newToken = createdConversation.token;
conversationId = createdConversation.conversationId;

نقوم أيضًا بتخزين newToken وconversationId، وكلاهما ضروري للمستخدم لإرسال رسائل إلى الروبوت.

إرسال النشاط إلى المحادثة

الآن، باستخدام conversationId وconversationEndpoint، يمكننا إنشاء نقطة النهاية النهائية لإرسال Activity وهو request من ملف json.

/// 3 - Send an activity to the conversation with new token and conversationId
string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";
Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(entry.Request));

احصل على أحدث رسالة

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

/// 4 - Get all activities, we get a List<activity> and a watermark
var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

/// 5 - Get the latest activity which is the response we should be expecting
var latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];

وهذا كل ما في هذا الجزء، الجزء التالي سيتضمن الجزء الذي نحصل فيه على النص من assert في json، وتحويله إلى كود مثل استخدام eval() في Javascript ولكن في C#، ثم استخدام Assert.isTrue() للحصول على نتيجة الاختبار النهائية.

تذكر أنه تم تخزين كافة التعليمات البرمجية في جيثب الخاص بي في مستودع هذا.

اختبار التكامل باستخدام Bot Framework وDirectLine (1)

Tue, 24 Apr 2018 00:00:00 +0000

منذ أن بدأت العمل في إحدى الشركات لفترة قصيرة من الزمن، تم تكليفي بالعمل على اختبار التكامل لإطار عمل الروبوت.

عملي في المجموعة هو جعل الروبوت مستقرًا قدر الإمكان، ولكن أولاً، ما هو إطار عمل الروبوت؟

قم ببناء الروبوتات الذكية وتوصيلها ونشرها وإدارتها للتفاعل بشكل طبيعي مع المستخدمين لديك على موقع ويب وتطبيق وCortana وMicrosoft Teams وSkype وSlack وFacebook Messenger والمزيد. ابدأ بسرعة مع بيئة بناء الروبوتات الكاملة، كل ذلك مع الدفع مقابل ما تستخدمه فقط.

يمكنك العثور على مزيد من المعلومات حول Bot Framework مباشرة هنا.

لماذا أحتاج إلى اختبار التكامل؟

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

اختبار التكامل في الروبوتات؟

أعتقد أن اختبار التكامل مهم جدًا في الروبوتات. لا يمكن أن يكون لديك روبوت حيث لا تعمل بعض قوائمه، أو لا تقوم بعض الميزات بإرجاع أي شيء.

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

نظرة عامة على الحل.

من أجل إنجاز هذا العمل، استخدمت مشروع اختبار في Visual Studio، والذي سيستخدم WebClient لـ API Rest وملف Json، حيث سنقوم بتخزين حالاتنا.

ملف جيسون

{
 "secret": "direct-line-secret",
 "directlineGenerateTokenEndpoint": "https://directline.botframework.com/v3/directline/tokens/generate",
 "directlineConversationEndpoint": "https://directline.botframework.com/v3/directline/conversations/",
 "entries": [
 {
 "name": "DecirHola",
 "request": {
 "type": "message",
 "text": "Hola",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 "response": {
 "type": "message",
 "timestamp": "2018-04-09T08:04:37.901Z",
 "localTimestamp": "2018-04-09T09:04:37+01:00",
 "serviceUrl": "http://localhost:50629",
 "channelId": "emulator",
 "from": {
 "id": "j98bbdf097a",
 "name": "Bot"
 },
 "conversation": {
 "id": "eabcie4be8ak"
 },
 "recipient": {
 "id": "default-user"
 },
 "locale": "es",
 "text": "No tengo respuesta para eso.",
 "attachments": [],
 "entities": [],
 "replyToId": "61hacck8j6jg",
 "id": "47me557ikbf7"
 },
 "assert": "Request.Text == Response.Text"
 }
 ]
}

كما ترون لدينا:

سر الخط المباشر -> سر من الروبوت المنشور
نقطة نهاية إنشاء الرمز المميز للخط المباشر -> نقطة النهاية للحصول على الرمز المميز باستخدام السر
نقطة نهاية محادثة الخط المباشر -> نقطة النهاية للعب بالمحادثة
الدخول -> حالة الاختبار
- طلب -> ما نرسله إلى المحادثة
- الاستجابة -> ما نتوقع الحصول عليه
- أكد -> ما الذي نقارنه

إلغاء التسلسل

لدينا ملف json منسق بشكل مثالي، وعلينا الآن تحميله في الحل، لذلك سنستخدم JSON.NET وبعض الفئات. أولاً لدينا مجموعة الإدخالات، التي تحتوي على كل شيء، وبعد ذلك لدينا قائمة إدخالات لكل مجموعة.

 /// <summary>
 /// Object to parse from the file
 /// </summary>
 public class TestEntriesCollection
 {
 /// <summary>
 /// DirectLine Secret
 /// </summary>
 [JsonProperty("secret")]
 public string Secret { get; set; }
 /// <summary>
 /// Endpoint to get the token using the secret for DirectLine
 /// </summary>
 [JsonProperty("directlineGenerateTokenEndpoint")]
 public string DirectLineGenerateTokenEndpoint { get; set; }
 /// <summary>
 /// Endpoint for a conversation in DirectLine
 /// </summary>
 [JsonProperty("directlineConversationEndpoint")]
 public string DirectLineConversationEndpoint { get; set; }
 /// <summary>
 /// Entries list
 /// </summary>
 [JsonProperty("entries")]
 public List<TestEntry> Entries { get; set; }
 }

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


 public class TestEntry
 {
 /// <summary>
 /// Entry name
 /// </summary>
 [JsonProperty("name")]
 public string Name { get; set; }
 /// <summary>
 /// Activity requested by the entry
 /// </summary>
 [JsonProperty("request")]
 public Activity Request { get; set; }
 /// <summary>
 /// Activity response expected by the entry
 /// </summary>
 [JsonProperty("response")]
 public Activity Response { get; set; }
 /// <summary>
 /// Assert value in string
 /// </summary>
 [JsonProperty("assert")]
 public string Assert { get; set; }
 }

التحليل من json إلى الكائن في حالة الاختبار

إن الحصول على فئات لكائن التحليل أمر سهل للغاية لأننا نحتاج إلى قراءته ككائن.

// Load entries from file
var path = System.IO.File.ReadAllText(@"C:\data.json");

// Deserialize to object
var data = JsonConvert.DeserializeObject<TestEntriesCollection>(path);

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

 foreach (TestEntry entry in data.Entries)
 {
 ....
 }

وهذا كل ما في هذا الجزء، الجزء التالي سيتضمن ترخيص DirectLine، تذكر أنه يتم تخزين جميع التعليمات البرمجية في جيثب الخاص بي في مستودع هذا.

اختبار التكامل باستخدام Bot Framework وDirectLine (3)

Tue, 24 Apr 2018 00:00:00 +0000

هذا هو الجزء الأحدث من الدليل، في هذا الجزء، سنقوم بتقييم النص من التأكيد في ملف json.

الآن بعد أن استخدمنا request وأرسلنا كـ activity إلى الروبوت، حصلنا على response وعلينا مقارنة ما assert في json (الاستجابة التي قمنا بتخزينها في json، هذه هي الاستجابة المتوقعة) مع الاستجابة التي حصلنا عليها من الروبوت.

إضافة Microsoft.CodeAnalogy إلى الحل

أولاً، يتعين علينا تضمين CodeAnalogy كحزمة NuGet.

بعد التثبيت، تذكر إضافة الحزمة إلى ملف .cs.

using Microsoft.CodeAnalysis.CSharp.Scripting;

إنشاء كائن `Globals`

من أجل التقييم، علينا تمرير المعلمات إلى المقيم. يحتاج هذا المقيم إلى ملف التكوين.

 /// <summary>
/// Object to pass parameters to Roslyn compiler
/// </summary>
public class Globals
{
 /// <summary>
 /// ExpectedResponse
 /// </summary>
 public Activity Request;
 /// <summary>
 /// ReceivedResponse
 /// </summary>
 public Activity Response;
}

هذا الجزء مهم جدًا، في ملف التكوين هذا، سنقوم بتضمين الكائنات التي سنقارنها، لذلك بالنسبة لنا، نحتاج إلى تمرير الاستجابة المتوقعة و الاستجابة المستلمة.

باستخدام هذه المعلومات، سيتم استخدام assert في ملف json وسيقوم بتقييم ما يقال.

/// Arrange with new values
var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

/// Assert
Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));

** يقوم EvaluateAsync<T> بتقييم وإرجاع T، في حالتنا نمرر string للتقييم وglobals، الذي يحتوي على البيانات التي سيتم تقييمها.**

سأحاول شرح ذلك بمثال، باستخدام إدخال (يحتوي على اسم وطلب واستجابة وتأكيد).

{
 "name": "DecirHola",
 "request": {
 "type": "message",
 "text": "Hola",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 "response": {
 "type": "message",
 "timestamp": "2018-04-09T08:04:37.901Z",
 "localTimestamp": "2018-04-09T09:04:37+01:00",
 "serviceUrl": "http://localhost:50629",
 "channelId": "emulator",
 "from": {
 "id": "j98bbdf097a",
 "name": "Bot"
 },
 "conversation": {
 "id": "eabcie4be8ak"
 },
 "recipient": {
 "id": "default-user"
 },
 "locale": "es",
 "text": "No tengo respuesta para eso.",
 "attachments": [],
 "entities": [],
 "replyToId": "61hacck8j6jg",
 "id": "47me557ikbf7"
 },
 "assert": "Request.Text == Response.Text"
 }

دعنا نحصل على الأشياء المهمة من هذا الإدخال، أولاً التأكيد "assert": "Request.Text == Response.Text"، وهذا يعني أنه سيقارن Request.Text مع Response.Text، ويعيد القيمة كقيمة منطقية.

لكن عندما نستدعي الدالة await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals) فإننا نمرر معلمتين:

string السلسلة المطلوب تقييمها -> "Request.Text == Response.Text"
globals بيانات للمقيم -> في هذه الحالة يتعين علينا تقديم Request وResponse، الطلب هو ردنا المتوقع والرد هو الرد المستلم.

بما أننا نقوم بملء البيانات في المقيم، يمكننا الآن استخدام السلسلة وتقييمها، لذلك ستُرجع true أو false.

تم

لقد انتهينا، هنا يمكنك رؤية TestMethod النهائي

[TestMethod]
public async Task ShouldTestSingleCases()
{
 // Load entries from file
 var path = System.IO.File.ReadAllText(@"C:\data.json");

 // Deserialize to object
 var data = JsonConvert.DeserializeObject<TestEntriesCollection>(path);

 /// Flow: Arrange -> Act -> arrange -> assert

 foreach (TestEntry entry in data.Entries)
 {
 /// Arrange with current requested values
 string token, newToken, conversationId;

 if (entry.Request.Type == ActivityTypes.Message)
 {
 /// Act

 /// 1 - Get token using secret from DirectLine in BotFramework panel
 token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

 /// 2 -Create a new conversation
 var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

 // This returns a new token and a conversationId
 newToken = createdConversation.token;
 conversationId = createdConversation.conversationId;

 /// 3 - Send an activity to the conversation with new token and conversationId
 string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";
 Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(entry.Request));

 /// 4 - Get all activities, we get a List<activity> and a watermark
 var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

 /// 5 - Get the latest activity which is the response we should be expecting
 var latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];

 /// Arrange with new values
 var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

 /// Assert
 Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));
 }
 }
 await Task.CompletedTask;
}

رسم بياني

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

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

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

!https://gyazo.com/d964cfac395ed438a5282e60614863e7](https://gyazo.com/d964cfac395ed438a5282e60614863e7)

تذكر أنه تم تخزين كافة التعليمات البرمجية في جيثب الخاص بي في مستودع هذا.

المحاضرات

Mon, 01 Jan 0001 00:00:00 +0000

أنا متحدث متكرر في المؤتمرات التقنية الدولية، مع التركيز على .NET وAzure والذكاء الاصطناعي والتطوير السحابي الأصيل. تم تكريمي كـ أكثر المتحدثين نشاطاً في Sessionize في 2023 و2024 و2025، وأحمل شهادة مايكروسوفت MVP في تقنيات المطورين.

إذا كنت تريدني أن أتحدث في فعاليتك، لنتحدث!

2026

Blazor في 2026

نظرة على الحالة الراهنة لـ Blazor في 2026 وكيف تطور جنبًا إلى جنب مع .NET 10. نراجع أحدث التغييرات والتحسينات وتأثيرها على تطوير التطبيقات الحقيقية، وأي نموذج استضافة Blazor يناسب كل سيناريو.

تعزيز دعم المستوى 3 بالذكاء الاصطناعي: Azure Functions + OpenAI في العمل

كيف تعمل Azure Functions وتنبيهات Azure Monitor وAzure OpenAI معًا لتسريع دعم المستوى 3. من الفرز التلقائي للتنبيهات إلى التحليل الذكي للسجلات — نظرة عملية على إضافة الذكاء الاصطناعي لسير عمل الدعم الحقيقي.

من لوحة القيادة إلى الوكيل: الخطوة التالية للمراقبة

جلسة تطبيقية تربط بين عالم وكلاء الذكاء الاصطناعي والمراقبة في الإنتاج. من Semantic Kernel إلى الوكلاء المستقلين الذين يستعلمون بيانات OpenTelemetry ويتفاعلون مع Grafana عبر MCP ويساعدون في تشغيل وتحسين الأنظمة الحقيقية.

قادم: Global Azure 2026 — أبريل 2026، مدريد، إسبانيا

2025

إطار عمل الوكلاء من مايكروسوفت لإنقاذ عيد الميلاد

بناء وتنسيق وكلاء ذكاء اصطناعي متعددين باستخدام Microsoft Agent Framework للعثور على هدايا عيد الميلاد المثالية. كل وكيل متخصص — من توليد أفكار الهدايا إلى مقارنة الأسعار — يعملون معًا لتسوق موسمي أذكى.

تعزيز دعم المستوى 3 بالذكاء الاصطناعي: Azure Functions + Semantic Kernel في العمل

Azure Functions وAzure Monitor وSemantic Kernel يعملون معًا لجعل دعم المستوى 3 أسرع وأكثر كفاءة — من الكشف التلقائي عن التنبيهات إلى التحليل الذكي للسجلات.

ما الجديد في Blazor مع .NET 10؟

استكشاف الميزات الجديدة الرئيسية في Blazor لـ .NET 10، بما في ذلك تحسينات الأداء والنماذج والحالة الدائمة والتشغيل البيني لـ JavaScript الأكثر قوة.

الذكاء الاصطناعي الهجين مع C# وSemantic Kernel وGemini: بناء تطبيقات مؤسسية أذكى

تنسيق سير عمل الذكاء الاصطناعي الهجين في C# — دمج النماذج المحلية (Phi-3) مع Gemini Pro/Ultra عبر Vertex AI، وبناء وكلاء معرفيين بمكونات إضافية لـ Semantic Kernel، وتصميم معماريات تكيفية.

.NET Aspire: بناء تطبيقات Cloud-Native بلا صداع

جلسة تطبيقية لبناء خدمات مصغرة cloud-first تولد قابلة للتوسع ومرنة وقابلة للمراقبة. استكشاف كيف يلغي .NET Aspire 70% من النمطية السحابية.

.NET Aspire: Cloud-Native بلا فوضى

أمثلة حقيقية لتصميم تطبيقات ولدت قابلة للتوسع — مع المراقبة والمرونة التلقائية مدمجة من أول commit.

2024

الذكاء الاصطناعي يلتقي SQL: بناء محل بيتزا ذكي مع .NET وSemantic Kernel

تفاعلات الذكاء الاصطناعي باللغة الطبيعية التي تفهم كودك وبياناتك — بناء محل بيتزا ذكي مدعوم بـ .NET وSemantic Kernel.

.NET Aspire: تطبيقات Cloud-Native بلا تعقيدات

بناء خدمات مصغرة cloud-first بلا صداع — جلسة عملية مدفوعة بالعروض التوضيحية تُظهر كيف يبسّط .NET Aspire التطوير السحابي الأصيل.

Power Platform: الرحلة من Low-code إلى تقنيات Pro-code

الانتقال من Power Apps المنخفض الكود إلى مكونات pro-code المتقدمة باستخدام TypeScript، كل ذلك داخل نفس المنصة.

الأتمتة الذكية: حوّل تطبيقاتك المؤسسية بذكاء اصطناعي متكامل

رفع تطبيقات .NET إلى المستوى التالي — الجمع بين المنطق التقليدي والتفكير المبني على الذكاء الاصطناعي باستخدام Semantic Kernel و.NET Aspire.

من Low-Code إلى Pro-Code: مناهج لتطوير الذكاء الاصطناعي في الحلول المؤسسية

استكشاف مناهج مختلفة للحلول المؤسسية — من Power Platform مع الذكاء الاصطناعي إلى التطوير التقليدي مع Semantic Kernel.

التحكم في مصاريف السفر مع Azure

استخدام Azure AI Vision وDocument Intelligence وOpenAI مع Semantic Kernel لأتمتة إدارة مصاريف السفر.

الشارات والتكريم

🏆 Sessionize Most Active Speaker 2025
🏆 Sessionize Most Active Speaker 2024
🏆 Sessionize Most Active Speaker 2023
🏅 مايكروسوفت MVP في تقنيات المطورين

عرض جميع الجلسات على Sessionize →

عن المؤلف

Mon, 01 Jan 0001 00:00:00 +0000

عن المؤلف

أنا إيميليانو مونتيسديوكا (Emiliano Montesdeoca)، مطور برمجيات من أصول أوروغوانية-إسبانية، مايكروسوفت MVP في تقنيات المطورين، وأب فخور مقيم في تينيريفي، جزر الكناري.

أحب مواجهة التحديات التقنية المعقدة وبناء حلول سحابية قابلة للتوسع باستخدام تقنيات مايكروسوفت. تتمحور أدواتي اليومية حول .NET وAzure والذكاء الاصطناعي مع Semantic Kernel والمعماريات الحديثة مثل .NET Aspire.

ماذا أفعل

بصفتي قائد فريق حلول السحابة في Intelequia Technologies، أقود تصميم وتسليم التطبيقات السحابية الأصيلة — مزجاً بين الرؤية الاستراتيجية والتنفيذ العملي. أزدهر عند تقاطع المعمارية والكود، لضمان تقديم فريقنا لحلول أنيقة وجاهزة للإنتاج.

المجتمع

أنا متحدث دولي متكرر، وقد تم الاعتراف بي كـ أكثر المتحدثين نشاطاً في Sessionize في 2023 و2024 و2025. أشارك رؤى عملية من العالم الحقيقي من خلال محاضرات في مؤتمرات حول العالم وعبر مدوناتي.

أنا أيضاً مؤسس The .NET Blog — مورد لمجتمع .NET — وأكتب بانتظام في هذه المدونة عن الأشياء التي أتعلمها وأبنيها.

الإرشاد وبناء المجتمع جزء أساسي من هويتي. تقديم شيء للنظام البيئي الذي شكّل مسيرتي المهنية أمر أتعامل معه بجدية.

لنتواصل

أنا دائماً منفتح على التحدث في الفعاليات، والتعاون في المشاريع، أو الحديث عن معمارية السحابة والذكاء الاصطناعي. لا تتردد في التواصل!

البريد الإلكتروني: emimontesdeoca@outlook.es
GitHub: @emimontesdeoca
X / Twitter: @emimontesdeocaa
LinkedIn: emimontesdeoca
Instagram: @emimontesdeoca
Sessionize: emimontesdeoca

Emiliano Montesdeoca

Blazor من الصفر: الفصل 3 — مكوّنات قابلة للتوسّع

ما هو مكوّن Blazor فعليًا؟

الخطوة 1: ابدأ بمكوّن صغير ومحدد

الخطوة 2: اجعل السلوك صريحًا بالمعاملات

الخطوة 3: استخدم RenderFragment للتركيب

الخطوة 4: فضّل التركيب على الصفحات العملاقة

الخطوة 5: وازن بين الـ markup والمنطق

الخطوة 6: بنية مجلدات عملية

أخطاء شائعة في بدايات مشاريع Blazor

الفصل القادم

Blazor من الصفر: الفصل 2 — أول تطبيق Blazor لك

الخطوة 1: إنشاء المشروع

الخطوة 2: التشغيل محلياً

الخطوة 3: فهم هيكل المشروع

الخطوة 4: نفّذ أول تعديل

الخطوة 5: اقرأ Program.cs مرة واحدة

مشاكل شائعة

القادم

Blazor من الصفر: الفصل الأول — ما هو Blazor؟

نبذة تاريخية مختصرة

ما هو Blazor فعلاً

نماذج التصيير

SSR الثابت

الخادم التفاعلي

WebAssembly التفاعلي

وضع Auto

مزج الأوضاع في التطبيق الواحد

كيف يقارن Blazor بأطر عمل JavaScript

ما تحتاجه للمتابعة

الفصل القادم

Blazor من الصفر: سلسلة جديدة

لمن هذه السلسلة

ما سنتناوله

لماذا سلسلة، ولماذا الآن

كيف تتابع السلسلة

أنواع اتحادات C#: النقابات التمييزية قادمة أخيرًا

ما هي النقابات التي تعاني من التمييز؟

كيف نحاكي النقابات اليوم

السجلات المجردة بالميراث

التعداد اليدوي + نمط البيانات

اقتراح C#: الكلمة الرئيسية union

الأعضاء ذوو القيمة فقط

النقابات العامة

النقابات مع الأساليب

مطابقة الأنماط المتداخلة

شروط الحراسة

أمثلة عملية

نمط النتيجة: استبدال الاستثناءات للأخطاء المتوقعة

نمذجة النطاق: أنواع الدفع

آلات الدولة

كيفية تجربتها

المقارنة مع المقاربات الموجودة

ماذا يعني هذا بالنسبة للنظام البيئي .NET

الخلاصة

بناء نظام RAG في C# مع Semantic Kernel

مقدمة

كيف يعمل RAG

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

إعداد النواة

تحديد نموذج البيانات

تقطيع المستندات

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

البحث عن القطع ذات الصلة

توليد الإجابات مع السياق

استخدامه

الانتقال إلى الإنتاج

بناء سير عمل الوكيل باستخدام Microsoft Agent Framework

مقدمة

ما هي مسارات عمل الوكيل؟

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

بناء سير عمل متسلسل

تعريف الوكلاء

التنفيذ بالتسلسل

التنفيذ الموازي

التفرع المشروط

إضافة المكونات الإضافية إلى وكلاء سير العمل

معالجة الأخطاء في سير العمل

أفضل الممارسات

الخلاصة

الخطوة 3: استخدم `RenderFragment` للتركيب

اقتراح C#: الكلمة الرئيسية `union`