Посібник: Відкриття документів за допомогою впровадженого Doconut Viewer у .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()`
Статичні виклики завантаження ліцензії у коді запиту	Налаштуйте введення ліцензії у `AddDoconut()`
Синхронні приклади `OpenDocument(...)`	Використовуйте `OpenDocumentAsync(...)`
Зовнішній або вигаданий CDN переглядача	Виводьте вбудовані ресурси за допомогою `ReferenceCss` та `ReferenceScripts`
Загальний JavaScript API `init()`	Ініціалізуйте `$('#div_ctlDoc').docViewer(...)`
Збереження токену переглядача	Зберігайте ваш ідентифікатор документа; розглядайте токен як тимчасовий

Використовуйте офіційну документацію Doconut і перевіряйте приклади проти встановленої версії пакету перед їх адаптацією до продуктивного коду.