Швидкий старт

Відобразіть ваш перший документ у MVC 5 або Web Forms

Цей посібник переносить застосунок ASP.NET на .NET Framework 4.7.2 з встановленого пакету до документа, що відображається у браузері: Global.asax, відкритий кінцевий пункт, ресурси переглядача, віджет і токен, що їх з’єднує. Припускається, що реєстрації Web.config з Встановлення виконані — без обробника DocImage.axd та модуля ресурсів нічого нижче не зможе досягти сервера.

Скласти Doconut у Global.asax

Повний Application_Start для застосунку MVC 5:

csharp
// 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 немає ін’єкції через конструктор для нього:

csharp
// 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, призначена для код‑бекенду, який не використовує асинхронні сторінки:

csharp
// 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:

csharp
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
@Html.Raw(ViewBag.ViewerCss)
...
@Html.Raw(ViewBag.ViewerScripts)

Залиште цю роботу в контролері. MVC 5 компілює представлення під час їх першого запиту, і без додаткового пакету компілятора цей компілятор розуміє лише C# 5 — без ?., без $"...", без nameof. Представлення, яке їх використовує, успішно компілюється у Visual Studio, а в браузері повертає порожній 500.

Web Forms. Відкрийте ті ж рядки у код‑бекенді та запишіть їх за допомогою <%= %>:

html
<head>
    <%= ViewerCss %>
</head>
<body>
    ...
    <%= ViewerScripts %>
</body>

IncludeViewerCss і IncludeViewerScripts є обов’язковим ядром. Щоб додати стрічки Пошуку та Анотації, також встановіть IncludeSearchCss, IncludeAnnotationCss, IncludeSearchScripts, IncludeSearchBar, IncludeAnnotationScripts та IncludeAnnotationBar. Обидва методи пропускають файли стрічки, якщо ліцензія не надає таку можливість; сам переглядач все одно запускається.

Додати переглядач на сторінку

Поверхня рендерингу складається з двох вкладених div:

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

Надайте зовнішньому div реальну висоту — переглядач заповнює свій контейнер і вимірює його під час запуску. Переглядач не малює власну панель інструментів: GotoPage, Next, Zoom, FitType, а решта — це методи, які ваша сторінка підключає до своїх кнопок, розташованих поруч із переглядачем:

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.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>

Ініціалізувати переглядач і показати документ

Після скриптів переглядача створіть віджет, а потім передайте йому токен:

javascript
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). Він існує лише в цьому пакеті:

csharp
// 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);
}
html
<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 шукає вашу ліцензію.

Чи була ця сторінка корисною?