การแก้ปัญหา
วินิจฉัยข้อผิดพลาดทั่วไป
ข้อความต่อไปนี้เป็นข้อความดิบที่ 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 พร้อมกับ:
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 จะลงทะเบียนแคชไว้แล้ว)
รูปภาพข้อผิดพลาดในพื้นที่หน้าแสดงข้อความว่า:
You Are Not Authorized To View This Page.โทเคนถูกเปิดโดยเซสชันของเบราว์เซอร์ที่แตกต่าง สาเหตุทั่วไปคือ คุกกี้เซสชันไม่ถึงคำขอของหน้า (การตั้งค่า cross‑origin, นโยบาย SameSite, หรือไคลเอนต์ API ที่ไม่มี cookie jar) หรือแอปรีสตาร์ท (คีย์เซสชันใหม่) สิ่งนี้เป็นชั้นความปลอดภัยทำงานตามออกแบบ — ดู “แนวคิดหลัก → เซสชันและความปลอดภัย” การปฏิเสธเป็นรูปภาพที่ให้สถานะ 200 ดังนั้นตัวตรวจสอบที่ตรวจสอบแค่รหัสสถานะจะนับเป็นหน้า
รูปภาพข้อผิดพลาดแสดงข้อความว่า:
Document session not found. Please re-open document.โทเคนหมดอายุ (หน้าต่างเลื่อน, ค่าเริ่มต้น 60 นาที — DocOptions.TimeOut) หรือเซสชันถูกปิด เปิดเอกสารใหม่เพื่อรับโทเคนใหม่
การเปิดเอกสารล้มเหลว
LicenseException พร้อมข้อความปฏิเสธ — พบไฟล์ใบอนุญาตแต่ถูกปฏิเสธ (ลายเซ็นไม่ถูกต้อง, ถูกดัดแปลง, อยู่ในรายการห้าม, หรือเวอร์ชัน/ช่วงอัปเดตของใบอนุญาตไม่ตรง) สถานะนี้บล็อกการเปิด (fail‑fast) แทนที่จะลดระดับเป็นลายน้ำ; อ่าน License.RejectionMessage เพื่อทราบเหตุผล
LicenseException:
This document type requires the 'Dicom' plugin license.ส่วนขยายนี้จัดการได้เฉพาะโดยปลั๊กอิน (ที่นี่: DICOM) ปลั๊กอินได้ลงทะเบียนแล้ว แต่ไม่มีใบอนุญาตใดให้ความสามารถนี้อีก — ปกติเป็นใบอนุญาตชั่วคราว (Temporary license) ที่หมดอายุหลังจากแอปเริ่มทำงาน ติดตั้งใบอนุญาตที่ให้สิทธิ์และตรวจสอบ IsCapabilityGranted(LicenseCapability.Dicom) บน IDoconutLicenseService การขาดหรือสิทธิ์ที่ไม่เพียงพอแบบไม่ใช่ชั่วคราวมักล้มเหลวตั้งแต่ต้น ระหว่าง AddDoconut()
FormatNotSupportedException:
Document format '<extension>' is not supported.ไม่มีตัวดู — ในตัว, ปลั๊กอิน, หรือแบบกำหนดเอง — รองรับส่วนขยายนี้ ตรวจสอบรายการรูปแบบที่สนับสนุน; สำหรับรูปแบบของคุณเอง, DoconutOptions.RegisterViewer สามารถเพิ่มได้หนึ่งรายการ
InvalidDataException — เนื้อหาไฟล์เสียหายหรือไม่ตรงกับส่วนขยาย (เช่น ไฟล์ที่เปลี่ยนชื่อ) ตรวจสอบการอัปโหลดก่อนเปิด
InvalidOperationException:
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().คุณได้แก้ไข DocumentConverter โดยไม่ได้ลงทะเบียนปลั๊กอิน Converter.
การเริ่มต้นล้มเหลว
InvalidOperationException กล่าวถึงปลั๊กอินที่ลงทะเบียนผ่าน AddPlugin — ใบอนุญาตที่ไม่ใช่ชั่วคราวในปัจจุบันไม่ได้ให้สิทธิ์การทำงานของปลั๊กอินนั้น. ลบการลงทะเบียนหรือทำการติดตั้งใบอนุญาตที่ให้สิทธิ์นั้น. ใบอนุญาตที่หายไปและไฟล์ TRIAL รุ่นเก่าไม่ได้ให้สิทธิ์การทำงานของปลั๊กอินใดๆ.
ArgumentException จาก AddDoconut():
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, หรือขณะรันไทม์เมื่อเปิดเอกสาร:
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. เพิ่มเพียงครั้งเดียวที่การเริ่มต้น:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);ฟอนต์ผิดหรือถูกแทนที่ — เซิร์ฟเวอร์ไม่มีฟอนต์ของเอกสาร. ติดตั้งฟอนต์เหล่านั้น, หรือชี้ FontFolders (บน WordConfig/PptConfig) ไปยังโฟลเดอร์ที่เก็บฟอนต์เหล่านั้น. บน Linux, ดูด้านล่าง.
คำอธิบายภาพแสดงในตัวดูแต่การส่งออกมีกล่อง "Image blocked" — โฮสต์ของภาพมีที่อยู่ส่วนตัวหรือ loopback, ซึ่งเซิร์ฟเวอร์ปฏิเสธการดึงข้อมูล. ดู คำอธิบายภาพ.
Linux
การเปิดเอกสารใดๆ ล้มเหลวด้วย:
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). ดู การติดตั้ง.
การเปิดเอกสารใดๆ ล้มเหลวด้วย:
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 นั้น.
การเปิดเอกสารใดๆ ล้มเหลวด้วย:
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 ของคุณ, และผลลัพธ์การวินิจฉัยใบอนุญาต.
หน้านี้เป็นประโยชน์หรือไม่?