Установка

Добавьте Doconut в ваш проект .NET Standard 2.1

Базовый просмотрщик Doconut для .NET Standard поставляется в виде одного пакета NuGet, который подключается к любому приложению ASP.NET Core. Дополнительные плагины используют отдельные пакеты. Эта страница устанавливает базовый пакет, проверяет, может ли ваш хост его использовать, и регистрирует промежуточное ПО — минимум, необходимый перед первым рендером.

Сначала проверьте фреймворк хоста

Библиотека нацелена на netstandard2.1. Это более узкий контракт, чем предыдущая сборка netstandard2.0, и его следует проверить в первую очередь:

ХостПоддерживается
.NET Core 3.0 или новее, включая .NET 5/6/7/8Да
.NET Framework (любая версия)Нет — netstandard2.1 не может использоваться в .NET Framework

Пакет работает только на Windows. Для хоста Linux используйте Doconut.NET8 или Doconut.NET6.

Если приложение работает на .NET Framework, это не тот пакет. Используйте Doconut.NETFramework вместо него; начиная с версии 26.9.0 требуется .NET Framework 4.7.2.

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

bash
dotnet add package Doconut.NETStandard

Неверсионированная команда устанавливает последнюю стабильную версию. Чтобы зафиксировать релиз, описанный в этой документации, передайте версию как отдельный параметр:

bash
dotnet add package Doconut.NETStandard --version 26.10.0

Doconut.NETStandard — это идентификатор пакета. Суффикс версии относится к загруженному файлу Doconut.NETStandard.<version>.nupkg и не является частью идентификатора.

Номер версии — это поколение

Это важнее, чем название пакета. Обе версии библиотеки .NET Standard публикуются под одним и тем же идентификатором пакета, и только версия различает их:

ВерсияЦельAPI
26.7.0 и нижеnetstandard2.0предыдущая интеграция
26.8.0 и вышеnetstandard2.1интеграция, описанная здесь

Совместимого shim'а и параллельного пакета нет. Повышение версии есть обновление, и компилятор сразу сообщит о различиях API.

Не выбирайте документацию только по названию пакета:

  • new Viewer(_cache, _accessor, …), UnSafeMode, синхронный OpenDocument(...), viewer.InitCache(), UseDoconutWebFarm и вручную скопированные скрипты просмотрщика указывают на предыдущую интеграцию;
  • AddDoconut(), UseDoconutResources(), внедрённый Viewer и OpenDocumentAsync(...) указывают на текущую интеграцию, описанную здесь.

Переведённый руководство по предыдущей настройке по‑прежнему доступно.
Используйте руководство по миграции, чтобы сменить поколение; обновление пакета не преобразует стартовый код, жизненный цикл просмотрщика или ресурсы браузера автоматически.

Регистрация Doconut

AddDoconut() — единственная точка входа для регистрации; существует единственная перегрузка, и она подключает сервис Viewer, сервис лицензий и инфраструктуру рендеринга в контейнер DI.

Два вызова промежуточного ПО завершают настройку, и их порядок имеет значение: UseDoconutResources() должен выполняться до UseDoconut(). UseDoconut() — терминальное промежуточное ПО, поэтому вызов его первым приводит к тому, что каждый запрос к ресурсу /doconut-res никогда не достигает обработчика ресурсов и получает 404. UseDoconut() отвечает на каждый запрос, который до него доходит, поэтому монтируйте его в отдельной ветке с помощью app.Map. Подключение сессии также требуется — стандартная защита документов Doconut проверяет каждый запрос страницы против состояния сессии ASP.NET.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // состоянию сессии нужен кэш (MVC/Razor Pages уже добавляют его)
builder.Services.AddSession(); // Безопасность документов Doconut опирается на состояние сессии ASP.NET

app.UseSession();          // вызовите UseSession() перед UseDoconut()
app.UseDoconutResources(); // должно быть зарегистрировано перед UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

Пространства имён

Типы конфигурации больше не распределены по четырём пространствам имён. В этом релизе почти всё находится в корневом пространстве имён Doconut:

csharp
using Doconut;                       // Viewer, DoconutOptions, DocOptions, все конфигурации форматов
using Doconut.Middleware;            // AddDoconut, UseDoconut, UseDoconutResources
using Doconut.Clouds;                // конфигурации облака и файлового доступа
using Doconut.Configs.Conversion;    // ConversionTarget

Имена типов сами по себе не изменились — PdfConfig, WordConfig, ExcelConfig, CssConfig, ScriptConfig и остальные всё ещё присутствуют. Если вы переносите существующее приложение, большинству файлов достаточно удалить две строки using; см. руководство по миграции.

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

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

СвойствоПо умолчаниюОписание
ShowDoconutInfofalseКогда true, запрос без token возвращает баннер версии вместо 404. Полезно как проверка; отключайте в продакшене.
UnsafeModefalseКогда true, пропускает проверку безопасности ASP.NET‑session при запросах страниц. Отключайте в продакшене. Обратите внимание на написание — в предыдущей библиотеке это называлось UnSafeMode.
MiddlewarePath"/doconut"Координационное значение для конечной точки page‑image. Оно проверяется, но само по себе не монтирует ветку; держите его согласованным с фактическим сопоставлением UseDoconut() и клиентским BasePath.
ResourcesPath"/doconut-res"Где обслуживаются встроенные ресурсы JS/CSS/изображения.
LicensePath"" (empty string)Путь к файлу лицензии. Пустое значение означает переход к следующему источнику, затем авто‑поиск.
LicenseContent"" (empty string)Сырой контент лицензии — из переменной окружения, менеджера секретов или базы данных.
LicenseStreamnullЛицензия как поток, читается один раз при старте.
ResetLicensefalseЗарезервированный флаг совместимости. Лицензия читается во время AddDoconut(); перезапустите приложение после замены лицензии.
MaxConcurrentEditorSessions200Максимальное количество живых сессий редактора (документы, открытые через DocOptions.EditMode). При превышении самая давно неиспользуемая сессия закрывается. Обычные сессии просмотрщика не учитываются. 0 или отрицательное значение означают отсутствие ограничения.
EditorSnapshotEveryOps50При включённом сохранении редактора (AddDoconutEditorPersistence) создаётся снимок живого документа каждые N записанных изменений. 0 или отрицательное значение никогда не создают снимки в середине сессии. Нет эффекта, когда сохранение отключено.

Приоритет лицензий, когда задано более одного источника: LicenseStream имеет приоритет над LicenseContent, который имеет приоритет над LicensePath, который имеет приоритет над авто‑поиском — см. Настройка лицензии.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.MiddlewarePath  = "/doconut";     // координировать с сопоставлением приложения и BasePath клиента
    options.ResourcesPath   = "/doconut-res"; // откуда обслуживаются JS/CSS/изображения viewer'а
    options.UnsafeMode      = false;          // оставьте безопасность сессии включенной
    options.ShowDoconutInfo = false;
});

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

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