Pengaturan Lisensi

Di mana Doconut mencari file lisensi Anda

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

Lisensi dimuat sekali, selama AddDoconut(). Itu merupakan perubahan dari perpustakaan .NET Standard sebelumnya, di mana lisensi diberikan ke instance Viewer atau diatur melalui panggilan 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 — aliran, konten mentah, atau jalur file — serta penemuan otomatis ketika tidak ada yang diatur. Ketika lebih dari satu diatur, urutan prioritasnya tepat:

LicenseStream mengalahkan LicenseContent mengalahkan LicensePath mengalahkan pencarian otomatis.

Berdasarkan jalur

LicensePath diteruskan ke File.Exists persis seperti yang diberikan. Jalur relatif diselesaikan terhadap direktori kerja saat ini proses — bukan folder proyek Anda, dan bukan folder tempat Program.cs berada. Jika jalur tidak dapat diselesaikan, Doconut tidak melempar pengecualian 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. 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 jalur 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, "wwwroot", "Doconut.Viewer.lic");
});

Berdasarkan aliran

LicenseStream dibaca sekali saat startup — berguna ketika lisensi berasal dari penyimpanan rahasia alih‑alih berkas di disk.

csharp
// 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:

csharp
// XML lisensi dari basis data, variabel lingkungan, atau pengelola rahasia —
// tidak ada file di disk. Hanya terlampaui oleh 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
// Tidak mengkonfigurasi apa pun, dan Doconut mencari lisensi sendiri, hanya di dua folder ini:
//   1. {CurrentDirectory}/wwwroot
//   2. {AppContext.BaseDirectory}/wwwroot   (wwwroot di dalam folder output build)
// Ia mencari Doconut.lic terlebih dahulu; jika tidak ada, Doconut.Viewer.lic plus apa pun
// berkas Doconut.Viewer.<Capability>.lic per kapabilitas.
builder.Services.AddDoconut();

Folder penyelidikan, dalam urutan, dan nama berkas yang dicari:

text
1. {CurrentDirectory}/wwwroot
2. {AppContext.BaseDirectory}/wwwroot

Filenames, in order (each one looked for in folder 1, then folder 2):
  Doconut.lic                          — legacy all-in-one license; if found, nothing else is read
  Doconut.Viewer.lic                   — base viewer license
  Doconut.Viewer.<Capability>.lic      — per-capability licenses, read only when Doconut.Viewer.lic was found

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

Jika sebelumnya Anda memberikan List<string> jalur lisensi ke konstruktor Viewer — satu per kemampuan — simpan berkas pendamping itu di sebelah Doconut.Viewer.lic dan biarkan penemuan otomatis mengambilnya. Tidak ada opsi daftar‑jalur pada DoconutOptions.

Salin lisensi ke folder output Anda

Ketika proses tidak dijalankan dari folder proyek — sebuah aplikasi yang dipublikasikan, IIS, sebuah kontainer, atau test runner — percobaan pertama gagal, dan percobaan kedua, {AppContext.BaseDirectory}/wwwroot, harus menemukan file tersebut. Target MSBuild ini menyalin lisensi ke sana pada setiap build:

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

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

Jaga file .lic tetap di luar kontrol sumber — distribusikan 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 mulai, dan penampil berjalan — tetapi 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, daftar hitam, atau build di luar jendela versi lisensi menyebabkan OpenDocumentAsync melempar LicenseException dengan License.RejectionMessage. Lisensi Temporary yang kedaluwarsa tetap beroperasi dalam mode berwatermark. Lisensi berbayar yang tanggal berlangganannya telah lewat tetap berfungsi, bersih, dan dengan kemampuan yang dimilikinya, pada setiap build yang dirilis sebelum tanggal tersebut.

Plugin membutuhkan kemampuan

Mendaftarkan plugin tanpa hak yang sesuai berbeda: untuk lisensi yang hilang, file legacy TRIAL, atau lisensi berbayar tanpa kemampuan tersebut, AddDoconut() melempar InvalidOperationException, sehingga aplikasi tidak dapat dimulai. 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 panggilan options.AddPlugin<...>() untuk plugin itu, atau instal lisensi berbayar atau lisensi Temporary/Demo (NFR) yang aktif yang memberikan kemampuan tersebut. Pendaftaran Temporary 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 yang digunakan oleh SDK, untuk mengekspos endpoint diagnostik yang terautentikasi atau untuk 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 adalah properti kompatibilitas tanpa jalur reload aktif, sehingga mengganti file lisensi memerlukan restart aplikasi.

Matriks pemecahan masalah

GejalaPenyebab kemungkinanPeriksa
Penampil berfungsi tetapi setiap halaman berwatermarkTidak ada lisensi yang dimuat, atau lisensi Temporary telah kedaluwarsaSelesaikan IDoconutLicenseService; verifikasi direktori output dan direktori kerja proses
AddDoconut() melempar untuk pluginLisensi tidak memberikan kemampuan plugin tersebutPeriksa IsCapabilityGranted(...) dan hapus pendaftaran yang tidak Anda beli
Path relatif yang dikonfigurasi berfungsi secara lokal tetapi tidak di IIS/kontainerDirektori kerja proses berubahGunakan AppContext.BaseDirectory atau path absolut
File .lic yang diganti tidak berpengaruhLayanan lisensi singleton sudah dibuatRestart aplikasi
OpenDocumentAsync melempar LicenseExceptionTanda tangan, domain, jendela versi, daftar hitam, atau gerbang runtime plugin menolak lisensiBaca pesan pengecualian/penolakan tanpa mengeksposnya ke klien yang tidak terpercaya
Lisensi per-kemampuan berfungsi sebelumnya tetapi tidak sekarangKode lama memberikan jalur lisensi eksplisit ke konstruktor ViewerPindahkan file .lic pendamping di sebelah Doconut.Viewer.lic dan biarkan penemuan otomatis memuatnya

Langkah selanjutnya

  • Lisensi — kemampuan, tingkatan lisensi, dan memverifikasi apa yang dimuat saat runtime.
  • Pemecahan Masalah — tanda air, lisensi yang ditolak, dan kesalahan kemampuan.

Apakah halaman ini membantu?