ย้ายไปยัง .NET Standard 2.1
ย้ายแอปพลิเคชัน Doconut.NETStandard ที่มีอยู่จากเวอร์ชัน 26.7.0 ไปเป็น 26.8.0
Doconut มีการบูรณาการ .NET Standard ที่แตกต่างกันสองแบบ พวกมันใช้ชื่อแพ็กเกจ Doconut.NETStandard เดียวกัน ดังนั้นให้ระบุรุ่นจากเวอร์ชันและ API ในแอปพลิเคชันก่อนที่จะเปลี่ยนแพ็กเกจ, การเริ่มต้น, ไลเซนส์ หรือทรัพยากรของเบราว์เซอร์
เวอร์ชันคือการแยกทาง
ทั้งสองรุ่นเผยแพร่ภายใต้ ID แพ็กเกจเดียวกัน. เฉพาะเวอร์ชันเท่านั้นที่บ่งบอกความแตกต่าง:
| เวอร์ชัน | เป้าหมาย | API |
|---|---|---|
| 26.7.0 และต่ำกว่า | netstandard2.0 | API ก่อนหน้า |
| 26.8.0 และสูงกว่า | netstandard2.1 | API ปัจจุบัน |
การเพิ่มหมายเลขเวอร์ชันคือการอัปเกรด ไม่มีแพ็กเกจแยกต่างหากให้ติดตั้งและไม่มี shim ความเข้ากันได้ — 26.8.0 มีพื้นผิว API ที่แตกต่างกัน คาดว่าจะเกิดข้อผิดพลาดการคอมไพล์หลังจากอัปเดต; ส่วนที่เหลือของคู่มือนี้คือรายการของข้อผิดพลาดเหล่านั้น.
การบูรณาการแบบใดที่คุณใช้?
| หากโครงการมี… | รุ่น |
|---|---|
new Viewer(_cache, _accessor, ...) | ก่อนหน้า |
viewer.OpenDocument(...) (synchronous) | ก่อนหน้า |
viewer.InitCache() | ก่อนหน้า |
UseDoconut(new DoconutOptions { ... }) | ก่อนหน้า |
UseDoconutWebFarm(...) / WebFarmOptions | ก่อนหน้า |
Viewer.DoconutLicense(...) หรือ Viewer.SetLicensePlugin(...) | ก่อนหน้า |
viewer.Converter.GetConverter() | ก่อนหน้า |
using Doconut.Configs; / using Doconut.Models; | ก่อนหน้า |
คัดลอกด้วยตนเอง docViewer.js, documentLinks.js, หรือ docViewer.UI.js | ก่อนหน้า |
builder.Services.AddDoconut(...) | ปัจจุบัน |
app.UseDoconutResources() พร้อมกับ app.UseDoconut() โดยไม่มีอาร์กิวเมนต์ | ปัจจุบัน |
Viewer ที่ได้รับจากการฉีดพึ่งพา | ปัจจุบัน |
await viewer.OpenDocumentAsync(...) | ปัจจุบัน |
หากคอลัมน์ทั้งสองปรากฏในแอปพลิเคชันเดียวกัน ให้ถือว่าการย้ายยังไม่สมบูรณ์ อย่าส่งโทเคนเอกสารหนึ่งผ่านทรัพยากรหรือ middleware จากรุ่นอื่น
ตรวจสอบเฟรมเวิร์กโฮสต์ก่อน
นี่คือเกตที่เข้มงวด ไม่ใช่ความชอบส่วนบุคคล แพ็กเกจปัจจุบันมุ่งเป้าไปที่ netstandard2.1:
| โฮสต์ | สามารถใช้ 26.8.0 ได้ |
|---|---|
| .NET Core 3.0 หรือใหม่กว่า (รวมถึง .NET 5/6/7/8) | ใช่ |
| .NET Framework, เวอร์ชันใดก็ได้ | ไม่ |
.NET Framework ไม่สามารถอ้างอิงไลบรารี netstandard2.1 ได้ หากแอปพลิเคชันทำงานบน .NET Framework ให้หยุดที่นี่และใช้แพ็กเกจ Doconut.NETFramework แทน; ตั้งแต่เวอร์ชัน 26.9.0 จะต้องใช้ .NET Framework 4.7.2 ทั้งสองแอปพลิเคชันอ้างอิงสำหรับการปล่อยนี้มุ่งเป้าไปที่ net8.0.
ก่อนที่คุณจะย้าย
- สร้างสาขาและสำรองข้อมูลที่สามารถปรับใช้ได้ของแอปพลิเคชันที่มีอยู่
- บันทึกเวอร์ชันของแพ็กเกจ core และ plugin อย่างแม่นยำ
- ทำรายการตรวจสอบทุกการเรียก
new Viewer(...), การเรียกInitCache(), การโหลดไลเซนส์, การแมปUseDoconutWebFarm, ตัวควบคุมการแปลง, สคริปต์ Doconut ที่คัดลอก, การกระทำแถบเครื่องมือแบบกำหนดเอง, คอลแบ็กของ viewer, และจุดสิ้นสุดการเปิดเอกสาร - เก็บไฟล์
.licปัจจุบันและความลับการปรับใช้ไว้ด้านนอกระบบควบคุมเวอร์ชัน - จับชุดตัวอย่างของเอกสาร PDF, Office, รูปภาพ, CAD, อีเมล, DICOM, ที่สามารถค้นหาได้, ป้องกันด้วยรหัสผ่าน, และที่มีคำอธิบายประกอบ
- บันทึกค่า timeout ของเซสชันที่มีอยู่, พฤติกรรมความปลอดภัย, ฟอนต์, และการตั้งค่าแพลตฟอร์ม
ย้ายหนึ่งสภาพแวดล้อมก่อนเปลี่ยนการผลิต การบูรณาการปัจจุบันเปลี่ยนอายุการบริการ, การกำหนดเส้นทางคำขอ, ความเป็นเจ้าของเซสชัน, การส่งมอบทรัพยากรของไคลเอนต์, และ — หากคุณรันฟาร์ม — วิธีที่หน้าเว็บเข้าถึงเบราว์เซอร์ทั้งหมด
1. เนมสเปซ: เกือบทุกอย่างย้ายไปยังรูท
ประเภทการกำหนดค่าถูกกระจายอยู่ในสี่เนมสเปซ ตอนนี้ทั้งหมดอยู่ใน Doconut.
| ก่อนหน้า | ตอนนี้ |
|---|---|
using Doconut.Configs.View; | using Doconut; |
using Doconut.Models; | using Doconut; |
using Doconut.Configs; | using Doconut; |
using Doconut.Configs.Cloud; | using Doconut.Clouds; |
using Doconut.Configs.Conversion; | ไม่เปลี่ยนแปลง |
using Doconut.Middleware; | ไม่เปลี่ยนแปลง |
ชื่อประเภทไม่ได้เปลี่ยนแปลง: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, CloudUploadConfig, AzureConfig, CDNConfig, FileShareConfig และส่วนที่เหลือทั้งหมดยังคงอยู่ ในไฟล์ส่วนใหญ่การแก้ไขทั้งหมดคือการลบสองบรรทัด using
Doconut.Configs.Editor (BaseConfigEditor, PdfConfigEditor) ถูกลบและไม่มีการทดแทนในแพ็กเกจนี้ หากแอปพลิเคชันของคุณอ้างอิงประเภทเหล่านั้น ให้วางแผนส่วนนั้นแยกต่างหากและอย่าพิจารณาเป็นส่วนหนึ่งของการย้ายนี้
2. ความเข้ากันได้ของแพ็กเกจและใบอนุญาต
แทนที่หรืออัปเดตแพ็กเกจหลักโดยเจตนา; อย่าอาศัย ID ของแพ็กเกจที่เหมือนกันเพื่อเลือก API ใหม่ คำสั่งเริ่มต้นจะติดตั้งรุ่นเสถียรล่าสุด:
dotnet add package Doconut.NETStandardเพื่อการย้ายเวอร์ชันที่ทำซ้ำได้ไปยังรุ่นที่ได้รับการตรวจสอบโดยคู่มือนี้ ให้ส่งเวอร์ชันเป็นตัวเลือกแยกต่างหาก:
dotnet add package Doconut.NETStandard --version 26.9.0รักษาให้ปลั๊กอิน Doconut ทุกตัวอยู่ในเวอร์ชันเดียวกับแพ็กเกจหลัก — Doconut.NETStandard.Converter และ Doconut.NETStandard.Dicom. การรวมปัจจุบันโหลดใบอนุญาตหนึ่งครั้งในระหว่าง AddDoconut() โดยใช้ลำดับความสำคัญนี้:
LicenseStream > LicenseContent > LicensePath > automatic discoveryการค้นหาอัตโนมัติมองหาไฟล์ Doconut.Viewer.lic และไฟล์คู่กัน Doconut.Viewer.<Capability>.lic. การเรียกแบบคงที่ก่อนหน้านี้ Viewer.DoconutLicense(...) และ Viewer.SetLicensePlugin(...) ไม่เป็นกลไกการเริ่มต้นในปัจจุบัน, และเช่นเดียวกับ List<string> ของเส้นทางใบอนุญาตที่คอนสตรัคเตอร์เก่า Viewer ยอมรับ. ย้ายใบอนุญาตไปยัง DoconutOptions, รักษาไฟล์คู่กันไว้ด้วยกันเมื่อใช้การค้นหาอัตโนมัติ, รีสตาร์ทหลังจากเปลี่ยนใบอนุญาต, และตรวจสอบความสามารถผ่าน IDoconutLicenseService.
อย่าเชื่อว่าการมีใบอนุญาตปลั๊กอินเก่าแสดงถึงสิทธิ์สำหรับการสร้างปลั๊กอินในปัจจุบัน ทดสอบ Viewer, Search, Annotation, Converter, และ DICOM แยกกันด้วยศิลปวัตถุของรุ่นที่ได้รับการอนุมัติ.
3. การเริ่มต้นและการฉีดพึ่งพา
ก่อนหน้านี้ viewer ถูกสร้างต่อคำขอและตัวเลือกถูกส่งไปยัง middleware:
// การรวมก่อนหน้า — เพียงเพื่อเปรียบเทียบ; อย่าคอมไพล์สิ่งนี้กับ SDK ปัจจุบัน.
var viewer = new Viewer(_cache, _accessor);
// …
appBranch.UseDoconut(new DoconutOptions { UnSafeMode = false, ShowDoconutInfo = false });การรวมปัจจุบันลงทะเบียน Doconut ครั้งเดียวและรับ Viewer จากการฉีดพึ่งพา:
builder.Services.AddDoconut(options =>
{
options.UnsafeMode = false; // บันทึกการเปลี่ยนแปลงการสะกด: UnSafeMode → UnsafeMode
options.ShowDoconutInfo = false;
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // session state ต้องการแคช (MVC/Razor Pages มีการเพิ่มไว้แล้ว)
builder.Services.AddSession();
app.UseSession();
app.UseDoconutResources();
app.UseDoconut();Viewer เป็นบริการชั่วคราว ตัวจัดการเซสชันเอกสารและแคชของมันเป็นเจ้าของสถานะเอกสารที่อายุยาวกว่า, ไม่ใช่อินสแตนซ์ Viewer ที่ฉีดเข้ามาโดยเฉพาะ.
สามสิ่งที่ต้องนำต่อไป:
new Viewer(cache, accessor)หายไป. ฉีดDoconut.Viewerเข้าไปในคอนโทรลเลอร์ของคุณ, หรือใช้@inject Doconut.Viewer Viewerใน Razor view.UseDoconutResources()แทนที่การเชื่อมต่อด้วยมือapp.UseMiddleware<EmbeddedResourceMiddleware>(), และต้องทำงาน ก่อน สาขาเอกสาร.UnSafeMode→UnsafeMode. การเปลี่ยนชื่อหนึ่งอักขระที่คอมไพเลอร์จะตรวจจับได้.
เมื่อ UnsafeMode เป็น false SDK จะตรวจสอบโทเค็นเซสชันกับคำขอที่มาจาก, ดังนั้น AddSession() / UseSession() ต้องยังคงอยู่ใน pipeline, UseSession() ก่อนสาขา.
วิธีการที่ไม่มีอยู่แล้ว
| ก่อน | ตอนนี้ |
|---|---|
viewer.OpenDocument(path, config, options) | await viewer.OpenDocumentAsync(path, config, options) |
viewer.InitCache() | ลบออก — ไม่มีอะไรให้ทำความร้อนด้วยมือ; ลบการเรียกและแฟล็ก "ฉันได้เริ่มต้นแล้วหรือยัง?" ใด ๆ ที่อยู่รอบ ๆ |
viewer.ExportToPng(sharedPath) | ดู §7 |
viewer.ExportToCloud(cloudConfig) | ดู §7 |
using var v = new Viewer(...); v.CloseDocument(t) | viewer.CloseDocument(token) บนอินสแตนซ์ที่ฉีดเข้ามา |
4. Middleware และการกำหนดเส้นทางทรัพยากร
UseDoconut() ตอนนี้ไม่รับอาร์กิวเมนต์ใด ๆ รูปแบบสาขา MapWhen เองไม่จำเป็นต้องเปลี่ยน — มีเพียง middleware ภายในเท่านั้นที่ต้องเปลี่ยน:
app.UseDoconutResources(); // ก่อนสาขา
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());ใน pipeline ปัจจุบัน:
- เรียก
UseSession()ก่อน Doconut ขณะที่การรักษาความปลอดภัยของเซสชันเปิดใช้งาน; - เรียก
UseDoconutResources()ก่อนUseDoconut(); - รักษา
ResourcesPath, URL ของทรัพยากรที่สร้างขึ้น, และResPathของไคลเอนต์ให้สอดคล้องกัน; - รักษาสาขาที่คุณแมปและ
BasePathของไคลเอนต์ให้สอดคล้องกัน.
MiddlewarePath เป็นการกำหนดค่าที่ตรวจสอบแล้ว; มันไม่ได้สร้างสาขา ASP.NET Core ด้วยตนเอง.
5. การสร้างและอายุการใช้งานของ Viewer
ลบแคชที่เป็นของแอปพลิเคชันสำหรับวัตถุ Viewer objects. ไม่มีอะไรเหลืออยู่ใน Viewer ที่คุ้มค่าที่จะเก็บไว้: มันไม่มีสถานะเอกสารใด ๆ และแคชเซสชันเป็นเจ้าของทุกอย่างที่คงอยู่หลังจากคำขอเสร็จสิ้น. ฉีดมันเข้าไปใน endpoint, หน้า Razor, controller หรือบริการแอปพลิเคชันที่มีขอบเขต:
app.MapPost("/api/open", async (Viewer viewer) =>
{
var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
return Results.Ok(new { token });
});โทเคนที่คืนมาระบุเซสชันเอกสารบนเซิร์ฟเวอร์. ปฏิบัติกับมันเหมือนเป็นข้อมูลรับรองแบบ bearer: อย่าบันทึก, อย่าจัดเก็บ, หรือใส่ลงในระบบวิเคราะห์.
6. การเปิดและปิดเอกสาร
แทนที่ OpenDocument(...) แบบ synchronous ด้วย OpenDocumentAsync(...):
// การบูรณาการปัจจุบัน: Viewer มาจาก DI และการเปิดเอกสารเป็นแบบอะซิงโครนัส.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });ฟังก์ชัน overload ปัจจุบันรับพาธไฟล์หรือสตรีม, การกำหนดค่าฟอร์แมตแบบเลือก, DocOptions แบบเลือก, และ cancellation token. ปิดเซสชันเซิร์ฟเวอร์อย่างชัดเจนเมื่อเบราว์เซอร์ไม่ต้องการอีกต่อไป:
viewer.CloseDocument(token);ลบการเรียก InitCache() ใด ๆ และแฟล็กที่ป้องกันมันออก — ไม่มีอะไรที่ต้องเตรียมล่วงหน้าด้วยมือ. ห้ามใช้โทเคนที่สร้างโดยไลบรารีก่อนหน้าอีกหลังการเปลี่ยนแปลง: เปิดเอกสารแต่ละไฟล์ใหม่ผ่าน API ปัจจุบัน.
7. Web farm → distributed: การเปลี่ยนแปลงที่ใหญ่ที่สุด
UseDoconutWebFarm และ WebFarmOptions ไม่อยู่แล้ว หากแอปของคุณเรียกใช้พวกมัน, ส่วนนี้คือการอัปเกรดของคุณ; หากไม่, ข้ามไปที่ §8.
ก่อนหน้านี้ middleware ตัวเดียวทำทุกอย่าง: มันให้บริการภาพที่เรนเดอร์ล่วงหน้าออกจากโฟลเดอร์ที่แชร์, และ ตรวจสอบอย่างต่อเนื่อง ขณะที่โหนดอื่นยังคงเขียนมันอยู่.
// การบูรณาการก่อนหน้า — การเรียกหนึ่งครั้ง, การประสานงานโดยอ้อมผ่านระบบไฟล์.
appBranch.UseDoconutWebFarm(new WebFarmOptions
{
Path = Path.Combine(env.WebRootPath, "webfarm"),
PageWaitTimeSeconds = 180,
StartWaitFromPage = 5,
});งานเดียวกันตอนนี้ถูกแบ่งออกเป็นสองส่วนที่ชัดเจน ด้านการเขียน — โหนดที่เปิดเอกสารจะเผยแพร่ชุดอาร์ติแฟกต์ทั้งหมด (หน้า, ข้อมูลเอกสาร, ดัชนีการค้นหา, เมตาดาต้า) ไปยังแชร์:
var result = await _publisher.PublishAsync( // DistributedDocumentPublisher, ถูกฉีดจาก DI
pathToFile,
new FileShareConfig
{
Location = CloudLocation.FileShare,
RootPath = @"\\fileserver\doconut", // โฟลเดอร์เดียวกันที่คุณใช้ในวันนี้
UsePerTokenSubfolders = true,
},
config,
documentOptions,
new DistributedDocumentPublishOptions
{
CleanUpStagingDirectory = true,
FirstPagePriority = true,
});
return Content(result.Token);ด้านการอ่าน — โหนดใดก็ได้ให้บริการจากแชร์:
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = /* FileShareConfig SAME ตามที่กล่าวข้างบน */;
}, "/"));| ก่อน | ตอนนี้ |
|---|---|
WebFarmOptions.Path | FileShareConfig.RootPath |
PageWaitTimeSeconds / StartWaitFromPage | หายไป — แทนที่ด้วย FirstPagePriority บนด้านการเขียนและ FileShareConfig.ReadReadyPollMs บนด้านการอ่าน |
viewer.OpenDocument(...) แล้ว viewer.ExportToPng(share) | หนึ่งการเรียก PublishAsync(...) |
DocOptions.IsWebfarm / WebfarmPath | ยังคงอยู่, เขียนเป็น IsWebFarm / WebFarmPath — แต่ไม่จำเป็นบนเส้นทางการเผยแพร่ |
โครงสร้างของคุณไม่เปลี่ยนแปลง ตั้งค่า RootPath ไปยัง UNC share เดียวกันและโหนดทุกตัวจะทำงานต่อไปเช่นเดิม. สิ่งที่เปลี่ยนแปลงคือการเผยแพร่เป็นการดำเนินการที่คุณเรียกใช้, แทนที่จะเป็นผลข้างเคียงของการเรนเดอร์.
ทั้งสองส่วนต้องสอดคล้องกัน หาก
RootPathหรือUsePerTokenSubfoldersแตกต่างกันระหว่างผู้เผยแพร่และตัวจัดการ, โหนดอีกฝั่งจะตอบ 404. สร้างการกำหนดค่าใน helper ตัวเดียวและเรียกใช้จากทั้งสองด้าน.
PageWaitTimeSeconds = 180 หมายถึง “บล็อกสูงสุดสามนาทีโดยคาดว่าหน้าจะปรากฏ”. การแทนที่เป็นแบบชัดเจน: ด้วย FirstPagePriority = true, หน้า 1 สามารถให้บริการได้ทันทีและหน้าถัดไปจะตอบ HTTP 202 Accepted จนกว่าจะเขียนเสร็จ. Viewer ที่รวมมาด้วยจะลองใหม่โดยอัตโนมัติเมื่อกำหนดค่า retryOn409. คลไอเอนต์ที่ไม่ลองใหม่จะเห็นแผ่นภาพเสียสำหรับหน้าที่ยังอยู่ระหว่างการเรนเดอร์.
การจัดเรียงเต็มรูปแบบ, รวมถึงการเผยแพร่เบื้องหลังและตั๋วเข้าถึง, อยู่ใน การปรับใช้แบบกระจาย.
8. การแปลงเป็นปลั๊กอินและมีขนาดเล็กกว่ามาก
ลงทะเบียนปลั๊กอินแล้วฉีด facades ของ DocumentConverter:
builder.Services.AddDoconut(o => o.AddPlugin<ConverterPlugin>());// การรวมก่อนหน้า
var converter = viewer.Converter.GetConverter();
var config = new WordConfigConverter { TargetFormat = WordConfigConverter.EnTargetFormat.PDF };
var result = converter.Convert(stream, SourceFormatConverter.DOCX, config);
// การรวมปัจจุบัน
var result = await _converter.ConvertAsync(stream, ".docx", ConversionTarget.Pdf, null, ct);สิ่งที่แทนที่:
SourceFormatConverter— หายไป. ส่งต่อส่วนขยายไฟล์เป็นสตริงรวมจุด.- ประเภท
*ConfigConverterของแต่ละครอบครัว (WordConfigConverter,ExcelConfigConverter, …), แต่ละประเภทมี enumEnTargetFormatซ้อนอยู่ — หายไป. ตอนนี้มี enumConversionTargetหนึ่งตัวสำหรับแต่ละครอบครัว. viewer.Converter.GetConverter()— หายไป. ฉีดDoconut.DocumentConverter.
ConvertAsync คืนค่า stream ที่สามารถเลื่อนตำแหน่งได้, ดังนั้น return File(result, mime, name) ทำงานโดยตรง — การคัดลอก MemoryStream ของโค้ดเก่าที่จำเป็นจึงไม่จำเป็น. ในตัวอย่างที่จัดส่งนี้ได้ลบสวิตช์ส่วนขยาย 68 กรณีและคอนโทรลเลอร์ที่คล้ายกันสิบตัว.
ดู ปลั๊กอินแปลง สำหรับรายละเอียดทั้งหมด.
9. ผู้ให้บริการคลาวด์
UseDoconutCloud กลายเป็นทั่วไป. ผู้ให้บริการเป็นอาร์กิวเมนต์ประเภทแทนค่าของ Location ที่สลับภายใน middleware:
// การรวมก่อนหน้า
appBranch.UseDoconutCloud(new CloudOptions { Location = CloudLocation.CDN, ... });
// การรวมปัจจุบัน
branch.UseDoconutCloud<CDNCloudHandler>(options =>
{
options.Location = CloudLocation.CDN;
options.CloudUploadConfig = new CDNConfig { DoconutCdnUrl = "..." };
}, "/");คลาสการกำหนดค่าไม่ได้เปลี่ยนแปลงยกเว้นชื่อเนมสเปซ (Doconut.Configs.Cloud → Doconut.Clouds): AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig, FTPConfig, พร้อมกับ FileShareConfig ใหม่. ตัวจัดการมีชื่อว่า <Provider>CloudHandler.
ตัวจัดการ CDN เป็น อ่านอย่างเดียว — มันให้บริการสิ่งที่มีอยู่แล้วบน CDN; ไม่อัปโหลด.
10. อ็อบเจ็กต์การกำหนดค่าที่เปลี่ยนชื่อ
| Before | Now |
|---|---|
DoconutOptions.UnSafeMode | UnsafeMode |
DocOptions.IsWebfarm | IsWebFarm |
DocOptions.WebfarmPath | WebFarmPath |
DocOptions.ImageResolution | ยังอยู่แต่ ล้าสมัย — ตั้งค่าความละเอียดในการกำหนดค่ารูปแบบแทน |
DocOptions ยังได้รับ IsSecured เพิ่มเติม.
API ปัจจุบันยังแยกความกังวลอย่างเข้มงวดกว่าครั้งก่อน, ดังนั้นตรวจสอบว่าการตั้งค่าแต่ละอย่างอยู่บนอ็อบเจ็กต์ที่เป็นเจ้าของตอนนี้:
| Concern | Current type |
|---|---|
| เส้นทาง Middleware, การให้สิทธิ์, การลงทะเบียนปลั๊กอิน | DoconutOptions |
| รหัสผ่าน, เวลาหมด, ความปลอดภัย, ลายน้ำ | DocOptions |
| การเรนเดอร์รูปแบบและ DPI | PdfConfig, WordConfig, ExcelConfig, และประเภท BaseConfig อื่น ๆ |
| ค่าเริ่มต้นของวิดเจ็ตเบราว์เซอร์ | ViewerConfig หรือ ตัวเลือก JavaScript ที่เทียบเท่า |
| CSS และสคริปต์ที่สร้างขึ้น | CssConfig and ScriptConfig |
| ที่เก็บข้อมูลร่วมและผู้ให้บริการคลาวด์ | FileShareConfig and the other Doconut.Clouds configs |
อย่าใช้ DocOptions.ImageResolution ต่อไปเป็นตัวควบคุมการเรนเดอร์. มันล้าสมัย; ตั้งค่า BaseConfig.ImageResolution บนการกำหนดค่าที่เฉพาะรูปแบบ. ตรวจสอบค่าเริ่มต้นทั้งหมดแทนการสันนิษฐานว่าการกำหนดค่าก่อนหน้ามีพฤติกรรมเดียวกัน.
11. ตัวดูฝั่งไคลเอนท์ — การเปลี่ยนแปลงสองอย่างที่ล้มเหลวโดยเงียบ
ทั้งสองกรณีนี้ทำให้เซิร์ฟเวอร์ทำงานได้อย่างสมบูรณ์เอกสารของคุณแสดงผล, หน้าเว็บดูถูกต้อง, และไม่มีอะไรแสดงในคอนโซลของเบราว์เซอร์. อ่านส่วนนี้แม้ว่าการคอมไพล์ C# ของคุณจะสำเร็จในครั้งแรก.
คอลแบ็กของตัวดูเป็นตัวเลือกแล้ว, ไม่ใช่ฟังก์ชันระดับโลก
ตัวดูเดิมเรียกตัวจัดการของคุณ ตามชื่อ, สร้างชื่อฟังก์ชันระดับโลกจาก id ของคอนเทนเนอร์. การประกาศ function ctlDoc_OnViewerReady() บนหน้าที่มี <div id="div_ctlDoc"> เพียงพอ. ตัวดูปัจจุบันรับคอลแบ็กโดยตรงในอ็อบเจ็กต์ options และไม่ค้นหา globals เหล่านั้นอีกต่อไป:
objctlDoc = $("#div_ctlDoc").docViewer({
// ... ตัวเลือกที่มีอยู่ของคุณ ...
onViewerBusy: ctlDoc_OnViewerBusy, // พบโดยชื่อ
onViewerReady: ctlDoc_OnViewerReady, // พบโดยชื่อ
onCopy: ctlDoc_Copy, // คือ ctlDoc_Copy(text)
onAutoLoadStatus: ctlDoc_AutoLoadStatus // คือ ctlDoc_AutoLoadStatus(page)
});ทำไมเรื่องนี้ถึงแย่: การเรียกเก่าได้ถูกห่อหุ้มใน catch ว่างเปล่า, ซึ่งทำให้ทุกอย่างถูกกลืน. ตอนนี้ฟังก์ชันของคุณไม่ทำงานเลยและไม่มีอะไรรายงานข้อผิดพลาด. อาการทั่วไปคือสปินเนอร์ทำงานตลอดโดยไม่หยุด — เพราะฟังก์ชันที่ซ่อนมันคือ ctlDoc_OnViewerReady. เอกสารด้านหลังนั้นไม่มีปัญหา.
รายการตัวเลือกทั้งหมดคือ onPageLoading, onPageLoaded, onThumbnailClicked,
onPageClicked, onDoubleClick, onViewerBusy, onViewerReady, onViewerError,
onCopy, onAnnSaved, onAnnSaveError, onAnnLoaded, onAnnClosed,
onAutoLoadStatus, onThumbsShown, และ onError. ไม่มีคอลแบ็กสำหรับการคลิกลิงก์: การจัดการไฮเปอร์ลิงก์ถูกสร้างไว้แล้ว, ขับเคลื่อนโดย showHyperlinks.
ResPath ต้องชี้ไปที่คำนำหน้าทรัพยากร
ResPath: '', // ก่อน — resources came from the application root
ResPath: 'doconut-res/images', // ตอนนี้ — the prefix UseDoconutResources() mountsหากคุณเปลี่ยนคำนำหน้าผ่าน DoconutOptions.ResourcesPath ให้ใช้ค่าดังกล่าวแทน.
12. แถบเครื่องมือ Viewer, การค้นหา, และการอธิบาย
อย่าโยกย้ายสคริปต์เก่าแบบทีละไฟล์ แอปพลิเคชันอ้างอิงปัจจุบันประกอบเป็นแพ็กเกจหน้าเว็บที่สมบูรณ์หนึ่งชุด:
- ส่งออก CSS ของ Viewer และ CSS ของ Search/Annotation ที่ได้รับอนุญาตด้วย
ReferenceCss; - เรนเดอร์แถบเครื่องมือ Viewer ที่เป็นของแอปพลิเคชัน;
- เรนเดอร์
searchBarMount,annBarMount, และการเมานท์ Viewer ที่จำเป็น; - ส่งออกสคริปต์ Viewer และโมดูลที่ได้รับอนุญาตด้วย
ReferenceScripts; - โหลดสคริปต์ช่วยเหลือแถบเครื่องมือของแอปพลิเคชันเอง;
- เริ่มต้นหนึ่ง
objViewer; - เริ่มต้น Ribbon ของ Search และ Annotation ที่ได้รับอนุญาต;
- เรียก
attach(objViewer)บนแต่ละ Ribbon; - เปิดเอกสารและเรียก
objViewer.View(token).
Search และ Annotation เป็นโมดูลที่แนบกับ Viewer เดียวกัน ไม่ใช่แถบเครื่องมืออิสระ แถบเครื่องมือหลักเป็นของแอปพลิเคชันโฮสต์; Ribbon ของ Search และ Annotation ถูกฝังเป็นทรัพยากรที่จำกัดตามความสามารถ.
ลบไฟล์ที่คัดลอกด้วยตนเองเช่น documentLinks.js และ docViewer.UI.js เฉพาะหลังจากหน้าปัจจุบันทำงานกับทรัพยากรที่ส่งออกโดย ReferenceCss และ ReferenceScripts.
13. การลงทะเบียนปลั๊กอิน
เมธอด plugin-license แบบสแตติกไม่ได้ลงทะเบียนปลั๊กอินปัจจุบัน ให้ติดตั้งและลงทะเบียนแต่ละแพ็กเกจที่ปล่อยออกมาอย่างชัดเจน:
builder.Services.AddDoconut(options =>
{
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});AddDoconut() ตรวจสอบความสามารถของปลั๊กอินที่ลงทะเบียนในขณะเริ่มต้น Converter และ DICOM เป็นปลั๊กอิน .NET Standard ที่ปล่อยออกมา Search และ Annotation ปกติเป็นฟีเจอร์ที่มีลิขสิทธิ์ในตัว ไม่ใช่แพ็กเกจ AddPlugin<TPlugin>().
14. ความปลอดภัยของเซสชันและเอกสาร
การบูรณาการปัจจุบันผูกเอกสารกับโทเค็นที่ไม่โปร่งใสและเซสชันที่แคชไว้ ด้วยค่าเริ่มต้น UnsafeMode = false, UseDoconut() เพิ่มความปลอดภัยการเข้าถึงเอกสารและโฮสต์ต้องกำหนดค่าเซสชัน ASP.NET:
builder.Services.AddDistributedMemoryCache(); // session state needs a cache (MVC/Razor Pages already add one)
builder.Services.AddSession();
app.UseSession();เก็บ DocOptions.IsSecured = true ไว้ยกเว้นกรณีที่การออกแบบที่ตรวจสอบแล้วต้องการอย่างอื่น อย่าใช้ UnsafeMode = true เป็นทางลัดการย้ายข้อมูลบนโหนดเดียว ทดสอบคำขอที่ไม่มีโทเค็น, โทเค็นที่ผิดรูปแบบ, โทเค็นที่หมดอายุ, และโทเค็นจากเซสชันเบราว์เซอร์ที่ต่างกัน.
ในฟาร์ม คำขอหน้าอาจไปยังโหนดที่ไม่เคยเห็นคำขอเปิดแรก ทำให้การตรวจสอบต่อเซสชันจะปฏิเสธมัน นั่นคือกรณีเดียวที่ UnsafeMode = true ถูกต้อง — และต้องจับคู่กับตั๋วเข้าถึงที่ลงลายเซ็นผ่าน AddDoconutDistributedDocumentSecurity, ไม่ได้ส่งแยกออกมา ดูที่ การปรับใช้แบบกระจาย.
หมายเหตุการตั้งชื่อ
ในทุกเฟรมเวิร์กคลาสคือ Viewer หากคุณพบ DocumentViewer ในโค้ดตัวอย่างเก่าหรือบทความของบุคคลที่สาม ประเภทนั้นไม่มีอยู่ใน SDK.
15. ลำดับงานที่แนะนำ
- ยืนยันว่าเฟรมเวิร์กโฮสต์สามารถใช้ netstandard2.1 ได้ หากไม่ได้ ให้หยุด.
- อัปเดตแพ็กเกจเป็น 26.8.0 แล้วสร้าง ทำการแก้ไขข้อผิดพลาดการคอมไพล์ — ส่วนใหญ่เป็นบรรทัด
usingใน §1. - ย้ายการเริ่มต้นไปที่
AddDoconut()และการเรียก middleware ไปยังลำดับใหม่ของพวกมัน (§3, §4). - แทรก
Viewerที่คุณกำลังสร้างมัน, ทำให้OpenDocumentเป็นแบบ async, และลบInitCache()(§5, §6). - หากคุณใช้เว็บฟาร์ม ให้ทำ §7 — ส่วนเดียวที่เป็นการออกแบบใหม่แทนการเปลี่ยนชื่อ.
- หากคุณแปลงเอกสาร ให้ทำ §8.
- ทำ §11 — การเปลี่ยนแปลงด้านไคลเอนต์ พวกมันคือสิ่งที่ไม่จะแจ้งให้ทราบเอง.
- เปิดเอกสารจริงในเบราว์เซอร์และดูสปินเนอร์ที่แสดงการทำงาน การสร้างสีเขียวไม่ได้พิสูจน์อะไรที่นี่: การให้ลิขสิทธิ์, การลงทะเบียนปลั๊กอิน, เส้นทางทรัพยากร, และคอลแบ็กของ Viewer ล้วนล้มเหลวเฉพาะในช่วงรันไทม์ สำหรับฟาร์ม ให้ตรวจสอบว่าเอกสารที่เผยแพร่โดยโหนดหนึ่งถูกให้บริการโดยโหนดอื่น.
การทดสอบการย้ายข้อมูล
อย่างน้อยที่สุด ให้ตรวจสอบ:
- การเริ่มต้นแอปพลิเคชันด้วยใบอนุญาตการผลิตและปลั๊กอินที่ลงทะเบียนทั้งหมด;
- CSS/สคริปต์ของ Viewer และคำขอภาพหน้าทั้งหมดภายใต้เส้นทางที่เลือก;
- การเปิดเอกสาร, การนำทาง, การซูม, รูปย่อ, การพิมพ์, และการปิดอย่างชัดเจน;
- การค้นหาในเอกสารที่มีข้อความและสถานะที่ไม่สามารถค้นหาได้ของไฟล์ที่เป็นภาพเท่านั้น;
- การโหลด, บันทึก, ส่งออกของคำอธิบายประกอบ, และการควบคุมความสามารถ;
- การค้นหาเป้าหมายของตัวแปลง, ผลลัพธ์, การดาวน์โหลด, และสถานะลายน้ำ;
- หน้า DICOM, เฟรม, และแอนิเมชัน; ข้อมูลเมตาเทคนิคไม่พร้อมใช้งานในแพคเกจนี้;
- เอกสารที่ป้องกันด้วยรหัสผ่าน, ฟอนต์ที่กำหนดเอง, ข้อความที่ไม่ใช่ละติน, และการตั้งค่า timeout;
- การปฏิเสธโทเค็นข้ามเซสชันและพฤติกรรมของเซสชันที่หมดอายุ;
- สำหรับฟาร์ม: เผยแพร่บนโหนดหนึ่ง, ขอหน้าที่ล่าช้าจากอีกโหนดหนึ่ง, และยืนยันว่า viewer พยายามใหม่กับการตอบกลับ
202แทนการแสดงแผ่นภาพที่เสีย; - มือถือ, โหมดมืด, และเส้นทาง reverse-proxy ของการผลิต.
แผนการคืนค่า
เก็บ artifact การปรับใช้ก่อนหน้า, แพคเกจที่ตรงกัน, ไฟล์ใบอนุญาต, และทรัพยากรเบราว์เซอร์ที่คัดลอกไว้ด้วยกัน. การคืนค่าที่ปลอดภัยจะสลับรุ่นของแอปพลิเคชันทั้งหมด; มันไม่ผสานเซิร์ฟเวอร์รุ่นก่อนหน้ากับสคริปต์ปัจจุบัน, หรือเซิร์ฟเวอร์ปัจจุบันกับการเรียก new Viewer(...).
ก่อนการตัดเปลี่ยน, ให้บันทึก:
- ช่องสลอตการปรับใช้หรือ artifact ที่ใช้สำหรับการคืนค่า;
- ผลกระทบต่อ shared-storage, หากมี — artifact ที่เผยแพร่โดยเวอร์ชัน 26.8.0 จะไม่ถูกใช้โดย middleware ของเว็บฟาร์มก่อนหน้า;
- วิธีการทำให้เซสชันเอกสารที่ใช้งานอยู่เป็นโมฆะ;
- การตรวจสอบสุขภาพและเอกสาร smoke ที่ใช้เพื่อพิจารณาการคืนค่า;
- ผู้ที่สามารถกู้คืนชุดแพคเกจและการกำหนดค่าก่อนหน้าได้.
เอกสารเก่า
คู่มือก่อนหน้าที่แปลแล้วยังคงพร้อมใช้งานที่ การตั้งค่า Legacy .NET Standard. ส่วนต่อประสานการบูรณาการก่อนหน้าPrevious integration gateway อธิบายสัญญาณการระบุตัวเดียวกันและลิงก์กลับไปยังคู่มือการย้ายนี้.
เก็บ URL ประวัติไว้ในบุ๊กมาร์กและตั๋วสนับสนุนในขณะที่การติดตั้ง netstandard2.0 ยังมีอยู่. มันบันทึกรุ่นที่แตกต่างและไม่ได้ถูกเปลี่ยนเส้นทางไปยัง API ปัจจุบัน.
หน้านี้เป็นประโยชน์หรือไม่?