DoconutExtensions
Registrasi layanan dan middleware
DoconutExtensions (namespace Doconut.Middleware) adalah kelas statis dengan tiga panggilan yang dilakukan setiap host Doconut: satu pendaftaran layanan dan dua pendaftaran middleware.
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession(); // panggil UseSession() sebelum UseDoconut()
app.UseDoconutResources(); // harus didaftarkan sebelum UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());UseDoconut() menjawab setiap permintaan yang mencapainya, jadi pasang pada cabang terpisah dengan app.Map.
AddDoconut
IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)Membangun DoconutOptions, memvalidasi mereka secara fail-fast (lihat DoconutOptions → Validasi Startup), dan mendaftarkan grafik layanan lengkap:
| Layanan | Masa Hidup | Peran |
|---|---|---|
DoconutOptions | Singleton | Objek konfigurasi |
| Layanan cache sesi | Singleton | Token → cache sesi (IMemoryCache juga terdaftar) |
IDoconutLicenseService | Singleton | Lisensi dimuat sekali saat startup (prioritas: LicenseStream → LicenseContent → LicensePath → pencarian otomatis) |
| Pipeline gambar halaman | Singleton | Melakukan pemrosesan gambar untuk halaman (watermark, rotasi, skala, anotasi) |
| Keamanan dokumen (penyimpanan akses) | Singleton | Memberikan izin untuk pengikatan token-ke-sesi |
Viewer | Transient | Fasada buka/tutup publik |
DocumentConverter | Transient | Fasada konversi — memerlukan plugin Converter |
DocumentSigner | Transient | Fasada penandatanganan — memerlukan plugin Signer (lihat Plugin Penandatangan) |
DistributedDocumentPublisher | Transient | Menerbitkan artefak dokumen ke penyimpanan bersama |
Pemeriksaan kesehatan "doconut" | — | Melaporkan status lisensi/kedaluwarsa melalui pemeriksaan kesehatan ASP.NET |
Tidak ada panggilan yang setara dalam pustaka .NET Standard sebelumnya. Itu membangun new Viewer(cache, accessor) per permintaan dan meneruskan opsi ke middleware; keduanya digantikan oleh pendaftaran tunggal ini.
Dua perilaku yang penting untuk diketahui:
- Converter memerlukan plugin-nya. Menyelesaikan
DocumentConvertertanpaoptions.AddPlugin<ConverterPlugin>()melempar:
InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().DocumentSigner mengikuti aturan yang sama: tanpa options.AddPlugin<SignerPlugin>() ia melempar No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().
- Hak plugin divalidasi saat startup. Lisensi yang hilang, file legacy
TRIAL, atau lisensi berbayar tanpa kemampuan plugin yang terdaftar gagal pada waktuAddDoconut(). Pendaftaran Temporary/Demo bertahan melewati tanggal kedaluwarsa, sementara gerbang runtime mencabut kemampuan yang telah kedaluwarsa.
Pemeriksaan kesehatan terintegrasi dengan mekanisme standar ASP.NET Core — petakan jika Anda menginginkan status lisensi pada endpoint kesehatan Anda:
app.MapHealthChecks("/health");UseDoconut
IApplicationBuilder UseDoconut(this IApplicationBuilder app)Menambahkan middleware gambar halaman Doconut. Ia melayani setiap permintaan yang membawa parameter kueri ?token= — halaman, thumbnail, pencarian, anotasi, aksi halaman (tabel permintaan lengkap ada di Konsep Inti → Cara Kerja Penampil) — dan menjawab permintaan lain dengan 404 (atau spanduk ShowDoconutInfo): ia tidak pernah meneruskan permintaan ke sisa pipeline. Pasang pada cabang terpisah, seperti pada contoh di halaman ini. Ketika UnsafeMode adalah false, lapisan keamanan dokumen secara otomatis terhubung sebelum itu.
Tidak memerlukan argumen. Menyertakan instance DoconutOptions di sini adalah bentuk pustaka sebelumnya dan tidak lagi dapat dikompilasi.
Pengaturan umum mempertahankan bentuk permintaan historic DocImage.axd dengan cabang MapWhen (klien kemudian menggunakan BasePath: '/'):
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconutResources
IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)Melayani JS, CSS, gambar, dan font tersemat di DoconutOptions.ResourcesPath (default /doconut-res). Ini adalah file yang Viewer.ReferenceCss() / ReferenceScripts() menghasilkan tag untuknya.
Selalu panggil sebelum UseDoconut(). Jika area penampil tetap kosong dan konsol browser menampilkan 404 untuk /doconut-res/..., panggilan ini hilang atau berada di tempat yang salah.
Ini adalah pengganti yang didukung untuk menghubungkan middleware penanganan sumber daya tersemat secara manual.
Menyajikan dari penyimpanan bersama
Dua pendaftaran tambahan ada untuk penyebaran di mana node yang merender dokumen tidak selalu menjadi node yang menyajikan halamannya. Keduanya dibahas secara menyeluruh dalam Penyebaran Terdistribusi; tanda tangan adalah:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // antrian publikasi latar belakang opt-in
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // penyimpanan pendukung bersama untuk unggahan widgetSisi baca adalah middleware terpisah dari assembly Doconut.Clouds, yang dikirim dalam paket yang sama:
IApplicationBuilder UseDoconutCloud<THandler>(
this IApplicationBuilder app,
Action<CloudOptions>? configure = null,
string pathPrefix = "/doconut-cloud")
where THandler : BaseCloudHandlerUseDoconutWebFarm(...) dan WebFarmOptions tidak ada dalam rilis ini. Lihat panduan migrasi untuk pemetaan pengaturan demi pengaturan.
Ringkasan Urutan
app.UseRouting();
app.UseSession(); // panggil UseSession() sebelum UseDoconut()
app.UseDoconutResources(); // harus didaftarkan sebelum UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut()); // atau cabang MapWhenApakah halaman ini membantu?