บทแนะนำ: เปิดเอกสารด้วย Doconut Viewer ที่ฉีดเข้าใน .NET 8

บทนำ

ตัวอย่าง Doconut รุ่นเก่าอาจสร้าง Viewer โดยตรงด้วยอาร์กิวเมนต์ cache, HTTP-context, และ license-path นั่นไม่ใช่โมเดลการบูรณาการของ .NET 8 ปัจจุบัน AddDoconut() ลงทะเบียน Viewer ด้วย dependency injection และ endpoint ของแอปพลิเคชันจะรับบริการแทนการเรียกคอนสตรัคเตอร์.

ส่วนประกอบเซิร์ฟเวอร์เชิงนามธรรมส่ง token เซสชันที่ไม่เปิดเผยไปยังพื้นผิวการดูเอกสาร

บทแนะนำนี้ทำตามลำดับการร้องขอปัจจุบัน: ลงทะเบียนบริการและ middleware, ส่งออกทรัพยากร viewer ที่ฝังอยู่, เปิดเอกสารด้วย OpenDocumentAsync, คืนค่า token เซสชันที่ไม่เปิดเผย, และส่ง token นั้นไปยังวิดเจ็ตของเบราว์เซอร์.

1. ติดตั้งและลงทะเบียน Doconut

เพิ่มแพคเกจ .NET 8:

dotnet add package Doconut.NET8

ลงทะเบียน Doconut และบริการเซสชันของ ASP.NET:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false;
});

builder.Services.AddSession();

เชื่อมต่อ middleware ตามลำดับที่ต้องการ Middleware ของทรัพยากรต้องทำงานก่อน middleware ของเอกสารขั้นสุดท้าย:

app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());

MiddlewarePath ประสานการกำหนดค่าแต่ไม่ได้สร้างสาขา ASP.NET ด้วยตัวเอง เส้นทางที่แมพ /doconut ต้องตรงกับ BasePath ของวิดเจ็ต.

2. เพิ่มพื้นผิว viewer และทรัพยากร

Doconut browser viewer เป็นปลั๊กอิน jQuery ในหน้า Razor ให้ฉีด Viewer และขอให้มันส่งออกแท็กทรัพยากรตามลำดับการพึ่งพา:

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery = true,
    IncludeViewerScripts = true
}))

<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

เริ่มต้นวิดเจ็ตด้วยเส้นทางที่ตรงกับการลงทะเบียนบนเซิร์ฟเวอร์:

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad: false,
    pageZoom: 100,
    FitType: 'width',
    BasePath: '/doconut',
    ResPath: '/doconut-res/images',
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

การตั้งค่าตัวพิมพ์ใหญ่‑เล็กมีความสำคัญ ใช้ชื่อที่แสดงโดยเวอร์ชันที่ติดตั้งแทนการทำให้เป็นรูปแบบเดียวกัน.

3. ฉีด Viewer และเปิดเอกสาร

Viewer ลงทะเบียนเป็นบริการแบบ transient ให้ดึงผ่านการฉีด endpoint, การฉีดคอนสตรัคเตอร์ หรือกลไกที่เทียบเท่าในแอป ASP.NET Core ของคุณ.

app.MapPost("/api/open", async (
    Viewer viewer,
    CancellationToken ct) =>
{
    string token = await viewer.OpenDocumentAsync(
        "wwwroot/files/Sample.pdf",
        ct: ct);

    return Results.Ok(new { token });
});

สำหรับการอัปโหลด ให้สตรีมและ FileInfo ที่ส่วนขยายระบุรูปแบบแหล่งที่มา:

app.MapPost("/api/open-upload", async (
    IFormFile file,
    Viewer viewer,
    CancellationToken ct) =>
{
    await using var stream = file.OpenReadStream();
    string token = await viewer.OpenDocumentAsync(
        stream,
        new FileInfo(file.FileName),
        ct: ct);

    return Results.Ok(new { token });
});

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

