ย้ายจากการบูรณาการ .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 แยกกันด้วยศิลปวัตถุของรุ่นที่ได้รับการอนุมัติ

การเริ่มต้นและการฉีดพึ่งพา

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

// การรวมแบบคลาสสิก — เพื่อเปรียบเทียบเท่านั้น; อย่าคอมไพล์โค้ดนี้กับ SDK ปัจจุบัน.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

การรวมปัจจุบันลงทะเบียน Doconut ครั้งเดียวและรับ Viewer จากการฉีดพึ่งพา:

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

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

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

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

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

// การรวมแบบคลาสสิก — ลบในช่วงการย้าย.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

ในกระบวนการทำงานปัจจุบัน:

1. เรียก UseSession() ก่อน Doconut ขณะที่เปิดใช้งานความปลอดภัยของเซสชัน;
2. เรียก UseDoconutResources() ก่อน UseDoconut();
3. รักษา ResourcesPath URLs ของทรัพยากรที่สร้างขึ้น และ 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 });
});

โทเค็นที่ส่งกลับระบุเซสชันเอกสารฝั่งเซิร์ฟเวอร์ ปฏิบัติกับมันเหมือนข้อมูลรับรองแบบ bearer: อย่าบันทึก, อย่าจัดเก็บ, หรือใส่ในระบบวิเคราะห์ใด ๆ

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

แทนที่ OpenDocument(...) แบบซิงโครนัสด้วย OpenDocumentAsync(...):

// การรวม .NET 6 ปัจจุบัน: Viewer มาจาก DI และการเปิดเอกสารเป็นแบบอะซิงโครนัส.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

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

viewer.CloseDocument(token);

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

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

API ปัจจุบันแยกความกังวลออกจากกัน:

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

แถบเครื่องมือ Viewer, การค้นหา, และการอธิบายประกอบ

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

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

Search และ Annotation เป็นโมดูลที่แนบกับ Viewer เดียวกัน ไม่ใช่แถบเครื่องมืออิสระ แถบเครื่องมือหลักเป็นของแอปโฮสต์; 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 ที่ปล่อยออกมา ส่วน Normal Search และ Annotation เป็นฟีเจอร์ที่มีใบอนุญาตในตัว ไม่ใช่แพ็กเกจ AddPlugin<TPlugin>()

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

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

builder.Services.AddDistributedMemoryCache(); // สถานะเซสชันต้องการแคช (MVC/Razor Pages มีการเพิ่มไว้แล้ว)
builder.Services.AddSession();
app.UseSession();

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

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

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

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

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

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

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

ก่อนการตัดสวิตช์ ให้บันทึก:

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

เอกสารเก่า

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

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