การแก้ไขปัญหา

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

ข้อความต่อไปนี้เป็นข้อความดิบที่ 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) หรือแอปรีสตาร์ท (คีย์เซสชันใหม่) สิ่งนี้เป็นชั้นความปลอดภัยทำงานตามที่ออกแบบ — ดู Core Concepts → Sessions & Security การปฏิเสธเป็นรูปภาพที่ให้สถานะ 200, ดังนั้นตัวตรวจสอบที่ตรวจสอบเฉพาะรหัสสถานะจะนับเป็นหน้า.

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

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

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

เซิร์ฟเวอร์ทำงานปกติแต่หน้ามีพฤติกรรมแปลก — ไม่มีข้อผิดพลาดใดๆ

นี่คือโหมดความล้มเหลวที่ควรสงสัยเป็นอันดับแรกหลังจากย้ายแอปพลิเคชันไป ทั้งสามกรณีทำให้เซิร์ฟเวอร์ทำงานสมบูรณ์, แสดงเอกสารอย่างถูกต้อง, และไม่มีการรายงานใดในคอนโซลเบราว์เซอร์

สปินเนอร์ทำงานตลอดเวลา. คอลแบ็กของตัวดูของคุณถูกประกาศเป็นฟังก์ชันระดับ global ที่ตั้งชื่อตาม id ของคอนเทนเนอร์ — ctlDoc_OnViewerReady() และเพื่อนร่วมงาน ตัวดูก่อนหน้าค้นหาชื่อเหล่านั้น; ตัวนี้ไม่ทำเช่นนั้น ตัวจัดการที่ควรซ่อนสปินเนอร์ก็ไม่ทำงานเลย ส่งฟังก์ชันเป็นตัวเลือกแทน:

javascript
function ctlDoc_OnViewerBusy() { /* แสดงตัวบ่งชี้กำลังทำงานของคุณ */ }
function ctlDoc_OnViewerReady() { /* ซ่อนมัน */ }
function ctlDoc_Copy(text) { /* ใช้ข้อความที่คัดลอก */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* รายงานความคืบหน้า */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... ตัวเลือกที่มีอยู่ของคุณ ...
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

เอกสารที่อยู่หลังสปินเนอร์นั้นปกติ รายการตัวเลือกทั้งหมดอยู่ใน ViewerConfig.

ไอคอนหรือโครมของตัวดูหายไป, หน้าอื่นๆ ถูกต้อง. ResPath ว่างเปล่าหรือชี้ไปที่รูทของแอป — ถูกต้องในไลบรารีก่อนหน้า, ผิดที่นี่ มันต้องระบุพรีฟิกซ์ที่ UseDoconutResources() เมานท์:

javascript
ResPath: 'doconut-res/images'   // หรือ '<your ResourcesPath>/images'

แผ่นภาพเสียสำหรับหน้าถัดไปเมื่อให้บริการจากที่เก็บข้อมูลร่วม. หน้า ที่ยังคงเขียนอยู่ตอบกลับด้วย 202 Accepted. ไคลเอนต์ที่ไม่มี retryOn409: true จะถือว่าเป็นภาพล้มเหลว ดู Distributed Deployments.

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

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

LicenseException:

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

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

FormatNotSupportedException:

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

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

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

InvalidOperationException:

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

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

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

InvalidOperationException ที่กล่าวถึงปลั๊กอินที่ลงทะเบียนผ่าน AddPlugin — ใบอนุญาต non‑temporary ปัจจุบันไม่ได้ให้ความสามารถนั้นกับปลั๊กอิน. ลบการลงทะเบียนหรือทำการติดตั้งใบอนุญาตที่ให้สิทธิ์นั้น. การขาดใบอนุญาตและไฟล์ legacy 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 — แก้ไขเส้นทางที่ทำให้เกิดปัญหา.

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

แพคเกจไม่สามารถติดตั้งได้เลย — Doconut.NETStandard targets
netstandard2.1, ดังนั้น NuGet ปฏิเสธโครงการ .NET Framework. นี่ไม่ใช่ข้อผิดพลาดการกู้คืนที่แก้ได้: .NET Framework ไม่สามารถใช้ netstandard2.1. ใช้แพคเกจ Doconut.NETFramework แทน.

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

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

โครงการของคุณกำหนด System.Text.Json หรือ System.Text.Encodings.Web ไว้ต่ำกว่า dependencies 9.0.x ที่ประกาศโดย Doconut.NETStandard. ลบการดาวน์เกรดและให้ NuGet กู้คืนกราฟแพคเกจ (System.Text.Json 9.0.0 และ System.Text.Encodings.Web 9.0.0 ตามที่แพคเกจประกาศ).

ผนังของข้อผิดพลาดการคอมไพล์ปรากฏทันทีหลังจากอัปเดตแพคเกจ — นี่เป็นสิ่งที่คาดหวัง.
26.8.0 มี API surface ที่แตกต่างจาก 26.7.0, ไม่ใช่การอัปเดตที่เข้ากันได้. ส่วนใหญ่ของข้อผิดพลาดเป็นบรรทัด using ที่ย้ายไปยัง namespace ราก Doconut; ทำงานผ่าน ย้ายไปยัง .NET Standard 2.1 แทนการแก้ไขทีละบรรทัด.

TypeInitializationException บนไฟล์พรีเซนเทชันแรก:

text
Could not load ... System.Drawing.Common, Version=6.0.0.0

เครื่องยนต์พรีเซนเทชันต้องการ System.Drawing.Common 6.0.0 อย่างเข้มงวด (ที่ประกาศโดยแพคเกจ). อย่าลบหรือแทนที่ dependency นั้น — การเปิดทุกไฟล์ PPT/PPTX/PPS/POT/ODP จะล้มเหลหากไม่มีมัน.

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

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

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

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

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

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

ฟีเจอร์ทำงานในระหว่างการประเมิน, เงียบในสภาพการผลิต

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

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