التثبيت

إضافة 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 بواجهة برمجة تطبيقات مختلفة؛ تم إلغاء هذا الخط. تحديث تطبيق موجود عبر هذا الحد مغطى في الهجرة.

تثبيت الحزمة

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

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 فارغًا، وتفشل فقط الصفحات التي تُصطدم به. يظهر خطأ المترجم فقط في سجل أحداث Windows (المصدر 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 يبني الخدمات المعالج، وحدة الموارد، واستخدام الكود الخاص بك. يصل كودك إليها عبر 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"غير مستخدم في هذه الحزمة. نقطة النهاية للصفحة هي المعالج DocImage.axd المعلن في Web.config، مهما كان الإعداد. لا يزال يتم التحقق منه: يجب أن يبدأ بـ / ويختلف عن ResourcesPath.
ResetLicensefalseغير مستخدم في هذه الحزمة. يُقرأ الترخيص مرة واحدة، في DoconutHost.Initialize؛ أعد تدوير مجموعة التطبيقات بعد استبدال ملف الترخيص.
MaxConcurrentEditorSessions200الحد الأقصى لعدد جلسات المحرر الحية (المستندات المفتوحة بـ DocOptions.EditMode). عند تجاوز هذا العدد، تُغلق جلسة المحرر الخاملة الأقل استخدامًا مؤخرًا. لا تُحسب جلسات المشاهد العادية. 0 أو قيمة سلبية تعني عدم وجود حد.
EditorSnapshotEveryOps50مع تمكين بقاء المحرر (AddDoconutEditorPersistence)، يتم أخذ لقطة للمستند الحي كل N تغييرات مسجلة. 0 أو قيمة سلبية لا تأخذ لقطات أثناء الجلسة. لا تأثير له عندما يكون البقاء معطلًا.

عند تعيين أكثر من مصدر ترخيص، يتفوق LicenseStream على LicenseContent، والذي يتفوق على LicensePath، والذي يتفوق على الاكتشاف التلقائي — انظر إعداد الترخيص.

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // المكان الذي تُخدم منه ملفات JS/CSS/images للعارض
    options.UnsafeMode      = false;          // حافظ على تشغيل أمان الجلسة
    options.ShowDoconutInfo = false;
});
// نقطة النهاية للصفحة ليست خيارًا هنا: إنها معالج DocImage.axd المعلن في Web.config.

الخطوات التالية

هل كانت هذه الصفحة مفيدة؟