التثبيت

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

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

المتطلبات

المنصةمدعوم
Windows x64 / x86نعم
Linux x64، معتمد على glibc (Debian، Ubuntu، الصورة الرسمية mcr.microsoft.com/dotnet/aspnet:8.0)نعم
Alpine وغيرها من توزيعات muslلا
macOSلا

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

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

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

تثبيت الحزمة

bash
dotnet add package Doconut.NET8

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

bash
dotnet add package Doconut.NET8 --version 26.10.0

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

تسجيل Doconut

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

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

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

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 8 الحالية تقرأ الترخيص أثناء 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";     // التنسيق مع app mapping و BasePath للعميل
    options.ResourcesPath   = "/doconut-res"; // المكان الذي تُقدم منه ملفات JS/CSS/الصور الخاصة بـ viewer
    options.UnsafeMode      = false;          // حافظ على تشغيل أمان session
    options.ShowDoconutInfo = false;
});

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

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