نصب

Doconut را به برنامه وب .NET Framework 4.7.2 خود اضافه کنید

Doconut.NETFramework میزبان نمایشگر Doconut در یک برنامه کلاسیک 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).
  • سرور بر روی Windows اجرا می‌شود. این پکیج فقط برای Windows است.

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

نصب پکیج

از کنسول Package Manager:

powershell
Install-Package Doconut.NETFramework

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

bash
dotnet add package Doconut.NETFramework

دستورات بدون نسخه آخرین نسخه پایدار را نصب می‌کنند. برای قفل کردن نسخه‌ای که این مستندات توصیف می‌کند، نسخه را پاس دهید:

powershell
Install-Package Doconut.NETFramework -Version 26.10.0
bash
dotnet add package Doconut.NETFramework --version 26.10.0

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

پیکربندی Web.config

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

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

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

xml
<configuration>
  <system.web>
    <!-- فقط MVC 5: Razor نماها را در زمان اجرا کامپایل می‌کند و به واسط netstandard نیاز دارد. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength بر حسب KILOBYTES است: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- فایل‌های .cshtml و .aspx را به صورت UTF-8 بخوانید، نه به عنوان صفحه کد ANSI سرور. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength بر حسب BYTES است: همان 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 هیچ سازنده‌ای و هیچ خط لوله میانی‌نرم‌افزاری وجود ندارد. Doconut یک بار برای هر فرآیند کارگر توسط DoconutHost.Initialize در Application_Start ساخته می‌شود و توسط DoconutHost.Shutdown در Application_End آزاد می‌گردد:

csharp
// 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 سرویس‌های handler، ماژول منبع و استفاده کد شما را می‌سازد. کد شما از طریق DoconutHost.Services به آن‌ها دسترسی پیدا می‌کند (به DoconutHost مراجعه کنید). فقط اولین فراخوانی هر چیزی را پیکربندی می‌کند؛ فراخوانی دوم نادیده گرفته می‌شود. در یک برنامه MVC، همچنین دو مسیر Doconut را خارج از مسیردهی نگه دارید — شروع سریع مثال کامل Application_Start را نشان می‌دهد.

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

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

ویژگیپیش‌فرضتوضیح
UnsafeModefalseزمانی که false، DocImage.axd فقط به نشست ASP.NET که سند را باز کرده صفحه‌ای را سرو می‌کند. زمانی که true، هر درخواستی که توکن را حمل می‌کند سرو می‌شود. آن را false بگذارید.
ShowDoconutInfofalseزمانی که true، درخواست DocImage.axd بدون token به جای 404 بنر نسخه‌ای می‌دهد. برای بررسی سریع مفید است؛ در محیط تولید آن را خاموش بگذارید.
ResourcesPath"/doconut-res"محل سرو اسکریپت‌ها، سبک‌ها و آیکون‌های توکار توسط ماژول منبع. فقط همراه با ResPath نمایشگر و هر IgnoreRoute MVC تغییر دهید.
LicensePath""مسیر کامل فایل لایسنس. خالی بودن به معنای عبور به منبع بعدی، سپس کشف خودکار است.
LicenseContent""محتوای خام لایسنس — از یک متغیر محیطی، مخزن رمز یا پایگاه داده.
LicenseStreamnullلایسنس به‌صورت جریان، یک بار در زمان راه‌اندازی خوانده می‌شود.
MiddlewarePath"/doconut"در این بسته استفاده نمی‌شود. نقطه انتهای صفحه، handler DocImage.axd اعلام‌شده در Web.config است، هر مقدار تنظیم شده باشد. همچنان اعتبارسنجی می‌شود: باید با / شروع شود و متفاوت از ResourcesPath باشد.
ResetLicensefalseدر این بسته استفاده نمی‌شود. لایسنس یک بار در DoconutHost.Initialize خوانده می‌شود؛ پس از جایگزینی فایل لایسنس، استخر برنامه را بازنشانی کنید.
MaxConcurrentEditorSessions200حداکثر تعداد جلسات ویرایشگر زنده (سندهایی که با DocOptions.EditMode باز شده‌اند). در صورتی که بیشتر شود، کم‌استفاده‌ترین جلسه بیکار بسته می‌شود. جلسات عادی نمایشگر هرگز شمارش نمی‌شوند. 0 یا مقدار منفی به معنای عدم محدودیت است.
EditorSnapshotEveryOps50با فعال بودن پایداری ویرایشگر (AddDoconutEditorPersistence)، هر N تغییر ثبت‌شده، سند زنده را snapshot می‌کند. 0 یا مقدار منفی هرگز در میانه جلسه snapshot نمی‌گیرد. وقتی پایداری غیرفعال باشد، هیچ تأثیری ندارد.

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

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

گام‌های بعدی

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