آموزش: باز کردن اسناد با Viewer تزریق‌شده Doconut در .NET 8

مقدمه

نمونه‌های قدیمی Doconut ممکن است Viewer را مستقیماً با آرگومان‌های cache، HTTP-context و license-path بسازند. این مدل یکپارچه‌سازی .NET 8 فعلی نیست. AddDoconut() Viewer را با تزریق وابستگی ثبت می‌کند و نقاط انتهایی برنامه سرویس را دریافت می‌کنند نه اینکه سازنده را فراخوانی کنند.

اجزای سرور انتزاعی که توکن جلسه مبهم را به سطح نمایش سند منتقل می‌کنند

این آموزش جریان درخواست فعلی را دنبال می‌کند: ثبت سرویس‌ها و میدل‌ویرها، انتشار منابع جاسازی‌شده viewer، باز کردن سند با OpenDocumentAsync، بازگرداندن توکن مبهم، و عبور آن توکن به ویجت مرورگر.

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();

میان‌افزارها را به ترتیب مورد نیاز وصل کنید. میدل‌ویر منابع باید قبل از میدل‌ویر نهایی سند اجرا شود:

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

MiddlewarePath پیکربندی را هماهنگ می‌کند اما به تنهایی شاخه ASP.NET را ایجاد نمی‌کند. مسیر /doconut نقشه‌گذاری‌شده باید با BasePath ویجت مطابقت داشته باشد.

2. افزودن سطح نمایشگر و منابع

Viewer مرورگر Doconut یک افزونه 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) ثبت می‌شود. آن را از طریق تزریق نقطه انتهایی، تزریق سازنده یا تسهیلات معادل در برنامه 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 });
});

قبل از باز کردن محتوای ارائه‌شده توسط کاربر، اندازه بارگذاری، پسوند و مجوز را اعتبارسنجی کنید. نام فایل ارسال‌شده را به مسیر سرور تبدیل نکنید.

4. عبور توکن به ویجت

نقطه انتهایی باز کردن را فراخوانی کنید و توکن بازگشتی را به 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));

توکن را به‌عنوان اعتبار حامل برای یک جلسه سند زنده در نظر بگیرید:

توکن را لاگ یا ذخیره نکنید.
فقط به یک مشتری مجاز بازگردانید.
مسیر فایل منبع را فاش نکنید.
هنگامی که جلسه منقضی شد، سند را دوباره باز کنید.
زمانی که سند دیگر مورد نیاز نیست، جلسه را ببندید.

5. بستن جلسات سمت سرور به‌صورت عمدی

کد کلاینت می‌تواند هنگام خروج کاربر از viewer objViewer.Close() را فراخوانی کند. جریان‌های سروری نیز می‌توانند توکن شناخته‌شده را به‌صورت صریح لغو کنند:

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()`
Static license-loading calls in request code	پیکربندی ورودی لایسنس در `AddDoconut()`
Synchronous `OpenDocument(...)` examples	استفاده از `OpenDocumentAsync(...)`
An external or invented viewer CDN	انتشار منابع جاسازی‌شده با `ReferenceCss` و `ReferenceScripts`
A generic JavaScript `init()` API	مقداردهی اولیه `$('#div_ctlDoc').docViewer(...)`
Persisting the viewer token	شناسه سند خود را ذخیره کنید؛ توکن را موقت در نظر بگیرید

از مستندات رسمی Doconut استفاده کنید و مثال‌ها را نسبت به نسخه نصب‌شده بسته بررسی کنید قبل از این‌که آن‌ها را در کد تولید به‌کار ببرید.