ย้ายจากการบูรณาการ .NET 6 แบบคลาสสิก

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

คุณกำลังใช้การบูรณาการ .NET 6 แบบใด?

หากทั้งสองคอลัมน์ปรากฏในแอปเดียวกัน ให้ถือว่าการย้ายยังไม่สมบูรณ์ ไม่ ส่งโทเคนเอกสารหนึ่งผ่านทรัพยากรหรือมิดเดิลแวร์ของรุ่นอื่น

ทำไมชื่อแพ็กเกจ NuGet จึงอาจไม่บอกคุณได้

ทั้งสองรุ่นถูกจัดจำหน่ายภายใต้ ID แพ็กเกจ Doconut.NET6 การอ้างอิงแพ็กเกจ, ไฟล์ล็อก, หรือไฟล์ .nupkg ที่แคชไว้จึงไม่สามารถระบุ API ที่โฮสต์ได้ด้วยตนเอง ให้บันทึกเวอร์ชันแพ็กเกจที่แน่นอนและตรวจสอบ Program.cs, การสร้าง viewer, การเปิดเอกสาร, และสคริปต์เบราว์เซอร์พร้อมกัน

รุ่นที่ตรวจสอบสำหรับคู่มือนี้คือ Doconut.NET6 26.7.0 แพ็กเกจสาธารณะเสริมคือ Doconut.NET6.Converter และ Doconut.NET6.Dicom ซึ่งถูกตรึงไว้ที่เวอร์ชันเดียวกันกับแพ็กเกจหลัก

ก่อนที่คุณจะย้าย

1. สร้างสาขาและสำรองข้อมูลที่สามารถปรับใช้ได้ของแอปพลิเคชันที่มีอยู่
2. บันทึกเวอร์ชันของแพ็กเกจหลักและปลั๊กอินอย่างแม่นยำ
3. ทำรายการแมป DocImage.axd ทุกรายการ, การเรียก new Viewer(...), การโหลดไลเซนส์, สคริปต์ Doconut ที่คัดลอก, การกระทำแถบเครื่องมือที่กำหนดเอง, และ endpoint การเปิดเอกสาร
4. เก็บไฟล์ .lic ปัจจุบันและความลับการปรับใช้ไว้ภายนอกระบบควบคุมเวอร์ชัน
5. เก็บชุดตัวอย่าง PDF, Office, รูปภาพ, CAD, อีเมล, DICOM, เอกสารที่ค้นหาได้, เอกสารที่ป้องกันด้วยรหัสผ่าน, และเอกสารที่มีหมายเหตุไว้เป็นตัวอย่าง
6. บันทึกค่า timeout ของเซสชัน, พฤติกรรมความปลอดภัย, ฟอนต์, และการตั้งค่าแพลตฟอร์มที่มีอยู่

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

ความเข้ากันได้ของแพ็กเกจและไลเซนส์

แทนที่หรืออัปเดตแพ็กเกจหลักโดยเจตนา; ห้าม พึ่งพา ID แพ็กเกจเดียวกันเพื่อเลือก API ใหม่ คำสั่งเริ่มต้นจะติดตั้งรุ่นเสถียรล่าสุด:

dotnet add package Doconut.NET6

สำหรับการย้ายที่ทำซ้ำได้ตามรุ่นที่ตรวจสอบในคู่มือนี้ ให้ระบุเวอร์ชันเป็นตัวเลือกแยกต่างหาก:

dotnet add package Doconut.NET6 --version 26.7.0

เก็บปลั๊กอิน Doconut ทุกตัวให้มีเวอร์ชันเดียวกับแพ็กเกจหลัก การบูรณาการปัจจุบันโหลดไลเซนส์ครั้งเดียวใน AddDoconut() โดยใช้ลำดับความสำคัญดังนี้:

LicenseStream > LicenseContent > LicensePath > automatic discovery

