Migrace z klasické integrace .NET 6

Doconut má dvě odlišné integrace .NET 6. Mohou používat stejný název balíčku Doconut.NET6, takže před změnou balíčků, startováním, licencemi nebo zdrojů prohlížeče identifikujte generaci podle API v aplikaci.

Kterou integraci .NET 6 používáte?

Pokud se oba sloupce objeví ve stejné aplikaci, považujte migraci za neúplnou. Neposílejte jeden token dokumentu přes zdroje nebo middleware z jiné generace.

Proč název balíčku NuGet nemusí stačit

Obě generace jsou distribuovány pod ID balíčku Doconut.NET6. Odkaz na balíček, soubor lock nebo uložený .nupkg tedy samo o sobě neidentifikuje hostující API. Zaznamenejte přesnou verzi balíčku a společně prozkoumejte Program.cs, konstrukci vieweru, otevírání dokumentů a skripty prohlížeče.

Současné vydání ověřené pro tento průvodce je Doconut.NET6 26.7.0. Jeho volitelné veřejné balíčky jsou Doconut.NET6.Converter a Doconut.NET6.Dicom, které jsou svázány se stejnou verzí vydání jako hlavní balíček.

Před migrací

1. Vytvořte větev a nasaditelnou zálohu existující aplikace.
2. Zaznamenejte přesné verze hlavního a pluginového balíčku.
3. Zaznamenejte každé mapování DocImage.axd, volání new Viewer(...), volání načítání licence, zkopírovaný skript Doconut, vlastní akci nástrojové lišty a koncový bod pro otevírání dokumentů.
4. Uchovejte aktuální soubory .lic a nasazovací tajné informace mimo správu verzí.
5. Zaznamenejte reprezentativní sadu PDF, Office, obrázkových, CAD, e-mailových, DICOM, prohledávatelných, chráněných heslem a anotovaných dokumentů.
6. Zaznamenejte stávající časový limit relace, chování zabezpečení, fonty a nastavení platformy.

Migrujte jedno prostředí před změnou produkce. Současná integrace mění životnost služby, směrování požadavků, vlastnictví relace a doručování klientských zdrojů.

Kompatibilita balíčků a licencí

Nahradit nebo aktualizovat hlavní balíček úmyslně; nespoléhejte se na identické ID balíčku pro výběr nového API. Výchozí příkaz nainstaluje nejnovější stabilní verzi:

dotnet add package Doconut.NET6

Pro reprodukovatelnou migraci na verzi ověřenou tímto průvodcem, předávejte verzi jako samostatnou volbu:

dotnet add package Doconut.NET6 --version 26.7.0

Udržujte každý Doconut plugin ve stejné verzi jako hlavní balíček. Současná integrace načítá licence jednou během AddDoconut(), s následující prioritou:

LicenseStream > LicenseContent > LicensePath > automatic discovery

Automatické vyhledávání hledá soubory Doconut.Viewer.lic a doprovodné soubory Doconut.Viewer.<Capability>.lic. Klasické volání Viewer.DoconutLicense(...) nebo Viewer.SetLicensePlugin(...) není současný spouštěcí mechanismus. Přesuňte licenci do DoconutOptions, udržujte doprovodné soubory společně při použití automatického vyhledávání, restartujte po změně licence a ověřte funkce pomocí IDoconutLicenseService.

Nepředpokládejte, že přítomnost staré licence pluginu dokazuje oprávnění pro současnou verzi pluginu. Otestujte Viewer, Search, Annotation, Converter a DICOM samostatně s ověřenými artefakty vydání.

Spuštění a injekce závislostí

Klasické aplikace vytvářejí Viewer s cache ASP.NET a závislostmi request-accessoru:

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

Aktuální integrace zaregistruje Doconut jednou a získá Viewer z injekce závislostí:

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

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

Viewer je přechodná služba. Správce relace dokumentu a jeho cache vlastní dlouhodobější stav dokumentu, nikoli konkrétní injektovanou instanci Viewer.

Middleware a směrování zdrojů

Odstraňte klasickou větev MapWhen, která detekuje DocImage.axd:

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

V aktuálním pipeline:

1. zavolejte UseSession() před Doconut, zatímco je zabezpečení relace povoleno;
2. zavolejte UseDoconutResources() před UseDoconut();
3. udržujte ResourcesPath, generované URL zdrojů, a klientský ResPath v souladu;
4. při mapování UseDoconut() na větev udržujte tuto větev a klientský BasePath v souladu.

MiddlewarePath je ověřená konfigurace; sama o sobě nevytváří větev ASP.NET Core. Použijte buď jednoduchý pipeline v ukázce výše, nebo explicitní uspořádání app.Map("/doconut", branch => branch.UseDoconut()), které používá klient konzistentně.

Konstrukce a životní cyklus Vieweru

Odstraňte cache vlastněné aplikací pro objekty Viewer. Injektujte Viewer do koncového bodu, Razor stránky, kontroleru nebo scoped služby aplikace:

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

Vrácený token identifikuje serverovou relaci dokumentu. Zacházejte s ním jako s nosičem oprávnění: neukládejte jej do logů, neukládejte jej trvale ani jej nezasílejte do analytiky.

Otevírání a zavírání dokumentů

Nahraďte synchronní OpenDocument(...) metodou OpenDocumentAsync(...):

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

