التثبيت

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

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

تحقق من إطار عمل المضيف أولاً

المكتبة تستهدف netstandard2.1. هذا عقد أضيق من البناء السابق netstandard2.0، وهو أول شيء يجب التحقق منه:

المضيفمدعوم
.NET Core 3.0 أو أحدث، بما في ذلك .NET 5/6/7/8نعم
.NET Framework (أي نسخة)لا — لا يمكن استهلاك netstandard2.1 بواسطة .NET Framework

الحزمة تعمل على Windows فقط. لمضيف Linux، استخدم Doconut.NET8 أو Doconut.NET6.

إذا كان التطبيق يعمل على .NET Framework، فهذه ليست الحزمة الصحيحة. استخدم Doconut.NETFramework بدلاً من ذلك؛ بدءًا من الإصدار 26.9.0 يتطلب .NET Framework 4.7.2.

تثبيت الحزمة

bash
dotnet add package Doconut.NETStandard

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

bash
dotnet add package Doconut.NETStandard --version 26.10.0

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

رقم الإصدار هو الجيل

هذا مهم أكثر هنا من اسم الحزمة. كلا الجيلين من مكتبة .NET Standard يُنشران تحت نفس معرف الحزمة، وفقط الإصدار يميّزهما:

الإصدارالهدفAPI
26.7.0 وما دونnetstandard2.0التكامل السابق
26.8.0 وما فوقnetstandard2.1التكامل الموثق هنا

لا توجد طبقة توافق ولا حزمة جنبًا إلى جنب. رفع الإصدار هو التحديث، وسيُبلغ المترجم عن اختلافات API فورًا.

لا تختَر الوثائق بناءً على اسم الحزمة فقط:

  • new Viewer(_cache, _accessor, …), UnSafeMode, متزامن OpenDocument(...), viewer.InitCache(), UseDoconutWebFarm, وملفات عارض تم نسخها يدويًا تحدد التكامل السابق;
  • 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());

مساحات الأسماء

أنواع التكوين لم تعد موزعة عبر أربع مساحات أسماء. في هذا الإصدار تقريبًا كل شيء يعيش في مساحة الاسم الجذرية Doconut:

csharp
using Doconut;                       // Viewer, DoconutOptions, DocOptions, جميع إعدادات الصيغة
using Doconut.Middleware;            // AddDoconut, UseDoconut, UseDoconutResources
using Doconut.Clouds;                // إعدادات السحابة ومشاركة الملفات
using Doconut.Configs.Conversion;    // ConversionTarget

أسماء الأنواع نفسها لم تتغير — PdfConfig, WordConfig, ExcelConfig, CssConfig, ScriptConfig والبقية لا تزال موجودة. إذا كنت تنقل تطبيقًا موجودًا، فمعظم الملفات لا تحتاج سوى سطرين محذوفين من using؛ راجع دليل الترحيل.

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

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

الخاصيةالقيمة الافتراضيةالوصف
ShowDoconutInfofalseعند true، طلب بدون token يُعيد لافتة الإصدار بدلاً من 404. مفيد كفحص سريع؛ يُفضل إيقافه في الإنتاج.
UnsafeModefalseعند true، يتخطى فحص أمان جلسة ASP.NET على طلبات الصفحات. يُفضل إيقافه في الإنتاج. لاحظ التهجئة — المكتبة السابقة كانت تسمي هذا UnSafeMode.
MiddlewarePath"/doconut"قيمة التنسيق لنقطة النهاية page-image. يتم التحقق منها، لكنها لا تُنشئ فرعًا بحد ذاتها؛ حافظ على توافقها مع خريطة UseDoconut() الفعلية وعميل BasePath.
ResourcesPath"/doconut-res"المكان الذي تُقدم منه موارد JS/CSS/الصورة المدمجة.
LicensePath"" (empty string)المسار إلى ملف الترخيص. الفارغ يعني الانتقال إلى المصدر التالي، ثم البحث التلقائي.
LicenseContent"" (empty string)محتوى الترخيص الخام — من متغير بيئي، أو مدير أسرار، أو قاعدة بيانات.
LicenseStreamnullالترخيص كتيار، يُقرأ مرة واحدة عند بدء التشغيل.
ResetLicensefalseعلامة توافق محجوزة. يُقرأ الترخيص أثناء 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;
});

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

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