ย้ายจากการรวม .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 ที่คัดลอก, การกระทำแถบเครื่องมือที่กำหนดเอง, และจุดสิ้นสุดการเปิดเอกสาร
4. รักษาไฟล์ .lic ปัจจุบันและความลับการปรับใช้ให้อยู่ไกลจากการควบคุมเวอร์ชัน
5. เก็บชุดตัวอย่างของเอกสาร PDF, Office, รูปภาพ, CAD, อีเมล, DICOM, ที่สามารถค้นหาได้, ป้องกันด้วยรหัสผ่าน, และที่มีคำอธิบายประกอบ
6. บันทึกเวลาหมดอายุของเซสชันที่มีอยู่, พฤติกรรมความปลอดภัย, ฟอนต์, และการตั้งค่าแพลตฟอร์ม

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

ความเข้ากันได้ของแพ็กเกจและใบอนุญาต

แทนที่หรืออัปเดตแพ็กเกจหลักโดยเจตนา; อย่าพึ่งพา 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) เป็นการพึ่งพา:

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

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

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

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

Viewer เป็นบริการแบบชั่วคราว ตัวจัดการเซสชันเอกสารและแคชของมันเป็นผู้เป็นเจ้าของสถานะเอกสารที่อายุยาวกว่า ไม่ใช่อินสแตนซ์ 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()));

ในพายไลน์ปัจจุบัน:

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

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

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

ลบแคชของวัตถุ Viewer ที่เป็นของแอปพลิเคชันออก.Inject Viewer เข้าไปใน endpoint, หน้า Razor, คอนโทรลเลอร์, หรือบริการแอปพลิเคชันที่มีขอบเขต:

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

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

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

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

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

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

viewer.CloseDocument(token);

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

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

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

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

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

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

1. ส่งออก Viewer CSS และ Search/Annotation CSS ที่มีลิขสิทธิ์ด้วย 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.AddSession();
app.UseSession();

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

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

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

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

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

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

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

ก่อนทำการตัดสลับ ให้บันทึกข้อมูล:

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

เอกสารรุ่นเก่า

คู่มือคลาสสิกที่แปลแล้วยังคงสามารถเข้าถึงได้ที่ การตั้งค่า .NET 6 รุ่นเก่า ส่วน เกตเวย์การบูรณาการคลาสสิก จะอธิบายสัญญาณการระบุเดียวกันและเชื่อมโยงกลับไปยังคู่มือการย้ายนี้

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