Pemecahan Masalah

Mendiagnosa kesalahan umum

Setiap pesan di bawah ini adalah teks literal yang dihasilkan Doconut, diatur berdasarkan gejala. Temukan kesalahan 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 berada pertama dalam pipeline.

HTTP 500 dengan:

text
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: dalam aplikasi minimal-API tambahkan builder.Services.AddDistributedMemoryCache(), atau aplikasi berhenti saat startup dengan Unable to resolve service for type 'IDistributedCache' (aplikasi MVC dan Razor Pages sudah mendaftarkan satu).

Gambar kesalahan di area halaman menampilkan:

text
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 dimulai ulang (kunci sesi baru). Ini adalah lapisan keamanan yang berfungsi sebagaimana dirancang — lihat Konsep Inti → Sesi & Keamanan.

Gambar kesalahan menampilkan:

text
Document session not found. Please re-open document.

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

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:

text
This document type requires the 'Dicom' plugin license.

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

FormatNotSupportedException:

text
Document format '<extension>' is not supported.

Tidak ada penampil — bawaan, plugin, atau khusus — yang mengklaim ekstensi tersebut. Periksa daftar format yang didukung; untuk format Anda sendiri, DoconutOptions.RegisterViewer dapat menambahkan satu.

InvalidDataException — konten file rusak atau tidak cocok dengan ekstensi (misalnya file yang diubah namanya). Validasi unggahan sebelum membuka.

InvalidOperationException:

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

Anda menyelesaikan DocumentConverter tanpa mendaftarkan plugin Converter.

Startup gagal

InvalidOperationException menyebutkan plugin yang terdaftar melalui AddPlugin — lisensi non-temporer saat ini tidak memberikan kemampuan plugin tersebut. Hapus pendaftaran atau instal lisensi yang memberikannya. Lisensi yang hilang dan file legacy TRIAL tidak memberikan kemampuan plugin apa pun.

ArgumentException dari AddDoconut():

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.

Validasi opsi gagal cepat — perbaiki jalur yang bermasalah.

Kesalahan build / ketergantungan

Kesalahan kompilator CS1705, atau pada runtime saat membuka dokumen:

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

Proyek Anda menahan System.Text.Json atau System.Text.Encodings.Web di bawah dependensi 8.0.x yang dideklarasikan oleh Doconut.NET6. Hapus penurunan versi dan biarkan NuGet memulihkan grafik paket (System.Text.Json 8.0.6 dan System.Text.Encodings.Web 8.0.0 dalam paket 26.7.0 yang diaudit).

TypeInitializationException pada file presentasi pertama:

text
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 menghapus atau menimpa dependensi itu — setiap pembukaan PPT/PPTX/PPS/POT/ODP gagal tanpa itu.

Output terlihat salah

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

Dokumen legacy menampilkan teks berantakan — enkoding halaman kode tidak dimuat secara default pada .NET 6. Tambahkan sekali saat startup:

csharp
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 plus System.Drawing.EnableUnixSupport=true. Paket menyediakan System.Drawing.Common 6.0.0 karena itu versi terakhir yang menghormati pengalihan ini.

Fitur bekerja dalam evaluasi, diam dalam produksi

Kejutan klasik saat go-live: lisensi Temporary 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 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 saat dibuka. Word, Excel, dan PowerPoint mengekspos saklar yang sama melalui PdfConfig bersarang mereka.
  • 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 pada default mereka — atur DefaultRender = false sehingga mereka merender melalui proyeksi PDF dengan lapisan teks native. Word, Excel, PowerPoint, TXT, Visio, email, EPUB, dan MHT mencari pada default katalog mereka.
  • objViewer.CanSearch() adalah false setelah inisialisasi — format yang diselesaikan tidak memiliki jalur pencarian standar. Keputusan ini terpisah dari lisensi Search; verifikasi keduanya.

Masih terjebak?

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

Apakah halaman ini membantu?