Посібник: Відкриття документів за допомогою впровадженого переглядача Doconut у .NET 8

Вступ

Старі приклади Doconut могли створювати Viewer безпосередньо з аргументами кешу, HTTP‑контексту та шляху до ліцензії. Це не є поточною моделлю інтеграції .NET 8. AddDoconut() реєструє 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 у браузері — це 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 зареєстровано як транзитний сервіс. Отримайте його через впровадження в кінцеву точку, конструкторне впровадження або аналогічний механізм у вашій 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. Навмисне закриття серверних сесій

Клієнтський код може викликати objViewer.Close(), коли користувач залишає переглядач. Серверні робочі процеси також можуть явно анулювати відомий токен:

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

Явне закриття особливо корисне для великих документів. Закінчення сесії залишається резервним варіантом, а не заміною передбачуваного управління життєвим циклом програми.

6. Додавання додаткових модулів лише після успішної роботи ядра

Пошук та анотації підключаються до того ж ініціалізованого переглядача. Додавайте їх 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 і перевіряйте приклади проти встановленої версії пакету перед їх адаптацією до продуктивного коду.