ดึง endpoint ที่เปิดและส่ง token ที่ได้กลับไปยัง objViewer.View:

fetch('/api/open', { method: 'POST' })
    .then(response => {
        if (!response.ok) throw new Error('The document could not be opened.');
        return response.json();
    })
    .then(data => objViewer.View(data.token))
    .catch(error => console.error(error));

ถือ token ว่าเป็นข้อมูลรับรองแบบ bearer สำหรับเซสชันเอกสารสด:

ห้ามบันทึกหรือเก็บรักษาไว้
คืนค่าให้เฉพาะไคลเอนต์ที่ได้รับอนุญาต
ห้ามเปิดเผยเส้นทางไฟล์ต้นฉบับ
เปิดเอกสารใหม่เมื่อเซสชันหมดอายุ
ปิดเซสชันเมื่อเอกสารไม่จำเป็นต้องใช้ต่อ

5. ปิดเซสชันฝั่งเซิร์ฟเวอร์โดยเจตนา

โค้ดฝั่งคลไอเอนท์สามารถเรียก objViewer.Close() เมื่อผู้ใช้ออกจาก viewer ได้ กระบวนการฝั่งเซิร์ฟเวอร์ก็สามารถเพิกถอน token ที่รู้จักโดยชัดเจน:

app.MapPost("/api/close", (string token, Viewer viewer) =>
{
    viewer.CloseDocument(token);
    return Results.NoContent();
});

การปิดแบบชัดเจนมีประโยชน์เป็นพิเศษสำหรับเอกสารขนาดใหญ่ การหมดอายุของเซสชันยังคงเป็นวิธีสำรอง ไม่ใช่การแทนที่การจัดการวงจรชีวิตแอปพลิเคชันที่คาดเดาได้.

6. เพิ่มโมดูลเสริมหลังจากส่วนหลักทำงาน

การค้นหาและคำอธิบายแนบกับ viewer ที่ได้เริ่มต้นแล้ว ให้เพิ่ม CSS, สคริปต์, การเมานท์, การตรวจสอบลิขสิทธิ์, และคอลแบ็กของวงจรชีวิตเฉพาะหลังจากกระบวนการหลักสำเร็จ:

AddDoconut + session services
    -> UseSession
    -> UseDoconutResources
    -> mapped UseDoconut branch
    -> viewer resources and mount
    -> initialize docViewer
    -> OpenDocumentAsync
    -> objViewer.View(token)

ลำดับนี้ทำให้ความล้มเหลวของการเรนเดอร์ส่วนหลักแยกจากการกำหนดค่าโมดูลเสริมได้อย่างชัดเจน.

ข้อผิดพลาดทั่วไปในการย้าย

รูปแบบเก่าหรือไม่ถูกต้อง	แนวทาง .NET 8 ปัจจุบัน
`new Viewer(cache, accessor, licensePath)`	ฉีด `Viewer` หลังจาก `AddDoconut()`
การเรียกโหลดใบอนุญาตแบบคงที่ในโค้ดคำขอ	กำหนดค่าการป้อนใบอนุญาตใน `AddDoconut()`
ตัวอย่าง `OpenDocument(...)` แบบซิงโครนัส	ใช้ `OpenDocumentAsync(...)`
CDN viewer ภายนอกหรือที่สร้างขึ้น	ส่งออกทรัพยากรฝังด้วย `ReferenceCss` และ `ReferenceScripts`
API `init()` ของ JavaScript ทั่วไป	เริ่มต้น `$('#div_ctlDoc').docViewer(...)`
การเก็บ token ของ viewer	เก็บ ID ของเอกสารของคุณ; ปฏิบัติกับ token ว่าเป็นชั่วคราว

ใช้ เอกสาร Doconut อย่างเป็นทางการ และตรวจสอบตัวอย่างกับเวอร์ชันแพคเกจที่ติดตั้งก่อนนำไปปรับใช้ในโค้ดผลิตจริง.