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

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

يتم تحميل الترخيص مرة واحدة، أثناء AddDoconut(). هذا تغيير عن مكتبة .NET Standard السابقة، حيث كان يتم تمرير الترخيص إلى كائن Viewer أو تعيينه عبر استدعاءات Viewer.DoconutLicense(...) / Viewer.SetLicensePlugin(...) الثابتة. هذه الطرق ليست آلية بدء في هذا الإصدار — راجع دليل الترحيل.

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

هناك أربع: ثلاثة مصادر صريحة في 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-capability license, alongside the base license

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

إذا كنت قد مررت مسبقًا List<string> من مسارات الترخيص إلى مُنشئ Viewer — واحد لكل قدرة — احتفظ بتلك الملفات المرافقة بجوار Doconut.Viewer.lic ودع الاكتشاف التلقائي يلتقطها. لا يوجد خيار قائمة بالمسارات في DoconutOptions.

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

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

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

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

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