Aktuální přetížení přijímají cestu k souboru nebo stream, volitelnou konfiguraci formátu, volitelný DocOptions a token pro zrušení. Uzavřete serverovou relaci explicitně, když ji prohlížeč již nepotřebuje:

viewer.CloseDocument(token);

Po přechodu nepoužívejte klasický token znovu. Otevřete každý dokument znovu pomocí aktuálního API.

Konfigurační třídy

Aktuální API odděluje starosti:

Neproměňujte DocOptions.ImageResolution jako řídící prvek renderování. Je zastaralý; nastavte BaseConfig.ImageResolution v konfiguraci specifické pro formát. Přezkoumejte všechna výchozí nastavení místo předpokladu, že klasická konfigurace má stejné chování.

Toolbar Vieweru, Vyhledávání a Anotace

Nepamatujte staré skripty jeden po druhém. Aktuální referenční aplikace skládají kompletní balíček stránky:

1. vygenerujte CSS Vieweru a licencované CSS pro Vyhledávání/Anotaci pomocí ReferenceCss;
2. vykreslete toolbar Vieweru vlastněný aplikací;
3. vykreslete searchBarMount, annBarMount a požadovaný mount Vieweru;
4. vygenerujte skripty Vieweru a licencovaných modulů pomocí ReferenceScripts;
5. načtěte vlastní viewerToolbar.js aplikace;
6. inicializujte jeden objViewer;
7. inicializujte licencované pásky Vyhledávání a Anotace;
8. zavolejte attach(objViewer) na každé pásce;
9. otevřete dokument a zavolejte objViewer.View(token).

Vyhledávání a Anotace jsou moduly připojené ke stejnému Vieweru, nikoli nezávislé toolbary. Hlavní toolbar patří hostitelské aplikaci; pásky Vyhledávání a Anotace jsou vložené, zdroje řízené schopnostmi.

Odstraňte ručně zkopírované klasické soubory jako documentLinks.js a docViewer.UI.js až poté, co aktuální stránka funguje se zdroji vygenerovanými ReferenceCss a ReferenceScripts.

Registrace pluginu

Klasické statické metody plugin‑licencí neregistrují aktuální pluginy. Nainstalujte a zaregistrujte každý vydaný balíček explicitně:

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

AddDoconut() ověřuje registrované schopnosti pluginů při spuštění. Converter a DICOM jsou vydané .NET 6 pluginy. Normální vyhledávání a anotace jsou vestavěné licencované funkce, nikoli balíčky AddPlugin<TPlugin>().

Bezpečnost relace a dokumentu

Současná integrace svazuje dokumenty s neprůhlednými tokeny a kešovanými relacemi. S výchozím nastavením UnsafeMode = false přidává UseDoconut() zabezpečení přístupu k dokumentům a hostitel musí nakonfigurovat ASP.NET relaci:

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

Udržujte DocOptions.IsSecured = true, pokud revizní návrh nevyžaduje jinak. Nikdy nepoužívejte UnsafeMode = true jako migrační zkratku. Otestujte požadavky bez tokenu, s poškozeným tokenem, s prošlým tokenem a s tokenem z jiné relace prohlížeče.

Distribuovaná referenční aplikace přidává přístupové lístky a podrobnosti o transportu. Tyto API nejsou vyžadovány pro běžnou jednojádrovou migraci.

Testování migrace

V minimálním rozsahu ověřte:

• spuštění aplikace s produkční licencí a všemi registrovanými pluginy;
• CSS/scripts pro Viewer a všechny požadavky na obrázky stránek pod zvolenými cestami;
• otevření dokumentu, navigaci, přiblížení, miniatury, tisk a explicitní uzavření;
• vyhledávání v dokumentu obsahujícím text a stav nevyhledatelného souboru pouze s obrázkem;
• načtení, uložení, export a řízení oprávnění anotací;
• zjištění cíle Converteru, výstup, stažení a stav vodoznaku;
• stránky DICOM, snímky a animace; technická metadata .NET 6 nejsou k dispozici;
• dokumenty chráněné heslem, vlastní fonty, ne‑latinský text a nakonfigurované časové limity;
• odmítnutí tokenu napříč relacemi a chování při vypršení relace;
• mobilní zařízení, tmavý režim a cesta produkčního reverzního proxy.

Plán návratu

Uchovávejte klasický artefakt nasazení, odpovídající balíčky, licenční soubory a zkopírované zdroje prohlížeče společně. Bezpečný návrat přepíná celou generaci aplikace; neprovádí kombinaci klasického serveru s aktuálními skripty ani aktuálního serveru s klasickými voláními DocImage.axd.

Před přechodem dokumentujte:

• nasazovací slot nebo artefakt použitý pro návrat;
• dopad na databázi/keš, pokud existuje;
• jak budou neaktivní relace dokumentů neplatné;
• kontrolu zdraví a testovací dokument použitý k rozhodnutí o návratu;
• kdo může obnovit předchozí sadu balíčků a konfiguraci.

Historická dokumentace

Přeložený klasický manuál je stále k dispozici na Legacy .NET 6 nastavení. Nový Klasická integrační brána vysvětluje stejné identifikační signály a odkazuje zpět na tento migrační průvodce.

Uchovávejte historické URL v záložkách a podpoře, dokud existují klasické instalace. Dokumentuje jinou generaci a není přesměrováno na současné API.