Міграція з класичної інтеграції .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 та залежностями запит‑аксесора:

// Класична інтеграція — лише для порівняння; не компілюйте це проти поточної SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

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

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

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

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

Проміжне програмне забезпечення та маршрутизація ресурсів

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

// Класична інтеграція — видалити під час переходу.
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(...):

// Поточна інтеграція .NET 6: Viewer отримується через DI, а відкриття документа є асинхронним.
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. ініціалізуйте ліцензовані стрічки Пошуку та Анотації;
8. викличте attach(objViewer) на кожній стрічці;
9. відкрийте документ і викличте objViewer.View(token).

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

Видаліть вручну скопійовані класичні файли, такі як 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.AddDistributedMemoryCache(); // стан сесії потребує кешу (MVC/Razor Pages вже додають його)
builder.Services.AddSession();
app.UseSession();

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

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

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

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

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

План відкату

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

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

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

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

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

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