Sistem Plugin

Perluas penampil dengan plugin

Inti Doconut tetap ramping; fungsionalitas opsional dikirim sebagai plugin — paket NuGet terpisah yang menyumbangkan penampil atau layanan dan diaktifkan oleh lisensi Anda. Halaman ini menjelaskan model pendaftaran, apa yang terjadi saat startup ketika lisensi tidak mencakup sebuah plugin, dan cara memasang penampil Anda sendiri.

Mendaftarkan plugin

Setiap paket plugin mengekspos satu kelas plugin. Daftarkan sekali, di Application_Start:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});
// Plugin terdaftar yang lisensinya hilang melempar di sini, di Application_Start, dan
// situs kemudian menjawab setiap permintaan dengan 500 kosong. Alasannya ada di log peristiwa Windows.

AddPlugin<TPlugin>() membuat plugin dan membiarkannya mendaftarkan kontribusinya dengan DoconutOptions. Semua yang disumbangkan plugin ditandai dengan kapabilitas yang diperlukan plugin, dan DoconutHost.Initialize memeriksa setiap plugin yang terdaftar terhadap lisensi sebelum situs melayani permintaan pertamanya.

Lisensi plugin yang hilang menghentikan situs

Ketika tidak ada lisensi aktif yang memberikan kapabilitas plugin yang terdaftar — tidak ada lisensi sama sekali, file legacy TRIAL, atau lisensi berbayar tanpa kapabilitas tersebut — DoconutHost.Initialize melempar InvalidOperationException dari Application_Start:

text
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.

Di System.Web, pengecualian dalam Application_Start tidak menghasilkan halaman error. Setiap permintaan menjawab 500 kosong, log IIS tidak menunjukkan apa pun yang berguna, dan pesan hanya muncul di log peristiwa Windows (log Aplikasi, sumber ASP.NET). Ketika situs berhenti merespons tepat setelah baris AddPlugin ditambahkan, periksa file lisensi di wwwroot terlebih dahulu — lihat Pengaturan Lisensi.

Kontrak

Sebuah plugin mengimplementasikan antarmuka yang sengaja kecil:

csharp
public interface IDoconutPlugin
{
    string Name { get; }                          // mis. "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // gerbang lisensi
    void Register(IDoconutPluginBuilder builder); // kontribusi penampil/layanan
}

Di dalam Register, pembangun menerima dua jenis kontribusi:

  • builder.RegisterViewer(extension, factory) — sebuah penampil untuk ekstensi file; pabrik mengembalikan IFormatViewer (plugin DICOM mendaftarkan .dcm dan .ima dengan cara ini),
  • builder.RegisterService<TContract>(() => …) — layanan bertipe yang dapat dicari oleh bagian lain dari pipeline.

Kapabilitas dan pengaturan

Kapabilitas adalah unit lisensi. Converter, Dicom, dan Signer dikirim sebagai plugin opsional; Search dan Annotation adalah fitur bawaan yang diatur dengan cara yang sama. Penampil dasar bukan kapabilitas — itu adalah prasyarat, diekspos sebagai IsViewerLicensed pada layanan lisensi.

Validasi startup biasanya menjaga plugin tanpa lisensi keluar dari pipeline permintaan. Pabrik penampil juga menerapkan dua aturan defensif, yang penting jika hak berubah saat situs berjalan:

  • Plugin yang menggantikan penampil bawaan (ia mengklaim ekstensi yang juga ditangani penampil bawaan): dengan kapabilitas berlisensi, penampil plugin menang; tanpa itu, Doconut kembali ke penampil bawaan. Pengguna masih melihat dokumen mereka; mereka hanya tidak mendapatkan perilaku plugin.
  • Format hanya plugin (.dcm dan .ima — DICOM tidak memiliki penampil bawaan): tanpa kapabilitas, pembukaan gagal:
text
LicenseException: This document type requires the 'Dicom' plugin license.

