Міграція

Ця сторінка охоплює оновлення існуючого ASP.NET застосунку з Doconut.NETFramework 26.8.0 або раніше (.NET Framework 4.7) до 26.9.0 і пізніше (.NET Framework 4.7.2). Пакет зразків Doconut містить повний посібник з міграції та класичні зразки, портовані на новий API — MVC 5, веб‑ферму та Web Forms. Порівняння вашого застосунку з початковим зразком — найшвидший шлях.

Один пакет, дві версії

Обидві бібліотеки публікуються під одним ідентифікатором пакету, Doconut.NETFramework. Версія розрізняє їх:

Оновлення пакету — це оновлення. Окремого пакету для встановлення та сумісного шару немає: 26.9.0 має інший набір API, тому очікуйте помилки компіляції після оновлення — решта цієї сторінки. Лінія .NET Framework 4.7 припинена, і 26.8.0 є її останнім випуском. Ви можете залишитися на ній — тут немає виправлення безпеки, яке ви могли б пропустити — але нові випуски, плагіни, розподілений режим та готові віджети доступні лише в 26.9.0 і пізніше.

1. Перенаправити та оновити пакет

Спочатку перенаправте веб‑проект на .NET Framework 4.7.2: проект, який все ще орієнтується на 4.7, не може встановити 26.9.0, і NuGet відмовляє в оновленні. Потім оновіть Doconut.NETFramework і додайте пакети плагінів, які ви використовуєте (Doconut.NETFramework.Converter, Doconut.NETFramework.Dicom, …). Кожен плагін потребує ліцензії, яка його надає.

Якщо проект використовує packages.config, оновлення виконує крок видалення попередньої версії, який видаляє обробник DocImage з Web.config, і 26.9.0 не додає його назад. Зареєструйте його знову, як показано у кроці 3; доки цього не зробите, DocImage.axd відповідає 404 і жодна сторінка не відображається.

2. Простори імен: майже все переміщено у корінь

Назви типів не змінилися: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, FileShareConfig і решта все ще присутні. У більшості файлів вся правка полягає у видаленні рядків using.

3. Запуск: DoconutHost.Initialize та два записи у Web.config

Класичний пакет створював свій переглядач для кожного запиту, з параметрами як властивостями цього екземпляра. Новий пакет має корінь композиції, створений один раз у Application_Start, і переглядач є сервісом, який ви отримуєте:

// До - Doconut.NETFramework 26.8.0 та раніше, за запитом
var viewer = new Viewer
{
    ID = "ctlDoc",
    IncludeJQuery = true,
    BasePath = "/",
    FitType = "width"
};

// Doconut.NETFramework 26.9.0+ - Переглядач отримано з DoconutHost, ліцензію налаштовано один раз у DoconutHost.Initialize()
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
var token  = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

DoconutHost.Initialize розміщується у Application_Start, а DoconutHost.Shutdown — у Application_End, і Web.config отримує обробник DocImage.axd та модуль ресурсів — обидва знаходяться у Встановлення. Параметри зовнішнього вигляду для кожної сторінки (FitType, FixedZoom, ShowHyperlinks, …) переміщено з екземпляра переглядача до параметрів віджета, або до ViewerConfig, переданого у Viewer.RenderViewer (див. КонфігураціяПереглядача). new Viewer() все ще компілюється після запуску DoconutHost.Initialize, тому перенесений код‑зад може залишити цей рядок, поки ви переносите параметри.

Безпека працює як раніше. Відкриття документа надає поточній ASP.NET сесії доступ до його сторінок, а DocImage.axd відмовляє всім іншим. Параметр програми DoconutUnSafeMode, який вимикав це, тепер options.UnsafeMode у DoconutHost.Initialize — залиште його false. Див. Сесії та безпека.

Помилка запуску, яка зупиняє весь сайт. Зареєстрований плагін, можливості якого не надає жодна ліцензія, викидає виключення у Application_Start, і застосунок відповідає порожнім 500 на кожен запит — без сторінки помилки, нічого в журналі IIS, лише запис у журналі подій Windows (джерело ASP.NET). Ліцензії читаються з wwwroot у корені сайту і ніде більше, і базовий Doconut.Viewer.lic має бути присутнім, інакше ліцензії плагінів поруч не читаються. Див. Налаштування ліцензії.

4. Веб‑ферма: від прапора до розподіленого режиму

