DoconutOptions – Doconut Dokumentasi

DoconutOptions (namespace Doconut) adalah objek konfigurasi tunggal untuk seluruh SDK. Anda mengkonfigurasikannya sekali, di dalam AddDoconut(), dan objek ini didaftarkan sebagai singleton.

Ini merupakan perubahan lokasi sekaligus bentuk. Pada pustaka .NET Standard sebelumnya, sebuah instance DoconutOptions dibangun pada waktu pipeline dan diberikan ke UseDoconut(new DoconutOptions { … }). Di sini middleware tidak menerima opsi apa pun — semua diatur selama pendaftaran layanan.

csharp

builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.UnsafeMode      = false;
    options.ShowDoconutInfo = false;
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

Properti

Tipe	Properti	Default	Deskripsi
`bool`	`ShowDoconutInfo`	`false`	Ketika `true`, permintaan middleware tanpa token mengembalikan banner versi alih-alih 404. Berguna sebagai pemeriksaan cepat; biarkan `false` di produksi.
`bool`	`UnsafeMode`	`false`	Ketika `true`, melewati pemeriksaan keamanan sesi ASP.NET pada permintaan halaman. Biarkan `false` di produksi pada satu node (lihat Konsep Inti → Sesi & Keamanan). Sebelumnya ditulis `UnSafeMode`.
`string`	`MiddlewarePath`	`"/doconut"`	Nilai koordinasi untuk endpoint halaman‑gambar. Nilai ini divalidasi, tetapi tidak memasang cabang pipeline; pertahankan agar selaras dengan pemetaan `UseDoconut()` yang sebenarnya dan `BasePath` klien.
`string`	`ResourcesPath`	`"/doconut-res"`	Awalan jalur URL untuk sumber daya JS/CSS/gambar/font yang disematkan.
`string`	`LicensePath`	`""`	Jalur ke file lisensi. Kosong → sumber lisensi berikutnya, kemudian penemuan otomatis; tidak ada yang ditemukan → status evaluasi berwatermark tanpa kemampuan.
`string`	`LicenseContent`	`""`	Konten lisensi XML mentah (basis data, variabel lingkungan, manajer rahasia). Memiliki prioritas lebih tinggi daripada `LicensePath`.
`Stream?`	`LicenseStream`	`null`	Lisensi sebagai aliran, dibaca sekali saat startup. Memiliki prioritas lebih tinggi daripada kedua sumber lainnya.
`bool`	`ResetLicense`	`false`	Bendera kompatibilitas yang disiapkan. Implementasi saat ini tidak menggunakannya; restart aplikasi setelah mengganti lisensi.
`DoconutPluginRegistry`	`PluginRegistry`	—	Registri hanya‑baca yang mengumpulkan kontribusi plugin; digunakan oleh pabrik penampil. Isi melalui `AddPlugin<T>()`.

Prioritas lisensi (ditegakkan pada pendaftaran layanan): LicenseStream → LicenseContent → LicensePath → penemuan otomatis (lihat Memulai → Penyiapan Lisensi).

Metode

AddPlugin()

text

DoconutOptions AddPlugin<TPlugin>() where TPlugin : IDoconutPlugin, new()

Gunakan metode ini untuk paket Converter dan DICOM yang tersedia secara opt‑in. Anotasi dan pencarian normal adalah fitur berlisensi bawaan dan tidak menggunakan AddPlugin<TPlugin>().

Mendaftarkan plugin pihak pertama (Converter, DICOM). Fluent — mengembalikan instance opsi. AddDoconut() melempar InvalidOperationException untuk lisensi yang hilang, file TRIAL lama, atau lisensi berbayar yang tidak memberikan kemampuan plugin. Pendaftaran Temporary/Demo dipertahankan setelah kedaluwarsa dan menjadi tunduk pada gerbang runtime (lihat Konsep Inti → Sistem Plugin).

Widget Converter opt‑in diaktifkan dengan AddConverterWidget() dan ditampilkan melalui properti hanya‑baca ConverterWidget; opsi‑opsinya didokumentasikan pada halaman Plugin → Plugin Konverter.

RegisterViewer(extension, factory, defaultConfig?)

text

DoconutOptions RegisterViewer(
    string extension,                    // ".myext" — leading dot optional
    Func<IFormatViewer> factory,
    Func<BaseConfig>? defaultConfig = null)

Mendaftarkan penampil khusus untuk ekstensi file. Penampil khusus memiliki prioritas lebih tinggi daripada penampil bawaan dan plugin serta tidak dibatasi lisensi. Ketika defaultConfig dihilangkan dan dokumen dibuka tanpa konfigurasi eksplisit, sebuah ImageConfig digunakan.

Melempar ArgumentException (Extension must be a non-empty file extension.) untuk ekstensi kosong dan ArgumentNullException untuk pabrik (factory) yang null.

Validasi Startup

AddDoconut() memvalidasi opsi fail‑fast, sehingga miskonfigurasi muncul sebagai pengecualian yang jelas pada saat startup alih‑alih 404 yang membingungkan pada waktu permintaan:

text

DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

Konfigurasi Umum

csharp

// Production: explicit license, everything locked down (all security defaults)
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = builder.Configuration["Doconut:License"] ?? "";
});

// Custom paths (e.g. to avoid a route conflict)
builder.Services.AddDoconut(options =>
{
    options.MiddlewarePath = "/docs-engine";
    options.ResourcesPath  = "/docs-assets";
});

Saat Anda mengubah ResourcesPath, pastikan ResPath widget klien tetap sinkron (lihat ViewerConfig). Ini adalah salah satu dari dua pengaturan sisi klien yang gagal tanpa pesan error.

MiddlewarePath bukan pemetaan rute otomatis ASP.NET Core. Jika Doconut harus menjawab hanya di bawah awalan khusus, pasang UseDoconut() pada cabang tersebut (misalnya dengan app.Map("/docs-engine", branch => branch.UseDoconut())) dan atur BasePath klien ke URL yang sama. Aplikasi referensi justru mempertahankan bentuk permintaan historis DocImage.axd pada cabang MapWhen dengan BasePath: '/'.