Lisensi Sementara yang aktif memberikan semua kapabilitas. Itu adalah kejutan klasik saat go‑live: baris AddPlugin yang sama yang dijalankan selama evaluasi menghentikan situs ketika lisensi yang dibeli tidak menyertakan salah satu kapabilitas tersebut. Bandingkan IsCapabilityGranted(...) dengan apa yang Anda beli sebelum penyebaran. Dengan tidak ada lisensi sama sekali, tidak ada yang diberikan — lisensi yang hilang bukan lisensi Sementara.

Pengaturan yang sama mencapai browser: Viewer.ReferenceScripts() dan ReferenceCss() menghasilkan file untuk fitur yang diatur lisensi (Pencarian, Anotasi) hanya ketika lisensi memberikannya, sehingga halaman tidak pernah menawarkan fitur yang akan ditolak server.

Peta Fitur dan Plugin

FiturCara diaktifkanKapabilitasKontribusi
AnotasiTerintegrasi dalam penampil; sertakan sumber daya anotasiAnnotationPembuatan di browser, persistensi sesi, ekspor yang dibakar
PencarianTerintegrasi dalam penampil format yang dapat dicari; sertakan sumber daya pencarianSearchIndeks teks asli, sorotan, navigasi hasil
KonverterPasang Doconut.NETFramework.Converter dan daftarkan ConverterPluginConverterLayanan konversi C# dan widget web opsional
DICOMPasang Doconut.NETFramework.Dicom dan daftarkan DicomPluginDicomPenampilan gambar medis untuk .dcm dan .ima
PenandatanganPasang Doconut.NETFramework.Signer dan daftarkan SignerPluginSignerTanda tangan terlihat dan segel digital untuk PDF dan Word: layanan penandatangan C# dan widget web opsional

Anotasi dan Pencarian tidak menggunakan AddPlugin<TPlugin>(). Konverter, DICOM, dan Penandatangan masing‑masing memiliki halaman di bawah Plugin dengan konfigurasi dan penggunaannya. Pada paket ini, DICOM merender halaman, bingkai, dan animasi, tetapi tidak membaca metadata teknis — lihat Plugin DICOM.

Penampil khusus — penangan format Anda sendiri

Anda dapat memasang penampil ke dalam pipeline tanpa menulis paket plugin, langsung di Application_Start:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),                        // mengimplementasikan IFormatViewer
        () => new ImageConfig { ImageResolution = 150 });  // konfigurasi default opsional
});

// Penangani format yang dibuat oleh factory. Ganti anggota ini dengan rendering Anda sendiri.
public sealed class MyCustomViewer : Doconut.Core.Interfaces.IFormatViewer
{
    public ViewerType ViewerType => ViewerType.None;
    public int TotalPages => 0;
    public int DefaultWidth => 0;
    public int DefaultHeight => 0;
    public bool PreferOcr => false;

    public Task LoadAsync(Stream documentStream, BaseConfig config, CancellationToken ct = default)
        => Task.CompletedTask;

    public Task<byte[]> GetPageImageAsync(int pageNumber, CancellationToken ct = default)
        => Task.FromResult(Array.Empty<byte>());

    public void Dispose() { }
}

Penampil khusus memiliki prioritas di atas semua — bawaan dan plugin sekaligus — dan tidak diatur lisensi: mereka adalah kode Anda. Ketika Anda tidak menyediakan konfigurasi default, pabrik menggunakan ImageConfig.

Kesimpulan

  • Plugin didaftarkan secara eksplisit di DoconutHost.Initialize, dan kapabilitasnya divalidasi di sana; hak yang hilang menghentikan situs dengan 500 kosong yang alasannya ada di log peristiwa Windows.
  • Plugin gaya override menurun secara elegan; format hanya plugin gagal dengan LicenseException.
  • Lisensi Sementara yang aktif membuka semua; produksi membuka apa yang Anda beli. Periksa dengan IDoconutLicenseService sebelum mengirim.

Apakah halaman ini membantu?