การค้นหาอัตโนมัติจะมองหาไฟล์ Doconut.Viewer.lic และไฟล์คู่ Doconut.Viewer.<Capability>.lic คำเรียกแบบคลาสสิก Viewer.DoconutLicense(...) หรือ Viewer.SetLicensePlugin(...) ไม่ใช่กลไกการเริ่มต้นของรุ่นปัจจุบัน ย้ายไลเซนส์ไปยัง DoconutOptions เก็บไฟล์คู่ไว้ด้วยกันเมื่อใช้การค้นหาอัตโนมัติ รีสตาร์ทหลังจากเปลี่ยนไลเซนส์ และตรวจสอบความสามารถผ่าน IDoconutLicenseService

ห้าม สมมติว่าการมีไลเซนส์ปลั๊กอินเก่าแสดงว่ามีสิทธิ์ใช้ปลั๊กอินรุ่นปัจจุบัน ทดสอบ Viewer, Search, Annotation, Converter, และ DICOM แยกกันด้วย artifacts ของรุ่นที่ได้รับการอนุมัติ

การเริ่มต้นและการฉีดขึ้นของ dependency injection

แอปพลิเคชันแบบคลาสสิกสร้าง Viewer ด้วยแคช ASP.NET และ dependency ของ request‑accessor:

// Classic integration — contrast only; do not compile this against the current SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

การบูรณาการปัจจุบันลงทะเบียน Doconut ครั้งเดียวและรับ Viewer จาก dependency injection:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

Viewer เป็นบริการแบบ transient ตัวจัดการเซสชันเอกสารและแคชของมันเป็นผู้ครอบครองสถานะเอกสารที่อายุยาวกว่า ไม่ใช่ instance Viewer ที่ฉีดเข้ามาโดยเฉพาะ

มิดเดิลแวร์และการกำหนดเส้นทางทรัพยากร

ลบสาขา MapWhen แบบคลาสสิกที่ตรวจจับ DocImage.axd:

// Classic integration — remove during the cutover.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

ใน pipeline ปัจจุบัน:

1. เรียก UseSession() ก่อน Doconut ขณะที่เปิดใช้งานความปลอดภัยของเซสชัน
2. เรียก UseDoconutResources() ก่อน UseDoconut()
3. รักษา ResourcesPath, URL ของทรัพยากรที่สร้าง, และ ResPath ของไคลเอนต์ให้สอดคล้องกัน
4. เมื่อแมป UseDoconut() ไปยังสาขา ให้รักษาสาขานั้นและ BasePath ของไคลเอนต์ให้สอดคล้องกัน

MiddlewarePath เป็นการกำหนดค่าที่ตรวจสอบ; มันไม่สร้างสาขา ASP.NET Core ด้วยตัวเอง ใช้ pipeline ง่ายในตัวอย่างที่คอมไพล์ด้านบนหรือใช้การจัดเรียง app.Map("/doconut", branch => branch.UseDoconut()) อย่างสม่ำเสมอโดยไคลเอนต์

การสร้าง Viewer และอายุการใช้งาน

ลบแคชที่เป็นของแอปพลิเคชันสำหรับอ็อบเจ็กต์ Viewer ฉีด Viewer เข้าไปใน endpoint, หน้า Razor, controller, หรือบริการแอปพลิเคชันแบบ scoped:

app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

โทเคนที่ส่งกลับระบุเซสชันเอกสารฝั่งเซิร์ฟเวอร์ ถือเป็น credential ประเภท bearer: ห้าม บันทึก, เก็บถาวร, หรือใส่ใน analytics

การเปิดและปิดเอกสาร

แทนที่ OpenDocument(...) แบบ synchronous ด้วย OpenDocumentAsync(...):

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

โอเวอร์โหลดปัจจุบันรับพาธไฟล์หรือสตรีม, config รูปแบบที่เป็นออปชัน, DocOptions ที่เป็นออปชัน, และ cancellation token ปิดเซสชันเซิร์ฟเวอร์อย่างชัดเจนเมื่อเบราว์เซอร์ไม่ต้องการอีกต่อไป:

