Установка

Добавьте 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; эта ветка прекращена. Обновление существующего приложения через эту границу описано в разделе Миграция.

Установить пакет

Из консоли диспетчера пакетов:

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 code page сервера. -->
    <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 нет билдера и конвейера 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 вне маршрутизации — Быстрый старт показывает полный Application_Start.

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

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

PropertyDefaultDescription
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, который имеет приоритет над автоматическим обнаружением — см. Настройка лицензии.

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.

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

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