การแก้ปัญหา

วินิจฉัยข้อผิดพลาดทั่วไป

ข้อความต่อไปนี้เป็นข้อความดิบที่ Doconut สร้างขึ้น จัดเรียงตามอาการ ค้นหาข้อผิดพลาดของคุณและใช้วิธีแก้

ตัวดูแสดงไม่มีอะไร

พื้นที่ตัวดูว่างเปล่า, คอนโซลเบราว์เซอร์เต็มไปด้วย 404 สำหรับ /doconut-res/...
UseDoconutResources() หายไป หรือวางไว้หลัง UseDoconut(). มันต้องมาก่อนใน pipeline

ตัวดูรายงาน The viewer handler could not be reached (no response).
คำขอไม่เคยได้รับคำตอบ สาเหตุทั่วไปคือ BasePath ที่เริ่มต้นด้วย /: '/doconut' กลายเป็น //doconut/DocImage.axd, คำขอไปยังโฮสต์อื่น เขียนโดยไม่มีสแลชนำหน้า (BasePath: 'doconut')

ตัวดูรายงาน Please make sure your middleware is configured.
จุดสิ้นสุดของหน้าให้คำตอบ 404: UseDoconut() ไม่ได้ถูกเมานท์ที่ตำแหน่งที่ BasePath ของไคลเอนต์ชี้ไป ด้วย app.Map("/doconut", branch => branch.UseDoconut()), ไคลเอนต์ใช้ BasePath: 'doconut'

HTTP 500 พร้อมกับ:

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

Doconut's token security (เปิดใช้งานโดยค่าเริ่มต้น) ต้องการ ASP.NET session state เพิ่ม builder.Services.AddSession() และ app.UseSession() ก่อน สาขา middleware ของ Doconut Session state ยังต้องการแคชด้วย: ในแอป minimal‑API ให้เพิ่ม builder.Services.AddDistributedMemoryCache(), หรือแอปจะหยุดทำงานที่การเริ่มต้นด้วยข้อผิดพลาด Unable to resolve service for type 'IDistributedCache' (แอป MVC และ Razor Pages จะลงทะเบียนแคชไว้แล้ว)

รูปภาพข้อผิดพลาดในพื้นที่หน้าแสดงข้อความว่า:

text
You Are Not Authorized To View This Page.

โทเคนถูกเปิดโดยเซสชันของเบราว์เซอร์ที่แตกต่าง สาเหตุทั่วไปคือ คุกกี้เซสชันไม่ถึงคำขอของหน้า (การตั้งค่า cross‑origin, นโยบาย SameSite, หรือไคลเอนต์ API ที่ไม่มี cookie jar) หรือแอปรีสตาร์ท (คีย์เซสชันใหม่) สิ่งนี้เป็นชั้นความปลอดภัยทำงานตามออกแบบ — ดู “แนวคิดหลัก → เซสชันและความปลอดภัย” การปฏิเสธเป็นรูปภาพที่ให้สถานะ 200 ดังนั้นตัวตรวจสอบที่ตรวจสอบแค่รหัสสถานะจะนับเป็นหน้า

รูปภาพข้อผิดพลาดแสดงข้อความว่า:

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

โทเคนหมดอายุ (หน้าต่างเลื่อน, ค่าเริ่มต้น 60 นาที — DocOptions.TimeOut) หรือเซสชันถูกปิด เปิดเอกสารใหม่เพื่อรับโทเคนใหม่

การเปิดเอกสารล้มเหลว

LicenseException พร้อมข้อความปฏิเสธ — พบไฟล์ใบอนุญาตแต่ถูกปฏิเสธ (ลายเซ็นไม่ถูกต้อง, ถูกดัดแปลง, อยู่ในรายการห้าม, หรือเวอร์ชัน/ช่วงอัปเดตของใบอนุญาตไม่ตรง) สถานะนี้บล็อกการเปิด (fail‑fast) แทนที่จะลดระดับเป็นลายน้ำ; อ่าน License.RejectionMessage เพื่อทราบเหตุผล

LicenseException:

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

ส่วนขยายนี้จัดการได้เฉพาะโดยปลั๊กอิน (ที่นี่: DICOM) ปลั๊กอินได้ลงทะเบียนแล้ว แต่ไม่มีใบอนุญาตใดให้ความสามารถนี้อีก — ปกติเป็นใบอนุญาตชั่วคราว (Temporary license) ที่หมดอายุหลังจากแอปเริ่มทำงาน ติดตั้งใบอนุญาตที่ให้สิทธิ์และตรวจสอบ IsCapabilityGranted(LicenseCapability.Dicom) บน IDoconutLicenseService การขาดหรือสิทธิ์ที่ไม่เพียงพอแบบไม่ใช่ชั่วคราวมักล้มเหลวตั้งแต่ต้น ระหว่าง AddDoconut()

