نمایشگر – مستندات Doconut

Viewer (namespace Doconut) نقطهٔ ورودی عمومی برای باز کردن اسناد از کنترلرهای MVC، صفحات Web Forms و هندلرها است. این یک سرویس موقتی است که توسط DoconutHost.Initialize ساخته شده؛ آن را در جایی که استفاده می‌کنید حل کنید:

csharp

var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

new Viewer() همچنین پس از اجرای DoconutHost.Initialize کار می‌کند — سرویس‌های یکسان را حل می‌کند — که باعث می‌شود کد منتقل‌شده از بستهٔ کلاسیک بدون مشکل کامپایل شود. قبل از Initialize، استثنای InvalidOperationException را پرتاب می‌کند.

Viewer هیچ وضعیت سندی به‌صورت درخواست‌محور نگه نمی‌دارد و عمداً پیاده‌سازی IDisposable نمی‌کند: جلسات سند به‌صورت مستقل از آن زندگی می‌کنند، بنابراین حذف یک Viewer هرگز نمی‌تواند سند باز را ببندد (به نحوه کار Viewer مراجعه کنید).

OpenDocumentAsync

یک سند را باز می‌کند و توکن جلسه‌ای را که ویجت برای هر درخواست بعدی استفاده می‌کند برمی‌گرداند. وقتی UnsafeMode برابر با false باشد (پیش‌فرض)، توکن به جلسه ASP.NET درخواست فعلی اختصاص می‌یابد — آن را از درخواستی که وضعیت جلسه دارد صدا بزنید (به جلسات و امنیت مراجعه کنید).

بارگذاری	زمان استفاده
`Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)`	باز کردن از دیسک با تشخیص خودکار فرمت و پیکربندی پیش‌فرض فرمت
`Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)`	شما به گزینه‌های رندر برای هر فرمت نیاز دارید (`PdfConfig`، `WordConfig`، …)
`Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)`	سند یک فایل روی دیسک نیست (یک بارگذاری، یک پایگاه داده، یک blob). `fileInfo` باید پسوند صحیح را داشته باشد — آن فرمت را انتخاب می‌کند

csharp

// باز کردن ساده
string token = await viewer.OpenDocumentAsync(path);

// با پیکربندی و گزینه‌های هر فرمت
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// از یک بارگذاری (HttpPostedFileBase in MVC; HttpPostedFile in Web Forms)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

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

LicenseException — یک لایسنس یافت شد اما رد شد (پیام دلیل را حمل می‌کند)، یا فرمت به قابلیت افزونه‌ای نیاز دارد که لایسنس آن را اعطا نکرده است.
FormatNotSupportedException — هیچ Viewer ای پسوند فایل را پشتیبانی نمی‌کند.
InvalidDataException — محتوا خراب است یا با پسوند آن مطابقت ندارد.

OpenDocument (همزمان)

برای کد‑پشت Web Forms و سایر کدهایی که از صفحات ناهمزمان استفاده نمی‌کنند:

text

string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

هر کدام توکن را برمی‌گردانند و همچنین آن را در viewer.Token ذخیره می‌کنند. fileName باید پسوند صحیح را داشته باشد. این wrapper ها برای فراخوانی از یک صفحه Web Forms ایمن هستند: مسیر باز کردن هرگز در زمینهٔ درخواست ASP.NET ادامه نمی‌یابد، بنابراین انتظار برای آن نمی‌تواند منجر به بن‌بست شود. همین امر برای تمام APIهای ناهمزمان Doconut صادق نیست — به بخش Web Forms از پلاگین مبدل مراجعه کنید.

بستن سند

text

void CloseDocument(string token)

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

پرس‌وجوهای جلسه

