DoconutExtensions – Doconut الوثائق

DoconutExtensions (namespace Doconut.Middleware) هي الفئة الثابتة التي تحتوي على الثلاث استدعاءات التي يقوم بها كل مضيف Doconut: تسجيل خدمة واحدة وتسجيل وسيطين.

csharp

builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseDoconutResources(); // BEFORE UseDoconut()
app.UseDoconut();

AddDoconut

text

IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)

يبني كائن DoconutOptions، يتحقق من صحته بسرعة (انظر DoconutOptions → التحقق من بدء التشغيل)، ويسجل الرسم البياني الكامل للخدمات:

الخدمة	مدة الحياة	الدور
`DoconutOptions`	Singleton	كائن التكوين
`IViewerFactory`	Singleton	يربط الامتدادات بعارضات الصيغ
`IDocumentSessionManager`	Singleton	الرمز → ذاكرة التخزين المؤقت للجلسة (`IMemoryCache` مسجل أيضًا)
`IDoconutLicenseService`	Singleton	الرخصة تُحمَّل مرة واحدة عند بدء التشغيل (الأولوية: `LicenseStream` → `LicenseContent` → `LicensePath` → البحث التلقائي)
`PageImageService`	Singleton	خط أنابيب صورة الصفحة (علامة مائية/تدوير/تحجيم/تعليقات توضيحية)
Document security (access store)	Singleton	منح لربط الرمز بالجلسة
`Viewer`	Transient	الواجهة العامة للفتح/الإغلاق
`DocumentConverter`	Transient	واجهة التحويل — تتطلب ملحق Converter
Health check `"doconut"`	—	تقارير حالة الرخصة/انتهاء الصلاحية عبر فحوصات الصحة في ASP.NET

سلوكان يستحقان المعرفة:

يتطلب Converter ملحقه. محاولة حل DocumentConverter دون options.AddPlugin<ConverterPlugin>() ينتج الاستثناء التالي:

text

InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

يتم التحقق من صلاحية الملحق عند بدء التشغيل. إذا كانت الرخصة مفقودة أو ملف TRIAL قديم أو رخصة مدفوعة بدون تمكين الملحق المناسب، سيفشل الاستدعاء AddDoconut() أثناء بدء التشغيل. التسجيلات المؤقتة/التجريبية تظل صالحة بعد تاريخ انتهاء صلاحيتها، بينما تُعطل القدرات المنتهية أثناء وقت التشغيل.

فحص الصحة يندمج مع آلية ASP.NET Core القياسية — قم بإنشائه إذا أردت عرض حالة الرخصة على نقطة صحة التطبيق:

csharp

app.MapHealthChecks("/health");

UseDoconut

text

IApplicationBuilder UseDoconut(this IApplicationBuilder app)

يضيف وسيط صورة الصفحة Doconut. يرد على كل طلب يحمل معامل الاستعلام ?token= — الصفحات، المصغرات، البحث، التعليقات التوضيحية، إجراءات الصفحة (جدول الطلب الكامل موجود في المفاهيم الأساسية → كيف يعمل العارض). عندما تكون UnsafeMode مساوية لـ false، يتم ربط طبقة أمان المستند تلقائيًا قبل هذا الوسيط.

العينة المرجعية توجه طلبات الودجت عبر فرع مسار:

csharp

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconutResources

text

IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)

يقدم ملفات JS و CSS والصور والخطوط المدمجة في المسار DoconutOptions.ResourcesPath (الافتراضي /doconut-res). هذه هي الملفات التي تُصدر الوسوم لها الدوال Viewer.ReferenceCss() / ReferenceScripts().

يجب استدعاؤه دائمًا قبل UseDoconut(). إذا بقيت منطقة العارض فارغة وأظهر وحدة تحكم المتصفح أخطاء 404 للمسار /doconut-res/...، فهذا يعني أن هذا الاستدعاء مفقود أو في غير مكانه.

ملخص الترتيب

csharp

app.UseRouting();
app.UseSession();          // required when UnsafeMode = false
app.UseDoconutResources(); // 1st Doconut call
app.UseDoconut();          // 2nd Doconut call (or via a MapWhen branch)