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

Додайте 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‑контейнера.

Два виклики middleware завершують налаштування, і їх порядок має значення: UseDoconutResources() має виконуватись перед UseDoconut(). UseDoconut() — це термінальний middleware, тому його виклик першим означає, що кожен запит до ресурсу /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;
});

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

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