Pengaturan Lisensi

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.

Lisensi dimuat sekali, selama AddDoconut(). Ini merupakan perubahan dari perpustakaan .NET Standard sebelumnya, di mana lisensi diberikan ke instance Viewer atau diatur melalui pemanggilan statis Viewer.DoconutLicense(...) / Viewer.SetLicensePlugin(...). Metode-metode tersebut bukan mekanisme startup dalam rilis ini — lihat panduan migrasi.

Empat cara menyediakan lisensi

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

LicenseStream mengalahkan LicenseContent mengalahkan LicensePath mengalahkan pencarian otomatis.

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 pengecualian dan tidak kembali ke pencarian otomatis — ia hanya tidak memuat lisensi dan viewer menampilkan watermark. Pencarian otomatis hanya dijalankan ketika tidak ada LicensePath, LicenseContent, atau LicenseStream yang diatur. Berkas lisensi per‑plugin di folder yang sama (Doconut.Viewer.<Capability>.lic) dibaca bersamanya, sehingga LicensePath dan AddPlugin<...>() bekerja bersama ketika lisensi plugin berada di samping lisensi dasar.

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

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

Berdasarkan stream

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

// Prioritas: LicenseStream > LicenseContent > LicensePath > pencarian otomatis.
builder.Services.AddDoconut(options =>
{
    options.LicenseStream = licenseStream;
});

Berdasarkan konten

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

// Lisensi XML dari basis data, variabel lingkungan, atau manajer rahasia —
// tidak ada file di disk. Hanya dikalahkan oleh LicenseStream.
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

Penemuan otomatis

Tidak mengonfigurasi ketiga sumber eksplisit, dan Doconut mencari lisensi secara otomatis:

// Tidak mengonfigurasi apa pun, dan Doconut mencari lisensi secara otomatis, hanya di dua folder ini:
//   1. {CurrentDirectory}/wwwroot
//   2. {AppContext.BaseDirectory}/wwwroot   (wwwroot di dalam folder output build)
// Ia mencari Doconut.lic terlebih dahulu, kemudian Doconut.Viewer.lic, serta setiap lisensi per-kemampuan
// Doconut.Viewer.<Capability>.lic yang berada di sampingnya.
builder.Services.AddDoconut();

Folder penyelidikan, dalam urutan, dan nama berkas yang dicari di masing-masing:

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

Tidak ada apa pun di luar folder wwwroot yang dibaca: sebuah .lic di folder output itu sendiri, atau di wwwroot/lib, diabaikan.

Jika sebelumnya Anda memberikan List<string> berisi path lisensi ke konstruktor Viewer — satu per kemampuan — pertahankan berkas pendamping tersebut di samping Doconut.Viewer.lic dan biarkan penemuan otomatis mengambilnya. Tidak ada opsi daftar‑path pada DoconutOptions.

Salin lisensi ke folder output Anda

Ketika proses tidak dijalankan dari folder proyek — misalnya aplikasi yang dipublikasikan, IIS, kontainer, atau test runner — percobaan pertama gagal, dan percobaan kedua, {AppContext.BaseDirectory}/wwwroot, harus menemukan file tersebut. Aplikasi uji SDK sendiri menyalin lisensi ke sana pada setiap build dengan target MSBuild berikut:

<Target Name="CopyLicensesToOutput" AfterTargets="Build">
  <ItemGroup>
    <DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
    <StaleOutputLicenses Include="$(OutDir)wwwroot\*.lic" />
  </ItemGroup>
  <!-- Hapus terlebih dahulu, sehingga mengganti nama atau menghapus .lic di wwwroot juga akan mengeluarkannya dari output. -->
  <Delete Files="@(StaleOutputLicenses)" />
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)wwwroot" />
</Target>

Tujuan harus $(OutDir)wwwroot: .lic yang disalin ke akar output tidak akan pernah ditemukan oleh pencarian otomatis. Contoh LicensePath pada halaman ini mengarah ke tempat yang sama.

Jaga agar file .lic tidak masuk ke kontrol sumber — sebarkan bersama aplikasi, atau sisipkan lisensi melalui LicenseContent atau LicenseStream dari penyimpanan rahasia Anda.

Apa yang terjadi tanpa lisensi

Kehilangan lisensi tidak menyebabkan pengecualian. AddDoconut() berhasil, aplikasi berjalan, dan penampil beroperasi — namun setiap halaman menampilkan watermark evaluasi dan tidak ada kemampuan opsional yang diberikan.

File lisensi yang ditemukan tetapi ditolak berbeda. Tanda tangan yang tidak valid, manipulasi, masuk 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 memerlukan kemampuan

Mendaftarkan plugin tanpa hak yang sesuai berbeda: untuk lisensi yang hilang, file TRIAL lama, atau lisensi berbayar yang tidak mencakup kemampuan tersebut, AddDoconut() melempar InvalidOperationException, sehingga aplikasi tidak dapat dijalankan. Misalnya, mendaftarkan plugin Converter tanpa lisensi yang memberikan 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.

Pesan tersebut memberi tahu perbaikan secara langsung: hapus pemanggilan options.AddPlugin<...>() untuk plugin tersebut, atau instal lisensi berbayar atau lisensi Temporary/Demo (NFR) yang aktif yang memberikan kemampuan itu. Pendaftaran sementara diizinkan bertahan melewati tanggal kedaluwarsa sehingga aplikasi yang sudah dikonfigurasi dapat berkurang fungsinya pada waktu berjalan 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 yang terautentikasi atau untuk mengendalikan flag fitur. Jangan mengembalikan isi lisensi atau kunci.

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 muat ulang aktif, sehingga mengganti file lisensi memerlukan restart aplikasi.

Matriks pemecahan masalah

Langkah Selanjutnya

• Lisensi — kemampuan, tingkatan lisensi, dan memverifikasi apa yang dimuat pada waktu berjalan.
• Pemecahan Masalah — tanda air, lisensi yang ditolak, dan kesalahan kemampuan.