Instalasi

Tambahkan Doconut ke proyek .NET 8 Anda

Penampil Doconut dasar untuk .NET 8 hadir sebagai satu paket NuGet yang dapat dipasang ke aplikasi ASP.NET Core apa pun. Plugin opsional menggunakan paket terpisah. Halaman ini menginstal paket dasar dan mendaftarkan middleware — minimum yang diperlukan sebelum render pertama Anda.

Persyaratan

Paket ini berjalan pada platform berikut:

PlatformDidukung
Windows x64 / x86Yes
Linux x64, glibc-based (Debian, Ubuntu, the official mcr.microsoft.com/dotnet/aspnet:8.0 image)Yes
Alpine and other musl-based distributionsNo
macOSNo

Di Linux, instal perpustakaan konfigurasi font sebelum dokumen pertama dibuka:

bash
apt-get update && apt-get install -y libfontconfig1

Pada RHEL, Fedora, dan distribusi serupa paketnya adalah fontconfig (dnf install -y fontconfig). Itu satu-satunya paket sistem yang dibutuhkan Doconut: perpustakaan native yang digunakannya dikirim dalam paket NuGet, dan libgdiplus tidak diperlukan. Halaman digambar dengan font yang terpasang di server, jadi lihat Pemecahan Masalah untuk font dan pesan kesalahan Linux.

Instal paket

bash
dotnet add package Doconut.NET8

Perintah tanpa versi menginstal rilis stabil terbaru. Untuk mengunci rilis yang dijelaskan dalam dokumentasi ini, berikan versi sebagai opsi terpisah:

bash
dotnet add package Doconut.NET8 --version 26.10.0

Doconut.NET8 adalah ID paket. Akhiran versi merupakan bagian dari nama file Doconut.NET8.<version>.nupkg yang diunduh dan bukan bagian dari ID.

Daftarkan Doconut

AddDoconut() adalah satu-satunya titik masuk pendaftaran — ada satu overload, dan ia menghubungkan layanan Viewer, layanan lisensi, serta infrastruktur rendering ke dalam kontainer DI.

Dua pemanggilan middleware menyelesaikan pengaturan, dan urutannya penting: UseDoconutResources() harus dijalankan sebelum UseDoconut(). UseDoconut() adalah middleware terminal, sehingga memanggilnya terlebih dahulu berarti setiap permintaan ke aset /doconut-res tidak pernah mencapai penangan sumber daya dan menghasilkan 404. UseDoconut() menjawab setiap permintaan yang mencapainya, jadi pasanglah pada cabang terpisah dengan app.Map. Penyambungan sesi juga diperlukan — keamanan dokumen default Doconut memvalidasi setiap permintaan halaman terhadap status sesi ASP.NET.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // status sesi membutuhkan cache (MVC/Razor Pages sudah menambah satu)
builder.Services.AddSession(); // Keamanan dokumen Doconut bergantung pada status sesi ASP.NET

app.UseSession();          // panggil UseSession() sebelum UseDoconut()
app.UseDoconutResources(); // harus didaftarkan sebelum UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

Semua opsi

DoconutOptions menerima properti yang dapat diatur berikut ini. Semua bersifat opsional — nilai default di bawah ini berlaku ketika properti dibiarkan tidak diatur.

PropertiDefaultDeskripsi
ShowDoconutInfofalseKetika true, permintaan tanpa token mengembalikan banner versi alih-alih 404. Berguna sebagai pemeriksaan cepat; matikan di produksi.
UnsafeModefalseKetika true, melewatkan pemeriksaan keamanan sesi ASP.NET pada permintaan halaman. Matikan di produksi.
MiddlewarePath"/doconut"Nilai koordinasi untuk endpoint halaman-gambar. Nilai ini divalidasi, tetapi tidak memasang cabang sendiri; pertahankan agar selaras dengan pemetaan UseDoconut() yang sebenarnya dan BasePath klien.
ResourcesPath"/doconut-res"Lokasi sumber daya JS/CSS/gambar tersemat yang dilayani.
LicensePath"" (empty string)Jalur ke file lisensi. Kosong berarti melanjutkan ke sumber berikutnya, lalu pencarian otomatis.
LicenseContent"" (empty string)Konten lisensi mentah — dari variabel lingkungan, manajer rahasia, atau basis data.
LicenseStreamnullLisensi sebagai aliran, dibaca sekali saat startup.
ResetLicensefalseBendera kompatibilitas yang disiapkan. Layanan .NET 8 saat ini membaca lisensi selama AddDoconut(); restart aplikasi setelah mengganti lisensi.
MaxConcurrentEditorSessions200Jumlah maksimum sesi editor live (dokumen yang dibuka dengan DocOptions.EditMode). Di atasnya, sesi editor idle yang paling lama tidak digunakan akan ditutup. Sesi penampil normal tidak pernah dihitung. 0 atau nilai negatif berarti tidak ada batas.
EditorSnapshotEveryOps50Dengan persistensi editor diaktifkan (AddDoconutEditorPersistence), ambil snapshot dokumen live setiap N perubahan yang tercatat. 0 atau nilai negatif tidak pernah mengambil snapshot di tengah sesi. Tidak berpengaruh ketika persistensi dinonaktifkan.

Prioritas lisensi ketika lebih dari satu sumber diatur: LicenseStream mengalahkan LicenseContent mengalahkan LicensePath mengalahkan pencarian otomatis — lihat License Setup.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.MiddlewarePath  = "/doconut";     // koordinasikan dengan pemetaan aplikasi dan BasePath klien
    options.ResourcesPath   = "/doconut-res"; // dari mana JS/CSS/gambar viewer disajikan
    options.UnsafeMode      = false;          // jaga keamanan sesi tetap aktif
    options.ShowDoconutInfo = false;
});

Langkah selanjutnya

Apakah halaman ini membantu?