การแก้ปัญหา

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

ข้อความต่อไปนี้เป็นข้อความดิบที่ 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 (เปิดโดยค่าเริ่มต้น) ต้องการ 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 ที่หมดอายุหลังจากแอปเริ่มทำงาน ติดตั้งใบอนุญาตที่ให้สิทธิ์และตรวจสอบ IsCapabilityGranted(LicenseCapability.Dicom) บน IDoconutLicenseService. สิทธิ์ที่หายไปหรือไม่เพียงพอแบบไม่ใช่ Temporary มักล้มเหลวก่อนหน้า, ระหว่าง 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.

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

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

ข้อผิดพลาดคอมไพเลอร์ 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.NET6. ลบการลดระดับเวอร์ชันและให้ NuGet กู้คืนกราฟแพ็กเกจ (System.Text.Json 8.0.6 และ System.Text.Encodings.Web 8.0.0 ตามที่แพ็กเกจประกาศ).

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

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

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

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.

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

ความประหลาดใจคลาสสิกเมื่อเปิดใช้งานจริง: ใบอนุญาต Temporary ที่ใช้งานอยู่ให้ทุกความสามารถ; ใบอนุญาตที่คุณซื้อให้เฉพาะสิ่งที่คุณได้ซื้อเท่านั้น. ชุดค้นหาและการทำหมายเหตุอาจหายไปเมื่อความสามารถของมันไม่มีอยู่. ตัวแปลงที่ลงทะเบียนหรือปลั๊กอิน 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 ของคุณ, และผลลัพธ์การวินิจฉัยใบอนุญาต.

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