Встановлення

Додайте Doconut до вашого веб‑застосунку .NET Framework 4.7.2

Doconut.NETFramework розміщує переглядач Doconut у класичному застосунку ASP.NET на .NET Framework 4.7.2 — IIS або IIS Express, MVC 5 або Web Forms. Налаштування складається з трьох частин: пакет NuGet, два реєстрації у Web.config і один виклик у Global.asax. Ця сторінка охоплює всі три; Швидкий старт потім розміщує документ на сторінці.

Вимоги

  • Веб‑проект націлений на .NET Framework 4.7.2 або новіший. Проект 4.7 не може споживати цей пакет; спочатку змініть цільову платформу.
  • Сайт працює в інтегрованому конвеєрі (за замовчуванням для пулів застосунків IIS та IIS Express).
  • Сервер працює під Windows. Пакет доступний лише для Windows.

Ця сторінка охоплює Doconut.NETFramework 26.9.0 і новіші. Версії 26.8.0 та раніше орієнтувалися на .NET Framework 4.7 з іншим API; ця гілка більше не підтримується. Оновлення існуючого застосунку через цей межовий перехід описано в Міграція.

Встановлення пакету

З консолі Package Manager:

powershell
Install-Package Doconut.NETFramework

Або в проєкті типу SDK:

bash
dotnet add package Doconut.NETFramework

Команди без вказання версії встановлюють останній стабільний реліз. Щоб зафіксувати реліз, описаний у цій документації, передайте версію:

powershell
Install-Package Doconut.NETFramework -Version 26.10.0
bash
dotnet add package Doconut.NETFramework --version 26.10.0

Рендеринговий движок вбудований у пакет: немає окремої збірки движка для посилання, копіювання чи розгортання. Додаткові можливості постачаються у вигляді окремих пакетів — наприклад Doconut.NETFramework.Converter і Doconut.NETFramework.Dicom — і кожен з них потребує ліцензії, яка їх надає (див. Система плагінів).

Налаштування Web.config

