نصب

Doconut.NETFramework Doconut viewer را در یک برنامه کلاسیک ASP.NET بر روی .NET Framework 4.7.2 میزبانی می‌کند — IIS یا IIS Express، MVC 5 یا Web Forms. راه‌اندازی شامل سه بخش است: پکیج NuGet، دو ثبت در Web.config، و یک فراخوانی در Global.asax. این صفحه هر سه را پوشش می‌دهد؛ شروع سریع سپس یک سند را بر روی صفحه قرار می‌دهد.

نیازمندی‌ها

• پروژه وب هدف .NET Framework 4.7.2 یا بالاتر است. یک پروژه 4.7 نمی‌تواند این پکیج را مصرف کند؛ ابتدا هدف‌گذاری آن را تغییر دهید.
• سایت در خط لوله یکپارچه اجرا می‌شود (پیش‌فرض برای استخرهای برنامه IIS و IIS Express).

این صفحه Doconut.NETFramework نسخه 26.9.0 و بالاتر را پوشش می‌دهد. نسخه‌های 26.8.0 و قبلی .NET Framework 4.7 را با API متفاوت هدف‌گذاری می‌کردند؛ آن خط متوقف شده است. به‌روزرسانی یک برنامه موجود عبور از این مرز در مهاجرت پوشش داده شده است.

نصب بسته

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

Install-Package Doconut.NETFramework

یا، در یک پروژه با سبک SDK:

dotnet add package Doconut.NETFramework

موتور رندرینگ درون بسته تعبیه شده است: هیچ اسمبلی جداگانه‌ای برای ارجاع، کپی یا استقرار وجود ندارد. قابلیت‌های اختیاری به صورت بسته‌های جداگانه عرضه می‌شوند — برای مثال Doconut.NETFramework.Converter و Doconut.NETFramework.Dicom — و هر یک به مجوزی نیاز دارند که آن را اعطا کند (به سیستم افزونه مراجعه کنید).

پیکربندی Web.config

Doconut دو نوع درخواست را سرو می‌کند، و IIS هر دو را از طریق Web.config مسیردهی می‌کند:

