Быстрый старт

Отобразите ваш первый документ за несколько минут

Этот пошаговый гид переводит приложение ASP.NET Core из пустого Program.cs в документ, отображаемый в браузере: регистрация сервера, полный пакет Viewer (панель инструментов Viewer, монтирование Viewer и необязательные ленты Поиска/Аннотаций), ссылки на ресурсы, инициализация клиента, открытие документа и выполнение.

Хост‑приложение должно целиться в среду выполнения, поддерживающую netstandard2.1 — .NET Core 3.0 или новее.

Server setup

AddDoconut() регистрирует сервисы; UseDoconutResources() и UseDoconut() подключают middleware. Вызов ресурсов должен быть первым. UseDoconut() отвечает на каждый запрос, который к нему попадает, поэтому смонтируйте его на отдельной ветке с помощью app.Map. Вызовы сессии также необходимы — стандартная безопасность документов Doconut проверяет каждый запрос страницы против состояния сессии ASP.NET. Состоянию сессии нужен кэш: AddDistributedMemoryCache() предоставляет его. Приложение MVC или Razor Pages уже регистрирует его, но минимальное приложение API — нет, и без него приложение останавливается при запуске с Unable to resolve service for type 'IDistributedCache'. Уже регистрировали Doconut во время Установка? Перейдите к следующему разделу.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // состояние сеанса требует кэш (MVC/Razor Pages уже добавляют его)
builder.Services.AddSession(); // Безопасность документов Doconut опирается на состояние сеанса ASP.NET

app.UseSession();          // вызовите UseSession() перед UseDoconut()
app.UseDoconutResources(); // должно быть зарегистрировано перед UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

Эта настройка сохраняет историческую форму запросов DocImage.axd и монтирует middleware документа на соответствующей ветке. Это конфигурация, которую следует копировать при переносе существующего приложения .NET Standard, поскольку клиент продолжает обращаться к тому же URL, что и раньше:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // оставьте проверку сеанса Doconut\u0027s включённой
    options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // состояние сеанса требует кэш (MVC/Razor Pages уже добавляют его)
builder.Services.AddSession(options =>
{
    options.IdleTimeout        = TimeSpan.FromSeconds(3600);
    options.Cookie.HttpOnly    = true;
    options.Cookie.IsEssential = true;
});

// Требуется для многобайтовых кодировок в некоторых форматах документов.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();   // ПЕРЕД веткой документа
app.MapWhen(
    context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconut() не принимает опций в этом выпуске — всё перенесено в AddDoconut(). MiddlewarePath — это значение координации; оно само по себе не сопоставляет ветку ASP.NET Core. С веткой DocImage.axd выше клиент использует BasePath: '/'; с app.Map("/doconut", ...) из минимальной настройки клиент использует BasePath: 'doconut'. ResourcesPath обслуживает встроенный пакет по адресу /doconut-res, а путь к ресурсам изображений виджета соответственно ResPath: 'doconut-res/images'.

Add the viewer to a page

Viewer — обязательное ядро страницы. Его поверхность рендеринга использует два вложенных div:

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

Рассматривайте панель инструментов, монтирование модулей и поверхность Viewer как единую композицию страницы. Поиск и Аннотация внедряют свои встроенные ленты в необязательные монтирования, но эти модули никогда не работают отдельно: они всегда присоединяются к Viewer на той же странице.

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Кнопки навигации, масштабирования, поиска и аннотаций Viewer -->
</nav>

<div id="searchBarMount"></div>
<div id="annBarMount"></div>

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

Ссылка на ресурсы просмотрщика

В Razor‑представлении внедренный сервис Viewer выводит теги <link> и <script> просмотрщика в порядке зависимостей — виджет является плагином jQuery, поэтому jQuery должен быть загружен до скриптов просмотрщика:

html
@inject Doconut.Viewer Viewer

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

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

Чтобы получить полный пакет Viewer, запросите ресурсы Viewer и модуля одновременно:

html
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeBootstrapCss  = true,
    IncludeViewerCss     = true,
    IncludeSearchCss     = true,
    IncludeAnnotationCss = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery            = true,
    IncludeBootstrap         = true,
    IncludeViewerScripts     = true,
    IncludeSearchScripts     = true,
    IncludeSearchBar         = true,
    IncludeAnnotationScripts = true,
    IncludeAnnotationBar     = true
}))

