إعداد الترخيص

بدون ترخيص، لا يزال Doconut يعرض المستندات — كل صفحة تحمل علامة مائية للتقييم فقط. تغطي هذه الصفحة الأربع طرق لتوفير ترخيص في Global.asax، ومكان بحث Doconut عندما لا تزود أي ترخيص، وما يحدث عندما يكون ترخيص الإضافة مفقودًا.

أربع طرق لتوفير الترخيص

هناك ثلاثة مصادر صريحة في DoconutOptions — مسار ملف، أو دفق، أو محتوى خام — بالإضافة إلى الاكتشاف التلقائي عندما لا يتم تعيين أي منها. يتم قراءة جميعها مرة واحدة في DoconutHost.Initialize. عندما يتم تعيين أكثر من مصدر، تكون الأولوية كما يلي:

LicenseStream يتفوق على LicenseContent يتفوق على LicensePath يتفوق على الاكتشاف التلقائي.

عن طريق المسار

امنح LicensePath مسارًا كاملاً. يتم حل المسار النسبي بالنسبة إلى الدليل الحالي للعملية، وتحت IIS يكون ذلك مجلد عملية العامل نفسها، وليس موقعك. يقوم HostingEnvironment.MapPath بتحويل مسار نسبي للموقع إلى مسار كامل:

Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
});

إذا لم يكن الملف موجودًا، لا يرمي Doconut استثناءً ولا يتراجع إلى الاكتشاف التلقائي: لا يتم تحميل أي ترخيص، وتظهر العلامة المائية في العارض. يتم قراءة ملفات الترخيص الخاصة بكل إضافة في نفس المجلد (Doconut.Viewer.<Capability>.lic) معها، لذا يعمل LicensePath و AddPlugin<...>() معًا عندما تكون تراخيص الإضافات بجوار الترخيص الأساسي.

عن طريق الدفق

LicenseStream يُقرأ مرة واحدة عند بدء التشغيل — مفيد عندما يأتي الترخيص من مورد مدمج أو مخزن سري بدلاً من ملف على القرص.

// Precedence: LicenseStream > LicenseContent > LicensePath > auto-search.
Doconut.DoconutHost.Initialize(options =>
{
    options.LicenseStream = licenseStream;
});

عن طريق المحتوى

LicenseContent يأخذ نص الترخيص نفسه — من متغيّر بيئي، قاعدة بيانات، أو مخزن سري — لذا لا يلزم نشر ملف ترخيص مع الموقع.

