Pemecahan Masalah

Setiap pesan di bawah ini adalah teks literal yang dihasilkan Doconut, diatur berdasarkan gejala. Temukan error Anda, terapkan perbaikan.

Penampil tidak menampilkan apa pun

Area penampil kosong, konsol browser penuh dengan 404 untuk /doconut-res/...
UseDoconutResources() tidak ada, atau ditempatkan setelah UseDoconut(). Itu harus menjadi yang pertama dalam pipeline.

HTTP 500 dengan:

Session middleware not configured. Call UseSession() before UseDoconut().

Keamanan token Doconut (aktif secara default) memerlukan status sesi ASP.NET. Tambahkan builder.Services.AddSession() dan app.UseSession() sebelum cabang middleware Doconut. Status sesi juga memerlukan cache: pada aplikasi minimal-API tambahkan builder.Services.AddDistributedMemoryCache(), atau aplikasi akan berhenti saat startup dengan Unable to resolve service for type 'IDistributedCache' (aplikasi MVC dan Razor Pages sudah mendaftarkan satu).

Gambar error di area halaman menampilkan:

You Are Not Authorized To View This Page.

Token dibuka oleh sesi browser yang berbeda. Penyebab umum: cookie sesi tidak mencapai permintaan halaman (pengaturan lintas asal, kebijakan SameSite, klien API tanpa cookie jar), atau aplikasi di‑restart (kunci sesi baru). Ini adalah lapisan keamanan yang berfungsi sebagaimana dirancang — lihat Konsep Inti → Sesi & Keamanan.

Gambar error menampilkan:

Document session not found. Please re-open document.

Token telah kedaluwarsa (jendela geser, default 60 menit — DocOptions.TimeOut) atau sesi telah ditutup. Buka kembali dokumen untuk mendapatkan token baru.

Server baik-baik saja tetapi halaman berperilaku tidak semestinya — tanpa error di mana pun

Ini adalah mode kegagalan yang pertama harus dicurigai setelah melanjutkan sebuah aplikasi. Ketiganya membuat server berfungsi dengan sempurna, merender dokumen dengan benar, dan tidak melaporkan apa pun di konsol browser.

Spinner sibuk yang tidak pernah berhenti.
Callback penampil Anda dideklarasikan sebagai fungsi global yang dinamai sesuai dengan id kontainer — ctlDoc_OnViewerReady() dan teman‑temannya. Penampil sebelumnya mencari nama‑nama itu; yang ini tidak. Penangan yang seharusnya menyembunyikan spinner tidak pernah dijalankan. Kirimkan fungsi‑fungsi tersebut sebagai opsi saja:

objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

Dokumen di balik spinner baik‑baik saja. Daftar lengkap opsi ada di KonfigurasiPenampil.

Ikon penampil atau chrome hilang, halaman lainnya benar.
ResPath kosong atau mengarah ke root aplikasi — benar pada pustaka sebelumnya, salah di sini. Itu harus menyebutkan prefiks yang dipasang oleh UseDoconutResources():

ResPath: 'doconut-res/images'   // or '<your ResourcesPath>/images'

Ubin rusak untuk halaman selanjutnya saat melayani dari penyimpanan bersama.
Halaman yang masih ditulis menjawab 202 Accepted. Klien tanpa retryOn409: true memperlakukan itu sebagai gambar gagal. Lihat Penyebaran Terdistribusi.

Membuka dokumen gagal

LicenseException dengan pesan penolakan — file lisensi ditemukan tetapi ditolak (tanda tangan tidak valid, diubah, masuk daftar hitam, atau build di luar jendela versi/pembaruan lisensi). Keadaan ini memblokir pembukaan (gagal cepat) alih‑alih menurunkan menjadi watermark; baca License.RejectionMessage untuk alasannya.

LicenseException:

This document type requires the 'Dicom' plugin license.

Ekstensi hanya ditangani oleh plugin (di sini: DICOM) dan kemampuan tersebut tidak lagi diberikan. Daftarkan plugin dan verifikasi lic.IsCapabilityGranted(LicenseCapability.Dicom). Hak yang hilang atau tidak cukup (bukan sementara) biasanya gagal lebih awal selama AddDoconut().

FormatNotSupportedException:

Document format '<extension>' is not supported.

Tidak ada penampil — bawaan, plugin, atau kustom — yang mendukung ekstensi tersebut. Periksa daftar format yang didukung; untuk format Anda sendiri, DoconutOptions.RegisterViewer dapat menambahkannya.

InvalidDataException — konten file rusak atau tidak cocok dengan ekstensi (misalnya file yang di‑rename). Validasi unggahan sebelum membuka.

InvalidOperationException:

No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

Anda menyelesaikan DocumentConverter tanpa mendaftarkan plugin Converter.

Gagal Memulai

InvalidOperationException mentioning a plugin registered via AddPlugin — lisensi non‑temporer saat ini tidak memberikan kemampuan plugin tersebut. Hapus pendaftaran atau instal lisensi yang memberikan kemampuan itu. Lisensi yang hilang dan file TRIAL warisan tidak memberikan kemampuan plugin apa pun.

