Міграція з класичної інтеграції .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 окремо, використовуючи затверджені артефакти випуску.

Старт і dependency injection

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

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

Поточна інтеграція реєструє Doconut один раз і отримує Viewer через dependency injection:

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

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

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

Middleware і маршрутизація ресурсів

Видаліть класичну гілку 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‑сторінку, контролер або scoped‑сервіс застосунку:

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

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

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

Замініть синхронний 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, Search та Annotation

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

1. виводять CSS Viewer та ліцензований CSS Search/Annotation за допомогою 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).

Search і Annotation — це модулі, підключені до того ж 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 плагіни. Звичайні Search і Annotation — вбудовані ліцензовані функції, а не пакети AddPlugin<TPlugin>().

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

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

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

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

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

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

Щонайменше перевірте:

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

План відкату

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

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

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

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

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

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