viewer.CloseDocument(token);

ห้าม ใช้โทเคนแบบคลาสสิกหลังจากการตัดเปลี่ยน เปิดเอกสารแต่ละไฟล์ใหม่ผ่าน API ปัจจุบัน

คลาสการกำหนดค่า

API ปัจจุบันแยกความรับผิดชอบออกจากกัน:

ห้าม นำ DocOptions.ImageResolution ไปต่อเป็นการควบคุมการเรนเดอร์ มันล้าสมัย; ตั้งค่า BaseConfig.ImageResolution บน config เฉพาะรูปแบบ ตรวจสอบค่าเริ่มต้นทั้งหมดแทนการสันนิษฐานว่าคอนฟิกแบบคลาสสิกทำงานเช่นเดียวกัน

แถบเครื่องมือ Viewer, Search, และ Annotation

ห้าม ย้ายสคริปต์เก่าแบบทีละไฟล์ แอปอ้างอิงรุ่นปัจจุบันประกอบเป็นแพ็กเกจหน้าเต็มหนึ่งชุด:

1. ส่งออก Viewer CSS และ Search/Annotation CSS ที่มีไลเซนส์ด้วย ReferenceCss
2. เรนเดอร์แถบเครื่องมือ Viewer ที่เป็นของแอปพลิเคชัน
3. เรนเดอร์ searchBarMount, annBarMount, และ Viewer mount ที่จำเป็น
4. ส่งออกสคริปต์ Viewer และโมดูลที่มีไลเซนส์ด้วย ReferenceScripts
5. โหลด viewerToolbar.js ของแอปพลิเคชันเอง
6. เริ่มต้น objViewer หนึ่งตัว
7. เริ่มต้น Ribbon ของ Search และ Annotation ที่มีไลเซนส์
8. เรียก attach(objViewer) บนแต่ละ Ribbon
9. เปิดเอกสารและเรียก objViewer.View(token)

Search และ Annotation เป็นโมดูลที่แนบกับ Viewer เดียวกัน ไม่ใช่แถบเครื่องมืออิสระ Ribbon หลักเป็นของแอปโฮสต์; Ribbon ของ Search และ Annotation เป็นทรัพยากรที่เปิดใช้งานตามความสามารถ

ลบไฟล์คลาสสิกที่คัดลอกด้วยตนเอง เช่น documentLinks.js และ docViewer.UI.js หลังจาก หน้าแบบปัจจุบันทำงานกับทรัพยากรที่ส่งออกโดย ReferenceCss และ ReferenceScripts เท่านั้น

การลงทะเบียนปลั๊กอิน

วิธีการแบบคลาสสิกที่ใช้ไลเซนส์สแตติกไม่ลงทะเบียนปลั๊กอินรุ่นปัจจุบัน ติดตั้งและลงทะเบียนแต่ละแพ็กเกจที่ปล่อยออกมาชัดเจน:

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() ตรวจสอบความสามารถของปลั๊กอินที่ลงทะเบียนในขั้นตอนเริ่มต้น Converter และ DICOM เป็นปลั๊กอิน .NET 6 ที่ปล่อยออกมา Search และ Annotation ปกติเป็นฟีเจอร์ที่มีไลเซนส์ในตัว ไม่ใช่แพ็กเกจ AddPlugin<TPlugin>()

เซสชันและความปลอดภัยของเอกสาร

การบูรณาการปัจจุบันผูกเอกสารกับโทเคนที่ไม่เปิดเผยและเซสชันที่แคชไว้ ด้วยค่าเริ่มต้น UnsafeMode = false UseDoconut() จะเพิ่มความปลอดภัยการเข้าถึงเอกสารและโฮสต์ต้องกำหนดค่า ASP.NET session:

builder.Services.AddSession();
app.UseSession();

