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

تثبيت الحزمة

bash

dotnet add package Doconut.NET8

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

bash

dotnet add package Doconut.NET8 --version 26.7.0

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

تسجيل Doconut

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

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

// مثال يوضح كيفية إضافة Doconut وتسجيل خدمات الجلسة والموارد

csharp

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddSession(); // أمان مستندات Doconut يعتمد على حالة جلسة ASP.NET

app.UseSession();          // استدعِ UseSession() قبل UseDoconut()
app.UseDoconutResources(); // يجب تسجيله قبل UseDoconut()
app.UseDoconut();

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

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

الخاصية	القيمة الافتراضية	الوصف
`ShowDoconutInfo`	`false`	عند `true`، يُعيد الطلب بدون `token` شريط إصدارة بدلاً من 404. مفيد كاختبار سريع؛ يُفضل إيقافه في بيئة الإنتاج.
`UnsafeMode`	`false`	عند `true`، يتخطى فحص أمان جلسة ASP.NET على طلبات الصفحات. يُفضل إيقافه في بيئة الإنتاج.
`MiddlewarePath`	`"/doconut"`	قيمة التنسيق لنقطة النهاية page-image. يتم التحقق منها، لكنها لا تُنشئ فرعًا بحد ذاتها؛ احرص على توافقها مع تعيين `UseDoconut()` الفعلي ومسار BasePath للعميل.
`ResourcesPath`	`"/doconut-res"`	المكان الذي تُقدَّم منه موارد JS/CSS/الصورة المدمجة.
`LicensePath`	`""` (empty string)	مسار ملف الترخيص. إذا كان فارغًا يعني الانتقال إلى المصدر التالي، ثم البحث التلقائي.
`LicenseContent`	`""` (empty string)	محتوى الترخيص الخام — من متغيّر بيئي، أو مدير أسرار، أو قاعدة بيانات.
`LicenseStream`	`null`	الترخيص كتيار، يُقرأ مرة واحدة عند بدء التشغيل.
`ResetLicense`	`false`	علامة توافقية محجوزة. خدمات .NET 8 الحالية تقرأ الترخيص أثناء `AddDoconut()`؛ أعد تشغيل التطبيق بعد استبدال الترخيص.

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

// مثال يوضح كيفية تعيين خيارات Doconut المختلفة

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;
});

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

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