Pemecahan Masalah

Mendiagnosa kesalahan umum

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

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.

Penampil melaporkan The viewer handler could not be reached (no response).
Permintaan tidak pernah mendapatkan jawaban. Penyebab umum adalah BasePath yang dimulai dengan /: '/doconut' menjadi //doconut/DocImage.axd, sebuah permintaan ke host lain. Tulis tanpa garis miring di depan (BasePath: 'doconut').

Penampil melaporkan Please make sure your middleware is configured.
Endpoint halaman menjawab 404: UseDoconut() tidak dipasang di tempat yang ditunjuk oleh BasePath klien. Dengan app.Map("/doconut", branch => branch.UseDoconut()), klien menggunakan BasePath: 'doconut'.

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 berbunyi:

text
You Are Not Authorized To View This Page.

Token dibuka oleh sesi browser yang berbeda. Penyebab umum: cookie sesi tidak sampai ke permintaan halaman (pengaturan lintas asal, kebijakan SameSite, klien API tanpa wadah cookie), atau aplikasi di‑restart (kunci sesi baru). Ini adalah lapisan keamanan yang berfungsi sebagaimana dirancang — lihat Core Concepts → Sessions & Security. Penolakan tersebut adalah gambar yang disajikan dengan status 200, sehingga monitor yang hanya memeriksa kode status menghitungnya sebagai halaman.

Gambar kesalahan berbunyi:

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 mendapatkan token baru.

Server berfungsi baik tetapi halaman berperilaku tidak semestinya — tanpa kesalahan di mana pun

Ini adalah mode kegagalan yang pertama kali dicurigai setelah melanjutkan sebuah aplikasi. Ketiganya membuat server berfungsi 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:

javascript
function ctlDoc_OnViewerBusy() { /* tampilkan indikator sibuk Anda */ }
function ctlDoc_OnViewerReady() { /* sembunyikan */ }
function ctlDoc_Copy(text) { /* gunakan teks yang disalin */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* laporkan kemajuan */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... opsi yang sudah ada ...
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

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

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

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

Ubin rusak untuk halaman selanjutnya saat melayani dari penyimpanan bersama.
Halaman yang masih sedang 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, telah 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). Plugin tersebut terdaftar, tetapi tidak ada lisensi yang lagi memberikan kemampuan tersebut — biasanya lisensi Sementara yang kedaluwarsa setelah aplikasi dimulai. Instal lisensi yang memberikannya dan verifikasi IsCapabilityGranted(LicenseCapability.Dicom) pada IDoconutLicenseService. Hak non-sementara 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 itu. Periksa daftar format yang didukung; untuk format Anda sendiri, DoconutOptions.RegisterViewer dapat menambahkan satu.

InvalidDataException — konten file rusak atau tidak cocok dengan ekstensinya (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.

Gagal memulai

InvalidOperationException menyebutkan plugin yang terdaftar melalui AddPlugin — lisensi non-sementara 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

Paket tidak akan terpasang sama sekali — Doconut.NETStandard 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 kompiler CS1705, atau pada runtime saat membuka dokumen:

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

Proyek Anda mengunci System.Text.Json atau System.Text.Encodings.Web di bawah dependensi 9.0.x yang dideklarasikan oleh Doconut.NETStandard. Hapus penurunan versi dan biarkan NuGet memulihkan graf paket (System.Text.Json 9.0.0 dan System.Text.Encodings.Web 9.0.0 sebagaimana dinyatakan oleh paket).

Sejumlah besar kesalahan kompilasi segera setelah meningkatkan paket — ini diharapkan. 26.8.0 memiliki permukaan API yang berbeda dari 26.7.0, bukan pembaruan yang kompatibel. Sebagian besar kesalahan adalah baris using yang dipindahkan ke namespace root Doconut; selesaikan melalui Migrasi ke .NET Standard 2.1 alih-alih memperbaikinya satu per satu.

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 hapus atau menimpa ketergantungan itu — setiap pembukaan PPT/PPTX/PPS/POT/ODP akan gagal tanpa itu.

Output terlihat salah

Halaman menampilkan watermark — aplikasi berada dalam status evaluasi: tidak ada file lisensi yang ditemukan, lisensi Sementara yang kedaluwarsa, atau domain tidak valid. Di bawah lisensi Sementara yang aktif, hanya output plugin yang diberi watermark. Build yang dirilis setelah tanggal berlangganan lisensi berbayar tidak diberi watermark: pembukaan melempar LicenseException. 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. Tambahkan sekali saat memulai:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Font yang salah atau diganti — server tidak memiliki font dokumen. Instal font tersebut, atau arahkan FontFolders (pada WordConfig/PptConfig) ke folder yang menyimpannya.

Anotasi gambar muncul di penampil tetapi ekspor memiliki kotak "Gambar diblokir" — host gambar memiliki alamat privat atau loopback, yang ditolak server untuk diambil. Lihat Anotasi.

Fitur berfungsi dalam evaluasi, diam dalam produksi

Kejutan klasik saat go-live: sebuah lisensi Sementara 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. Converter yang terdaftar atau plugin DICOM dengan lisensi non-sementara yang tidak cukup gagal selama AddDoconut(). Bandingkan IsCapabilityGranted(...) dengan setiap fitur yang Anda aktifkan sebelum penyebaran.

Pencarian tidak menemukan apa-apa (atau terlalu sedikit)

  • Untuk PDF langsung, AllowSearch tidak diaktifkan saat dibuka. Word, Excel, dan PowerPoint menampilkan 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 mereka — atur DefaultRender = false sehingga mereka dirender melalui proyeksi PDF dengan lapisan teks asli. Word, Excel, PowerPoint, TXT, Visio, email, EPUB, dan MHT dapat mencari dengan pengaturan default katalog mereka.
  • objViewer.CanSearch() adalah false setelah inisialisasi — format yang dihasilkan tidak memiliki jalur pencarian standar. Keputusan ini terpisah dari lisensi Pencarian; verifikasi keduanya.
  • Halaman membaca nilai kembali dari objViewer.Search(...) — hitungan tiba pada argumen ketiganya, sebuah callback.

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?