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

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

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

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

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

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

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

بستن صریح به‌ویژه برای اسناد بزرگ مفید است. انقضای جلسه به‌عنوان یک راه‌حل پشتیبان باقی می‌ماند و جایگزین مدیریت پیش‌بینی‌شده چرخه حیات برنامه نیست.

6. افزودن ماژول‌های اختیاری فقط پس از کارکرد هسته

جستجو و حاشیه‌نویسی‌ها به همان viewer مقداردهی‌شده متصل می‌شوند. CSS، اسکریپت‌ها، mountها، بررسی‌های لایسنس و callbackهای چرخه حیات را فقط پس از موفقیت جریان پایه اضافه کنید:

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)`	پس از `AddDoconut()` `Viewer` را تزریق کنید
فراخوانی‌های بارگذاری استاتیک لایسنس در کد درخواست	ورودی لایسنس را در `AddDoconut()` پیکربندی کنید
مثال‌های `OpenDocument(...)` همزمان	از `OpenDocumentAsync(...)` استفاده کنید
CDN خارجی یا ساختگی viewer	منابع توکار را با `ReferenceCss` و `ReferenceScripts` تولید کنید
API عمومی JavaScript `init()`	`$('#div_ctlDoc').docViewer(...)` را مقداردهی کنید
ذخیره توکن viewer	شناسه سند خود را ذخیره کنید؛ توکن را موقت در نظر بگیرید

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