Viewer بدون حالت — به‌صورت‌طراحی

Viewer نه هیچ داده‌ای از سند مربوط به هر درخواست را نگه نمی‌دارد. این یک کلاس sealed است، هرگز IDisposable را پیاده‌سازی نمی‌کند، و هر سندی که باز می‌کنید در یک جلسه جداگانه که کش چارچوب مدیریت می‌کند، زندگی می‌کند. به همین دلیل می‌توانید یک نمونهٔ واحد از Viewer را در هر جایی از برنامهٔ ASP.NET Core خود تزریق کنید و به‌صورت ایمن از آن در درخواست‌های همزمان فراخوانی کنید.

---

پیامدهای سرویس بدون حالت

• بدون منابع پنهان – خود سرویس هرگز بافرهای بزرگ که نیاز به پاک‌سازی صریح داشته باشند، تخصیص نمی‌دهد.
• به‌صورت پیش‌فرض ایمن برای رشته‌ها – چون هیچ حالت خاص درخواست‌محوری ذخیره نمی‌شود، همان نمونهٔ Viewer می‌تواند توسط چندین رشته بدون قفل‌گذاری استفاده شود.
• استقرارهای مقیاس‌پذیر – مقیاس‌گذاری افقی به‌صورت پیش‌فرض کار می‌کند؛ نیازی به جلسات چسبان یا وابستگی سرور ندارید، فقط توکن جلسه‌ای که کلاینت نگه می‌دارد.

تمام اطلاعات خاص سند (صفحات، حاشیه‌نویسی‌ها، فهرست جستجو) در یک جلسه که توسط OpenDocumentAsync ایجاد می‌شود، نگه‌داری می‌شود. جلسه در IMemoryCache (یا هر IDistributedCache که پیکربندی می‌کنید) ذخیره می‌شود و به‌صورت خودکار پس از دوره‌ای عدم فعالیت (به‌صورت پیش‌فرض ۶۰ دقیقه) منقضی می‌شود. وقتی کارتان تمام شد می‌توانید با فراخوانی CloseDocument ورودی کش را زودتر آزاد کنید.

---

ثبت Viewer بدون حالت

به‌دلیل اینکه Viewer هیچ حالت قابل تغییر ندارد، یک بار در زمان راه‌اندازی آن را ثبت کنید:

builder.Services.AddDoconut();               // Viewer را ثبت می‌کند و میدل‌ویرهای مورد نیاز
builder.Services.AddSession();               // برای امنیت توکن مورد نیاز
builder.Services.AddDistributedMemoryCache(); // کش ساده برای دموی

فراخوانی AddDoconut همچنین میانی‌افزارهایی را که منابع استاتیک viewer را سرو می‌کند، وصل می‌کند. پس از آماده شدن سرویس‌ها می‌توانید Viewer را در هر امضای نقطهٔ انتهایی درخواست کنید.

---

نقطه انتهایی باز‑سند حداقل (مثال net‑8)

کد زیر دقیقاً همان قطعه‌ای است که در مستندات رسمی آمده و به‌صورت پیش‌فرض در یک پروژهٔ .NET 8 Minimal‑API کار می‌کند:

app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync($"files/{fileName}");
    return Results.Content(token, "text/plain");
});

عملکرد کد

1. پذیرش نام فایل – کلاینت به سرور می‌گوید کدام فایل تحت wwwroot/files باز شود.
2. فراخوانی OpenDocumentAsync – Viewer بدون حالت یک جلسه جدید ایجاد می‌کند، آن را در کش ذخیره می‌کند و یک توکن نامشخص برمی‌گرداند.
3. بازگرداندن توکن به‌صورت متن ساده – کلاینت فقط توکن را دریافت می‌کند؛ سرور هرگز بایت‌های سند را در این پاسخ ارسال نمی‌کند.

به‌دلیل اینکه Viewer هیچ دادهٔ سندی نگه نمی‌دارد، نقطهٔ انتهایی نیازی به بلوک‌های using، فراخوانی‌های Dispose یا کارخانه‌های مربوط به هر درخواست ندارد. توکن تنها اعتبارسندی است که کلاینت هرگز به ویجت viewer (objViewer.View(token) در فرانت‌اند) باز می‌گرداند.

---

استفاده از توکن در سمت کلاینت

پس از بازگرداندن توکن، ویجت فرانت‌اند objViewer.View(token) را فراخوانی می‌کند. سپس ویجت همان توکن را با هر درخواست بعدی برای تصاویر صفحه، جستجو یا عملیات حاشیه‌نویسی همراه می‌فرستد. سرور توکن را نسبت به جلسه‌ای که ابتدا سند را باز کرده است، اعتبارسنجی می‌کند. اگر توکن از یک جلسه مرورگر متفاوت ارائه شود، viewer خطای مجوزدهی برمی‌گرداند که رفتار امنیتی موردنظر است.

---

بستن جلسه زودتر (اختیاری)

اگر جریان کاری شما می‌داند که سند دیگر دسترسی نخواهد داشت، می‌توانید با فراخوانی CloseDocument بر روی Viewer ورودی کش را آزاد کنید. این کار جلسه را از کش حذف می‌کند و از نگه داشتن آن توسط تایمر انقضای لغزشی جلوگیری می‌نماید.

---

مرور کلی جریان بدون حالت

مرحله	چه اتفاقی می‌افتد	کجا وضعیت ذخیره می‌شود
تزریق Viewer	یک نمونهٔ واحد از Viewer در زمان راه‌اندازی ایجاد می‌شود.	در کانتینر DI (singleton).
OpenDocumentAsync	مجوز بررسی شد → جلسه ایجاد شد → توکن برگردانده شد.	جلسه در IMemoryCache (یا کش توزیع‌شده) ذخیره می‌شود.
کلاینت رندر می‌کند	ویجت توکن را با هر درخواست می‌فرستد.	توکن تنها دادهٔ مربوط به سند است که کلاینت نگه می‌دارد.
انقضای جلسه / CloseDocument	ورودی کش پس از زمان‌سنجی یا بستن صریح حذف می‌شود.	هیچ منبع باقی‌مانده‌ای در سرویس Viewer وجود ندارد.

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

---

استقرار Viewer بدون حالت در برنامهٔ شما

1. AddDoconut، AddSession و یک ارائه‌دهندهٔ کش را به Program.cs اضافه کنید.
2. قطعه کد نقطهٔ انتهایی باز را در پیکربندی Minimal‑API خود بچسبانید.
3. توکن بازگردانده شده را به objViewer.View(token) در فرانت‌اند پاس دهید.

اکنون یک API باز‑سند کاملاً بدون حالت و آماده برای تولید دارید که از طراحی Viewer داکونات بهره می‌برد.