عضو	نتیجه
`int GetPageCount(string token)`	کل صفحات سند باز
`(int Width, int Height) GetPageDimensions(string token, int page = 1)`	اندازه پیش‌فرض صفحه رندر شده با زوم ۱۰۰٪ — فضای مختصات برای حاشیه‌نویسی‌های ساخته‌شده در کد
`IReadOnlyList<string> GetWorksheetNames(string token)`	ورق‌های کاری رندر شده یک صفحه‌گسترده، به ترتیب کتاب کار؛ برای سایر اسناد خالی است

هر یک در صورت ناشناخته یا منقضی بودن توکن استثنا می‌اندازد.

گزینه‌های سند

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

نوع	ویژگی	پیش‌فرض	توضیح
`string`	`Password`	`""`	رمز عبور برای اسناد محافظت‌شده (به‌صورت خودکار به پیکربندی قالب کپی می‌شود).
`string`	`Watermark`	`""`	متن علامت‌آب سفارشی که بر روی صفحات رندر شده کشیده می‌شود — به زیر مراجعه کنید.
`int`	`TimeOut`	`60`	انقضای لغزان جلسه، بر حسب دقیقه.
`string`	`BrowserId`	`""`	مزرعه‌های وب: مرورگری که بلیط امضا شده به آن متصل است. با `DoconutFarmBinding.EnsureBrowserId` تنظیم کنید (به جلسات و امنیت مراجعه کنید).
`string`	`UserId`	`""`	مزرعه‌های وب: کاربری که وارد شده است و بلیط به او متصل است، از `DoconutFarmBinding.ResolveUserId`.
`int`	`ImageResolution`	`0`	منسوخ. به‌جای آن `ImageResolution` را در پیکربندی قالب تنظیم کنید.
`bool`	`IsSecured`	`true`	رزرو شده؛ اعمال نمی‌شود. کنترل دسترسی `DoconutOptions.UnsafeMode` است.
`bool`	`IsWebFarm` / `string` `WebFarmPath`	`false` / `""`	برای کدی که از بسته کلاسیک مهاجرت کرده نگه داشته شده‌اند. آن‌ها حالت مزرعه را فعال نمی‌کنند — `AddDoconutDistributed` این کار را انجام می‌دهد.
`bool`	`EditMode`	`false`	برای ویرایشگر جداگانه توزیع‌شده رزرو شده؛ `false` را دست نخورده بگذارید.

علامت‌آب سفارشی

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

text

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

csharp

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

فیلد	مثال	معنی
Leading `^`	`^`	چیدمان تمام‌گوشه‌ای اختیاری. بدون آن، مکان‌گذاری معمولی استفاده می‌شود.
Text	`Confidential`	متنی که بر هر صفحه کشیده می‌شود. نباید خالی باشد.
Color	`Red`	یک رنگ نام‌گذاری‌شده.
FontSize	`24`	اندازهٔ قلم؛ ورودی عددی نامعتبر به پیش‌فرض بازمی‌گردد.
FontName	`Verdana`	خانوادهٔ قلم. باید بر روی سرور نصب باشد — Windows Server قلم‌های کمتری نسبت به دسکتاپ دارد.
Opacity	`80`	از ۰ تا ۲۵۵. باید قابل تجزیه باشد.
Angle	`-45`	چرخش به درجه؛ ورودی عددی نامعتبر به پیش‌فرض بازمی‌گردد.

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

تصمیم‌گیری مجوز

وضعیت مجوز	مقدار سفارشی ارائه‌شده	نتیجه رندر
مجوز مشاهده‌گر پرداختی معتبر	خیر	صفحهٔ پاک
مجوز مشاهده‌گر پرداختی معتبر	بله	علامت‌آب سفارشی
مجوز موقت/دموی فعال	خیر	صفحهٔ پاک
مجوز موقت/دموی فعال	بله	علامت‌آب سفارشی
مجوز گمشده، رد شده، منقضی‌شده، نسخه نادرست یا دامنه نامعتبر	هر کدام	علامت‌آب ارزیابی؛ مقدار سفارشی آن را جایگزین نمی‌کند

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

