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

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

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

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

LicenseStream يتفوق على LicenseContent يتفوق على LicensePath يتفوق على البحث التلقائي.

عبر المسار

LicensePath يُمرَّر إلى File.Exists كما هو بالضبط. يتم حل المسار النسبي بالنسبة إلى دليل العمل الحالي للعملية — ليس مجلد مشروعك، ولا المجلد الذي يوجد فيه Program.cs. إذا لم يتم حل المسار، لا يرمي Doconut استثناء ولا يتراجع إلى البحث التلقائي — فهو ببساطة لا يحمل أي ترخيص وتظهر العلامة المائية في المشاهد. البحث التلقائي يعمل فقط عندما لا يتم تعيين أي من LicensePath أو LicenseContent أو LicenseStream.

يفضل استخدام مسار مطلق (مثلاً مبنيًا من IWebHostEnvironment.WebRootPath أو AppContext.BaseDirectory)، أو تخطي LicensePath تمامًا والاعتماد على الاكتشاف التلقائي أدناه.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "Doconut.Viewer.lic");
});

عبر التدفق

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

// Precedence: LicenseStream > LicenseContent > LicensePath > auto-search.
builder.Services.AddDoconut(options =>
{
    options.LicenseStream = licenseStream;
});

عبر المحتوى

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

// License XML from a database, environment variable, or secret manager —
// no file on disk. Beaten only by LicenseStream.
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

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

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

// Configure nothing, and Doconut searches for the license itself:
//   1. {CurrentDirectory}/wwwroot
//   2. {CurrentDirectory}/wwwroot/lib
//   3. AppContext.BaseDirectory  (the build output folder)
// It looks for Doconut.Viewer.lic plus any per-plugin
// Doconut.Viewer.<Capability>.lic files alongside it.
builder.Services.AddDoconut();

1. {CurrentDirectory}/wwwroot
2. {CurrentDirectory}/wwwroot/lib
3. AppContext.BaseDirectory

Filenames (checked in each directory above, in order):
  Doconut.Viewer.lic                   — base viewer license
  Doconut.Viewer.<Capability>.lic      — per-plugin license, alongside Doconut.Viewer.lic

نسخ الترخيص إلى مجلد الإخراج الخاص بك

LicensePath، وفحص AppContext.BaseDirectory في البحث التلقائي، كلاهما يحتاج إلى وجود ملف .lic بجوار التطبيق المبني — ليس فقط في wwwroot المصدر الخاص بك. ينسخ تطبيق الاختبار الخاص بـ SDK ذلك في كل بناء باستخدام هدف MSBuild هذا:

<Target Name="CopyLicensesToOutput" AfterTargets="Build">
  <ItemGroup>
    <DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
  </ItemGroup>
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)" SkipUnchangedFiles="true" />
</Target>

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

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

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

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

الإضافات تحتاج إلى قدرات

تسجيل إضافة بدون استحقاق مطابق يختلف: في حالة عدم وجود ترخيص، أو ملف TRIAL قديم، أو ترخيص مدفوع بدون تلك القدرة، يرمي AddDoconut() استثناء InvalidOperationException، وبالتالي لا يبدأ التطبيق. على سبيل المثال، تسجيل إضافة Converter بدون ترخيص يمنح Converter:

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.

الرسالة تخبرك بالإصلاح مباشرةً: إما إزالة استدعاء options.AddPlugin<...>() لتلك الإضافة، أو تثبيت ترخيص مدفوع أو ترخيص مؤقت/تجريبي (NFR) نشط يمنح القدرة. يُسمح للتسجيلات المؤقتة بالبقاء بعد تاريخ انتهاء صلاحيتها حتى يتمكن التطبيق المُكوَّن مسبقًا من التراجع في وقت التشغيل بدلاً من التعطل أثناء إعادة التشغيل؛ بمجرد انتهاء الصلاحية، تُسحب قدراتها.

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

استخدم IDoconutLicenseService، المصدر نفسه للحقائق الذي يستخدمه SDK، لكشف نقطة تشخيص موثوقة أو لتوجيه أعلام الميزات. لا تُرجع محتويات الترخيص أو المفاتيح.

app.MapGet("/api/doconut/license", (IDoconutLicenseService license) => Results.Ok(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
}));

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

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

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

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