التثبيت

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

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

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

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

تثبيت الحزمة

dotnet add package Doconut.NETStandard

الأمر غير المحدد للإصدار يثبت أحدث إصدار ثابت. لإعادة إنتاج الإصدار الحالي 26.8.0 بدقة، مرّر الإصدار كخيار منفصل:

dotnet add package Doconut.NETStandard --version 26.8.0

Doconut.NETStandard هو معرف الحزمة. اللاحقة .26.8.0 تنتمي إلى اسم الملف Doconut.NETStandard.26.8.0.nupkg الذي تم تنزيله ولا تشكل جزءًا من المعرف.

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

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

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

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

• new Viewer(_cache, _accessor, …)، UnSafeMode، المتزامن OpenDocument(...)، viewer.InitCache()، UseDoconutWebFarm، والبرمجيات النصية للعارض المنسوخة يدويًا تُحدد التكامل السابق؛
• AddDoconut()، UseDoconutResources()، Viewer المُحقن، وOpenDocumentAsync(...) تُحدد التكامل الحالي الموثق هنا.

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

تسجيل Doconut

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

مكالمتا middleware تكملان الإعداد، وترتيبهما مهم: UseDoconutResources() يجب أن يُنفّذ قبل UseDoconut(). UseDoconut() هو middleware نهائي، لذا استدعاؤه أولًا يعني أن كل طلب إلى مورد /doconut-res لا يصل إلى معالج الموارد ويتلقى 404. ربط الجلسة مطلوب أيضًا — أمان المستند الافتراضي لـ 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.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 يقبل الخصائص القابلة للتعيين التالية. كل واحدة اختيارية — القيم الافتراضية أدناه تُطبق عندما تُترك الخاصية غير مُحددة.

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

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

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

• البدء السريع — افتح مستندك الأول وعرضه في المتصفح.
• إعداد الترخيص — حيث يبحث Doconut عن ملف الترخيص الخاص بك.