Быстрый старт
Отобразите ваш первый документ в MVC 5 или Web Forms
Это руководство переводит приложение ASP.NET на .NET Framework 4.7.2 из установленного пакета в документ, отображаемый в браузере: Global.asax, открытый конечный пункт, ресурсы просмотрщика, виджет и токен, связывающий их. Предполагается, что регистрации Web.config из Установка выполнены — без обработчика DocImage.axd и модуля ресурсов ничего ниже не сможет достичь сервера.
Составление Doconut в Global.asax
Полный Application_Start для приложения MVC 5:
// Global.asax.cs - создавать один раз на процесс‑воркер, освобождать при завершении.
protected void Application_Start()
{
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.UnsafeMode = false; // страница обслуживается только той сессией, которая открыла документ
});
// Только MVC: держите два эндпоинта Doconut вне маршрутизации.
RouteTable.Routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
RouteTable.Routes.IgnoreRoute("doconut-res/{*pathInfo}");
}
protected void Application_End()
{
Doconut.DoconutHost.Shutdown();
}Encoding.RegisterProviderделает доступными для процесса устаревшие страницы кода, используемые некоторыми форматами документов. Вызовите его один раз, перед открытием первого документа.UnsafeMode = falseявляется значением по умолчанию, явно указано, чтобы никто случайно не изменил его:DocImage.axdобслуживает страницу только для ASP.NET‑сессии, открывшей документ.- Два вызова
IgnoreRouteудерживают маршрутизацию MVC подальше отDocImage.axdи/doconut-res/*, которые обслуживают обработчик и модуль. Приложение Web Forms не имеет маршрутов MVC и не нуждается в этой строке. DoconutHost.Shutdownостанавливает фоновые задачи Doconut и освобождает его сервисы при переразборе пула приложений. Вызывать его безопасно, даже еслиInitializeникогда не запускался.
Открыть документ
Открытие документа возвращает непрозрачный токен. Виджет отправляет этот токен с каждым запросом страницы.
В MVC 5 действие контроллера получает сервис Viewer из DoconutHost.Services — в MVC 5 нет внедрения через конструктор для него:
// POST /Document/Open
[HttpPost]
public async Task<ActionResult> Open()
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
// Токен непрозрачный - передайте его просмотрщику, никогда не логируйте и не сохраняйте его.
string token = await viewer.OpenDocumentAsync(Server.MapPath("~/files/Sample.pdf"));
return Json(new { token });
}Документ должен быть открыт внутри запроса, имеющего состояние сессии, поскольку именно открытие предоставляет текущей ASP.NET‑сессии доступ к его страницам. Контроллеры MVC и страницы Web Forms имеют состояние сессии по умолчанию. Пользовательский IHttpHandler его не имеет, если только он не реализует System.Web.SessionState.IRequiresSessionState. Откройте документ из обработчика без него, и просмотрщик будет показывать «У вас нет прав для просмотра этой страницы.» на каждой странице.
В Web Forms сама страница может открыть документ в своем коде‑заднем плане. OpenDocument — синхронная форма OpenDocumentAsync, предназначенная для кода‑заднего плана, не использующего асинхронные страницы:
// Default.aspx.cs
protected string Token;
protected void Page_Load(object sender, EventArgs e)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
Token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
}Обращайтесь с токеном как с удостоверением‑носителем: никогда не записывайте его в журнал и не сохраняйте; передавайте его только виджету. Он перестаёт работать, когда сессия документа истекает — откройте документ снова, чтобы получить новый токен.
Ссылка на ресурсы просмотрщика
Viewer.ReferenceCss и Viewer.ReferenceScripts генерируют теги <link> и <script> для встроенных ресурсов, в порядке зависимостей, указывая на /doconut-res/. Виджет — это плагин jQuery, поэтому jQuery загружается первым.
MVC 5. Представления не имеют @inject, поэтому генерируйте теги в контроллере и передайте их через ViewBag:
public ActionResult Index()
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true
});
ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true
});
return View();
}@Html.Raw(ViewBag.ViewerCss)
...
@Html.Raw(ViewBag.ViewerScripts)Оставьте эту работу в контроллере. MVC 5 компилирует представления при первом их обслуживании, и без дополнительного пакета компилятора этот компилятор понимает только C# 5 — нет ?., нет $"...", нет nameof. Представление, использующее их, успешно компилируется в Visual Studio, а в браузере возвращает пустой 500.
Web Forms. Откройте те же строки из кода‑behind и запишите их с помощью <%= %>:
<head>
<%= ViewerCss %>
</head>
<body>
...
<%= ViewerScripts %>
</body>IncludeViewerCss и IncludeViewerScripts — обязательное ядро. Чтобы добавить ленты поиска и аннотаций, также задайте IncludeSearchCss, IncludeAnnotationCss, IncludeSearchScripts, IncludeSearchBar, IncludeAnnotationScripts и IncludeAnnotationBar. Оба метода опускают файлы ленты, если лицензия не предоставляет эту возможность; сам просмотрщик всё равно запускается.
Добавление просмотрщика на страницу
Поверхность рендеринга состоит из двух вложенных div:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Задайте внешнему div реальную высоту — просмотрщик заполняет свой контейнер и измеряет его при запуске. Просмотрщик не рисует собственную панель инструментов: GotoPage, Next, Zoom, FitType, а остальные — это методы, которые ваша страница привязывает к своим кнопкам, размещённым рядом с просмотрщиком:
<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.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>
</nav>Инициализация просмотрщика и отображение документа
После скриптов просмотрщика создайте виджет, затем передайте ему токен:
var objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: '/', // '/' означает DocImage.axd в корне сайта
ResPath: 'doconut-res/images', // нет ведущего '/'
onViewerReady: function () {
// страницы видимы; скрыть индикатор загрузки здесь
},
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});
fetch('/Document/Open', { method: 'POST' })
.then(function (resp) { return resp.json(); })
.then(function (data) { objViewer.View(data.token); });В Web Forms, где страница сама открывает документ, последние три строки становятся objViewer.View('<%= Token %>');.
Четыре детали здесь приводят к сбоям без сообщения об ошибке:
BasePath: '/'указывает наDocImage.axdв корне сайта. Для приложения в виртуальном каталоге используйте его имя без слешей ('myapp'запрашивает/myapp/DocImage.axd). Начальный слеш ('/myapp') приводит к//myapp/DocImage.axd, который браузер воспринимает как запрос к другому хосту.ResPath: 'doconut-res/images'— иконки находятся на одну папку ниже корня ресурсов. При использовании'doconut-res'каждая иконка возвращает 404: нет значков панели инструментов и индикатора загрузки, хотя сам документ всё ещё отображается. Начальный слеш ломает это так же, какBasePath.- Обратные вызовы — параметры.
onViewerReady,onErrorи остальные передаются в объект, передаваемый вdocViewer(...). Глобальная функция, названная в честь просмотрщика, напримерctlDoc_ViewerReady, никогда не вызывается. - Сохраните просмотрщик, а затем вызовите
Viewотдельно.docViewer(...)возвращает объект сZoom,NextиFitType;View(...)возвращает что‑то другое.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)рендерит документ, затем падает сobjViewer.Zoom is not a functionпри первом щелчке по панели инструментов.
Имена параметров смешивают camelCase (showThumbs, autoLoad, pageZoom) и PascalCase (FitType, BasePath, ResPath). Ошибочно написанный параметр игнорируется, и виджет использует значение по умолчанию.
Однострочная альтернатива
Для страницы, которой нужно лишь отобразить документ и у которой нет собственной панели инструментов, Viewer.RenderViewer пишет весь скрипт инициализации — docViewer(...) с BasePath: '/' и ResPath: 'doconut-res/images', затем .View(token). Он существует только в этом пакете:
// Default.aspx.cs
protected string ViewerInit;
protected void Page_Load(object sender, EventArgs e)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
string token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
ViewerInit = viewer.RenderViewer("div_ctlDoc", token);
}<div id="div_ctlDoc" style="height: 100vh"></div>
<%= ViewerScripts %>
<%= ViewerInit %>Передайте ViewerConfig в качестве третьего аргумента, чтобы изменить масштаб, подгонку или панель миниатюр. Поскольку сгенерированный скрипт не хранит ссылку на просмотрщик, используйте написанную вручную инициализацию выше, когда вашей странице нужна собственная панель инструментов.
Закрыть документ
Вызовите objViewer.Close(true), когда пользователь покидает просмотрщик или открывает замену: он очищает виджет и отправляет запрос на закрытие к DocImage.axd. objViewer.Close() без аргументов очищает только виджет. На сервере viewer.CloseDocument(token) сразу удаляет сессию документа, освобождает её ресурсы рендеринга и отзывает доступ сессии к её страницам. Скользящее истечение срока действия в конечном итоге делает то же самое, но явное закрытие больших документов освобождает память быстрее.
Запустить
Разместите PDF по адресу ~/files/Sample.pdf, запустите сайт в IIS Express (F5 в Visual Studio) и откройте страницу, содержащую виджет. Первая страница отрисовывается, с миниатюрами слева. Если этого не происходит, см. Устранение неполадок.
Что вы получаете без лицензии
Отсутствие лицензии не вызывает ошибку. Просмотрщик отрисовывается нормально, но каждая страница содержит водяной знак оценки. См. Настройка лицензии для того, где Doconut ищет вашу лицензию.
Была ли эта страница полезной?