تسجيل وتمكين أداة تحويل Doconut المدمجة في .NET 8

أداة التحويل المدمجة هي واجهة مستخدم جاهزة من Doconut لرفع ملف، تشغيل عملية تحويل، وتنزيل النتيجة.
بشكل افتراضي، تُعيد نقاط النهاية الثلاثة ?convert= للأداة حالة 404؛ وتصبح نشطة فقط عندما تسجل ملحق Converter وتستدعي AddConverterWidget() على DoconutOptions.

فيما يلي تكوين بدء تشغيل كامل جاهز للنسخ واللصق يلبي المتطلبين.

---

1. المتطلبات المسبقة – الترخيص ودعم الجلسة

• الترخيص – يتطلب ملحق Converter ترخيصًا يمنح القدرة Converter. ضع الملف (مثال: Doconut.Viewer.lic) في مكان يمكن للتطبيق الوصول إليه ووجه DoconutOptions.LicensePath إليه.
• حالة الجلسة – نموذج أمان Doconut يخزن رموز جلسة المستند في جلسة ASP.NET Core. أضف ذاكرة تخزين موزعة وAddSession() قبل ربط الطبقة الوسيطة.

builder.Services.AddDistributedMemoryCache();   // مطلوب للجلسة
builder.Services.AddSession();                  // يُمكّن IDistributedCache‑backed session

---

2. تسجيل خدمات Doconut الأساسية

AddDoconut() هو نقطة الدخول الوحيدة التي تُحقن العارض، خدمة الترخيص، وسجل الملحقات.

builder.Services.AddDoconut(options =>
{
    // أخبر Doconut بمكان العثور على ملف الترخيص.
    options.LicensePath = "Doconut.Viewer.lic";

    // سجّل ملحق Converter – هذا أيضًا يتحقق من صلاحية الترخيص.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

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

---

3. تشغيل الأداة باستخدام AddConverterWidget

الأداة اختيارية. استدعاء AddConverterWidget() يسجل نقاط النهاية الثلاثة للتحويل (?convert=open، ?convert=run، ?convert=download) ويربط كمية صغيرة من إعدادات الجانب العميل (الحد الأقصى لحجم الرفع، المسارات الأساسية، إلخ).

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();

    // فعّل واجهة المستخدم القابلة للإدراج وضع حد التحميل من جانب العميل.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // فحص مسبق للعميل؛ الخادم يفرض حدّه الخاص
    });
});

فقط استدعاء AddConverterWidget يُنشئ نقاط النهاية؛ ملف JavaScript الثابت (doconutConverter.js) يُقدم دائمًا كمورد مدمج، لكنه سيفشل في الاتصال بالخادم إذا كانت نقاط النهاية مفقودة.

---

4. ربط الطبقة الوسيطة بالترتيب الصحيح

يجب أن تُنفّذ الطبقة الوسيطة التي تخدم الأصول الثابتة (UseDoconutResources) قبل طبقة عارض الطرفية (UseDoconut). كما يجب وضع طبقة جلسة العمل في وقت مبكر لأن Doconut يتحقق من الجلسة في كل طلب.

app.UseSession();           // يجب أن يسبق UseDoconut()
app.UseDoconutResources();  // يقدم ملفات JS و CSS والصور
app.UseDoconut();           // يتعامل مع ?convert= وطلبات صفحات المستند

مع وجود هذا خط الأنابيب، ينجح طلب إلى /doconut-res/doconutConverter.js، ويمكن للأداة استدعاء /doconut?convert=open، /doconut?convert=run، و/doconut?convert=download.

---

5. ما تفعله الأداة فعليًا

المرحلة	نقطة النهاية الخادم	الاستجابة النموذجية
فتح	?convert=open	تُعيد حمولة JSON تحتوي على token، عدد الصفحات، امتداد المصدر، وقائمة صيغ الهدف المسموح بها.
تشغيل	?convert=run	يبدأ التحويل ويُعيد downloadToken، عدد صفحات النتيجة، اسم ملف مقترح، وعلم يُشير إلى ما إذا كان الإخراج مائيًا.
تنزيل	?convert=download	يبث الملف المحول عندما يتبع العميل عنوان URL التنزيل المقدم.

من جانب العميل، تقوم الأداة بفحص حجم ما قبل الرفع مقابل widget.MaxUploadMb. إذا تجاوز الملف هذا الحد، تُلغي الأداة الرفع وتُطلق رد النداء onError مع phase = "open" ورسالة ودية. يفرض الخادم حدوده الخاصة وسيُجيب 413 Payload Too Large إذا تجاوز الطلب فحص العميل.

---

6. ربط أحداث الأداة (ليس هناك حاجة للجانب C#)

جميع ردود النداء (onReady، onSourceLoaded، onConverted، onError، إلخ) هي دوال JavaScript تُوفرها الصفحة التي تستضيف الأداة. بما أن السؤال يركز على جانب التسجيل، لا تحتاج إلى كتابة أي كود C# إضافي لمعالجة تلك الردود—فالأداة تستدعيها تلقائيًا بمجرد أن تكون نقاط النهاية نشطة.

---

7. الأخطاء الشائعة وكيفية تجنّبها

العَرَض	السبب المحتمل	الحل
404 على /doconut?convert=open	تم حذف AddConverterWidget().	أضف الاستدعاء كما هو موضح في القسم 3.
فشل التطبيق في البدء مع InvalidOperationException بخصوص القدرة المفقودة	ملف الترخيص لا يمنح Converter.	احصل على ترخيص يتضمن القدرة Converter.
خطأ 500 متعلق بالجلسة	تم وضع UseSession() بعد UseDoconut() أو عدم تسجيل ذاكرة التخزين المؤقت.	تأكد من تشغيل app.UseSession() قبل app.UseDoconut() وأن خدمة التخزين المؤقت مسجلة.

---

8. تشغيل التطبيق ورؤية الأداة تعمل

1. ابنِ وشغِّل مشروع ASP.NET Core.
2. افتح صفحة تحتوي على عنصر <div id="doconut-convert"></div> وتضمّن سكريبت محول Doconut (يتم تقديم السكريبت تلقائيًا من /doconut-res/doconutConverter.js).
3. اسحب ملفًا مدعومًا (PDF، DOCX، DWG، إلخ) إلى منطقة الإسقاط.
4. ستستدعي الأداة ?convert=open، ثم ?convert=run، وأخيرًا تعرض رابط Download يشير إلى ?convert=download.

إذا استجبت نقاط النهاية الثلاثة بـ JSON بدلاً من 404، فإن الأداة مسجلة بشكل صحيح وجاهزة للاستخدام في الإنتاج.

---

الخطوة التالية: أضف مقتطفات الشيفرة أعلاه إلى Program.cs (أو Startup.cs)، تحقق من وجود ملف الترخيص، وشغِّل التطبيق. ستكون أداة التحويل المدمجة متاحة دون أي تغييرات إضافية على الخادم.