Migrujte z klasické integrace .NET 6

Doconut má dvě odlišné integrace .NET 6. Mohou používat stejný název balíčku Doconut.NET6, proto je třeba před změnou balíčků, startováním, licencemi nebo zdroji prohlížeče určit 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 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ě neurčuje, které API je použito. 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í verze ověřená pro tento průvodce je Doconut.NET6 26.7.0. Její volitelné veřejné balíčky jsou Doconut.NET6.Converter a Doconut.NET6.Dicom, které jsou svázány se stejnou verzí jako hlavní balíček.

Před migrací

1. Vytvořte větev a nasaditelnou zálohu stávající aplikace.
2. Zaznamenejte přesné verze hlavního a pluginového balíčku.
3. Zaznamenejte všechny mapování DocImage.axd, volání new Viewer(...), 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é ú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í, fonty a nastavení platformy.

Proveďte migraci v jednom prostředí před změnou produkce. Současná integrace mění životnost služeb, směrování požadavků, vlastnictví relací a doručování klientských zdrojů.

Kompatibilita balíčků a licencí

Nahradťe nebo aktualizujte hlavní balíček úmyslně; nespoléhejte se na totožné ID balíčku při výběru 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ý plugin Doconut ve stejné verzi jako hlavní balíček. Současná integrace načítá licence jednou během AddDoconut(), s následujícím pořadím přednosti:

LicenseStream > LicenseContent > LicensePath > automatic discovery

Automatické vyhledávání hledá soubory Doconut.Viewer.lic a související soubory Doconut.Viewer.<Capability>.lic. Klasické volání Viewer.DoconutLicense(...) nebo Viewer.SetLicensePlugin(...) není současným startovacím mechanismem. Přesuňte licenci do DoconutOptions, udržujte související soubory pohromadě při použití automatického vyhledávání, po změně licence restartujte a ověřte funkce prostřednictvím 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:

// Klasická integrace — pouze pro kontrast; tento kód nekompilujte proti aktuálnímu 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.AddDistributedMemoryCache();
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í injektovanou instanci Viewer.

Middleware a směrování zdrojů

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

// Klasická integrace — odeberte během přechodu.
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, zatímco je zabezpečení relace povoleno;
2. volání UseDoconutResources() před UseDoconut();
3. ponechte ResourcesPath, generované URL zdrojů, a klientský ResPath sladěné;
4. při mapování UseDoconut() na větev, udržujte tuto větev a klientský BasePath sladěné.

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

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. Považujte jej za nosič pověření: neukládejte jej do logů, neperzistujte jej ani neumisťujte jej do analytiky.

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

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

// Aktuální integrace .NET 6: Viewer pochází z DI a otevírání dokumentu je asynchronní.
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 pomocí aktuálního API.

Konfigurační třídy

Aktuální API odděluje starosti:

Nepřenášejte DocOptions.ImageResolution jako řízení 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í.

Panel nástrojů Vieweru, Vyhledávání a Anotace

Nepřevádějte staré skripty jeden po druhém. Aktuální referenční aplikace sestavují jeden kompletní balíček stránky:

1. vygenerujte CSS Vieweru a licencované CSS pro Vyhledávání/Anotaci pomocí ReferenceCss;
2. vyrenderujte panel nástrojů Vieweru vlastněný aplikací;
3. vyrenderujte 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ém pásku;
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é panely nástrojů. Hlavní panel nástrojů 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 jsou documentLinks.js a docViewer.UI.js, až poté, co aktuální stránka funguje se zdroji vygenerovanými pomocí ReferenceCss a ReferenceScripts.

Registrace pluginu

Klasické statické metody licencování pluginů 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

Aktuální integrace váže dokumenty k neprůhledným tokenům a ke kešovaným relacím. 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.AddDistributedMemoryCache(); // stav relace potřebuje cache (MVC/Razor Pages již přidávají jednu)
builder.Services.AddSession();
app.UseSession();

Nechte DocOptions.IsSecured = true, pokud revizní návrh nevyžaduje jinak. Nikdy nepoužívejte UnsafeMode = true jako migrační zkratku. 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 přenosu. 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/skrypty Vieweru a všechny požadavky na obrázky stránek pod zvolenými cestami;
• otevření dokumentu, navigaci, zoom, miniatury, tisk a explicitní uzavření;
• vyhledávání v dokumentu obsahujícím text a stav nevyhledatelného souboru jen s obrázkem;
• načítání, ukládání, export a řízení funkcí anotací;
• objevení cíle Converteru, výstup, stažení a stav vodoznaku;
• stránky, snímky a animace DICOM; technická metadata .NET 6 nejsou k dispozici;
• dokumenty chráněné heslem, vlastní fonty, ne‑latinský text a nastavené č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 nadále k dispozici na Historické nastavení .NET 6. 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 tiketů, dokud klasické instalace stále existují. Dokumentuje jinou generaci a není přesměrováno na aktuální API.