نمایشگر
کلاس اصلی نمایشگر سند
Viewer (namespace Doconut) نقطهٔ ورودی عمومی برای باز کردن اسناد از کنترلرهای MVC، صفحات Web Forms و هندلرها است. این یک سرویس موقتی است که توسط DoconutHost.Initialize ترکیب شده؛ آن را در جایی که استفاده میکنید حل کنید:
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();new Viewer() همچنین پس از اجرای DoconutHost.Initialize کار میکند — سرویسهای یکسان را حل میکند — که باعث میشود کد منتقلشده از بستهٔ کلاسیک همچنان کامپایل شود. قبل از Initialize، استثنای InvalidOperationException را پرتاب میکند.
Viewer هیچ وضعیت سندی به ازای هر درخواست نگه نمیدارد و عمداً نه پیادهسازی IDisposable را انجام میدهد: نشستهای سند بهصورت مستقل از آن زندگی میکنند، بنابراین حذف یک 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) | سند یک فایل روی دیسک نیست (یک بارگذاری، یک پایگاه داده، یک بلاب). fileInfo باید پسوند صحیح را داشته باشد — آن فرمت را انتخاب میکند |
// باز کردن ساده
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— هیچ نمایشگری پسوند فایل را پشتیبانی نمیکند.InvalidDataException— محتوا خراب است یا با پسوند آن مطابقت ندارد.
OpenDocument (synchronous)
برای کد‑پشت Web Forms و سایر کدهایی که از صفحات ناهمزمان استفاده نمیکنند:
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 از افزونه مبدل مراجعه کنید.
CloseDocument
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) | ورقهای کاری رندر شده یک صفحهگسترده، به ترتیب کتاب کار؛ برای سایر اسناد خالی است |
هر یک InvalidOperationException (Document session not found. Please re-open document.) را در صورت ناشناخته یا منقضی بودن توکن، و ArgumentException را برای توکن خالی پرتاب میکند.
گزینههای سند
گزینههای مستقل از قالب برای هر باز شدن (فضای نام 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~Color~FontSize~FontName~Opacity~Anglestring 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 جایگزین میشود بهجای ناپدید شدن بیصدا.
تصمیمگیری لایسنس
| وضعیت لایسنس | مقدار سفارشی ارائهشده | نتیجهٔ رندر شده |
|---|---|---|
| لایسنس مشاهدهگر پرداختشدهٔ معتبر | خیر | صفحهٔ تمیز |
| لایسنس مشاهدهگر پرداختشدهٔ معتبر | بله | علامت آب سفارشی |
| لایسنس موقت/دموی فعال | خیر | صفحهٔ تمیز |
| لایسنس موقت/دموی فعال | بله | علامت آب سفارشی |
| لایسنس گمشده، ردشده، منقضیشده، نسخهنادرست یا دامنهنامعتبر | هرکدام | علامت آب ارزیابی؛ مقدار سفارشی جایگزین آن نمیشود |
همین تصمیم برای صفحات سروشده و خروجیهای حاشیهنویسی اعمال میشود. یک علامت آب سفارشی ویژگی یک برنامهٔ دارای لایسنس است، نه روشی برای جایگزینی علامت آب ارزیابی.
API حاشیهنویسی
بارگذاری و صادرات حاشیهنویسیها در سمت سرور. راهنمای گامبهگام در حاشیهنویسیها موجود است.
| عضو | هدف |
|---|---|
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(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | یک PNG برای هر صفحه، حاشیهنویسیهای تعبیهشده، نوشته شده به directoryPath (در صورت عدم وجود ایجاد میشود)؛ تعداد تصاویر نوشتهشده را برمیگرداند |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | ZIP حاوی PNGهای صفحه به صفحه با حاشیهنویسیهای تعبیهشده |
متادیتای DICOM
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)در این بسته همیشه null را برمیگرداند، و درخواست متادیتای ویجت پاسخ میدهد 501 Not Implemented: خواندن برچسبهای DICOM در .NET Framework در دسترس نیست. رندرینگ DICOM — صفحات، فریمها و انیمیشن — کار میکند. ببینید افزونه DICOM.
کمککنندههای منبع — ReferenceCss / ReferenceScripts
برچسبهای <link> و <script> را برای منابعی که ماژول منبع تحت DoconutOptions.ResourcesPath سرویس میدهد، به ترتیب وابستگی تولید کنید. فایلهای ویژگیهای وابسته به لایسنس (جستجو، حاشیهنویسی) فقط زمانی که لایسنس به آنها اجازه میدهد تولید میشوند.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; } // وضعیت license، برای محافظت از کد init ribbon
bool IsAnnotationEnabled { get; }پرچمهای CssConfig: IncludeBootstrapCss، IncludeViewerCss، IncludeSearchCss (محدود به جستجو)، IncludeAnnotationCss (محدود به حاشیهنویسی).
پرچمهای ScriptConfig: IncludeJQuery (نیازمند توسط همهٔ دیگران)، IncludeBootstrap، IncludeViewerScripts (اسکریپتهای اصلی نمایشگر)، IncludeSearchScripts و IncludeSearchBar (محدود به جستجو)، IncludeAnnotationScripts و IncludeAnnotationBar (محدود به حاشیهنویسی)، EmitFeatureFlags (پیشفرض true: همچنین یک اسکریپت inline window.Doconut.features = { search, annotation, editor } مینویسد؛ آن را به false تنظیم کنید تحت یک Content‑Security‑Policy که اسکریپتهای inline را مسدود میکند).
هر دو HTML برمیگردانند: آنها را با @Html.Raw(...) در MVC 5 بنویسید (در کنترلر تولید میشوند — نماها هیچ @inject ندارند) یا با <%= %> در Web Forms. شروع سریع هر دو را نشان میدهد.
RenderViewer
string RenderViewer(string elementId, string token, ViewerConfig? config = null)یک بلوک <script> برمیگرداند که ویجت را بر روی عنصری با شناسهٔ elementId مقداردهی اولیه میکند و سند را نشان میدهد: docViewer({...}) ساختهشده از ViewerConfig (پیشفرض: BasePath: '/'، ResPath: 'doconut-res/images')، سپس .View(token). آن را پس از اسکریپتهای نمایشگر بنویسید. اسکریپت تولید شده هیچ ارجاعی به شیء نمایشگر نگه نمیدارد، بنابراین صفحهای که نوار ابزار خود را دارد باید بهصورت دستی ویجت را مقداردهی کند. ببینید پیکربندینمایشگر.
مزرعه وب
string? AccessToken بلیت امضاشدهای را نگه میدارد که توسط آخرین باز کردن هنگام فعال بودن حالت توزیعشده صادر شده و UnsafeMode برابر با false است؛ در یک سرور واحد null است. آن را با توکن به ویجت بفرستید: objViewer.View(token, accessToken).
آیا این صفحه مفید بود؟