شروع سریع

رندر اولین سند خود در MVC 5 یا Web Forms

این راهنما یک برنامه ASP.NET بر روی .NET Framework 4.7.2 را از یک بسته نصب‌شده به سندی که در مرورگر رندر می‌شود می‌برد: Global.asax، یک نقطه انتهایی باز، دارایی‌های نمایشگر، ویجت، و توکنی که آن‌ها را به هم متصل می‌کند. فرض می‌کند ثبت‌نام‌های Web.config از نصب در جای خود هستند — بدون هندلر DocImage.axd و ماژول منبع، هیچ‌یک از موارد زیر نمی‌تواند به سرور دسترسی پیدا کند.

ترکیب Doconut در Global.asax

یک Application_Start کامل برای برنامه MVC 5:

csharp
// Global.asax.cs - یک بار در هر فرآیند کارگر ترکیب می‌شود، در زمان خاموش شدن آزاد می‌شود.
protected void Application_Start()
{
    Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.UnsafeMode  = false; // یک صفحه فقط به جلسه‌ای که سند را باز کرده است سرو می‌شود
    });

    // فقط MVC: دو نقطه انتهایی Doconut را از مسیریابی خارج نگه دارید.
    RouteTable.Routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
    RouteTable.Routes.IgnoreRoute("doconut-res/{*pathInfo}");
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}
  • Encoding.RegisterProvider صفحات کد قدیمی که برخی فرمت‌های سند استفاده می‌کنند را برای فرآیند در دسترس می‌کند. یک بار صدا بزنید، قبل از اینکه اولین سند باز شود.
  • UnsafeMode = false مقدار پیش‌فرض است، به‌گونه‌ای نوشته شده که هیچ‌کس به‌صورت تصادفی آن را تغییر ندهد: DocImage.axd فقط صفحه‌ای را به نشست ASP.NET که سند را باز کرده سرو می‌کند.
  • دو فراخوانی IgnoreRoute مسیردهی MVC را از DocImage.axd و /doconut-res/* دور نگه می‌دارند، که توسط هندلر و ماژول سرو می‌شوند. یک برنامه Web Forms مسیرهای MVC ندارد و به هیچ‌یک از این خطوط نیاز ندارد.
  • DoconutHost.Shutdown کار پس‌زمینه Doconut را متوقف می‌کند و سرویس‌های آن را هنگام بازیابی استخر برنامه آزاد می‌کند. حتی اگر Initialize هرگز اجرا نشده باشد، صدا زدن آن ایمن است.

باز کردن یک سند

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

در MVC 5، یک اکشن کنترلر سرویس Viewer را از DoconutHost.Services حل می‌کند — MVC 5 برای آن تزریق سازنده ندارد:

csharp
// POST /Document/Open
[HttpPost]
public async Task<ActionResult> Open()
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

    // توکن نامشخص است - آن را به نمایشگر بدهید، هرگز لاگ نکنید یا ذخیره نکنید.
    string token = await viewer.OpenDocumentAsync(Server.MapPath("~/files/Sample.pdf"));
    return Json(new { token });
}

سند باید درون درخواستی که وضعیت جلسه دارد باز شود، زیرا باز کردن آن است که به نشست فعلی ASP.NET دسترسی به صفحاتش را می‌دهد. کنترلرهای MVC و صفحات Web Forms به‌صورت پیش‌فرض وضعیت جلسه دارند. یک IHttpHandler سفارشی این ویژگی را ندارد، مگر اینکه System.Web.SessionState.IRequiresSessionState را پیاده‌سازی کند. اگر سندی را از یک هندلر بدون آن باز کنید، نمایشگر پیام «You Are Not Authorized To View This Page.» را در هر صفحه نشان می‌دهد.

در Web Forms، خود صفحه می‌تواند سند را در کد‑پشت خود باز کند. OpenDocument فرم همزمان OpenDocumentAsync است، که برای کد‑پشتی که از صفحات ناهمزمان استفاده نمی‌کند، منظور شده است:

csharp
// Default.aspx.cs
protected string Token;

protected void Page_Load(object sender, EventArgs e)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    Token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
}

توکن را مانند یک اعتبار حامل در نظر بگیرید: هرگز آن را لاگ نکنید یا ذخیره نکنید؛ فقط به ویجت تحویل دهید. وقتی جلسه سند منقضی شود، کار خود را متوقف می‌کند — برای دریافت توکن جدید، سند را دوباره باز کنید.

ارجاع به دارایی‌های نمایشگر

Viewer.ReferenceCss و Viewer.ReferenceScripts تگ‌های <link> و <script> را برای دارایی‌های جاسازی‌شده، به ترتیب وابستگی، که به /doconut-res/ اشاره می‌کنند، تولید می‌کنند. ویجت یک افزونه jQuery است، بنابراین jQuery اول می‌آید.

MVC 5. نماها @inject ندارند، بنابراین تگ‌ها را در کنترلر تولید کنید و آنها را به ViewBag منتقل کنید:

csharp
public ActionResult Index()
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
    {
        IncludeBootstrapCss = true,
        IncludeViewerCss    = true
    });
    ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
    {
        IncludeJQuery        = true,
        IncludeBootstrap     = true,
        IncludeViewerScripts = true
    });
    return View();
}
html
@Html.Raw(ViewBag.ViewerCss)
...
@Html.Raw(ViewBag.ViewerScripts)

این کار را در کنترلر نگه دارید. MVC 5 نماها را زمانی که برای اولین بار سرو می‌شوند، کامپایل می‌کند، و بدون بستهٔ کامپایلر اضافی، آن کامپایلر فقط C# 5 را می‌فهمد — هیچ ?.، هیچ $"..."، هیچ nameof نیست. نمایی که از آنها استفاده می‌کند به‌صورت تمیز در Visual Studio کامپایل می‌شود، سپس یک 500 خالی را در مرورگر برمی‌گرداند.

Web Forms. همان رشته‌ها را از کد‑پشت (code‑behind) در دسترس قرار دهید و آنها را با <%= %> بنویسید:

html
<head>
    <%= ViewerCss %>
</head>
<body>
    ...
    <%= ViewerScripts %>
</body>

IncludeViewerCss و IncludeViewerScripts هستهٔ اجباری هستند. برای افزودن نوارهای جستجو و حاشیه‌نویسی، همچنین IncludeSearchCss، IncludeAnnotationCss، IncludeSearchScripts، IncludeSearchBar، IncludeAnnotationScripts و IncludeAnnotationBar را تنظیم کنید. هر دو روش فایل‌های یک نوار را زمانی که مجوز آن قابلیت را نمی‌دهد، حذف می‌کنند؛ نمایشگر خود همچنان شروع می‌شود.

افزودن نمایشگر به یک صفحه

سطح رندر دو div تو در تو است:

html
<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

به div بیرونی یک ارتفاع واقعی بدهید — نمایشگر محفظهٔ خود را پر می‌کند و هنگام شروع آن را اندازه‌گیری می‌کند. نمایشگر نوار ابزار خود را رسم نمی‌کند: GotoPage، Next، Zoom، FitType و بقیه متدهایی هستند که صفحهٔ شما به دکمه‌های خود متصل می‌کند، در کنار نمایشگر قرار می‌گیرند:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <button type="button" onclick="objViewer.GotoPage(1)">First</button>
    <button type="button" onclick="objViewer.Next(false)">Previous</button>
    <button type="button" onclick="objViewer.Next(true)">Next</button>
    <button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
    <button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
    <button type="button" onclick="objViewer.FitType('width')">Fit width</button>
</nav>

مقداردهی اولیهٔ نمایشگر و نمایش سند

پس از اسکریپت‌های نمایشگر، ویجت را ایجاد کنید، سپس توکن را به آن بدهید:

javascript
var objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // '/' به معنی DocImage.axd در ریشه سایت است
    ResPath:    'doconut-res/images',  // بدون '/' پیش‌رو
    onViewerReady: function () {
        // صفحات قابل مشاهده‌اند؛ اینجا نشانگر بارگذاری را مخفی کنید
    },
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

fetch('/Document/Open', { method: 'POST' })
    .then(function (resp) { return resp.json(); })
    .then(function (data) { objViewer.View(data.token); });

در Web Forms، جایی که صفحه خود سند را باز می‌کند، سه خط آخر به objViewer.View('<%= Token %>'); تبدیل می‌شوند.

چهار جزئیات در اینجا بدون پیام خطا شکست می‌خورند:

  • BasePath: '/' آدرس DocImage.axd را در ریشهٔ سایت می‌دهد. برای برنامه‌ای در یک دایرکتوری مجازی، از نام آن بدون اسلش‌ها استفاده کنید (درخواست 'myapp' برای /myapp/DocImage.axd). یک اسلش پیشرو ('/myapp') باعث تولید //myapp/DocImage.axd می‌شود که مرورگر آن را به‌عنوان درخواست به میزبان دیگری می‌خواند.
  • ResPath: 'doconut-res/images' — آیکون‌ها یک پوشه زیر ریشهٔ منبع قرار دارند. با 'doconut-res'، هر آیکون 404 برمی‌گرداند: هیچ گلیف نوار ابزار و هیچ چرخ‌لودگی وجود ندارد، در حالی که خود سند هنوز رندر می‌شود. یک اسلش پیشرو همانند BasePath آن را خراب می‌کند.
  • Callbackها گزینه‌ها هستند. onViewerReady، onError و بقیه در شیء‌ای که به docViewer(...) پاس داده می‌شود، قرار می‌گیرند. یک تابع سراسری با نام نمایشگر، مانند ctlDoc_ViewerReady، هرگز فراخوانی نمی‌شود.
  • نمایشگر را نگه دارید، سپس View را جداگانه فراخوانی کنید. docViewer(...) شیء‌ای را با Zoom، Next و FitType برمی‌گرداند؛ View(...) چیز دیگری برمی‌گرداند. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) سند را رندر می‌کند، سپس در اولین کلیک نوار ابزار با objViewer.Zoom is not a function شکست می‌خورد.

نام گزینه‌ها ترکیبی از camelCase (showThumbs، autoLoad، pageZoom) و PascalCase (FitType، BasePath، ResPath) هستند. گزینه‌ای که غلط املایی دارد نادیده گرفته می‌شود و ویجت از مقدار پیش‌فرض خود استفاده می‌کند.

جایگزین یک‌خطی

برای صفحه‌ای که فقط نیاز به نمایش یک سند دارد و نوار ابزار خودتان را ندارد، Viewer.RenderViewer کل اسکریپت مقداردهی اولیه را می‌نویسد — docViewer(...) با BasePath: '/' و ResPath: 'doconut-res/images'، سپس .View(token). این فقط در این بسته وجود دارد:

csharp
// Default.aspx.cs
protected string ViewerInit;

protected void Page_Load(object sender, EventArgs e)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    string token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
    ViewerInit = viewer.RenderViewer("div_ctlDoc", token);
}
html
<div id="div_ctlDoc" style="height: 100vh"></div>
<%= ViewerScripts %>
<%= ViewerInit %>

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

بستن سند

زمانی که کاربر نمایشگر را ترک می‌کند یا جایگزینی باز می‌کند، objViewer.Close(true) را فراخوانی کنید: این ویجت را پاک می‌کند و درخواست بستن را به DocImage.axd ارسال می‌نماید. objViewer.Close() بدون آرگومان فقط ویجت را پاک می‌کند. در سرور، viewer.CloseDocument(token) جلسه سند را بلافاصله حذف می‌کند، منابع رندرینگ آن را آزاد می‌سازد و دسترسی جلسه به صفحات آن را می‌برد. انقضای لغزشی در نهایت همین کار را انجام می‌دهد، اما بستن صریح اسناد بزرگ حافظه را زودتر آزاد می‌کند.

اجرا کنید

یک PDF را در ~/files/Sample.pdf قرار دهید، سایت را در IIS Express (F5 در Visual Studio) راه‌اندازی کنید و صفحه‌ای که ویجت را میزبانی می‌کند باز کنید. صفحهٔ اول رندر می‌شود، با تصویرهای بندانگشتی در سمت چپ. اگر این‌طور نیست، به بخش عیب‌یابی مراجعه کنید.

آنچه بدون لایسنس دریافت می‌کنید

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

آیا این صفحه مفید بود؟