Міграція з класичної інтеграції .NET 6

Doconut має два різних інтеграції .NET 6. Вони можуть використовувати одну й ту ж назву пакету Doconut.NET6, тому визначте покоління за API у застосунку перед зміною пакетів, запуску, ліцензій або ресурсів браузера.

Яку інтеграцію .NET 6 ви використовуєте?

Якщо обидві колонки присутні в одному застосунку, розглядайте міграцію як неповну. Не надсилайте токен документа через ресурси або middleware іншого покоління.

Чому назва пакету NuGet може не підказати

Обидва покоління розповсюджуються під ідентифікатором пакету Doconut.NET6. Тому посилання на пакет, lock‑файл або кешований .nupkg не визначають API хостингу самостійно. Зафіксуйте точну версію пакету та разом перегляньте Program.cs, створення viewer, відкриття документів та скрипти браузера.

Поточний випуск, перевірений для цього посібника, — Doconut.NET6 26.7.0. Його додаткові публічні пакети — Doconut.NET6.Converter та Doconut.NET6.Dicom, закріплені на тій самій версії випуску, що й основний пакет.

Перед міграцією

1. Створіть гілку та розгортувальний резервний копію існуючого застосунку.
2. Зафіксуйте точні версії ядра та плагінових пакетів.
3. Складіть інвентаризацію кожного мапінгу DocImage.axd, виклику new Viewer(...), виклику завантаження ліцензії, скопійованого скрипту Doconut, користувацької дії панелі інструментів та кінцевої точки відкриття документу.
4. Збережіть поточні файли .lic та секрети розгортання поза системою контролю версій.
5. Зберіть репрезентативний набір PDF, Office, зображень, CAD, електронних листів, DICOM, документів з можливістю пошуку, захищених паролем та анотованих.
6. Зафіксуйте поточний тайм‑аут сесії, поведінку безпеки, шрифти та налаштування платформи.

Мігуруйте одне середовище перед зміною продакшн. Поточна інтеграція змінює час життя сервісу, маршрутизацію запитів, власність сесії та доставку ресурсів клієнту.

Сумісність пакетів та ліцензій

Замініть або оновіть основний пакет свідомо; не покладайтеся на ідентичний ідентифікатор пакету для вибору нового API. Команда за замовчуванням встановлює останній стабільний випуск:

dotnet add package Doconut.NET6

Для відтворюваної міграції до випуску, перевіреного цим посібником, передайте версію як окрему опцію:

dotnet add package Doconut.NET6 --version 26.7.0

Тримайте кожен плагін Doconut на тій же версії, що й основний пакет. Поточна інтеграція завантажує ліцензії один раз під час AddDoconut(), використовуючи таку пріоритетність:

LicenseStream > LicenseContent > LicensePath > automatic discovery

Автоматичне виявлення шукає файли Doconut.Viewer.lic та супутні файли Doconut.Viewer.<Capability>.lic. Класичний виклик Viewer.DoconutLicense(...) або Viewer.SetLicensePlugin(...) не є поточним механізмом запуску. Перенесіть ліцензію до DoconutOptions, тримайте супутні файли разом при використанні автоматичного виявлення, перезапустіть після зміни ліцензії та перевірте можливості через IDoconutLicenseService.

Не вважайте, що наявність старої ліцензії плагіна підтверджує право на поточну збірку плагіна. Тестуйте Viewer, Search, Annotation, Converter та DICOM окремо з затвердженими артефактами випуску.

Запуск та впровадження залежностей

Класичні застосунки створюють Viewer з кешем ASP.NET та залежностями‑доступу до запиту:

// Classic integration — contrast only; do not compile this against the current SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

Поточна інтеграція реєструє Doconut один раз і отримує Viewer через впровадження залежностей:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

Viewer — це транзитна служба. Менеджер сесії документу та його кеш володіють довготривалою станом документу, а не конкретним інжектованим екземпляром Viewer.

Проміжне ПЗ та маршрутизація ресурсів

Видаліть класичну гілку MapWhen, яка виявляє DocImage.axd:

// Classic integration — remove during the cutover.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

У поточному конвеєрі:

1. викликайте UseSession() до Doconut, доки ввімкнено безпеку сесії;
2. викликайте UseDoconutResources() до UseDoconut();
3. тримайте ResourcesPath, згенеровані URL‑и ресурсів та клієнтський ResPath узгодженими;
4. при мапуванні UseDoconut() до гілки, зберігайте узгодженість цієї гілки та клієнтського BasePath.

MiddlewarePath — це перевірена конфігурація; вона сама по собі не створює гілку ASP.NET Core. Використовуйте або простий конвеєр у наведеному вище прикладі, або явне розташування app.Map("/doconut", branch => branch.UseDoconut()), яке використовується послідовно клієнтом.

Конструювання та життєвий цикл Viewer

Видаліть кеші, що належать застосунку, для об’єктів Viewer. Інжектуйте Viewer у кінцеву точку, Razor‑сторінку, контролер або область застосунку зі сферою дії:

