التثبيت
إضافة 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.
تثبيت الحزمة
dotnet add package Doconut.NETStandardالأمر غير المُحدَّد للإصدار يثبت أحدث إصدار ثابت. لتثبيت الإصدار الذي تصفه هذه الوثائق، مرّر الإصدار كخيار منفصل:
dotnet add package Doconut.NETStandard --version 26.10.0Doconut.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.
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:
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 يقبل الخصائص القابلة للتعيين التالية. كل واحدة اختيارية — القيم الافتراضية أدناه تُطبق عندما تُترك الخاصية غير مُحددة.
| الخاصية | القيمة الافتراضية | الوصف |
|---|---|---|
ShowDoconutInfo | false | عند true، طلب بدون token يُعيد لافتة الإصدار بدلاً من 404. مفيد كفحص سريع؛ يُفضل إيقافه في الإنتاج. |
UnsafeMode | false | عند true، يتخطى فحص أمان جلسة ASP.NET على طلبات الصفحات. يُفضل إيقافه في الإنتاج. لاحظ التهجئة — المكتبة السابقة كانت تسمي هذا UnSafeMode. |
MiddlewarePath | "/doconut" | قيمة التنسيق لنقطة النهاية page-image. يتم التحقق منها، لكنها لا تُنشئ فرعًا بحد ذاتها؛ حافظ على توافقها مع خريطة UseDoconut() الفعلية وعميل BasePath. |
ResourcesPath | "/doconut-res" | المكان الذي تُقدم منه موارد JS/CSS/الصورة المدمجة. |
LicensePath | "" (empty string) | المسار إلى ملف الترخيص. الفارغ يعني الانتقال إلى المصدر التالي، ثم البحث التلقائي. |
LicenseContent | "" (empty string) | محتوى الترخيص الخام — من متغير بيئي، أو مدير أسرار، أو قاعدة بيانات. |
LicenseStream | null | الترخيص كتيار، يُقرأ مرة واحدة عند بدء التشغيل. |
ResetLicense | false | علامة توافق محجوزة. يُقرأ الترخيص أثناء AddDoconut()؛ أعد تشغيل التطبيق بعد استبدال الترخيص. |
MaxConcurrentEditorSessions | 200 | الحد الأقصى لعدد جلسات المحرر الحية (المستندات المفتوحة بـ DocOptions.EditMode). إذا تجاوزت ذلك، تُغلق جلسة المحرر الخاملة الأقل استخدامًا مؤخرًا. جلسات العارض العادية لا تُحسب أبداً. 0 أو قيمة سلبية تعني عدم وجود حد. |
EditorSnapshotEveryOps | 50 | مع تمكين استمرارية المحرر (AddDoconutEditorPersistence)، يتم أخذ لقطة للمستند الحي كل N تغييرات مسجلة. 0 أو قيمة سلبية لا تأخذ لقطة خلال الجلسة. لا تأثير عندما تكون الاستمرارية معطلة. |
أولوية الترخيص عندما يتم تعيين أكثر من مصدر: LicenseStream يتفوق على LicenseContent يتفوق على LicensePath يتفوق على البحث التلقائي — راجع إعداد الترخيص.
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;
});الخطوات التالية
- البدء السريع — افتح مستندك الأول وقم بعرضه في المتصفح.
- إعداد الترخيص — حيث يبحث Doconut عن ملف الترخيص الخاص بك.
هل كانت هذه الصفحة مفيدة؟