การฝัง Doconut ในแอปพลิเคชันเว็บของคุณ: คู่มือเชิงปฏิบัติ

ตัวดู Doconut เป็นไลบรารี .NET สำหรับการดูเอกสารที่ออกแบบให้แสดง PDF, Office, CAD, รูปภาพ และครอบครัวเอกสารที่รองรับอื่น ๆ ภายในแอปพลิเคชัน การรวม Doconut อย่างเหมาะสมไม่ได้หมายถึงการหาโค้ดสั้นที่สุดเท่านั้น แต่เป็นการเลือกขอบเขตที่ชัดเจนระหว่างแอปพลิเคชันของคุณ, ตัวดู, และเบราว์เซอร์

ศูนย์เอกสาร Doconut มีลิงก์ไปยังเส้นทางการตั้งค่าที่ได้รับการดูแลสำหรับประเภทโครงการ .NET ที่รองรับ ใช้คู่มือที่ตรงกับเวอร์ชันที่ติดตั้งในแอปพลิเคชันของคุณ แล้วถือหน้าที่การตรวจสอบตัวตนและกระบวนการเข้าถึงเป็นโค้ดของแอปพลิเคชันที่ทีมของคุณเป็นเจ้าของ

---

เริ่มต้นด้วยขอบเขตการรวม

มีสามวิธีทั่วไปในการวางตัวอย่างเอกสารในผลิตภัณฑ์ ตัวเลือกที่เหมาะสมขึ้นอยู่กับว่าใครเป็นเจ้าของการนำทาง, การตรวจสอบสิทธิ์, และวงจรชีวิตของตัวดู

รูปแบบ	การใช้งานที่เหมาะสม	ข้อเสียหลัก
มุมมองแอปพลิเคชัน	หน้า .NET ที่เรนเดอร์ตัวดูข้างควบคุมผลิตภัณฑ์	การรวมอย่างแน่นหนา แต่หน้าและวงจรชีวิตของตัวดูถูกผูกมัดกัน
iframe ที่เป็นของแอปพลิเคชัน	พอร์ทัลที่ต้องการการแยกจาก UI โฮสต์และเส้นทางตัวอย่าง	ขอบเขตชัดเจน แต่การสื่อสารต้องออกแบบอย่างชัดเจน
ส่วนประกอบเฟรมเวิร์กรอบเส้นทางเซิร์ฟเวอร์	เชลล์ React, Angular หรือ Vue ที่สนับสนุนโดยแอปพลิเคชัน .NET	การจัดองค์ประกอบส่วนหน้าที่คุ้นเคย แต่มีสถานะวงจรชีวิตที่ต้องจัดการเพิ่มขึ้น

รูปแบบ iframe ไม่จำเป็นต้องชี้ไปที่ URL ของเอกสารสาธารณะ มันสามารถชี้ไปที่เส้นทางที่ต้องการการตรวจสอบสิทธิ์ในแอปของคุณเอง เส้นทางนั้นสามารถตรวจสอบการเข้าถึงและเรนเดอร์หน้าตัวดูโดยไม่เปิดเผยเส้นทางที่เก็บไฟล์ต่อหน้าโฮสต์

สร้างพื้นผิวตัวอย่างที่เสถียรและตอบสนอง

อย่าพยายามสร้าง markup หรือการเริ่มต้นของตัวดูจากโค้ดตัวอย่างในบล็อก Doconut มีไฟล์, ขั้นตอน middleware, namespace, และการตั้งค่าตัวดูที่เหมาะสมกับแต่ละสาย .NET ตัวอย่างเช่น คู่มือการตั้งค่า .NET 6 หรือสูงกว่า อธิบาย middleware ของเซิร์ฟเวอร์, วัตถุตัวดู, ตัวเลือกเอกสาร, การกำหนดค่าการเรนเดอร์, และ assets ของไคลเอนต์ที่จำเป็น

ใช้วัสดุที่เวอร์ชันเหล่านั้นเพื่อสร้างตัวดู, จากนั้นกำหนดความกว้างและความสูงที่เสถียรให้กับโซนโฮสต์ในเลย์เอาต์ของคุณ จองพื้นที่เพียงพอก่อนโหลดเพื่อให้หน้าโดยรอบไม่กระตุก, และทดสอบแถบเครื่องมือและหน้าที่หนึ่งที่จุดพักจริงที่ผลิตภัณฑ์ของคุณรองรับ

ก่อนทำการผสาน, เปรียบเทียบกับ สาธิตสด Doconut อย่างเป็นทางการ สาธิตเหล่านี้ครอบคลุมสไตล์การรวม .NET และส่วนหน้าแบบหลายรูปแบบ, รวมถึงตัวอย่าง iframe เฉพาะ, และช่วยแยกเส้นทางที่ได้รับการสนับสนุนอย่างเป็นทางการจากโค้ดสั้นที่ดูสมเหตุสมผล

