Установка

Добавьте 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 для первой страницы, чтобы определить анимированные изображения. Без этого глагола 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 нет построителя и конвейера промежуточного ПО. 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 вне маршрутизации — Быстрый старт показывает полный Application_Start.

Все параметры

DoconutOptions принимает следующий набор настраиваемых свойств. Каждое из них необязательно.

СвойствоПо умолчаниюОписание
UnsafeModefalseКогда false, DocImage.axd обслуживает страницу только той ASP.NET‑сессии, которая открыла документ. Когда true, обслуживается любой запрос с токеном. Оставьте false.
ShowDoconutInfofalseКогда true, запрос DocImage.axd без token возвращает баннер с версией вместо 404. Полезно для быстрой проверки; отключайте в продакшене.
ResourcesPath"/doconut-res"Путь, по которому модуль ресурсов обслуживает встроенные скрипты, стили и иконки. Меняйте только совместно с ResPath просмотрщика и любыми IgnoreRoute в MVC.
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.

Следующие шаги

Была ли эта страница полезной?