التثبيت

إضافة Doconut إلى مشروع .NET 6 الخاص بك

المشاهد الأساسي لـ Doconut لـ .NET 6 يُوزع كحزمة NuGet واحدة يمكن توصيلها بأي تطبيق ASP.NET Core. الإضافات الاختيارية تستخدم حزمًا منفصلة. تُثبت هذه الصفحة الحزمة الأساسية وتُسجل الطبقة الوسيطة — الحد الأدنى المطلوب قبل أول عرض لك.

المتطلبات

تشغل الحزمة على هذه الأنظمة:

المنصةمدعوم
Windows x64 / x86نعم
Linux x64، مبني على glibc (Debian، Ubuntu، الصورة الرسمية mcr.microsoft.com/dotnet/aspnet:6.0-bookworm-slim)نعم
Alpine والتوزيعات الأخرى المبنية على muslلا
macOSلا

على Linux، ثبّت مكتبة تكوين الخطوط قبل فتح أول مستند:

bash
apt-get update && apt-get install -y libfontconfig1

على RHEL وFedora والتوزيعات المشابهة تكون الحزمة fontconfig (dnf install -y fontconfig). هذه هي الحزمة النظامية الوحيدة التي تحتاجها Doconut: المكتبات الأصلية التي تستخدمها تُشحن داخل حزمة NuGet، وlibgdiplus غير مطلوب.
في Docker، يُفضَّل aspnet:6.0-bookworm-slim (Debian 12): العلامة الافتراضية aspnet:6.0 هي Debian 11، التي قد تفشل مرايا الحزم فيها في تثبيت libfontconfig1. تُرسم الصفحات بالخطوط المثبتة على الخادم، لذا راجع استكشاف الأخطاء وإصلاحها للخطوط ورسائل الأخطاء على Linux.

تثبيت الحزمة

bash
dotnet add package Doconut.NET6

الأمر غير المُحدَّد للإصدار يثبت أحدث نسخة مستقرة. لتثبيت الإصدار المحدد الذي تصفه هذه الوثائق، مرّر الإصدار كخيار منفصل:

bash
dotnet add package Doconut.NET6 --version 26.10.0

Doconut.NET6 هو معرف الحزمة. لاحقة الإصدار تنتمي إلى اسم ملف Doconut.NET6.<version>.nupkg المُحمَّل ولا تُعد جزءًا من المعرف.

تحديد التكامل قبل الترقية

معرف الحزمة Doconut.NET6 استُخدم من قبل كل من التكامل الكلاسيكي والحالي لـ .NET 6. لا تختَر الوثائق بناءً على اسم الحزمة فقط:

  • DocImage.axd، new Viewer(_cache, _accessor, ...)، المتزامن OpenDocument(...)، والسكريبتات المنسوخة يدويًا للعارض تُحدِّد التكامل الكلاسيكي؛
  • AddDoconut()، UseDoconutResources()، حقن Viewer، وOpenDocumentAsync(...) تُحدِّد التكامل الحالي الموثَّق هنا.

دليل الإعداد الكلاسيكي المترجم دليل الإعداد الكلاسيكي لا يزال متاحًا. استخدم دليل الترحيل لتغيير الأجيال؛ تحديث الحزمة العادي لا يُحوِّل بدء التشغيل أو عمر العارض أو موارد المتصفح تلقائيًا.

تسجيل Doconut

AddDoconut() هو نقطة التسجيل الوحيدة — هناك تحميل زائد واحد، وهو يربط خدمة Viewer، خدمة الترخيص، وبنية التقديم داخل حاوية DI.

يُكمل نداءان للطبقة الوسيطة الإعداد، وترتيبهما مهم: UseDoconutResources() يجب أن يُنفَّذ قبل UseDoconut(). UseDoconut() هي طبقة وسيطة نهائية، لذا استدعاؤها أولًا يعني أن كل طلب إلى أصل /doconut-res لا يصل إلى معالج الموارد ويُعيد 404. UseDoconut() تُجيب على كل طلب يصل إليها، لذا ضعها على فرعها الخاص باستخدام app.Map. توصيل الجلسة مطلوب أيضًا — أمان المستند الافتراضي لـ Doconut يتحقق من كل طلب صفحة مقابل حالة جلسة ASP.NET.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // حالة الجلسة تحتاج إلى ذاكرة مؤقتة (MVC/Razor Pages يضيف واحدة بالفعل)
builder.Services.AddSession(); // أمان مستند Doconut يعتمد على حالة جلسة ASP.NET

app.UseSession();          // استدعِ UseSession() قبل UseDoconut()
app.UseDoconutResources(); // يجب تسجيله قبل UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

جميع الخيارات

DoconutOptions يقبل الخصائص القابلة للتعيين التالية. كل واحدة اختيارية — القيم الافتراضية أدناه تُطبق عندما تُترك الخاصية غير مُحدَّدة.

الخاصيةالافتراضيالوصف
ShowDoconutInfofalseعند true، طلب بدون token يُعيد لافتة الإصدار بدلاً من 404. مفيد كفحص سريع؛ يُترك معطلاً في الإنتاج.
UnsafeModefalseعند true، يتخطى فحص أمان جلسة ASP.NET على طلبات الصفحات. يُترك معطلاً في الإنتاج.
MiddlewarePath"/doconut"قيمة التنسيق لنقطة النهاية page-image. يتم التحقق منها، لكنها لا تُنشئ فرعًا بحد ذاتها؛ احرص على توافقها مع تعيين UseDoconut() الفعلي وBasePath الخاص بالعميل.
ResourcesPath"/doconut-res"المكان الذي تُخدم منه موارد JS/CSS/الصورة المدمجة.
LicensePath"" (empty string)المسار إلى ملف الترخيص. الفارغ يعني الانتقال إلى المصدر التالي، ثم البحث التلقائي.
LicenseContent"" (empty string)محتوى الترخيص الخام — من متغيّر بيئي، مدير أسرار، أو قاعدة بيانات.
LicenseStreamnullالترخيص كتيار، يُقرأ مرة واحدة عند بدء التشغيل.
ResetLicensefalseعلامة توافق محجوزة. خدمات .NET 6 الحالية تقرأ الترخيص أثناء AddDoconut()؛ أعد تشغيل التطبيق بعد استبدال الترخيص.
MaxConcurrentEditorSessions200الحد الأقصى لعدد جلسات المحرر الحية (المستندات المفتوحة بـ DocOptions.EditMode). إذا تجاوزت، تُغلق جلسة المحرر الخاملة الأقل استخدامًا. لا تُحسب جلسات العارض العادية. 0 أو قيمة سلبية تعني عدم وجود حد.
EditorSnapshotEveryOps50مع تمكين استمرارية المحرر (AddDoconutEditorPersistence)، يتم أخذ لقطة للمستند الحي كل N تغيّر مسجّل. 0 أو قيمة سلبية لا تلتقط لقطة أثناء الجلسة. لا تأثير عندما تكون الاستمرارية معطلة.

أولوية الترخيص عندما تُحدَّد أكثر من مصدر: LicenseStream يتفوق على LicenseContent يتفوق على LicensePath يتفوق على البحث التلقائي — راجع إعداد الترخيص.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.MiddlewarePath  = "/doconut";     // تنسيق مع تخطيط التطبيق و BasePath الخاص بالعميل
    options.ResourcesPath   = "/doconut-res"; // المكان الذي تُقدَّم منه ملفات JS/CSS/الصور الخاصة بالعارض
    options.UnsafeMode      = false;          // حافظ على تشغيل أمان الجلسة
    options.ShowDoconutInfo = false;
});

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

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