Pemecahan Masalah

Mendiagnosis kesalahan umum

Setiap pesan di bawah ini adalah teks harfiah yang dihasilkan Doconut, diorganisir 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 yang 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 (penyiapan lintas asal, kebijakan SameSite, klien API tanpa penyimpanan cookie), atau aplikasi di-restart (kunci sesi baru). Ini adalah lapisan keamanan yang berfungsi seperti yang dirancang — lihat Konsep Inti → Sesi & Keamanan. Penolakan tersebut adalah gambar yang disajikan dengan status 200, sehingga monitor yang hanya memeriksa kode status menghitungnya sebagai halaman.

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 mendapatkan 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). Plugin 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. Entitlement 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 kustom — 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 di-rename). 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-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 fail-fast — perbaiki jalur yang bermasalah.

Kesalahan Build / ketergantungan

Kesalahan kompilator CS1705, atau pada waktu berjalan 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 seperti yang dideklarasikan oleh paket).

Output terlihat salah

Halaman membawa watermark — aplikasi berada dalam status evaluasi: tidak ada file lisensi yang ditemukan, lisensi Temporary yang kedaluwarsa, atau domain yang tidak valid. Di bawah lisensi Temporary yang aktif, hanya output plugin yang diberi watermark. Build yang dirilis setelah tanggal berlangganan lisensi berbayar tidak diberi watermark: membuka melempar LicenseException. Periksa IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — referensi IDoconutLicenseService pada halaman Licensing 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 — server tidak memiliki font dokumen. Instal mereka, atau arahkan FontFolders (pada WordConfig/PptConfig) ke folder yang menyimpannya. Pada Linux, lihat di bawah.

Sebuah anotasi gambar muncul di penampil tetapi ekspor memiliki kotak "Image blocked" — host gambar memiliki alamat privat atau loopback, yang ditolak server untuk diambil. Lihat Annotations.

Linux

Membuka dokumen apa pun gagal dengan:

text
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Instal perpustakaan konfigurasi font: apt-get install -y libfontconfig1 (fontconfig pada RHEL/Fedora). Lihat Instalasi.

Membuka dokumen apa pun gagal dengan:

text
The application uses a newer SkiaSharp than Doconut's native graphics library. Add the package SkiaSharp.NativeAssets.Linux at the same version as the application's SkiaSharp; see the Linux section of the Doconut documentation.

Aplikasi merujuk pada SkiaSharp yang lebih baru, secara langsung atau melalui pustaka lain. Tambahkan SkiaSharp.NativeAssets.Linux dengan versi yang sama dengan SkiaSharp tersebut.

Membuka dokumen apa pun gagal dengan:

text
The native graphics library for this platform was not found next to the application. Doconut supports Windows x64/x86 and glibc-based Linux x64 (Alpine/musl is not supported); see the Linux section of the Doconut documentation.

Host tidak merupakan platform yang didukung. Alpine dan distribusi berbasis musl lainnya tidak didukung: gunakan image berbasis Debian atau Ubuntu.

Teks lebih lebar atau lebih sempit dibandingkan di Windows, atau baris terputus secara berbeda — font dokumen tidak diinstal, sehingga Doconut menggunakan font terdekat yang terinstal. Instal font yang kompatibel metrik (fonts-liberation untuk Arial, Times New Roman, dan Courier New; fonts-crosextra-carlito dan fonts-crosextra-caladea untuk Calibri dan Cambria), atau salin font berlisensi Anda ke /usr/share/fonts/ dan jalankan fc-cache -f. Teks Asia yang muncul sebagai kotak kosong memerlukan fonts-noto-cjk.

Fitur berfungsi dalam evaluasi, diam dalam produksi

Kejutan klasik saat go-live: sebuah 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 terdaftar atau DICOM dengan lisensi non-temporary yang tidak memadai 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.
  • Kontennya 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?