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

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

Doconut.NETFramework розміщує Doconut viewer у класичному додатку 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).

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

Встановити пакет

З консолі диспетчера пакетів:

powershell
Install-Package Doconut.NETFramework

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

bash
dotnet add package Doconut.NETFramework

Рендеринговий движок вбудовано в пакет: окремої збірки движка, яку треба посилати, копіювати чи розгортати, немає. Додаткові можливості постачаються у вигляді окремих пакетів — наприклад 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 only: Razor compiles views at run time and needs the netstandard facade. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength is in KILOBYTES: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Read .cshtml and .aspx files as UTF-8, not as the server's ANSI code page. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength is in BYTES: the same 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 створюється один раз на процес‑worker за допомогою 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 з маршрутизації — Швидкий старт показує повний 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; після заміни файлу ліцензії перезапустіть пул застосунків.

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

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // where the viewer's JS/CSS/images are served from
    options.UnsafeMode      = false;          // keep session security on
    options.ShowDoconutInfo = false;
});
// The page endpoint is not an option here: it is the DocImage.axd handler declared in Web.config.

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

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