ثبت و فعال‌سازی ویجت Drop‑in مبدل Doconut در .NET 8

ویجت Drop‑in، رابط کاربری آماده 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

---

2. ثبت سرویس‌های اصلی Doconut

AddDoconut() نقطهٔ ورودی تک است که viewer، سرویس مجوز و رجیستری پلاگین را تزریق می‌کند.

builder.Services.AddDoconut(options =>
{
    // به Doconut بگویید فایل لایسنس کجا قرار دارد.
    options.LicensePath = "Doconut.Viewer.lic";

    // پلاگین Converter را ثبت کنید – این همچنین قابلیت لایسنس را اعتبارسنجی می‌کند.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

اگر فایل مجوز شامل قابلیت Converter نباشد، فراخوانی فوق InvalidOperationException را پرتاب می‌کند و برنامه راه‌اندازی نمی‌شود. این رفتار fail‑fast از استقرار یک ساختار با مجوز نادرست جلوگیری می‌کند.

---

3. فعال‌سازی ویجت با AddConverterWidget

ویجت به‌صورت اختیاری است. فراخوانی AddConverterWidget() سه نقطهٔ پایان تبدیل (?convert=open، ?convert=run، ?convert=download) را ثبت می‌کند و مقدار کمی پیکربندی سمت کلاینت (حداکثر حجم بارگذاری، مسیرهای پایه و غیره) را وصل می‌سازد.

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

    // رابط کاربری drop‑in را فعال کنید و محدودیت بارگذاری سمت کلاینت را تنظیم کنید.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // پیش‌چک کلاینت؛ سرور محدودیت خود را اعمال می‌کند
    });
});

فقط فراخوانی AddConverterWidget نقاط پایان را ایجاد می‌کند؛ فایل ثابت JavaScript (doconutConverter.js) همیشه به‌عنوان منبع جاسازی‌شده سرو می‌شود، اما اگر نقاط پایان موجود نباشند، تماس با سرور شکست خواهد خورد.

---

4. اتصال میدل‌ویر به ترتیب صحیح

میان‌افزار سرو کردن دارایی‌های ثابت (UseDoconutResources) باید قبل از میدل‌ویر نهایی viewer (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	فایل تبدیل‌شده را به‌صورت جریان (stream) می‌فرستد هنگامی که کلاینت 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) خود اضافه کنید، اطمینان حاصل کنید که فایل مجوز موجود است و برنامه را اجرا کنید. ویجت مبدل Drop‑in بدون نیاز به تغییرات بیشتر سمت سرور فعال خواهد شد.