رابط برنامه‌نویسی حاشیه‌نویسی

بارگذاری و صادرات حاشیه‌نویسی در سمت سرور. راهنمای گام به گام در حاشیه‌نویسی‌ها موجود است.

عضو	هدف
`AnnotationManager GetAnnotationManager(string token)`	مدیر مرتبط با ابعاد صفحهٔ جلسهٔ باز
`AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)`	مدیر با ابعاد صفحهٔ صریح
`AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)`	مدیر مستقل از جلسه
`void LoadAnnotationData(string token, AnnotationManager manager)`	بارگذاری حاشیه‌نویسی‌های ساخته‌شده در C# به جلسه
`void LoadAnnotationData(string token, string annotationData)`	بارگذاری پاکت رمزگذاری‌شدهٔ بازگشت‌داده‌شده توسط `AnnotationManager.GetAnnotationData()`
`void LoadAnnotationXML(string token, XmlDocument annotationXml)`	بارگذاری حاشیه‌نویسی‌ها از XML
`XmlDocument GetAnnotationXML(string token)`	صادرات حاشیه‌نویسی‌های جلسه به‌صورت XML
`Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)`	PDF با حاشیه‌نویسی‌های تعبیه‌شده
`Task<int> ExportAnnotationsToPngAsync(…)`	فایل‌های PNG با حاشیه‌نویسی‌های تعبیه‌شده
`Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)`	ZIP از PNGهای صفحه به صفحه با حاشیه‌نویسی‌های تعبیه‌شده

متادیتای DICOM

text

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

در این بسته همیشه null برگردانده می‌شود و درخواست متادیتای ویجت پاسخ می‌دهد 501 Not Implemented: خواندن برچسب‌های DICOM در .NET Framework در دسترس نیست. رندرینگ DICOM — صفحات، فریم‌ها و انیمیشن — کار می‌کند. ببینید DICOM Plugin.

کمک‌کننده‌های منبع — ReferenceCss / ReferenceScripts

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

text

string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + نمایشگر + جستجو + حاشیه‌نویسی
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // وضعیت مجوز، برای محافظت از ribbon init code
bool IsAnnotationEnabled { get; }

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

پرچم‌های ScriptConfig: IncludeJQuery (ضروری برای همهٔ دیگران)، IncludeBootstrap، IncludeViewerScripts (اسکریپت‌های هستهٔ ویور)، IncludeSearchScripts و IncludeSearchBar (search-gated)، IncludeAnnotationScripts و IncludeAnnotationBar (annotation-gated).

هر دو HTML برمی‌گردانند: آن‌ها را با @Html.Raw(...) در MVC 5 بنویسید (در کنترلر تولید کنید — نماها هیچ @inject ندارند) یا با <%= %> در Web Forms. Quick Start هر دو را نشان می‌دهد.

RenderViewer

text

string RenderViewer(string elementId, string token, ViewerConfig? config = null)

یک بلوک <script> برمی‌گرداند که ویجت را بر روی عنصری با شناسه elementId مقداردهی اولیه می‌کند و سند را نمایش می‌دهد: docViewer({...}) ساخته‌شده از ViewerConfig (پیش‌فرض: BasePath: '/'، ResPath: 'doconut-res/images')، سپس .View(token). آن را پس از اسکریپت‌های ویور بنویسید. اسکریپت تولیدشده هیچ ارجاعی به شیء ویور نگه نمی‌دارد، بنابراین صفحه‌ای که نوار ابزار خود را دارد باید به‌صورت دستی ویجت را مقداردهی اولیه کند. ببینید ViewerConfig.

مزرعه وب

string? AccessToken بلیط امضاشده‌ای را که توسط آخرین باز کردن در حالت توزیع فعال صادر شده نگه می‌دارد و UnsafeMode برابر با false است؛ در یک سرور واحد null است. آن را با توکن به ویجت بفرستید: objViewer.View(token, access).