پیاده‌سازی مدیریت اسناد با Doconut

یک جریان کاری مدیریت سند در یک پورتال .NET معمولاً به سه مورد نیاز دارد:

1. راهی برای بارگذاری PDFها، فایل‌های Office، نقشه‌های CAD یا تصاویر بدون نوشتن یک نمایشگر از ابتدا.
2. یک توکن امن که سند بارگذاری‌شده را به جلسه مرورگر فعلی متصل می‌کند.
3. یک مرحله پاک‌سازی که بلافاصله پس از اتمام کار کاربر حافظه را آزاد می‌کند.

Doconut همه این سه را از طریق یک سرویس Viewer تک، یک جلسه سبک وزن IMemoryCache و فراخوانی‌های صریح CloseDocument فراهم می‌کند.

---

1. ثبت نمایشگر در کانتینر DI

در زمان راه‌اندازی برنامه، سرویس‌های Doconut را با فراخوانی روش ثبت Doconut که در مستندات رسمی توضیح داده شده است، به کانتینر DI اضافه کنید. این مرحله نمایشگر، مدیریت لایسنس و کش در‑حافظه‌ای که جلسات اسناد را نگه می‌دارد، ثبت می‌کند.

ثبت‌نام لایسنس را در زمان راه‌اندازی اعتبارسنجی می‌کند، بنابراین هر لایسنس گمشده یا نامعتبر بلافاصله خطا می‌دهد و شما مشکل را پیش از اولین درخواست که به سرور می‌رسد می‌دانید.

---

2. افزودن میدلور که تصاویر صفحه، تصویرهای کوچک و داده‌های حاشیه‌نویسی را سرو می‌کند

میان‌افزار Doconut را در خط لوله درخواست پیکربندی کنید تا هر درخواست حاوی رشتهٔ پرس‌وجوی ?token= توسط Doconut پردازش شود. این میدلور نشانگر امنیت پیش‌فرض (secure-{token}) را زمانی که UnsafeMode برابر false (پیش‌فرض) باشد اعمال می‌کند و تصاویر صفحه، تصویرهای کوچک و داده‌های حاشیه‌نویسی را سرو می‌کند.

قرار دادن میدلور در یک شاخهٔ اختصاصی بقیهٔ خط لوله شما را دست‌نخورده نگه می‌دارد و امکان مقیاس‌پذیری افقی بدون جلسات چسبنده را فراهم می‌کند.

---

3. باز کردن یک سند و دریافت توکن جلسهٔ مبهم

یک نقطهٔ انتهایی تک ایجاد کنید که مسیر فایل (یا یک جریان) را دریافت کرده و توکن را برگرداند. توکن تنها اعتبارنامه‌ای است که ویجت مشتری می‌بیند.

app.MapPost("/api/open", async (Viewer viewer) =>
{
    // توکن نامشخص است — آن را به widget تحویل دهید، هرگز log یا persist نکنید.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Contract.pdf");
    return Results.Ok(new { token });
});

چه اتفاقی داخل OpenDocumentAsync می‌افتد

1. دروازه لایسنس – یک لایسنس نامعتبر بلافاصله LicenseException را پرتاب می‌کند.
2. ایجاد جلسه – Doconut نمایشگر فرمت مناسب (PDF، Word، DWG، …) را انتخاب می‌کند و موتور را در IMemoryCache زیر یک توکن GUID ذخیره می‌نماید.
3. ثبت امنیت – با UnsafeMode = false توکن به جلسه ASP.NET فراخواننده از طریق یک نشانگر secure-{token} متصل می‌شود. فقط همان جلسه مرورگر می‌تواند صفحات را درخواست کند.
4. بازگرداندن توکن – مشتری توکن را دریافت می‌کند و برای هر درخواست بعدی از آن استفاده می‌کند (/DocImage.axd?token=…).

انقضای لغزشی پیش‌فرض ۶۰ دقیقه است (قابل تنظیم از طریق DocOptions.TimeOut). هر درخواست صفحه ساعت را بازنشانی می‌کند، بنابراین جلسات بیکار به‌صورت خودکار ناپدید می‌شوند.

---

4. رندر کردن سند در سمت مشتری

از مرورگر، نقطهٔ انتهایی را فراخوانی می‌کنید، توکن را می‌گیرید و به ویجت Doconut می‌سپارید:

fetch('/api/open', { method: 'POST' })
    .then(r => r.json())
    .then(d => {
        const token = d.token;
        objViewer.View(token);   // JavaScript widget تأمین‌شده توسط Doconut
    });

