Быстрый старт
Отобразите ваш первый документ за несколько минут
Этот пошаговый гид переводит приложение 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 во время Установка? Перейдите к следующему разделу.
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, что и раньше:
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:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Рассматривайте панель инструментов, монтирование модулей и поверхность Viewer как единую композицию страницы. Поиск и Аннотация внедряют свои встроенные ленты в необязательные монтирования, но эти модули никогда не работают отдельно: они всегда присоединяются к Viewer на той же странице.
<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 должен быть загружен до скриптов просмотрщика:
@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.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. Это минимальный набор реальных параметров инициализации (не псевдокод):
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:
<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>Соблюдайте следующий порядок инициализации:
- Выпустите CSS для Viewer и лицензированных модулей.
- Отобразите панель инструментов Viewer, монтирования Search/Annotation и монтирование Viewer вместе.
- Выпустите скрипты для Viewer и лицензированных модулей.
- Загрузите вспомогательный скрипт панели инструментов собственного приложения‑хоста.
- Инициализируйте
docViewerи сохраните полученныйobjViewer. - Инициализируйте каждую лицензированную ленту Search или Annotation.
- Вызовите
attach(objViewer)для каждой ленты. - Откройте документ и сохраните его токен для запросов Viewer и модулей.
Защита на стороне сервера важна: когда опциональная возможность недоступна, её скрипт не выводится, поэтому её функция jQuery‑плагина не существует.
<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 открывает документ и возвращает токен сеанса. Открытие происходит асинхронно в этом выпуске.
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):
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) немедленно удаляет кэшированный сеанс, освобождает движок рендеринга, удаляет его маркер безопасности и аннулирует токен. Скользящее истечение срока действия в конечном итоге выполняет ту же очистку, но явное закрытие рекомендуется для больших документов.
Завершённый поток запросов выглядит так:
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 находит лицензию и какие изменения происходят после её обнаружения.
Была ли эта страница полезной?