app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Повернутий токен ідентифікує серверну сесію документу. Ставтеся до нього як до токену доступу: не журналюйте його, не зберігайте і не передавайте у аналітику.

Відкриття та закриття документів

Замініть синхронний OpenDocument(...) на OpenDocumentAsync(...):

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Поточні перевантаження приймають шлях до файлу або потік, необов’язкову конфігурацію формату, необов’язкові DocOptions та токен скасування. Закривайте серверну сесію явно, коли браузер більше її не потребує:

viewer.CloseDocument(token);

Не використовуйте класичний токен після переходу. Відкривайте кожен документ знову через поточний API.

Класи конфігурації

Поточний API розділяє відповідальності:

Не переносіть DocOptions.ImageResolution як контроль рендерингу. Це застаріло; встановлюйте BaseConfig.ImageResolution у конфігурації, специфічній для формату. Перегляньте всі типові значення замість того, щоб припускати, що класична конфігурація поводиться так само.

Панель інструментів Viewer, пошук та анотації

Не мігруйте старі скрипти по одному. Поточні демонстраційні застосунки формують повний пакет сторінки:

1. виводять CSS Viewer та ліцензований CSS пошуку/анотації за допомогою ReferenceCss;
2. рендерять панель інструментів Viewer, що належить застосунку;
3. рендерять searchBarMount, annBarMount та необхідний елемент Viewer;
4. виводять скрипти Viewer та ліцензованих модулів за допомогою ReferenceScripts;
5. завантажують власний viewerToolbar.js застосунку;
6. ініціалізують один objViewer;
7. ініціалізують ліцензовані стрічки Search та Annotation;
8. викликають attach(objViewer) для кожної стрічки;
9. відкривають документ і викликають objViewer.View(token).

Пошук і анотації — це модулі, приєднані до того ж Viewer, а не окремі панелі інструментів. Головна панель належить хост‑застосунку; стрічки Search і Annotation вбудовані, їх доступність керується можливостями.

Видаліть вручну скопійовані класичні файли, такі як documentLinks.js і docViewer.UI.js, лише після того, як поточна сторінка працює з ресурсами, виведеними ReferenceCss та ReferenceScripts.

Реєстрація плагіна

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

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() перевіряє зареєстровані можливості плагінів під час запуску. Converter і DICOM — випущені плагіни .NET 6. Normal Search і Annotation — вбудовані ліцензовані функції, а не пакети AddPlugin<TPlugin>().

Сесія та безпека документів

Поточна інтеграція прив'язує документи до непрозорих токенів і кешованих сесій. За замовчуванням UnsafeMode = false, UseDoconut() додає безпеку доступу до документів, і хост повинен налаштувати сесію ASP.NET:

builder.Services.AddSession();
app.UseSession();

Залишайте DocOptions.IsSecured = true, якщо лише переглянутий дизайн не вимагає іншого. Ніколи не використовуйте UnsafeMode = true як короткий шлях міграції. Тестуйте запити без токену, з пошкодженим токеном, з простроченим токеном і з токеном з іншої сесії браузера.

Розподілене довідкове застосування додає квитки доступу та деталі транспорту. Ці API не потрібні для звичайної міграції на один вузол.

Тестування міграції

Як мінімум, перевірте:

• запуск застосунку з виробничою ліцензією та усіма зареєстрованими плагінами;
• CSS/скрипти Viewer та всі запити сторінок‑зображень за обраними шляхами;
• відкриття документа, навігація, масштабування, мініатюри, друк та явне закриття;
• Пошук у документі з текстом та стан не‑пошукового файлу лише з зображенням;
• Завантаження, збереження, експорт анотацій та контроль можливостей;
• Виявлення цілі Converter, вивід, завантаження та стан водяного знака;
• Сторінки, кадри та анімація DICOM; технічні метадані .NET 6 недоступні;
• документи, захищені паролем, користувацькі шрифти, нелатинський текст та налаштовані тайм‑аути;
• відхилення токену між сесіями та поведінка при простроченій сесії;
• мобільний, темний режим та шлях виробничого reverse‑proxy.

План відкату

Зберігайте класичний артефакт розгортання, відповідні пакети, ліцензійні файли та скопійовані ресурси браузера разом. Безпечний відкат переключає всю генерацію застосунку; він не змішує класичний сервер з поточними скриптами або поточний сервер з класичними викликами DocImage.axd.

Перед переходом задокументуйте:

• слот розгортання або артефакт, використаний для відкату;
• вплив на базу даних/кеш, якщо є;
• як активні сесії документів будуть анульовані;
• перевірку здоров'я та тестовий документ, використаний для рішення про відкат;
• хто може відновити попередній набір пакетів та конфігурацію.

Спадкова документація

Перекладений класичний посібник доступний за адресою Legacy .NET 6 setup. Новий Classic integration gateway пояснює ті ж сигнали ідентифікації та посилається назад на цей посібник з міграції.

Зберігайте історичну URL у закладках та запитах підтримки, доки існують класичні інсталяції. Вона документує інше покоління і не перенаправляється до поточного API.