รักษาการตัดสินใจการเข้าถึงบนเซิร์ฟเวอร์

หน้าโฮสต์ไม่ควรตัดสินใจว่าผู้ใช้สามารถดูเอกสารได้หรือไม่ ก่อนเรนเดอร์เส้นทางตัวอย่าง, แอปพลิเคชันควร:

1. ตรวจสอบการรับรองความถูกต้องของคำขอ
2. ให้สิทธิ์ผู้ใช้สำหรับเอกสารและเทนานท์ที่ร้องขอ
3. แก้ไขเอกสารผ่านตัวระบุที่ควบคุมโดยเซิร์ฟเวอร์
4. เปิดเอกสารผ่านตัวดูหลังจากตรวจสอบทั้งหมดผ่าน
5. ส่งคืนสถานะไม่พบหรือห้ามโดยทั่วไปโดยไม่เปิดเผยรายละเอียดการจัดเก็บ

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

ตัดสินใจวิธีการสื่อสารระหว่างโฮสต์และตัวดู

มุมมองแอปพลิเคชันสามารถเรียกส่วนประกอบของตนเองโดยตรง iframe ต้องการสัญญาที่แคบกว่า กำหนดเฉพาะเหตุการณ์ที่โฮสต์ต้องการจริง ๆ เช่น:

• พร้อมแสดงตัวอย่าง
• ไม่สามารถเปิดเอกสารได้
• หน้าปัจจุบันเปลี่ยน
• เซสชันหมดอายุ
• ผู้ใช้ขอปิดตัวอย่าง

หากคุณใช้ postMessage, ตรวจสอบทั้ง event.origin และรูปแบบข้อความ อย่ารับต้นกำเนิดแบบไวด์การ์ดในสภาพการผลิต, และห้ามส่งข้อมูลรับรอง, ตำแหน่งจัดเก็บ, หรือเนื้อหาเอกสารดิบผ่านข้อความ

ปฏิบัติตามข้อจำกัดของเบราว์เซอร์เป็นการป้องกันเชิงลึก

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

นอกจากนี้ให้ตรวจสอบ:

• frame-ancestors หรือ X-Frame-Options สำหรับเส้นทางตัวอย่าง
• frame-src สำหรับหน้าโฮสต์
• พฤติกรรมคุกกี้ Same-site หาก iframe ต้องการเซสชัน
• นโยบาย Referrer สำหรับ URL ที่มีตัวระบุการกำหนดเส้นทาง
• Header แคชสำหรับหน้าที่แสดงข้อมูลที่ละเอียดอ่อน

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

ออกแบบสถานะการโหลด, ข้อผิดพลาด, และหมดอายุ

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

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

การเข้าถึงและพฤติกรรมคีย์บอร์ด

ให้ทุก iframe มี title ที่มีประโยชน์ ทำให้ตัวอย่างเข้าถึงได้ด้วยคีย์บอร์ด, ให้วิธีที่มองเห็นได้เพื่อคืนโฟกัสไปยังหน้าโฮสต์, และห้ามกักฟอกโฟกัสภายในโอเวอร์เลย์แบบกำหนดเอง หากตัวดูมีคีย์ลัดของตนเอง, เอกสารความขัดแย้งกับคีย์ลัดที่ใช้ในเชลล์ผลิตภัณฑ์ของคุณ

ทางเลือกที่เข้าถึงได้สามารถเสนอการดาวน์โหลดที่ควบคุมหรือการแสดงผลทางเลือกเมื่อกฎธุรกิจของคุณอนุญาต อย่าเพิ่มลิงก์ไฟล์สาธารณะเพียงเพื่อเป็นทางเลือกสำรอง

รายการตรวจสอบการยืนยันเชิงปฏิบัติ

ก่อนปล่อย, ตรวจสอบเส้นทางคำขอทั้งหมดไม่ใช่แค่การโหลดหน้าแรก:

• ผู้ใช้ที่ได้รับอนุญาตสามารถเปิดเอกสารที่อนุญาตได้
• ผู้ใช้จากเทนานท์อื่นไม่สามารถใช้ URL ตัวอย่างซ้ำได้
• คำขอโดยตรงไปยัง endpoint ที่เกี่ยวกับตัวดูได้รับการตรวจสอบสิทธิ์เดียวกัน
• การรีเฟรช, การนำทางย้อนกลับ, และการหมดอายุของเซสชันสร้างสถานะที่เข้าใจได้
• ตัวอย่างยังใช้งานได้ที่ขนาด viewport และระดับซูมที่รองรับ
• ข้อผิดพลาดในคอนโซลของเบราว์เซอร์และคำขอเครือข่ายที่ล้มเหลวปรากฏในระบบมอนิเตอร์
• บันทึกการจัดเก็บและแอปพลิเคชันไม่บันทึกความลับหรือ URL เอกสารเต็ม

สรุป

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