Tanpa lisensi, Doconut tetap merender dokumen — setiap halaman hanya menampilkan watermark evaluasi. Halaman ini menjelaskan empat cara menyediakan lisensi, serta prioritas tepat ketika lebih dari satu diatur.

Empat cara menyediakan lisensi

Ada empat: tiga sumber eksplisit pada DoconutOptions — sebuah stream, konten mentah, atau jalur file — serta penemuan otomatis ketika tidak ada yang diatur. Ketika lebih dari satu diatur, prioritasnya tepat:

LicenseStream mengalahkan LicenseContent mengalahkan LicensePath mengalahkan auto-search.

Berdasarkan path

LicensePath diteruskan ke File.Exists persis seperti yang diberikan. Path relatif diselesaikan terhadap direktori kerja saat ini proses — bukan folder proyek Anda, dan bukan folder tempat Program.cs berada. Jika path tidak dapat diselesaikan, Doconut tidak melempar exception dan tidak kembali ke pencarian otomatis — ia hanya tidak memuat lisensi dan penampil menampilkan watermark. Pencarian otomatis hanya dijalankan ketika tidak ada LicensePath, LicenseContent, atau LicenseStream yang diatur.

Lebih disarankan menggunakan path absolut (misalnya dibangun dari IWebHostEnvironment.WebRootPath atau AppContext.BaseDirectory), atau lewati LicensePath sepenuhnya dan bergantung pada penemuan otomatis di bawah.

csharp

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

Berdasarkan stream

LicenseStream dibaca sekali saat startup — berguna ketika lisensi berasal dari penyimpanan rahasia bukan dari file di disk.

csharp

// Precedence: LicenseStream > LicenseContent > LicensePath > auto-search.
builder.Services.AddDoconut(options =>
{
    options.LicenseStream = licenseStream;
});

Berdasarkan konten

LicenseContent menerima teks lisensi itu sendiri — dari variabel lingkungan, basis data, atau manajer rahasia:

csharp

// 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") ?? "";
});

Penemuan otomatis

Jangan konfigurasikan ketiga sumber eksplisit, dan Doconut akan mencari lisensi secara otomatis:

csharp

// 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();

Direktori penyelidikan, dalam urutan, dan nama file yang dicari di masing-masing:

text

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

Salin lisensi ke folder output Anda

LicensePath, dan penyelidikan AppContext.BaseDirectory dari pencarian otomatis, keduanya memerlukan file .lic berada di samping aplikasi yang dibangun — bukan hanya di wwwroot sumber Anda. Aplikasi uji SDK sendiri menyalinnya pada setiap build dengan target MSBuild ini:

xml

<Target Name="CopyLicensesToOutput" AfterTargets="Build">
  <ItemGroup>
    <DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
  </ItemGroup>
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)" SkipUnchangedFiles="true" />
</Target>

Simpan file .lic di luar kontrol sumber — sebarkan bersama aplikasi, atau sisipkan lisensi melalui LicenseContent atau LicenseStream dari penyimpanan rahasia Anda.

Apa yang terjadi tanpa lisensi

Lisensi yang hilang tidak menyebabkan exception. AddDoconut() berhasil, aplikasi berjalan, dan penampil beroperasi — tetapi setiap halaman menampilkan watermark evaluasi dan tidak ada kemampuan opsional yang diberikan.

File lisensi yang ditemukan tetapi ditolak berbeda. Tanda tangan tidak valid, manipulasi, daftar hitam, atau build di luar jendela versi lisensi menyebabkan OpenDocumentAsync melempar LicenseException dengan License.RejectionMessage. Lisensi yang kedaluwarsa secara kalender tanpa pesan penolakan tetap beroperasi dalam mode berwatermark.

Plugin membutuhkan kemampuan

Mendaftarkan plugin tanpa hak yang sesuai berbeda: untuk lisensi yang hilang, file TRIAL lama, atau lisensi berbayar tanpa kemampuan tersebut, AddDoconut() melempar InvalidOperationException, sehingga aplikasi tidak dapat dijalankan. Misalnya, mendaftarkan plugin Converter tanpa lisensi yang memberikan Converter:

text

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.

Pesan tersebut memberi tahu Anda perbaikan secara langsung: hapus pemanggilan options.AddPlugin<...>() untuk plugin tersebut, atau instal lisensi berbayar atau lisensi Temporary/Demo (NFR) yang aktif yang memberikan kemampuan tersebut. Pendaftaran sementara diizinkan bertahan melewati tanggal kedaluwarsa sehingga aplikasi yang sudah dikonfigurasi dapat menurun fungsinya pada runtime alih-alih crash saat restart; setelah kedaluwarsa, kemampuan mereka tetap dicabut.

Verifikasi lisensi yang dimuat

Gunakan IDoconutLicenseService, sumber kebenaran yang sama digunakan oleh SDK, untuk mengekspos endpoint diagnostik terautentikasi atau mengendalikan feature flag. Jangan mengembalikan isi lisensi atau kunci.

csharp

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
}));

Lisensi dibaca selama pendaftaran AddDoconut(). ResetLicense saat ini merupakan properti kompatibilitas tanpa jalur reload aktif, sehingga mengganti file lisensi memerlukan restart aplikasi.

Matriks pemecahan masalah

Gejala	Penyebab kemungkinan	Periksa
Penampil berfungsi tetapi setiap halaman berwatermark	Tidak ada lisensi yang dimuat, atau lisensi kedaluwarsa secara kalender	Selesaikan `IDoconutLicenseService`; verifikasi direktori output dan direktori kerja proses
`AddDoconut()` melempar untuk sebuah plugin	Lisensi tidak memberikan kemampuan plugin tersebut	Periksa `IsCapabilityGranted(...)` dan hapus pendaftaran yang tidak Anda beli
Path relatif yang dikonfigurasi berfungsi secara lokal tetapi tidak di IIS/kontainer	Direktori kerja proses berubah	Gunakan `AppContext.BaseDirectory` atau path absolut
File `.lic` yang diganti tidak berpengaruh	Layanan lisensi singleton sudah dibuat	Restart aplikasi
`OpenDocumentAsync` melempar `LicenseException`	Tanda tangan, domain, jendela versi, daftar hitam, atau gerbang runtime plugin menolak lisensi	Baca pesan pengecualian/penolakan tanpa mengeksposnya ke klien yang tidak dipercaya

Langkah selanjutnya

Lisensi — kemampuan, tingkatan lisensi, dan memverifikasi apa yang dimuat pada runtime.
Pemecahan Masalah — watermark, lisensi yang ditolak, dan kesalahan kemampuan.