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

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

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

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

LicenseStream يتفوق على LicenseContent يتفوق على LicensePath يتفوق على auto-search.

حسب المسار

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 هي حاليًا خاصية توافقية بدون مسار إعادة تحميل نشط، لذا استبدال ملف الترخيص يتطلب إعادة تشغيل التطبيق.

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

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

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