IncludeViewerCss и IncludeViewerScripts являются обязательными флагами ядра. Никогда не публикуйте пример Search или Annotation Ribbon без них, монтирования Viewer и экземпляра docViewer. ReferenceCss и ReferenceScripts опускают ресурсы необязательного модуля, если текущая лицензия не предоставляет эту возможность; ядро Viewer всё равно запускается.

Эти вызовы заменяют вручную скопированные файлы скриптов. Если приложение всё ещё загружает свои собственные docViewer.js, documentLinks.js или docViewer.UI.js, удалите эти теги, как только страница начнёт работать с выданными ресурсами — см. руководство по миграции.

Инициализация просмотрщика

Клиентский виджет является плагином jQuery. Это минимальный набор реальных параметров инициализации (не псевдокод):

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // ветка DocImage.axd; 'doconut' с app.Map("/doconut", ...)
    ResPath:    'doconut-res/images',
    onViewerReady: function () {
        // страницы видимы; безопасно скрыть индикатор загрузки здесь
    },
    // Перенаправлять события жизненного цикла аннотации во встроенную ленту, когда она присутствует.
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Четыре детали определяют, будет ли эта страница работать вообще:

  • Обратные вызовы являются параметрами. onViewerReady, onViewerBusy, onCopy и onAutoLoadStatus передаются в объекте параметров. Предыдущий просмотрщик выводил имена глобальных функций из id контейнера и вызывал их; этот этого не делает. Обработчик, объявленный только как глобальная функция, никогда не запускается, и о нём ничего не сообщается.
  • ResPath указывает на префикс ресурсов, а не на корень приложения. При значении по умолчанию ResourcesPath, это значение равно doconut-res/images. Если вы изменили ResourcesPath, используйте свой собственный префикс. Иконки находятся на одну папку ниже корня ресурсов: при 'doconut-res' каждая иконка возвращает 404, хотя сам документ всё ещё отображается.
  • BasePath не имеет начального слеша, кроме значения корня сайта '/'. 'doconut' запрашивает /doconut/DocImage.axd; '/doconut' генерирует //doconut/DocImage.axd, который браузер воспринимает как запрос к другому хосту.
  • Сохраните просмотрщик, затем вызывайте View отдельно. docViewer(...) возвращает объект с Zoom, Next и FitType; View(...) возвращает что‑то другое. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) отображает документ, затем при первом клике по панели инструментов происходит ошибка objViewer.Zoom is not a function.

Все эти ошибки происходят тихо — см. Устранение неполадок и руководство по миграции.

Регистрозависимость параметров действительно смешана — showThumbs, autoLoad и pageZoom записаны в camelCase, а FitType, BasePath и ResPath — в PascalCase. Нет единого правила; если регистр указан неверно, параметр будет тихо проигнорирован (виджет вернётся к значениям по умолчанию вместо выброса ошибки).

Сборка полного пакета Viewer

Полная страница Viewer устанавливает следующие части вместе:

Часть пакетаТребованиеКак подключено
Ресурсы Viewer, монтирование и objViewerОбязательноОсновной рендерер документа
Панель инструментов ViewerТребуется для полной страницыРазметка хоста; кнопки вызывают тот же objViewer
Лента поискаОпциональный, лицензированный модульdoconutSearchBar(...).attach(objViewer)
Лента аннотацийОпциональный, лицензированный модульdoconutAnnotationBar(...).attach(objViewer)

Хотя основная панель инструментов Viewer является разметкой хоста, она устанавливается вместе с Viewer и никогда не должна документироваться как отдельный элемент управления. Это сохраняет её макет, подписи, значки и правила авторизации под контролем вашего приложения, в то время как каждая кнопка управляет тем же экземпляром Viewer:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <button type="button" onclick="objViewer.GotoPage(1)">First</button>
    <button type="button" onclick="objViewer.Next(false)">Previous</button>
    <button type="button" onclick="objViewer.Next(true)">Next</button>
    <button type="button" onclick="objViewer.GotoPage(objViewer.TotalPages())">Last</button>
    <button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
    <button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
    <button type="button" onclick="objViewer.FitType('width')">Fit width</button>
    <button type="button" onclick="objViewer.FitType('height')">Fit height</button>
    <button type="button" id="openSearch">Search</button>
    <button type="button" id="openAnnotations">Annotations</button>
</nav>

