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

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

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

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

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

حسب المسار

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

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

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

عبر التدفق

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

// الأولوية: LicenseStream > LicenseContent > LicensePath > البحث التلقائي.
builder.Services.AddDoconut(options =>
{
    options.LicenseStream = licenseStream;
});

عبر المحتوى

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

// ملف XML للترخيص من قاعدة بيانات أو متغيّر بيئي أو مدير أسرار —
// لا ملف على القرص. لا يتفوق عليه سوى LicenseStream.
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

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

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

// لا تقم بأي تكوين، و Doconut يبحث عن الترخيص نفسه، في هذين المجلدين فقط:
//   1. {CurrentDirectory}/wwwroot
//   2. {AppContext.BaseDirectory}/wwwroot   (wwwroot داخل مجلد مخرجات البناء)
// يبحث أولاً عن Doconut.lic، ثم Doconut.Viewer.lic، بالإضافة إلى أي مكوّن إضافي
// ملفات Doconut.Viewer.<Capability>.lic بجانبها.
builder.Services.AddDoconut();

مجلدات الفحص، بالترتيب، وأسماء الملفات (تم فحصها في كل مجلد أعلاه، بالترتيب):

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

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

لا يُقرأ شيء خارج مجلد wwwroot: يتم تجاهل .lic في مجلد الإخراج نفسه، أو في wwwroot/lib.

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

عندما لا يتم تشغيل العملية من مجلد المشروع — تطبيق منشور، IIS، حاوية، أو مُشغل اختبار — يفوت الفحص الأول، ويجب على الفحص الثاني، {AppContext.BaseDirectory}/wwwroot، العثور على الملف. ينسخ تطبيق الاختبار الخاص بـ SDK الترخيصات هناك في كل بناء باستخدام هدف MSBuild هذا:

<Target Name="CopyLicensesToOutput" AfterTargets="Build">
  <ItemGroup>
    <DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
    <StaleOutputLicenses Include="$(OutDir)wwwroot\*.lic" />
  </ItemGroup>
  <!-- احذف أولاً، حتى أن إعادة تسمية أو إزالة ملف .lic في wwwroot يزيله أيضاً من المخرجات. -->
  <Delete Files="@(StaleOutputLicenses)" />
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)wwwroot" />
</Target>

يجب أن يكون الوجهة $(OutDir)wwwroot: لا يُعثر أبدًا على .lic المنسوخ إلى جذر الإخراج بواسطة البحث التلقائي. تُشير أمثلة LicensePath في هذه الصفحة إلى نفس الموقع.

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

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

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

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