التثبيت

Doconut.NETFramework يستضيف عارض Doconut في تطبيق ASP.NET كلاسيكي على .NET Framework 4.7.2 — IIS أو IIS Express، MVC 5 أو Web Forms. الإعداد يتكون من ثلاثة أجزاء: حزمة NuGet، تسجيلين في Web.config، واستدعاء واحد في Global.asax. تغطي هذه الصفحة الثلاثة؛ Quick Start ثم وضع مستند على صفحة.

المتطلبات

• يستهدف مشروع الويب .NET Framework 4.7.2 أو أحدث. لا يمكن لمشروع 4.7 استهلاك هذه الحزمة؛ يجب إعادة استهدافه أولاً.
• يعمل الموقع في خط الأنابيب المتكامل (الإعداد الافتراضي لمجموعات تطبيقات IIS و IIS Express).

هذه الصفحة تغطي Doconut.NETFramework 26.9.0 وما بعده. الإصدارات 26.8.0 وما قبلها استهدفت .NET Framework 4.7 بواجهة برمجة تطبيقات مختلفة؛ تم إيقاف ذلك الخط. تحديث تطبيق موجود عبر هذا الحد مغطى في Migration.

تثبيت الحزمة

من وحدة تحكم مدير الحزم:

Install-Package Doconut.NETFramework

أو، في مشروع بنية SDK:

dotnet add package Doconut.NETFramework

محرك العرض مدمج في الحزمة: لا توجد تجميع محرك منفصل للإشارة إليه أو نسخه أو نشره. القدرات الاختيارية تُرسل كحزم مستقلة — على سبيل المثال Doconut.NETFramework.Converter و Doconut.NETFramework.Dicom — وكل واحدة تحتاج إلى ترخيص يمنحها (انظر Plugin System).

تكوين Web.config

Doconut يخدم نوعين من الطلبات، و IIS يوجه كلاهما عبر Web.config:

• DocImage.axd — صفحة العارض، الصورة المصغرة، البحث، ونقطة النهاية للتعليقات، تُخدم بواسطة Doconut.DocImageHandler.
• /doconut-res/* — سكريبتات العارض، ملفات الأنماط، والأيقونات الخاصة به، مدمجة في التجميع وتُخدم بواسطة Doconut.DoconutResourceModule.

أضف كلاهما، بالإضافة إلى الإعدادات التي يعتمدون عليها:

<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 بوحدة الكيلوبايت: 200 ميغابايت. -->
    <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 بوحدة البايت: نفس 200 ميغابايت. -->
        <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 فارغة، وتفشل فقط الصفحات التي تواجه هذا الخطأ. يظهر خطأ المترجم فقط في سجل أحداث Windows (المصدر ASP.NET). تطبيقات Web Forms لا تحتاج هذا السطر.
• حدود التحميل — ASP.NET يقرأ كامل جسم الطلب قبل تشغيل أي معالج، لذا أي تحميل يتجاوز هذه الحدود يُرفض من قبل IIS بصفحة خطأ خاصة به. حافظ على توافق maxRequestLength (كيلوبايت) و maxAllowedContentLength (بايت)، وتأكد من أنهما أعلى من أكبر ملف يفتحه أو يحمّله المستخدمون.

إعدادان آخران مهمان، وعادةً ما يكونان صحيحين بالفعل:

• حالة الجلسة تبقى مفعلة. بشكل افتراضي تُقدم الصفحة فقط لجلسة ASP.NET التي فتحت المستند، لذا يجب ألا يضبط الموقع <sessionState mode="Off" />. انظر Sessions & Security.
• إعادة توجيه الارتباطات. احتفظ بإعادة توجيه الارتباطات <runtime> التي يكتبها NuGet في Web.config. في مشروع بنية SDK، انسخها من bin\<YourApp>.dll.config المُولد، لأن ASP.NET الكلاسيكي يقرأ إعادة التوجيه فقط من Web.config. إعادة توجيه تشير إلى نسخة غير موجودة في bin\ توقف التطبيق بالكامل مع استجابة 500 فارغة عند بدء التشغيل.

تسجيل Doconut في Global.asax

لا يوجد مُنشئ ولا خط أنابيب middleware في System.Web. يتم تكوين 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، والذي يتفوق على 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 عن ملف الترخيص الخاص بك.