Doconut обслуговує два типи запитів, і IIS маршрутизує їх обидва через Web.config:

  • DocImage.axd — сторінка переглядача, мініатюра, пошук та кінцева точка анотацій, обслуговується Doconut.DocImageHandler.
  • /doconut-res/* — власні скрипти, таблиці стилів та іконки переглядача, вбудовані у збірку та обслуговуються Doconut.DoconutResourceModule.

Додайте обидва, а також налаштування, від яких вони залежать:

xml
<configuration>
  <system.web>
    <!-- Лише MVC 5: Razor компілює представлення під час виконання та потребує фасаду netstandard. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength у KILOBYTES: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Читати файли .cshtml і .aspx у кодуванні UTF-8, а не у ANSI кодовій сторінці сервера. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength у BYTES: те саме 200 MB. -->
        <requestLimits maxAllowedContentLength="209715200" />
      </requestFiltering>
    </security>
    <modules runAllManagedModulesForAllRequests="true">
      <add name="DoconutResourceModule" type="Doconut.DoconutResourceModule, Doconut" />
    </modules>
    <handlers>
      <add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd"
           type="Doconut.DocImageHandler, Doconut" />
    </handlers>
  </system.webServer>
</configuration>

Кожен рядок запобігає помилці, яка не генерує виключення:

  • verb="GET,HEAD,POST" — залиште HEAD. Переглядач надсилає запит HEAD для сторінки 1, щоб виявити анімовані зображення. Без цього дієслова IIS відповідає 404 до запуску обробника: документи все ще відображаються, але виявлення анімації не працює, і консоль браузера заповнюється 404.
  • runAllManagedModulesForAllRequests="true" — /doconut-res/*.js, .css і .png виглядають як статичні файли, і IIS передасть їх своєму обробнику статичних файлів до того, як модуль ресурсів їх побачить. Результат — переглядач без скриптів та іконок.
  • <globalization fileEncoding="utf-8"> — файли сторінок, збережені у UTF-8 без маркера порядку байтів, інакше читаються за ANSI‑кодуванням сервера, тому кожен не‑ASCII символ потрапляє у браузер подвійно закодованим (тире показується як —). Файл на диску правильний, і сторінка все ще оголошує <meta charset="utf-8">.
  • Збірка netstandard (MVC 5) — Razor компілює представлення під час першого запиту, використовуючи власний список посилань, який не містить цей фасад. Представлення, що виконує будь‑яку динамічну операцію, крім простого доступу до члена, тоді падає з CS0012 і повертає порожній 500, і лише сторінки, які його викликають, падають. Помилка компілятора з’являється лише в журналі подій Windows (джерело ASP.NET). Додатки Web Forms не потребують цього рядка.
  • Обмеження завантаження — ASP.NET читає весь тіло запиту перед запуском будь‑якого обробника, тому завантаження, що перевищує ці ліміти, відхиляється IIS зі своєю сторінкою помилки. Тримайте maxRequestLength (кілобайти) і maxAllowedContentLength (байти) у відповідності, і вище за найбільший файл, який ваші користувачі відкривають або завантажують.

Ще два налаштування важливі, і зазвичай вони вже правильні:

  • Стан сесії залишається ввімкненим. За замовчуванням сторінка подається лише до ASP.NET сесії, яка відкрила документ, тому сайт не повинен встановлювати <sessionState mode="Off" />. Дивіться Сесії та безпека.
  • Перенаправлення збірок. Залишайте <runtime> перенаправлення збірок, які NuGet записує у Web.config. У проєкті типу SDK скопіюйте їх із згенерованого bin\<YourApp>.dll.config, оскільки класичний ASP.NET читає перенаправлення лише з Web.config. Перенаправлення, яке вказує на версію, відсутню у bin\, зупиняє весь застосунок з порожнім 500 під час запуску.

Реєстрація Doconut у Global.asax

У System.Web немає builder'а та конвеєра middleware. Doconut створюється один раз на процес робітника за допомогою DoconutHost.Initialize у Application_Start і звільняється DoconutHost.Shutdown у Application_End:

csharp
// Global.asax.cs
protected void Application_Start()
{
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    });
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}

DoconutHost.Initialize створює служби, обробник, модуль ресурсів та використання вашого коду. Ваш код отримує їх через DoconutHost.Services (див. DoconutHost). Тільки перший виклик налаштовує щось; другий виклик ігнорується. У MVC‑застосунку також тримайте два шляхи Doconut поза маршрутизацією — Quick Start показує повний Application_Start.

Усі параметри

DoconutOptions приймає наступний набір налаштовуваних властивостей. Кожна з них є необов’язковою.

ВластивістьЗа замовчуваннямОпис
UnsafeModefalseКоли false, DocImage.axd подає сторінку лише до ASP.NET‑сесії, яка відкрила документ. Коли true, обслуговується будь‑який запит, що містить токен. Залиште його false.
ShowDoconutInfofalseКоли true, запит DocImage.axd без token відповідає банером версії замість 404. Корисно як швидка перевірка; залиште вимкненим у продакшн.
ResourcesPath"/doconut-res"Де модуль ресурсів подає вбудовані скрипти, стилі та іконки. Змінюйте лише разом із ResPath переглядача та будь‑яким MVC IgnoreRoute.
LicensePath""Повний шлях до файлу ліцензії. Порожнє значення означає переходити до наступного джерела, а потім до автоматичного виявлення.
LicenseContent""Необроблений вміст ліцензії — з змінної середовища, сховища секретів або бази даних.
LicenseStreamnullЛіцензія як потік, читається один раз під час запуску.
MiddlewarePath"/doconut"Не використовується в цьому пакеті. Кінцева точка сторінки — це обробник DocImage.axd, оголошений у Web.config, незалежно від його значення. Він все ще перевіряється: має починатися з / і відрізнятися від ResourcesPath.
ResetLicensefalseНе використовується в цьому пакеті. Ліцензія читається один раз у DoconutHost.Initialize; після заміни файлу ліцензії перезапустіть пул застосунків.
MaxConcurrentEditorSessions200Максимальна кількість активних сесій редактора (документів, відкритих за допомогою DocOptions.EditMode). При перевищенні закривається найстаріша неактивна сесія редактора. Звичайні сесії переглядача не враховуються. 0 або від’ємне значення означає відсутність обмеження.
EditorSnapshotEveryOps50При увімкненій стійкості редактора (AddDoconutEditorPersistence) створюється знімок живого документа кожні N зафіксованих змін. 0 або від’ємне значення ніколи не створює знімки під час сесії. Не впливає, коли стійкість вимкнена.

Коли встановлено більше одного джерела ліцензії, LicenseStream має пріоритет над LicenseContent, який має пріоритет над LicensePath, який має пріоритет над автоматичним виявленням — див. License Setup.

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // звідки подається JS/CSS/зображення переглядача
    options.UnsafeMode      = false;          // зберігайте безпеку сесії
    options.ShowDoconutInfo = false;
});
// Точка доступу сторінки тут не підходить: це обробник DocImage.axd, оголошений у Web.config.

Наступні кроки

  • Quick Start — відкрийте документ і відобразіть його у браузері, у MVC 5 або Web Forms.
  • License Setup — де Doconut шукає ваш файл ліцензії.

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