FormatNotSupportedException:

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

ไม่มีตัวดู — ในตัว, ปลั๊กอิน, หรือแบบกำหนดเอง — รองรับส่วนขยายนี้ ตรวจสอบรายการรูปแบบที่สนับสนุน; สำหรับรูปแบบของคุณเอง, DoconutOptions.RegisterViewer สามารถเพิ่มได้หนึ่งรายการ

InvalidDataException — เนื้อหาไฟล์เสียหายหรือไม่ตรงกับส่วนขยาย (เช่น ไฟล์ที่เปลี่ยนชื่อ) ตรวจสอบการอัปโหลดก่อนเปิด

InvalidOperationException:

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

คุณได้แก้ไข DocumentConverter โดยไม่ได้ลงทะเบียนปลั๊กอิน Converter.

การเริ่มต้นล้มเหลว

InvalidOperationException กล่าวถึงปลั๊กอินที่ลงทะเบียนผ่าน AddPlugin — ใบอนุญาตที่ไม่ใช่ชั่วคราวในปัจจุบันไม่ได้ให้สิทธิ์การทำงานของปลั๊กอินนั้น. ลบการลงทะเบียนหรือทำการติดตั้งใบอนุญาตที่ให้สิทธิ์นั้น. ใบอนุญาตที่หายไปและไฟล์ TRIAL รุ่นเก่าไม่ได้ให้สิทธิ์การทำงานของปลั๊กอินใดๆ.

ArgumentException จาก 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.

การตรวจสอบตัวเลือกแบบหยุดทำงานเร็ว — แก้ไขเส้นทางที่ทำให้เกิดข้อผิดพลาด.

ข้อผิดพลาดการสร้าง / ขึ้นอยู่กับ

ข้อผิดพลาดคอมไพเลอร์ CS1705, หรือขณะรันไทม์เมื่อเปิดเอกสาร:

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

โครงการของคุณระบุ System.Text.Json หรือ System.Text.Encodings.Web ให้ต่ำกว่าขึ้นอยู่กับ 8.0.x ที่ประกาศโดย Doconut.NET8. ลบการลดเวอร์ชันและให้ NuGet กู้คืนกราฟแพ็กเกจ (System.Text.Json 8.0.5 และ System.Text.Encodings.Web 8.0.0).

ผลลัพธ์ดูผิดพลาด

หน้ามีลายน้ำ — แอปอยู่ในสถานะการประเมิน: ไม่พบไฟล์ใบอนุญาต, ใบอนุญาต Temporary ที่หมดอายุ, หรือโดเมนที่ไม่ถูกต้อง. ภายใต้ใบอนุญาต Temporary ที่ใช้งานอยู่, ผลลัพธ์จากปลั๊กอินเท่านั้นที่มีลายน้ำ. การสร้างที่ปล่อยหลังจากวันที่สมัครใช้ใบอนุญาตแบบชำระเงินจะไม่มีลายน้ำ: การเปิดทำให้เกิด LicenseException. ตรวจสอบ IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — การอ้างอิง IDoconutLicenseService ของหน้าการให้สิทธิ์แสดงจุดสิ้นสุดที่เตรียมไว้.

เอกสารรุ่นเก่าแสดงข้อความเป็นอักขระผิด — การเข้ารหัสหน้าโค้ดไม่ได้โหลดโดยค่าเริ่มต้นใน .NET 8. เพิ่มเพียงครั้งเดียวที่การเริ่มต้น:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

ฟอนต์ผิดหรือถูกแทนที่ — เซิร์ฟเวอร์ไม่มีฟอนต์ของเอกสาร. ติดตั้งฟอนต์เหล่านั้น, หรือชี้ FontFolders (บน WordConfig/PptConfig) ไปยังโฟลเดอร์ที่เก็บฟอนต์เหล่านั้น. บน Linux, ดูด้านล่าง.

คำอธิบายภาพแสดงในตัวดูแต่การส่งออกมีกล่อง "Image blocked" — โฮสต์ของภาพมีที่อยู่ส่วนตัวหรือ loopback, ซึ่งเซิร์ฟเวอร์ปฏิเสธการดึงข้อมูล. ดู คำอธิบายภาพ.

Linux

การเปิดเอกสารใดๆ ล้มเหลวด้วย:

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.

ติดตั้งไลบรารีการกำหนดค่าฟอนต์: apt-get install -y libfontconfig1 (fontconfig บน RHEL/Fedora). ดู การติดตั้ง.