ArgumentException dari AddDoconut():

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.

Validasi opsi fail‑fast — perbaiki jalur yang bermasalah.

Kesalahan Build / Ketergantungan

Paket tidak akan terpasang sama sekali — Doconut.NETStandard 26.8.0 menargetkan netstandard2.1, sehingga NuGet menolak proyek .NET Framework. Ini bukan kesalahan pemulihan yang dapat diselesaikan: .NET Framework tidak dapat mengonsumsi netstandard2.1. Gunakan paket Doconut.NETFramework sebagai gantinya.

Kesalahan kompilator CS1705, atau pada waktu jalan saat membuka dokumen:

Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'

Proyek Anda mem‑pin System.Text.Json atau System.Text.Encodings.Web ke versi di bawah 9.0.x yang menjadi ketergantungan yang dideklarasikan oleh Doconut.NETStandard. Hapus penurunan versi tersebut dan biarkan NuGet memulihkan grafik paket (System.Text.Json 9.0.0 dan System.Text.Encodings.Web 9.0.0 dalam paket 26.8.0 yang diaudit).

Tumpukan kesalahan kompilasi segera setelah meningkatkan paket — ini memang diharapkan. 26.8.0 memiliki permukaan API yang berbeda dari 26.7.0, bukan pembaruan yang kompatibel. Sebagian besar kesalahan berasal dari baris using yang dipindahkan ke namespace akar Doconut; selesaikan dengan mengikuti Migrasi ke .NET Standard 2.1 alih‑alih memperbaikinya satu per satu.

TypeInitializationException pada file presentasi pertama:

Could not load ... System.Drawing.Common, Version=6.0.0.0

Mesin presentasi secara keras memerlukan System.Drawing.Common 6.0.0 (dideklarasikan oleh paket). Jangan hapus atau menimpa ketergantungan itu — setiap pembukaan PPT/PPTX/PPS/POT/ODP akan gagal tanpanya.

Output terlihat salah

Halaman menampilkan watermark — aplikasi berada dalam status evaluasi: file lisensi tidak ditemukan, jendela temporer atau langganan telah kedaluwarsa, atau domain tidak valid. Periksa IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — referensi IDoconutLicenseService pada halaman Licensing menunjukkan endpoint yang sudah siap pakai.

Dokumen lama menampilkan teks berantakan — enkoding kode‑halaman tidak dimuat secara default. Tambahkan sekali pada saat startup:

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Font yang salah atau diganti pada Linux/Docker — kontainer tidak memiliki font dokumen. Arahkan FontFolders (pada WordConfig/PptConfig) ke direktori font yang dipasang.

Presentasi terbuka tetapi gagal merender pada Linux/macOS — renderer PPT/PPTX/PPS/POT/ODP saat ini memerlukan libgdiplus native ditambah System.Drawing.EnableUnixSupport=true. Paket menyertakan System.Drawing.Common 6.0.0 karena itu versi terakhir yang menghormati saklar ini.

Fitur berfungsi dalam evaluasi, tidak berfungsi di produksi

Kejutan klasik saat go‑live: lisensi Temporary yang aktif memberikan semua kemampuan; lisensi yang Anda beli hanya memberikan apa yang Anda beli. Paket pencarian dan anotasi dapat menghilang ketika kemampuannya tidak ada. Plugin Converter atau DICOM yang terdaftar dengan lisensi non‑temporer yang tidak cukup akan gagal selama AddDoconut(). Bandingkan IsCapabilityGranted(...) dengan setiap fitur yang Anda aktifkan sebelum penyebaran.

Pencarian tidak menemukan apa pun (atau terlalu sedikit)

• Untuk PDF langsung, AllowSearch tidak diaktifkan pada saat pembukaan. Word, Excel, dan PowerPoint mengekspos saklar yang sama melalui PdfConfig yang bersarang.
• Konten dipindai/hanya gambar, sehingga Pencarian normal tidak memiliki lapisan teks untuk dicocokkan. Gunakan sumber yang berisi teks atau proyeksi PDF yang mempertahankan teks.
• HTML dan MS Project (MPP) tidak dapat dicari dengan pengaturan default — atur DefaultRender = false sehingga mereka dirender melalui proyeksi PDF dengan lapisan teks native. Word, Excel, PowerPoint, TXT, Visio, email, EPUB, dan MHT dapat dicari dengan pengaturan katalog default mereka.
• objViewer.CanSearch() bernilai false setelah inisialisasi — format yang terdeteksi tidak memiliki jalur pencarian standar. Keputusan ini terpisah dari lisensi Search; verifikasi keduanya.

Masih terjebak?

Isolasikan masalah terhadap aplikasi Quick Start minimal; jika masalah muncul kembali di sana, hubungi dukungan dengan dokumen, Program.cs Anda, dan output diagnostik lisensi.