Pemecahan Masalah – Doconut Dokumentasi

Banyak kegagalan System.Web tidak menghasilkan pengecualian yang dapat Anda lihat: halaman menjawab 500 kosong, ikon menghasilkan 404, atau permintaan tidak pernah kembali. Halaman ini diatur berdasarkan apa yang Anda amati. Pesan yang dikutip adalah teks literal yang dihasilkan Doconut.

Gejala sekilas

Apa yang Anda lihat	Penyebab paling mungkin	Perbaikan
Setiap permintaan menjawab `500` kosong	Sebuah pengecualian di `Application_Start`: plugin tanpa lisensinya, opsi tidak valid, konfigurasi farm yang tidak lengkap — atau pengalihan binding yang menyebutkan versi yang tidak ada di `bin\`	Log peristiwa Windows, Aplikasi, sumber ASP.NET. Lihat Kegagalan startup
Beberapa halaman MVC menjawab `500` kosong	Razor mengompilasi tampilan pada waktu jalan: fasad `netstandard` tidak ada di `<compilation>`, atau tampilan menggunakan C# lebih baru dari 5 (`?.`, `$"..."`, `nameof`)	Tambahkan fasad (Instalasi); pindahkan logika dari tampilan ke pengontrol
Halaman menampilkan `â€”`, `â€¦` atau serupa alih-alih tanda hubung dan aksen	Berkas halaman tanpa byte-order mark dibaca dengan kode halaman ANSI server	`<globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />`
Konsol peramban menampilkan `404` untuk `HEAD /DocImage.axd?...&page=1`	Handler terdaftar tanpa kata kerja `HEAD`	`verb="GET,HEAD,POST"` pada handler
Dokumen dirender, tetapi ikon bilah alat dan pemutar pemuatan tidak muncul	`ResPath` menunjuk ke akar sumber daya, atau dimulai dengan `/`	`ResPath: 'doconut-res/images'`
Permintaan `/doconut-res/...` menjawab `404`	Modul sumber daya tidak terdaftar, `runAllManagedModulesForAllRequests` dimatikan, atau routing MVC menangkap jalur	Entri `<modules>`, dan `routes.IgnoreRoute("doconut-res/{*pathInfo}")`
Penampil melaporkan `The viewer handler could not be reached (no response).`	`BasePath` dimulai dengan `/` (`'/myapp'` menjadi `//myapp/…`, host lain)	`BasePath: '/'` di akar situs; `'myapp'` dalam direktori virtual
Penampil melaporkan `Please make sure your middleware is configured.`	`DocImage.axd` menjawab `404`: handler tidak berada di `Web.config`, routing MVC menangkapnya, atau `BasePath` menunjuk ke tempat lain	Entri `<handlers>`, `routes.IgnoreRoute("{resource}.axd/{*pathInfo}")`, dan `BasePath`
Setiap halaman menampilkan `You Are Not Authorized To View This Page.`	Dokumen dibuka dalam permintaan tanpa status sesi, status sesi dimatikan, atau cookie sesi tidak mencapai `DocImage.axd`	Lihat Tidak diizinkan
Konversi Web Forms tidak pernah kembali	Halaman terblokir pada `ConvertAsync` — deadlock	`Async="true"` + `RegisterAsyncTask` (Plugin Konverter)
Setiap halaman membawa watermark evaluasi	Tidak ada lisensi yang ditemukan — tidak ada di `<site root>\wwwroot`	Pengaturan Lisensi
Widget dimuat, tetapi aksi pertamanya menjawab `404`	Widget tidak diaktifkan, atau `basePath` tidak `'/DocImage.axd'`	`options.Add…Widget()`, dan `basePath: '/DocImage.axd'`
Dokumen pertama setelah situs dimulai atau di-recycle memakan waktu satu menit atau lebih; dokumen selanjutnya cepat	Mesin dokumen dimuat pada pembukaan pertama, dan antivirus waktu nyata memindainya saat dimuat	Panaskan situs dan pertahankan pool berjalan — lihat Dokumen pertama setelah start
Unggahan besar menampilkan halaman error IIS	Unggahan melebihi `maxRequestLength` (KB) atau `maxAllowedContentLength` (byte)	Tingkatkan keduanya di atas file atau batas widget terbesar Anda

Kegagalan startup

Sebuah pengecualian yang dilempar di Application_Start tidak sampai ke peramban: setiap permintaan menjawab 500 kosong, dan log IIS tidak menunjukkan apa pun yang berguna. Pengecualian berada di log peristiwa Windows (Event Viewer → Windows Logs → Application, sumber ASP.NET). Yang biasanya:

Plugin tanpa lisensinya:

text

The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

Doconut.Viewer.<Capability>.lic plugin harus berada di wwwroot, di samping Doconut.Viewer.lic. Lisensi yang hilang dan berkas legacy TRIAL tidak memberikan kemampuan plugin apapun.

Opsi tidak valid:

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.

