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

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

المحول يتطلب ملحقه. استدعاء 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)