• DocImage.axd — صفحهٔ نمایشگر، تصویر بندانگشتی، جستجو و نقطهٔ انتهایی حاشیه‌نویسی، که توسط Doconut.DocImageHandler سرو می‌شود.
• /doconut-res/* — اسکریپت‌ها، استایل‌شییت‌ها و آیکون‌های خود نمایشگر، که در اسمبلی تعبیه شده‌اند و توسط Doconut.DoconutResourceModule سرو می‌شوند.

هر دو را اضافه کنید، به همراه تنظیماتی که به آن‌ها وابسته‌اند:

<configuration>
  <system.web>
    <!-- MVC 5 only: Razor compiles views at run time and needs the netstandard facade. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength is in KILOBYTES: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Read .cshtml and .aspx files as UTF-8, not as the server's ANSI code page. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength is in BYTES: the same 200 MB. -->
        <requestLimits maxAllowedContentLength="209715200" />
      </requestFiltering>
    </security>
    <modules runAllManagedModulesForAllRequests="true">
      <add name="DoconutResourceModule" type="Doconut.DoconutResourceModule, Doconut" />
    </modules>
    <handlers>
      <add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd"
           type="Doconut.DocImageHandler, Doconut" />
    </handlers>
  </system.webServer>
</configuration>

هر خط از بروز خطایی که استثنایی ایجاد نمی‌کند جلوگیری می‌کند:

• verb="GET,HEAD,POST" — HEAD را نگه دارید. نمایشگر یک درخواست HEAD برای صفحهٔ 1 ارسال می‌کند تا تصاویر متحرک را تشخیص دهد. بدون این صفت، IIS قبل از اجرای هندلر پاسخ 404 می‌دهد: اسناد هنوز نمایش داده می‌شوند، اما تشخیص انیمیشن هرگز کار نمی‌کند و کنسول مرورگر با 404ها پر می‌شود.
• runAllManagedModulesForAllRequests="true" — /doconut-res/*.js، .css و .png شبیه فایل‌های استاتیک به نظر می‌رسند و IIS قبل از اینکه ماژول منبع آن‌ها را ببیند، به هندلر فایل‌های استاتیک خود می‌سپارد. نتیجه یک نمایشگر بدون اسکریپت یا آیکون است.
• <globalization fileEncoding="utf-8"> — فایل‌های صفحه که به صورت UTF-8 بدون علامت ترتیب بایت ذخیره می‌شوند، در غیر این صورت با صفحه کد ANSI سرور خوانده می‌شوند، بنابراین هر کاراکتر غیر ASCII به مرورگر به‌صورت دو بار کدگذاری می‌رسد (یک خط تیرهٔ بزرگ به صورت — نمایش داده می‌شود). فایل روی دیسک صحیح است و صفحه همچنان <meta charset="utf-8"> را اعلام می‌کند.
• اسمبلی netstandard (MVC 5) — Razor هنگام اولین درخواست، نماها را کامپایل می‌کند و فهرست مرجع خود را دارد که این واسط را شامل نمی‌شود. یک نما که کاری پویا فراتر از دسترسی ساده به عضو انجام دهد، با خطای CS0012 مواجه می‌شود و یک پاسخ خالی 500 می‌دهد، و فقط صفحاتی که این خطا را ایجاد می‌کنند، شکست می‌خورند. خطای کامپایلر فقط در لاگ رویدادهای ویندوز (منبع ASP.NET) ظاهر می‌شود. برنامه‌های Web Forms به این خط نیاز ندارند.
• محدودیت‌های بارگذاری — ASP.NET تمام بدنهٔ درخواست را قبل از اجرای هر هندلری می‌خواند، بنابراین بارگذاری بالاتر از این محدودیت‌ها توسط IIS با صفحه خطای خود رد می‌شود. maxRequestLength (کیلوبایت) و maxAllowedContentLength (بایت) را هماهنگ نگه دارید و آن‌ها را بالاتر از بزرگ‌ترین فایلی که کاربران شما باز یا بارگذاری می‌کنند تنظیم کنید.

دو تنظیم دیگر نیز مهم هستند و معمولاً از پیش صحیح تنظیم شده‌اند:

• وضعیت جلسه فعال باقی می‌ماند. به‌طور پیش‌فرض یک صفحه فقط به جلسهٔ ASP.NET که سند را باز کرده سرو می‌شود، بنابراین سایت نباید <sessionState mode="Off" /> را تنظیم کند. به جلسات و امنیت مراجعه کنید.
• تغییر مسیرهای بایندینگ. تغییر مسیرهای بایندینگ <runtime> که NuGet در Web.config می‌نویسد را نگه دارید. در یک پروژهٔ سبک SDK، آن‌ها را از bin\<YourApp>.dll.config تولید شده کپی کنید، زیرا ASP.NET کلاسیک فقط از Web.config تغییر مسیرها را می‌خواند. یک تغییر مسیر که نسخه‌ای را نام می‌برد که در bin\ موجود نیست، کل برنامه را در زمان راه‌اندازی با یک 500 خالی متوقف می‌کند.

ثبت Doconut در Global.asax

در System.Web هیچ سازنده (builder) و هیچ خط لوله میدل‌ویر (middleware pipeline) وجود ندارد. Doconut یک بار برای هر فرآیند کارگر توسط DoconutHost.Initialize در Application_Start ساخته می‌شود و توسط DoconutHost.Shutdown در Application_End آزاد می‌گردد:

// Global.asax.cs
protected void Application_Start()
{
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    });
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}

DoconutHost.Initialize سرویس‌های مورد نیاز هندلر، ماژول منبع و کدهای شما را می‌سازد. کد شما از طریق DoconutHost.Services به این سرویس‌ها دسترسی پیدا می‌کند (به DoconutHost مراجعه کنید). فقط اولین فراخوانی تنظیمات را اعمال می‌کند؛ فراخوانی دوم نادیده گرفته می‌شود. در یک برنامه MVC، مسیرهای Doconut را نیز باید از مسیردهی خارج کنید — شروع سریع نمونه کامل Application_Start را نشان می‌دهد.

تمام گزینه‌ها

DoconutOptions ویژگی‌های قابل تنظیم زیر را می‌پذیرد. هر یک به‌صورت اختیاری هستند.

زمانی که بیش از یک منبع لایسنس تنظیم شده باشد، ترتیب برتری به صورت زیر است: LicenseStream بر LicenseContent، LicenseContent بر LicensePath، و در نهایت بر کشف خودکار — برای جزئیات به راه‌اندازی لایسنس مراجعه کنید.

Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // مسیر سرو کردن JS/CSS/تصاویر ویور
    options.UnsafeMode      = false;          // امنیت نشست را فعال نگه دارید
    options.ShowDoconutInfo = false;
});
// نقطه انتهایی صفحه گزینه‌ای نیست؛ این هندلر DocImage.axd است که در Web.config تعریف شده است.

گام‌های بعدی

• شروع سریع — یک سند را باز کنید و در مرورگر رندر کنید، در MVC 5 یا Web Forms.
• راه‌اندازی لایسنس — جایی که Doconut به دنبال فایل لایسنس شما می‌گردد.