Sebuah assembly yang tidak dapat dimuat. ASP.NET memuat setiap assembly di bin\ saat aplikasi dimulai, sehingga pengalihan binding di Web.config yang menyebutkan versi yang tidak ada di bin\ menghentikan seluruh situs. Salin pengalihan yang dihasilkan NuGet (untuk proyek bergaya SDK, dari bin\<YourApp>.dll.config) alih-alih mengeditnya secara manual, dan salin lagi setelah pembaruan paket.

Anda Tidak Diizinkan Untuk Melihat Halaman Ini.

Halaman ditolak karena sesi ASP.NET yang meminta tidak pernah diberikan dokumen. Periksa, secara berurutan:

Pembukaan dijalankan dengan status sesi. Kontroler MVC dan halaman Web Forms memilikinya. Sebuah IHttpHandler khusus yang membuka dokumen harus mengimplementasikan System.Web.SessionState.IRequiresSessionState, atau tidak memiliki sesi untuk diberikan.
Status sesi aktif. <sessionState mode="Off" /> menolak setiap halaman.
Cookie mencapai penangan. Permintaan same-origin widget membawa ASP.NET_SessionId; skrip, panggilan server-ke-server, atau halaman cross-origin tanpa cookie tidak.
Web farm: pembukaan mengikat browser (DocOptions.BrowserId) dan halaman melewatkan tiket (objViewer.View(token, access)); setiap node menggunakan kunci penandatanganan yang sama.

Penolakan tersebut adalah gambar yang disajikan dengan status 200, sekitar 2 KB. Monitor yang hanya memeriksa kode status menghitungnya sebagai halaman.

Sesi dokumen tidak ditemukan. Silakan buka kembali dokumen.

Token kedaluwarsa (jendela geser, DocOptions.TimeOut, default 60 menit), dokumen ditutup, atau — pada satu server — kolam aplikasi di‑recycle. Recycle terjadi sesuai jadwal, pada setiap penyuntingan Web.config, dan setelah batas waktu idle kolam (20 menit secara default di IIS). Buka kembali dokumen untuk mendapatkan token baru.

Membuka dokumen gagal

LicenseException dengan alasan penolakan — file lisensi ditemukan tetapi ditolak (tanda tangan tidak valid, manipulasi, pemblokiran, atau build di luar jendela versi lisensi). Pembukaan diblokir alih‑alih diberi watermark.

LicenseException:

text

This document type requires the 'Dicom' plugin license.

Ekstensi hanya ditangani oleh plugin (di sini DICOM) yang kemampuannya tidak diberikan.

FormatNotSupportedException — tidak ada penampil (bawaan, plugin, atau khusus) yang mengklaim ekstensi tersebut. DoconutOptions.RegisterViewer dapat menambahkan satu untuk format Anda sendiri.

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

InvalidOperationException:

text

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

DocumentConverter diselesaikan tanpa mendaftarkan plugin Converter.

Output terlihat salah

Halaman membawa watermark — tidak ada lisensi yang ditemukan, atau lisensi telah kedaluwarsa atau tidak mencakup versi ini. Di IIS, lisensi harus berada di wwwroot di bawah root situs (AppContext.BaseDirectory\wwwroot), bukan di bin\. Periksa IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, License.RejectionMessage).

Dokumen lama menampilkan teks berantakan — daftarkan enkoding kode halaman sekali, saat startup:

csharp

// Global.asax.cs, Application_Start - sebelum DoconutHost.Initialize.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Font yang salah atau diganti — server tidak memiliki font dokumen. Windows Server tanpa Office memiliki jauh lebih sedikit font dibandingkan mesin pengembangan. Instal font, atau arahkan FontFolders (pada WordConfig dan PptConfig) ke folder yang menyimpannya.

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

Fitur berfungsi dalam evaluasi, tidak aktif di produksi

Lisensi Sementara aktif memberikan semua kemampuan; lisensi yang Anda beli hanya memberikan apa yang Anda beli. Tanpa kemampuan, file Pencarian atau Anotasi tidak dihasilkan, dan plugin yang terdaftar menghentikan situs saat startup. Bandingkan IsCapabilityGranted(...) dengan setiap fitur yang Anda gunakan sebelum menerapkan.

Pencarian tidak menemukan apa-apa (atau terlalu sedikit)

Untuk PDF, AllowSearch tidak diaktifkan saat dokumen dibuka — secara default menjadi false. Word, Excel, dan PowerPoint memiliki saklar yang sama.
Konten dipindai atau hanya gambar, sehingga tidak ada lapisan teks untuk dicocokkan.
HTML dan Microsoft Project (MPP) tidak dapat dicari secara default: atur DefaultRender = false sehingga mereka dirender melalui proyeksi PDF dengan teks.
objViewer.CanSearch() adalah false setelah inisialisasi: format yang diresolusikan tidak memiliki jalur pencarian. Ini terpisah dari lisensi Pencarian; periksa keduanya.
Halaman membaca nilai kembali dari objViewer.Search(...) — hitungan tiba di argumen ketiganya, sebuah callback.

Masih terjebak?

Reproduksi masalah dengan pengaturan minimal dari Panduan Cepat. Jika masalah terulang di sana, hubungi dukungan dengan dokumen, Global.asax.cs Anda, bagian Doconut dari Web.config, dan entri log peristiwa Windows jika ada.