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

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

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

گام‌های بعدی

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