// License XML from a database, an environment variable or a secret store -
// no file on disk. Beaten only by LicenseStream.
Doconut.DoconutHost.Initialize(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

الاكتشاف التلقائي

لا تقم بتعيين أيٍ من الثلاثة، وسيبحث Doconut عن الترخيص بنفسه:

// Configure nothing, and Doconut searches for the license itself, in this order:
//   1. {CurrentDirectory}\wwwroot
//   2. {AppContext.BaseDirectory}\wwwroot   (under IIS: the site's root folder)
// It looks for Doconut.lic first, then Doconut.Viewer.lic, plus any per-plugin
// Doconut.Viewer.<Capability>.lic files alongside it.
Doconut.DoconutHost.Initialize();

المجلدان، بالترتيب، والملفات التي يتم البحث عنها:

1. {CurrentDirectory}\wwwroot
2. {AppContext.BaseDirectory}\wwwroot

In each folder:
  Doconut.lic                        — if found, this is the only file read
  Doconut.Viewer.lic                 — base viewer license
  Doconut.Viewer.<Capability>.lic    — per-plugin licenses, read only next to Doconut.Viewer.lic

تحت IIS و IIS Express، يكون AppContext.BaseDirectory هو مجلد جذر الموقع — المجلد الذي يحتوي على Web.config — وليس مجلد bin الخاص به. لذا يجب أن يكون الترخيص في wwwroot تحت جذر الموقع:

MySite\
  Web.config
  Global.asax
  bin\
  wwwroot\
    Doconut.Viewer.lic
    Doconut.Viewer.Converter.lic

في المشروع، احتفظ بملفات wwwroot\*.lic بجوار Web.config وانشر المجلد مع الموقع. لا يلزم أي خطوة بناء لنسخه إلى أي مكان. أي ملف .lic في مكان آخر — في bin\، بجوار Web.config، أو في مجلد فرعي داخل wwwroot — لا يُقرأ أبدًا.

احتفظ بملفات .lic خارج نظام التحكم في المصدر. انشرها بجوار الموقع، أو زوّد الترخيص عبر LicenseContent أو LicenseStream من مخزنك السري.

ماذا يحدث بدون ترخيص

عدم وجود ترخيص لا يسبب استثناءً. ينجح DoconutHost.Initialize، يبدأ الموقع، ويعمل العارض، لكن كل صفحة تحمل علامة مائية للتقييم ولا تُمنح أي قدرة اختيارية.

ملف الترخيص الذي يتم العثور عليه لكنه مرفوض يختلف. توقيع غير صالح، أو تعديل، أو بناء خارج نافذة إصدار الترخيص يجعل OpenDocumentAsync يرمي LicenseException مع السبب.

الإضافات تحتاج إلى ترخيصها عند بدء التشغيل

تسجيل إضافة لا يمنحها أي ترخيص القدرة يتوقف التطبيق عند بدء التشغيل. يرمي DoconutHost.Initialize استثناءً في Application_Start:

InvalidOperationException: The Converter plugin is registered via AddPlugin but no active
license grants Converter. Remove the AddPlugin<...>() call or install a license (or
trial/demo) that includes Converter.

تحت System.Web، لا ترى تلك الرسالة في المتصفح. كل طلب إلى الموقع يرد بـ 500 فارغ — لا صفحة خطأ، لا تتبع استدعاءات، ولا شيء في سجل IIS. يتم تسجيل الاستثناء فقط في سجل أحداث Windows (سجل التطبيقات، المصدر ASP.NET). إذا توقف الموقع بالكامل عن الاستجابة مباشرة بعد إضافة سطر AddPlugin، فتحقق من ملفات الترخيص في wwwroot قبل الكود: يجب أن يكون ملف الإضافة Doconut.Viewer.<Capability>.lic بجوار Doconut.Viewer.lic، وبدون الترخيص الأساسي لا تُقرأ ملفات الإضافة على الإطلاق.

تحقق من الترخيص المحمّل

IDoconutLicenseService هو نفس مصدر الحقيقة الذي يستخدمه SDK. احصل عليه من DoconutHost.Services لتوفير نقطة تشخيص موثوقة أو لتفعيل ميزات — لا تُعيد محتوى الترخيص أبدًا:

// GET /License/Status
public ActionResult Status()
{
    var license = Doconut.DoconutHost.Services.GetRequiredService<IDoconutLicenseService>();

    return Json(new
    {
        viewer     = license.IsViewerLicensed || license.IsTemporary,
        temporary  = license.IsTemporary,
        search     = license.IsCapabilityGranted(LicenseCapability.Search),
        annotation = license.IsCapabilityGranted(LicenseCapability.Annotation),
        converter  = license.HasConverter,
        dicom      = license.HasDicom
    }, JsonRequestBehavior.AllowGet);
}

يُقرأ الترخيص مرة واحدة، في DoconutHost.Initialize. بعد استبدال ملف الترخيص، أعد تدوير مجموعة التطبيقات (أو عدل Web.config) حتى يتم تشغيل Application_Start مرة أخرى.

استكشاف الأخطاء وإصلاحها

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

• الترخيص — القدرات، وكيفية التحقق منها أثناء التشغيل.
• استكشاف الأخطاء وإصلاحها — العلامات المائية، فشل بدء التشغيل، وأعراض أخرى.