نمایشگر

Viewer (namespace Doconut) نقطهٔ ورودی عمومی برای باز کردن اسناد از صفحات Razor، کنترلرهای MVC، کامپوننت‌های Blazor یا APIهای حداقل است. این کلاس sealed است، به‌عنوان سرویس transient توسط AddDoconut() ثبت می‌شود و از طریق تزریق سازنده حل می‌شود — هرگز به‌صورت مستقیم آن را ساخت نکنید.

Viewer هیچ وضعیت درخواست‑به‑درخواست نگه نمی‌دارد و عمداً does not پیاده‌سازی IDisposable را انجام می‌دهد: جلسات سند به‌صورت مستقل در کش جلسه زندگی می‌کنند، بنابراین تخلیه سرویس هرگز نمی‌تواند سند باز را از بین ببرد (به Core Concepts → How the Viewer Works مراجعه کنید).

OpenDocumentAsync

یک سند را باز می‌کند و توکن جلسه‌ای را برمی‌گرداند که ویجت مشتری برای تمام درخواست‌های بعدی از آن استفاده می‌کند.

// Simple open
string token = await viewer.OpenDocumentAsync(path);

// With per-format config and options
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// From an upload
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

استثناهای قابل مدیریت:

• LicenseException — یک لایسنس پیدا‌شده رد می‌شود (پیام دلیل رد را حمل می‌کند)، یا فرمت به قابلیت افزونه‌ای نیاز دارد که دیگر اعطا نشده است. انقضای تقویم بدون پیام رد، به رندرینگ واترمارکی تبدیل می‌شود به‌جای پرتاب استثنا.
• FormatNotSupportedException — Document format '<extension>' is not supported.
• InvalidDataException — محتوای فایل خراب است یا با پسوند آن مطابقت ندارد.

CloseDocument

void CloseDocument(string token)

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

GetPageCount

int GetPageCount(string token)

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

DocOptions

گزینه‌های مستقل از فرمت برای هر باز (namespace Doconut):

کلاس همچنین ویژگی‌های تخصصی را ارائه می‌دهد که عمداً خارج از جریان مشاهده تک‑میزبان معمولی هستند:

Custom watermark

DocOptions.Watermark از شش فیلد جدا شده با تیلده استفاده می‌کند. یک ^ پیش‌اختیاری درخواست چیدمان همه‌گوشه‌ای را می‌کند:

^Text~Color~FontSize~FontName~Opacity~Angle

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });

پارسر دقیقاً شش فیلد پس از ^ اختیاری انتظار دارد. تعریف نامعتبر با fallback قابل مشاهده Invalid Watermark SDK جایگزین می‌شود به‌جای این‌که به‌صورت ساکت ناپدید شود.

License decision

همین تصمیم برای تصاویر صفحه سرو شده و خروجی‌های حاشیه‌نویسی اعمال می‌شود. خروجی GIF متحرک فریم به فریم مهر می‌شود. بنابراین واترمارک سفارشی یک ویژگی برنامه‌دار تحت لایسنس است، نه روشی برای جایگزینی یا حذف واترمارک ارزیابی.

Annotations API

بارگذاری و خروجی حاشیه‌نویسی سمت سرور. راهنمای کامل در Guides → Annotations موجود است؛ سطح کارکرد به این صورت است:

DICOM metadata

Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

این متد برای هم‌سویی API وجود دارد، اما نمایشگر DICOM .NET 6 نمی‌تواند برچسب‌های فنی را فراهم کند. برای جلسات DICOM و غیر‑DICOM null برمی‌گرداند؛ در یک جلسه DICOM همچنین یک هشدار یک‌باریه می‌نویسد که محدودیت پلتفرم را توضیح می‌دهد. رندرینگ صفحه، فریم و انیمیشن همچنان پشتیبانی می‌شود.

Resource helpers — ReferenceCss / ReferenceScripts

برچسب‌های <link>/<script> برای منابع جاسازی‌شده‌ای که توسط UseDoconutResources() سرو می‌شوند، در ترتیب وابستگی صحیح تولید می‌کند. بسته‌ها برای ویژگی‌های تحت لایسنس مانند جستجو و حاشیه‌نویسی فقط زمانی که لایسنس آن‌ها را فعال کند تولید می‌شوند، به‌طوری که UI مشتری با رفتار سرور سازگار بماند.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

پرچم‌های CssConfig: IncludeBootstrapCss، IncludeViewerCss، IncludeSearchCss (search‑gated)، IncludeAnnotationCss (annotation‑gated).

پرچم‌های ScriptConfig: IncludeJQuery (required by all others)، IncludeBootstrap، IncludeViewerScripts (core: docViewer.js + splitter + links)، IncludeSearchScripts و IncludeSearchBar (search‑gated)، IncludeAnnotationScripts و IncludeAnnotationBar (annotation‑gated).

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))