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

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

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

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

LicenseStream بر LicenseContent برتری دارد، LicenseContent بر LicensePath برتری دارد، و LicensePath بر جستجوی خودکار برتری دارد.

بر اساس مسیر

LicensePath دقیقاً همان‌گونه که داده شده به File.Exists پاس داده می‌شود. یک مسیر نسبی نسبت به دایرکتوری کاری فعلی فرآیند حل می‌شود — نه پوشه پروژه شما، و نه پوشه‌ای که Program.cs در آن قرار دارد. اگر مسیر حل نشود، Doconut خطایی نمی‌اندازد و به‌طور خودکار به جستجوی خودکار باز نمی‌گردد — به سادگی هیچ مجوزی بارگذاری نمی‌کند و Viewer واترمارک می‌گیرد. جستجوی خودکار فقط زمانی اجرا می‌شود که هیچ‌یک از 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() موفق می‌شود، برنامه شروع می‌شود، و Viewer اجرا می‌شود — اما هر صفحه یک واترمارک ارزیابی دارد و هیچ قابلیت اختیاری اعطا نمی‌شود.

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

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

گام‌های بعدی

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