Соблюдайте следующий порядок инициализации:

  1. Выпустите CSS для Viewer и лицензированных модулей.
  2. Отобразите панель инструментов Viewer, монтирования Search/Annotation и монтирование Viewer вместе.
  3. Выпустите скрипты для Viewer и лицензированных модулей.
  4. Загрузите вспомогательный скрипт панели инструментов собственного приложения‑хоста.
  5. Инициализируйте docViewer и сохраните полученный objViewer.
  6. Инициализируйте каждую лицензированную ленту Search или Annotation.
  7. Вызовите attach(objViewer) для каждой ленты.
  8. Откройте документ и сохраните его токен для запросов Viewer и модулей.

Защита на стороне сервера важна: когда опциональная возможность недоступна, её скрипт не выводится, поэтому её функция jQuery‑плагина не существует.

html
<script>
    let token = '';

    const refitViewer = () =>
        requestAnimationFrame(() => objViewer.Refit());

    @if (Viewer.IsSearchEnabled)
    {
        <text>
    searchBar = $('#searchBarMount').doconutSearchBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token }),
        onLayout: refitViewer
    });
    searchBar.attach(objViewer);
        </text>
    }

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token }),
        onLayout: refitViewer
    });
    annBar.attach(objViewer);
        </text>
    }

    document.getElementById('openSearch').addEventListener('click', () => {
        if (!searchBar) return;
        searchBar.isOpen() ? searchBar.close() : searchBar.open();
    });

    document.getElementById('openAnnotations').addEventListener('click', () => {
        if (!annBar) return;
        annBar.isOpen() ? annBar.close() : annBar.open();
    });
</script>

Оба встроенных компонента генерируют собственный DOM ленты. Search содержит группы Find, Options и Results. Annotation содержит инструменты редактирования, элементы управления стилем, действия сохранения и опциональные действия экспорта/изображения. Панели предоставляют open(), close(), reset() и isOpen(); всегда вызывайте attach(objViewer) один раз после их создания.

В приведённом выше примере опущены опциональные обратные вызовы хоста и конечные точки экспорта/изображения Annotation, чтобы минимизировать запуск. См. Search и Annotations для полного настройки функций, или Custom Themes для стилизации или замены панели инструментов Viewer, принадлежащей хосту.

Открыть документ

Серверная часть представляет собой одну конечную точку: внедрённый сервис Viewer открывает документ и возвращает токен сеанса. Открытие происходит асинхронно в этом выпуске.

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // token является непрозрачным — передайте его widget, никогда не записывайте в лог и не сохраняйте его.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Клиент получает этот токен и передаёт его виджету с помощью objViewer.View(token):

javascript
fetch('/api/open', { method: 'POST' })
    .then(resp => resp.json())
    .then(data => {
        token = data.token;
        objViewer.View(token);
    });

Перед первым открытием ничего не требуется разогревать. Если вы переносите приложение
вперёд, удалите любые вызовы InitCache() и флаг, их защищающий — метод больше не
существует.

Закрыть документ

Вызовите objViewer.Close(true), когда пользователь покидает просмотрщик или открывает заменяющий документ: он очищает виджет и отправляет запрос на закрытие серверу. objViewer.Close() без аргументов очищает только виджет. При серверных рабочих процессах viewer.CloseDocument(token) немедленно удаляет кэшированный сеанс, освобождает движок рендеринга, удаляет его маркер безопасности и аннулирует токен. Скользящее истечение срока действия в конечном итоге выполняет ту же очистку, но явное закрытие рекомендуется для больших документов.

Завершённый поток запросов выглядит так:

text
AddDoconut + middleware
    -> render CSS/scripts and mount div
    -> initialize docViewer
    -> OpenDocumentAsync
    -> return opaque token
    -> objViewer.View(token)
    -> page/search/annotation requests
    -> Close / CloseDocument

Обращайтесь с токеном как с удостоверением‑носителем: никогда не записывайте его в журнал, никогда не сохраняйте, передавайте его только виджету. Он идентифицирует активный сеанс документа на сервере и перестаёт работать, когда срок сеанса истекает — откройте документ заново, чтобы получить новый.

Запустить

Разместите PDF по адресу wwwroot/files/Sample.pdf, запустите dotnet run и откройте страницу, содержащую виджет. Первая страница отображается во просмотрщике, с панелью миниатюр слева. Если этого не происходит, см. раздел Устранение неполадок.

Что вы получаете без лицензии

Отсутствие лицензии не вызывает ошибку. Просмотрщик отображает документ нормально, но каждая страница содержит водяной знак оценки. См. Настройка лицензии для того, как Doconut находит лицензию и какие изменения происходят после её обнаружения.

Была ли эта страница полезной?