ตั้งค่า DocOptions.IsSecured = true ยกเว้นมีการออกแบบที่ตรวจสอบแล้วต้องการอย่างอื่น ห้าม ใช้ UnsafeMode = true เป็นทางลัดในการย้าย ทดสอบคำขอโดยไม่มีโทเคน, โทเคนที่ผิดรูปแบบ, โทเคนที่หมดอายุ, และโทเคนจากเซสชันเบราว์เซอร์อื่น

แอปอ้างอิง Distributed เพิ่ม ticket การเข้าถึงและรายละเอียดการส่งผ่าน API เหล่านั้นไม่จำเป็นสำหรับการย้ายแบบโหนดเดียวปกติ

การทดสอบการย้าย

อย่างน้อยให้ตรวจสอบว่า:

• แอปพลิเคชันเริ่มทำงานด้วยไลเซนส์การผลิตและปลั๊กอินที่ลงทะเบียนทั้งหมด
• Viewer CSS/สคริปต์และคำขอรูปภาพทุกหน้าในเส้นทางที่เลือก
• การเปิดเอกสาร, การนำทาง, การซูม, thumbnails, การพิมพ์, และการปิดอย่างชัดเจน
• การค้นหาในเอกสารที่มีข้อความและสถานะไม่สามารถค้นหาในไฟล์ที่เป็นรูปภาพเท่านั้น
• การโหลด, บันทึก, ส่งออก, และการตรวจสอบความสามารถของ Annotation
• การค้นพบเป้าหมายของ Converter, ผลลัพธ์, การดาวน์โหลด, และสถานะ watermark
• หน้า DICOM, เฟรม, และแอนิเมชัน; metadata ทางเทคนิคของ .NET 6 ไม่พร้อมใช้งาน
• เอกสารที่ป้องกันด้วยรหัสผ่าน, ฟอนต์กำหนดเอง, ข้อความที่ไม่ใช่ละติน, และ timeout ที่กำหนดค่าไว้
• การปฏิเสธโทเคนข้ามเซสชันและพฤติกรรมเซสชันที่หมดอายุ
• การทำงานบนมือถือ, โหมดมืด, และเส้นทาง reverse‑proxy ของการผลิต

แผนการย้อนกลับ

เก็บ artifact การปรับใช้แบบคลาสสิก, แพ็กเกจที่ตรงกัน, ไฟล์ไลเซนส์, และทรัพยากรเบราว์เซอร์ที่คัดลอกไว้ด้วยกัน การย้อนกลับที่ปลอดภัยจะสลับทั้งแอปพลิเคชันไปยังรุ่นเดียวกัน; จะ ไม่ ผสมเซิร์ฟเวอร์แบบคลาสสิกกับสคริปต์รุ่นปัจจุบันหรือเซิร์ฟเวอร์รุ่นปัจจุบันกับการเรียก DocImage.axd แบบคลาสสิก

ก่อนการตัดเปลี่ยน ให้บันทึก:

• สล็อตหรือ artifact การปรับใช้ที่ใช้สำหรับการย้อนกลับ
• ผลกระทบต่อฐานข้อมูล/แคช (ถ้ามี)
• วิธีการทำให้เซสชันเอกสารที่กำลังทำงานเป็นโมฆะ
• เอกสารตรวจสอบสุขภาพและเอกสาร smoke ที่ใช้ตัดสินใจย้อนกลับ
• ผู้ที่สามารถกู้คืนชุดแพ็กเกจและการกำหนดค่าก่อนหน้าได้

เอกสารแบบคลาสสิก

คู่มือคลาสสิกที่แปลแล้วยังคงพร้อมใช้งานที่ Legacy .NET 6 setup ส่วน Classic integration gateway ใหม่อธิบายสัญญาณการระบุเดียวกันและลิงก์กลับไปยังคู่มือการย้ายนี้

เก็บ URL ประวัติในบุ๊กมาร์กและตั๋วสนับสนุนขณะที่การติดตั้งแบบคลาสสิกยังคงมีอยู่ มันบันทึกรุ่นที่แตกต่างและไม่ได้เปลี่ยนเส้นทางไปยัง API ปัจจุบัน