ویجت به‌صورت داخلی درخواست‌های صفحه، تصویر کوچک، جستجو و حاشیه‌نویسی را صادر می‌کند که همگی شامل همان token هستند. چون توکن به جلسه سمت سرور متصل است، کاربر مخرب نمی‌تواند سند کاربر دیگری را به‌دست آورد.

---

5. بستن سند به محض خروج کاربر از نمایشگر

برای PDFها یا فایل‌های CAD بزرگ باید موتور رندر را بلافاصله آزاد کنید. از یک نقطهٔ انتهایی سمت سرور یا از رویداد «unload» ویجت، CloseDocument را فراخوانی کنید.

// نقطهٔ انتهایی Server‑side
app.MapPost("/api/close", (Viewer viewer, string token) =>
{
    viewer.CloseDocument(token);
    return Results.Ok();
});

// تماس مستقیم از widget (اگر توکن را در backend در دسترس قرار دهید)
viewer.CloseDocument(token);

CloseDocument جلسه را از کش حذف می‌کند، موتور سند زیرین را از بین می‌برد، نشانگر secure-{token} را پاک می‌کند و دسترسی اعطا شده را لغو می‌نماید. انقضای لغزشی در نهایت همین کار را انجام می‌دهد، اما بستن صریح تضمین می‌کند که حافظه بلافاصله پس از اتمام کار کاربر بازیابی شود.

---

6. اختیاری: تبدیل سند در سرور

اگر جریان کاری شما نیاز به خروجی PDF از یک فایل Word بارگذاری‌شده دارد، افزونه Converter را در پیکربندی Doconut فعال کنید (مستندات را ببینید). پس از ثبت افزونه می‌توانید DocumentConverter را تزریق کنید و متد ConvertAsync آن را فراخوانی کنید. تبدیل در سرور اجرا می‌شود، بنابراین هرگز نیازی به نصب Office بر روی سرور وب ندارید.

---

7. ملاحظات مقیاس‌پذیری برای مدیریت اسناد سطح سازمانی

• فرانت‌اندهای بدون حالت – ویجت نمایشگر هرگز دادهٔ سند را نگه نمی‌دارد؛ تمام پردازش‌های سنگین بر روی سرور باقی می‌مانند.
• کش توزیع‌شده – کش پیش‌فرض در‑حافظه‌ای را با یک ارائه‌دهنده توزیع‌شده (Redis، NCache) جایگزین کنید اگر چندین گرهٔ وب‌فارم اجرا می‌کنید. نگاشت توکن‑به‑جلسه بدون تغییر کار می‌کند زیرا میدلور از IMemoryCache پیکربندی‌شده می‌خواند.
• کارهای پس‌زمینه – می‌توانید اسناد را به‌صورت پیش‌بارگذاری در یک کارگر پس‌زمینه باز کنید، توکن را کش کنید و بعداً به UI تحویل دهید. فقط به‌خاطر داشته باشید که هر توکن برای هر جلسه یک‌بار استفاده می‌شود؛ استفاده مجدد نیاز به فراخوانی تازهٔ OpenDocumentAsync دارد.

این الگوها به شما امکان می‌دهند یک پلتفرم مدیریت سند بسازید که از یک پورتال اینترانت تک‌سرور تا سرویس ابری چندمنطقه‌ای مقیاس‌پذیر باشد بدون اینکه منطق نمایشگر را بازنویسی کنید.

---

8. فهرست بررسی سریع برای پیاده‌سازی آماده برای تولید

مرحله	عمل
1	ثبت سرویس‌های Doconut در Program.cs (اعتبارسنجی لایسنس).
2	افزودن میدلور Doconut بر روی یک شاخهٔ اختصاصی.
3	نمایش یک نقطهٔ انتهایی /api/open که OpenDocumentAsync را فراخوانی می‌کند.
4	توکن بازگردانده‌شده را به objViewer.View(token) در سمت مشتری منتقل کنید.
5	زمانی که نمایشگر مخفی می‌شود یا صفحه unload می‌شود، CloseDocument(token) را فراخوانی کنید.
6	(اختیاری) اگر به تبدیل سمت سرور نیاز دارید، ConverterPlugin را فعال کنید.
7	(اختیاری) برای مقیاس‌پذیری افقی، IMemoryCache را با یک کش توزیع‌شده تعویض کنید.

فهرست را دنبال کنید، و یک جریان کامل، امن و با عملکرد بالا برای مدیریت سند خواهید داشت که بر پایهٔ نمایشگر بومی .NET Doconut ساخته شده است.