Migrace z klasické integrace .NET 6

Doconut má dvě odlišné integrace .NET 6. Mohou používat stejný název balíčku Doconut.NET6, proto identifikujte generaci podle API v aplikaci, než změníte balíčky, spouštění, licence nebo zdroje prohlížeče.

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

Pokud se v jedné aplikaci objeví oba sloupce, považujte migraci za neúplnou. Neposílejte 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 zamykání nebo uložený .nupkg tedy samy o sobě neurčují 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.

Aktuální vydání auditované 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 připnuty ke stejné verzi 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ých balíčků.
3. Zaznamenejte každé mapování DocImage.axd, volání new Viewer(...), volání načítání licence, zkopírovaný skript Doconut, vlastní akci panelu nástrojů a koncový bod pro otevírání dokumentu.
4. Uchovejte aktuální soubory .lic a nasazovací tajné údaje 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 aktuální časový limit relace, chování zabezpečení, písma a nastavení platformy.

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

Kompatibilita balíčků a licencí

Záměrně nahraďte nebo aktualizujte hlavní balíček; nespoléhejte se na stejné 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 auditovanou tímto průvodcem předejte verzi jako samostatnou volbu:

dotnet add package Doconut.NET6 --version 26.7.0

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

LicenseStream > LicenseContent > LicensePath > automatic discovery

Cílené 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í, po změně licence restartujte a ověřte funkce pomocí IDoconutLicenseService.

Nepředpokládejte, že přítomnost staré licence pluginu dokazuje oprávnění pro aktuální sestavení pluginu. Testujte Viewer, Search, Annotation, Converter a DICOM samostatně s schválenými artefakty vydání.

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

Klasické aplikace vytvářejí Viewer s cache ASP.NET a závislostmi na přístupu k požadavkům:

// 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 relací dokumentu a jeho cache vlastní dlouhodobější stav dokumentu, nikoli konkrétní injektovaná instance 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. volání UseSession() před Doconut, když je zabezpečení relace povoleno;
2. volání 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é klient používá konzistentně.

Konstrukce a životnost Vieweru

Odeberte 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. Považujte jej za nosiče oprávnění: neukládejte jej do logů, neperzistujte jej ani neumisťujte 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);

Nepoužívejte klasický token po přechodu. Otevřete každý dokument znovu přes aktuální API.

Konfigurační třídy

Aktuální API odděluje oblasti:

Nepřenášejte DocOptions.ImageResolution jako kontrolu renderování. Je zastaralý; nastavte BaseConfig.ImageResolution v konfiguraci specifické pro formát. Prohlédněte si všechny výchozí hodnoty místo předpokladu, že klasická konfigurace má stejné chování.

Toolbar Vieweru, Search a Annotation

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

1. vydávejte CSS Vieweru a licencované CSS pro Search/Annotation pomocí ReferenceCss;
2. vykreslete toolbar Vieweru vlastněný aplikací;
3. vykreslete searchBarMount, annBarMount a požadované umístění Vieweru;
4. vydávejte 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 Search a Annotation;
8. zavolejte attach(objViewer) na každé pásce;
9. otevřete dokument a zavolejte objViewer.View(token).

Search a Annotation jsou moduly připojené ke stejnému Vieweru, nikoli nezávislé panely nástrojů. Hlavní toolbar patří hostitelské aplikaci; pásky Search a Annotation jsou vložené, řízené podle schopností.

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

Registrace pluginů

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

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í Search a Annotation jsou vestavěné licencované funkce, nikoli balíčky AddPlugin<TPlugin>().

Bezpečnost relací a dokumentů

Aktuální integrace váže dokumenty k neprůhledným tokenům a cachovaným relacím. S výchozí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 není vyžadováno jinak po revizi návrhu. Nikdy nepoužívejte UnsafeMode = true jako zkratku při migraci. Testujte 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 migraci na jedné uzlu.

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/skripty Vieweru a všechny požadavky na obrázky stránky pod zvolenými cestami;
• otevření dokumentu, navigaci, zoom, miniatury, tisk a explicitní zavření;
• Search na dokumentu s textem a stav nevyhledatelnosti souboru jen s obrázkem;
• načtení, uložení, export a řízení schopností Annotation;
• objevení 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í písma, ne‑latinský text a nastavené časové limity;
• odmítnutí tokenu napříč relacemi a chování po vypršení relace;
• mobilní, tmavý režim a cesta produkčního reverzního proxy.

Plán návratu

Uchovejte klasický artefakt nasazení, odpovídající balíčky, licenční soubory a zkopírované prohlížečové zdroje společně. Bezpečný návrat přepne 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/cache, pokud existuje;
• jak budou aktivní 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.

Legacy dokumentace

Přeložený klasický manuál je nadále k dispozici na Legacy .NET 6 nastavení. Nová Brána klasické integrace 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 klasické instalace existují. Dokumentuje jinou generaci a není přesměrováno na aktuální API.