ย้ายไปยัง .NET Standard 2.1

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

เวอร์ชันคือการแยกทาง

ทั้งสองรุ่นเผยแพร่ภายใต้ package ID เดียวกัน เพียงเวอร์ชันเท่านั้นที่แยกความแตกต่างระหว่างกัน:

การเพิ่มหมายเลขเวอร์ชันคือการอัปเกรด ไม่มีแพ็กเกจแยกต่างหากให้ติดตั้งและไม่มี shim ความเข้ากันได้ — 26.8.0 มีพื้นผิว API ที่แตกต่างกัน คาดว่าจะมีข้อผิดพลาดในการคอมไพล์หลังจากอัปเดต; ส่วนที่เหลือของคู่มือนี้เป็นรายการของข้อผิดพลาดเหล่านั้น

การบูรณาการแบบใดที่คุณใช้?

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

ตรวจสอบเฟรมเวิร์กโฮสต์ก่อน

นี่เป็นเกตที่เข้มงวด ไม่ใช่เรื่องของความชอบ แพ็กเกจปัจจุบันมุ่งเป้าไปที่ netstandard2.1:

.NET Framework ไม่สามารถอ้างอิงไลบรารี netstandard2.1 ได้ หากแอปพลิเคชันทำงานบน .NET Framework ให้หยุดที่นี่และใช้แพ็กเกจ Doconut.NETFramework แทน; ตั้งแต่เวอร์ชัน 26.9.0 จะต้องใช้ .NET Framework 4.7.2 ทั้งสองแอปพลิเคชันอ้างอิงสำหรับการปล่อยนี้มุ่งเป้าไปที่ net8.0

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

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

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

1. เนมสเปซ: เกือบทุกอย่างย้ายไปยังรูท

ประเภทการกำหนดค่าถูกกระจายอยู่ในสี่เนมสเปซ ตอนนี้ทั้งหมดอยู่ใน Doconut.

ชื่อประเภทไม่ได้เปลี่ยนแปลง: 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.8.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(); // สถานะเซสชันต้องการแคช (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() ก่อนสาขา

วิธีการที่ไม่มีอยู่แล้ว

4. Middleware และการกำหนดเส้นทางทรัพยากร

UseDoconut() ตอนนี้ไม่รับอาร์กิวเมนต์ใด ๆ รูปแบบสาขา MapWhen เองไม่ต้องเปลี่ยน — เพียง middleware ภายในเท่านั้น:

app.UseDoconutResources();   // BEFORE the branch

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

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

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

MiddlewarePath เป็นการกำหนดค่าที่ตรวจสอบ; มันไม่ได้สร้างสาขา ASP.NET Core ด้วยตนเอง.

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

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

โอเวอร์โหลดปัจจุบันรับพาธไฟล์หรือสตรีม, การกำหนดรูปแบบแบบเลือก, 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 เดียวกันตามด้านบน */;
    }, "/"));

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

ทั้งสองส่วนต้องสอดคล้องกัน หาก RootPath หรือ UsePerTokenSubfolders แตกต่างกันระหว่างผู้เผยแพร่และตัวจัดการ, โหนดอีกฝั่งจะตอบ 404. สร้างการกำหนดค่าในตัวช่วยหนึ่งและเรียกใช้จากทั้งสองด้าน.

PageWaitTimeSeconds = 180 หมายถึง "บล็อกสูงสุดสามนาทีเพื่อรอให้หน้าปรากฏ". การแทนที่เป็นแบบชัดเจน: ด้วย FirstPagePriority = true หน้าแรกจะให้บริการได้ทันทีและหน้าถัดไปจะตอบ HTTP 202 Accepted จนกว่าจะเขียนเสร็จ. Viewer ที่รวมมาพร้อมจะลองใหม่อัตโนมัติเมื่อ retryOn409 ถูกตั้งค่า. ลูกค้าที่ไม่ลองใหม่จะเห็นไทล์เสียสำหรับหน้าที่ยังกำลังเรนเดอร์.

การจัดเรียงเต็มรูปแบบ, รวมถึงการเผยแพร่เบื้องหลังและตั๋วเข้าถึง, อยู่ใน การปรับใช้แบบกระจาย.

8. การแปลงเป็นปลั๊กอินและมีขนาดเล็กกว่าเดิม

ลงทะเบียนปลั๊กอินแล้วฉีด DocumentConverter facade:

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, …) ซึ่งแต่ละประเภทมี EnTargetFormat enum ย่อย — หายไป. ตอนนี้มี ConversionTarget enum หนึ่งตัวสำหรับทุกตระกูล.
• viewer.Converter.GetConverter() — หายไป. ฉีด Doconut.DocumentConverter.

ConvertAsync คืนค่า stream ที่สามารถเลื่อนตำแหน่งได้ ดังนั้น return File(result, mime, name) ทำงานโดยตรง — การคัดลอก MemoryStream ที่โค้ดเก่าต้องการจึงไม่จำเป็น. ในตัวอย่างที่จัดส่งนี้ได้ลบสวิตช์ส่วนขยาย 68 กรณีและคอนโทรลเลอร์ที่คล้ายกันสิบตัวออก.

ดู ปลั๊กอินแปลง สำหรับรายละเอียดทั้งหมด.

9. ผู้ให้บริการคลาวด์

UseDoconutCloud กลายเป็น generic. ผู้ให้บริการเป็นอาร์กิวเมนต์ประเภทแทนค่าของ 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. วัตถุการกำหนดค่าที่เปลี่ยนชื่อ