Класична модель була viewer.IsWebfarm = true плюс ExportToPng(path). Нова модель реєструється один раз: кожен вузол спільно використовує один сховищe і один ключ підпису, а підписаний квиток, прив’язаний до браузера, замінює «будь‑який вузол, що відповідає»:

Doconut.DoconutHost.Initialize(
    options => options.UnsafeMode = false,
    services => services.AddDoconutDistributed(d =>
    {
        d.Store             = CloudLocation.FileShare;
        d.FileShareRootPath = @"\\fileserver\doconut-shared";   // WebfarmPath — це псевдонім
        d.SigningKey        = farmKey;                           // >= 32 bytes, однакові на кожному вузлі
    }));

Потім відкривайте документи звичайним чином, прив’язуючи браузер (DocOptions.BrowserId = DoconutFarmBinding.EnsureBrowserId(...)) і передаючи viewer.AccessToken віджету разом з токеном. Сесії та безпека містить кроки; приклад веб‑ферми — це повний вузол. IsWebfarm і WebfarmPath все ще компілюються, але більше нічого не вмикають.

Дві речі, які виглядають як успіх, але не є ним: DistributedDocumentPublisher.PublishAsync записує відрендерені файли документа, але не відкриває сесію, тому переглядач, спрямований на опублікований токен, отримує ~2 KB зображення помилки зі статусом 200; і тестовий клієнт без кукі doconut-client отримує те саме зображення, а не 401. Відрізняйте справжню сторінку від зображення помилки за розміром.

5. Конвертація — це плагін, і набагато менший

SourceFormatConverter enum, дванадцять класів *ConfigConverter та їхні вкладені цільові enum‑и замінені одним enum‑ом ConversionTarget і одним викликом:

using System.IO;
using System.Threading;
using Doconut;
using Doconut.Configs.Conversion;

// Припустимо, DoconutHost вже ініціалізовано, і CancellationToken з ім'ям ct доступний.
var provider = DoconutHost.Services;
var converter = (DocumentConverter)provider.GetService(typeof(DocumentConverter));
Stream source = /* ваш вхідний потік */;
var result = await converter.ConvertAsync(source, ".dwg", ConversionTarget.Pdf, null, ct);

Формат джерела береться з розширення, яке ви передаєте. Немає сумісного shim‑у: кожне посилання SourceFormatConverter є помилкою компіляції, яку треба виправити, видаливши його. Об’єкти параметрів для кожного формату не збереглися — WordConfigConverter.HtmlOptions і CadConfigConverter.CadOptions.ShowColor не мають еквіваленту через ConvertAsync. У Web Forms ніколи не блокуйте ConvertAsync — дивіться Плагін конвертера.

6. Хмарне сховище: доступ до нього як до спільної папки

Типи конфігурації хмари переміщені до Doconut.Clouds без змін. Однак обробники запитів до хмари є компонентами ASP.NET Core, і класичний застосунок не має конвеєра для їх запуску. З сайту System.Web отримуйте доступ до хмарного сховища як до спільної папки — в Azure, спільний ресурс Azure Files, змонтований на кожному вузлі — доступний через FileShareConfig.

7. Зміни на стороні клієнта, які тихо провалюються

Кожен пункт нижче компілюється, виконується, не виводить журнал і робить неправильне:

Ще три: переглядач не малює власну панель інструментів (ваша сторінка підключає Zoom, Next, GotoPage та інші до своїх кнопок); переглядач, створений у прихованому модальному вікні Bootstrap, має розмір 0×0 і нічого не малює, доки ви не задасте його контейнеру явну висоту і не підлаштуєте його на shown.bs.modal; і AllowSearch за замовчуванням встановлює false для PDF, тому документ відображається ідеально, хоча кожен пошук нічого не повертає.

8. Що зникає

Пропонований порядок роботи

1. Перенаправити, замінити пакет і змусити Global.asax компілюватися з DoconutHost.Initialize та двома реєстраціями Web.config. Сайт має запуститися.
2. Одна сторінка переглядача: отримати документ для рендерингу, потім пройти розділ 7, доки панель інструментів, пошук і анотації працювали. Перевірте у реальному браузері — у цьому розділі не виникає жодних помилок.
3. Конвертація (розділ 5): механічна, і більшість помилок компіляції.
4. Залишкові сторінки, використовуючи портовані зразки як ціль порівняння.
5. Веб‑ферма (розділ 4), якщо вона у вас є. Тестуйте з двома вузлами та браузером, або клієнтом, який зберігає куки.