การเปิดเอกสารใดๆ ล้มเหลวด้วย:

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.

แอปพลิเคชันอ้างอิง SkiaSharp เวอร์ชันใหม่กว่า, โดยตรงหรือผ่านไลบรารีอื่น. เพิ่ม SkiaSharp.NativeAssets.Linux ที่เวอร์ชันเดียวกับ SkiaSharp นั้น.

การเปิดเอกสารใดๆ ล้มเหลวด้วย:

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.

โฮสต์ไม่ใช่แพลตฟอร์มที่รองรับ. Alpine และดิสทริบิวชันที่ใช้ musl อื่นๆ ไม่ได้รับการสนับสนุน: ใช้ภาพที่อิง Debian หรือ Ubuntu.

ข้อความกว้างหรือแคบกว่าบน Windows, หรือการตัดบรรทัดต่างกัน — ฟอนต์ของเอกสารไม่ได้ถูกติดตั้ง, ดังนั้น Doconut จะใช้ฟอนต์ที่ใกล้เคียงที่สุดที่ติดตั้งไว้. ติดตั้งฟอนต์ที่เข้ากันได้กับเมตริก (fonts-liberation สำหรับ Arial, Times New Roman และ Courier New; fonts-crosextra-carlito และ fonts-crosextra-caladea สำหรับ Calibri และ Cambria), หรือคัดลอกฟอนต์ที่คุณมีลิขสิทธิ์ไปยัง /usr/share/fonts/ และรัน fc-cache -f. ข้อความภาษาเอเชียที่แสดงเป็นกล่องว่างต้องการ fonts-noto-cjk.

คุณลักษณะทำงานในระหว่างการประเมิน, เงียบในสภาพการผลิต

ความประหลาดใจคลาสสิกเมื่อเปิดใช้งานจริง: ใบอนุญาตชั่วคราวที่ใช้งานอยู่ให้ทุกความสามารถ; ใบอนุญาตที่คุณซื้อให้เฉพาะสิ่งที่คุณได้ซื้อเท่านั้น. ชุดค้นหาและการทำหมายเหตุอาจหายไปเมื่อความสามารถของมันไม่มีอยู่. ตัวแปลงที่ลงทะเบียนหรือปลั๊กอิน DICOM ที่มีใบอนุญาตไม่ถาวรไม่เพียงพอจะล้มเหลวระหว่าง AddDoconut(). เปรียบเทียบ IsCapabilityGranted(...) กับทุกคุณลักษณะที่คุณเปิดใช้งานก่อนการปรับใช้.

การค้นหาไม่พบอะไร (หรือพบน้อยเกินไป)

  • สำหรับ PDF โดยตรง, AllowSearch ไม่ได้เปิดใช้งานในขณะเปิดไฟล์. Word, Excel, และ PowerPoint แสดงสวิตช์เดียวกันผ่าน PdfConfig ที่ซ้อนกัน.
  • เนื้อหาถูกสแกน/เป็นภาพเท่านั้น, ดังนั้นการค้นปกติจึงไม่มีชั้นข้อความให้จับคู่. ใช้แหล่งที่มีข้อความหรือการฉาย PDF ที่รักษาข้อความไว้.
  • HTML และ MS Project (MPP) ไม่สามารถค้นหาได้ในค่าเริ่มต้น — ตั้งค่า DefaultRender = false เพื่อให้พวกเขาแสดงผลผ่านการฉาย PDF ที่มีชั้นข้อความพื้นเมือง. Word, Excel, PowerPoint, TXT, Visio, email, EPUB, และ MHT ค้นหาได้ในค่าเริ่มต้นของแคตาล็อก.
  • objViewer.CanSearch() เป็น false หลังจากการเริ่มต้น — รูปแบบที่แก้ไขแล้วไม่มีเส้นทางการค้นมาตรฐาน. คำตัดสินนี้แยกจากใบอนุญาตการค้นหา; ตรวจสอบทั้งสอง.
  • หน้าอ่านค่าที่ส่งกลับของ objViewer.Search(...) — จำนวนจะมาถึงในอาร์กิวเมนต์ที่สามของมัน, เป็น callback.

ยังติดอยู่หรือไม่?

แยกปัญหาโดยเปรียบเทียบกับแอป Quick Start ขั้นพื้นฐาน; หากมันเกิดซ้ำที่นั่น, ติดต่อฝ่ายสนับสนุนพร้อมเอกสาร, Program.cs ของคุณ, และผลลัพธ์การวินิจฉัยใบอนุญาต.

หน้านี้เป็นประโยชน์หรือไม่?