DocOptions ยังเพิ่ม IsSecured ด้วย.

API ปัจจุบันยังแยกความรับผิดชอบอย่างเข้มงวดกว่ารุ่นก่อน ดังนั้นตรวจสอบว่าการตั้งค่าแต่ละอย่างอยู่บนอ็อบเจ็กต์ที่เป็นเจ้าของตอนนี้:

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

11. ตัวดูด้านคลไอเอนท์ — การเปลี่ยนแปลงสองอย่างที่ล้มเหลวโดยเงียบ

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

คอลแบ็กของตัวดูเป็นตัวเลือกแล้ว ไม่ใช่ฟังก์ชันทั่วโลก

ตัวดูเดิมเรียกตัวจัดการของคุณ ตามชื่อ, โดยสกัดชื่อฟังก์ชันทั่วโลกจาก id ของคอนเทนเนอร์. การประกาศ function ctlDoc_OnViewerReady() บนหน้าที่มี <div id="div_ctlDoc"> เพียงพอ. ตัวดูปัจจุบันรับคอลแบ็กอย่างชัดเจนในอ็อบเจ็กต์ options และไม่ค้นหาฟังก์ชันทั่วโลกเหล่านั้นอีกต่อไป:

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: '',                      // BEFORE — ทรัพยากรมาจากรูทของแอปพลิเคชัน
ResPath: 'doconut-res/images',    // NOW    — คำนำหน้าที่ UseDoconutResources() ติดตั้ง

หากคุณได้เปลี่ยนคำนำหน้าผ่าน DoconutOptions.ResourcesPath ให้ใช้ค่านั้นแทน

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

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

1. ส่งออก Viewer CSS และ Search/Annotation CSS ที่มีลิขสิทธิ์ด้วย ReferenceCss;
2. แสดงแถบเครื่องมือ Viewer ที่เป็นของแอปพลิเคชัน;
3. แสดง searchBarMount, annBarMount และส่วนที่จำเป็นของ Viewer;
4. ส่งออกสคริปต์ Viewer และโมดูลที่มีลิขสิทธิ์ด้วย ReferenceScripts;
5. โหลดสคริปต์ช่วยเหลือแถบเครื่องมือของแอปพลิเคชัน;
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 เท่านั้น

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

วิธีการแบบ static ของ 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(); // จำเป็นต้องมีแคชสำหรับสถานะเซสชัน (MVC/Razor Pages มีแล้ว)
builder.Services.AddSession();
app.UseSession();

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

ในสภาพแวดล้อมแบบฟาร์ม คำขอหน้าอาจไปยังโหนดที่ไม่เคยเห็นคำขอเปิดเอกสารแรก ดังนั้นการตรวจสอบต่อเซสชันจะถูกปฏิเสธ นี่คือกรณีเดียวที่ UnsafeMode = true ถือว่าถูกต้อง — แต่ต้องใช้ร่วมกับตั๋วเข้าถึงที่ลงลายเซ็นผ่าน AddDoconutDistributedDocumentSecurity ไม่ได้ใช้งานแยกจากกัน ดูที่ การปรับใช้แบบกระจาย

หมายเหตุการตั้งชื่อ

ในทุกเฟรมเวิร์กคลาสคือ Viewer หากคุณพบ DocumentViewer ในโค้ดตัวอย่างเก่าหรือบทความของบุคคลที่สาม นั่นเป็นชื่อที่ไม่มีอยู่จริงใน SDK

15. ลำดับการทำงานที่แนะนำ

1. ยืนยันว่าเฟรมเวิร์กโฮสต์สามารถใช้ netstandard2.1 ได้ หากไม่ได้ให้หยุดขั้นตอนนี้
2. เพิ่มเวอร์ชันแพคเกจเป็น 26.8.0 แล้วทำการคอมไพล์ แก้ไขข้อผิดพลาดที่เกิดขึ้น — ส่วนใหญ่เป็นบรรทัด using ใน §1
3. ย้ายการตั้งค่าเริ่มต้นไปที่ AddDoconut() และจัดเรียงการเรียก middleware ตามลำดับใหม่ (§3, §4)
4. แทรก Viewer ในที่ที่คุณสร้างมันก่อนหน้า ทำให้ OpenDocument เป็นแบบ async และลบ InitCache() (§5, §6)
5. หากใช้เว็บฟาร์ม ให้ทำตาม §7 — ส่วนนี้เป็นการออกแบบใหม่ ไม่ใช่การเปลี่ยนชื่อ
6. หากทำการแปลงเอกสาร ให้ทำตาม §8
7. ทำ §11 — การเปลี่ยนแปลงด้านไคลเอนต์ สิ่งเหล่านี้เป็นส่วนที่ไม่แสดงข้อความแจ้งเตือน
8. เปิดเอกสารจริงในเบราว์เซอร์และสังเกตสปินเนอร์ที่แสดง การสร้างสีเขียวไม่ได้พิสูจน์อะไร: ปัญหาเรื่องลิขสิทธิ์, การลงทะเบียนปลั๊กอิน, คำนำหน้าทรัพยากร, และคอลแบ็กของ viewer จะล้มเหลวเฉพาะตอนรันเท่านั้น สำหรับฟาร์ม ให้ตรวจสอบว่าเอกสารที่เผยแพร่จากโหนดหนึ่งถูกให้บริการโดยโหนดอื่นได้สำเร็จ

ทดสอบการย้ายข้อมูล

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

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

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

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

ก่อนการตัดสวิตช์, เอกสาร:

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

เอกสารเก่า

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

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