راه‌اندازی مجوز

بدون مجوز، Doconut همچنان اسناد را رندر می‌کند — هر صفحه فقط دارای یک واترمارک ارزیابی است. این صفحه چهار روش ارائه مجوز را پوشش می‌دهد و ترتیب دقیق اولویت‌ها را زمانی که بیش از یک منبع تنظیم شده باشد، توضیح می‌دهد.

چهار روش برای ارائه مجوز

چهار روش وجود دارد: سه منبع صریح در DoconutOptions — یک جریان، محتوای خام یا مسیر فایل — به‌علاوه کشف خودکار وقتی هیچ‌یک تنظیم نشده باشد. وقتی بیش از یک منبع تنظیم شود، ترتیب اولویت دقیق است:

LicenseStream بر LicenseContent، LicenseContent بر LicensePath و 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 در حال حاضر یک ویژگی سازگاری است بدون مسیر بارگذاری مجدد فعال، بنابراین جایگزینی فایل مجوز نیاز به راه‌اندازی مجدد برنامه دارد.

ماتریس عیب‌یابی

گام‌های بعدی

• مجوزدهی — قابلیت‌ها، سطوح مجوز، و تأیید آنچه در زمان اجرا بارگذاری شده است.
• عیب‌یابی — واترمارک‌ها، مجوزهای رد شده، و خطاهای قابلیت.