Migrace z klasické integrace .NET 6

Přesuňte existující aplikaci Doconut.NET6 na aktuální DI a asynchronní API

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ů, spuštění, licencí nebo zdrojů prohlížeče identifikujte generaci podle API v aplikaci.

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

Pokud projekt obsahuje…Generace
app.MapWhen(... "DocImage.axd" ...)Legacy / klasická
new Viewer(_cache, _accessor, ...)Legacy / klasická
Viewer.DoconutLicense(...) nebo Viewer.SetLicensePlugin(...)Legacy / klasická
Manuálně zkopírované docViewer.js, documentLinks.js, nebo docViewer.UI.jsLegacy / klasická
builder.Services.AddDoconut(...)Aktuální integrace
app.UseDoconutResources() plus app.UseDoconut()Aktuální integrace
Viewer poskytnuté pomocí dependency injectionAktuální integrace
await viewer.OpenDocumentAsync(...)Aktuální integrace

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 byly vydány pod ID balíčku Doconut.NET6. Odkaz na balíček, soubor lock nebo cacheovaný .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.

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, pevně svázané 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. Inventarizujte 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ření dokumentu.
  4. Zachovejte aktuální soubory .lic a tajné údaje nasazení 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. Aktuální 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í

Záměrně nahraďte nebo aktualizujte hlavní balíček; nespoléhejte se na identické ID balíčku při výběru nového API. Výchozí příkaz nainstaluje nejnovější stabilní verzi:

bash
dotnet add package Doconut.NET6

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

bash
dotnet add package Doconut.NET6 --version 26.9.0

Udržujte každý Doconut plugin ve stejné verzi jako hlavní balíček. Aktuální integrace načítá licence jednou během AddDoconut() s touto předností:

text
LicenseStream > LicenseContent > LicensePath > automatic discovery

Automatické vyhledávání hledá Doconut.Viewer.lic a doprovodné soubory Doconut.Viewer.<Capability>.lic. Klasické volání Viewer.DoconutLicense(...) nebo Viewer.SetLicensePlugin(...) není aktuální startovací mechanismus. Přesuňte licenci do DoconutOptions, udržujte doprovodné soubory pohromadě při použití automatického vyhledávání, restartujte po změně licence a ověřte funkce prostřednictvím IDoconutLicenseService.

Nepředpokládejte, že přítomnost staré licence pluginu dokazuje oprávnění pro aktuální sestavení pluginu. Otestujte 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 mezipamětí ASP.NET a závislostmi request-accessor:

csharp
// Klasická integrace — pouze kontrast; nekompilujte to 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í:

csharp
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 mezipaměť 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:

csharp
// 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. volat UseSession() před Doconut, když je zabezpečení relace povoleno;
  2. volat UseDoconutResources() před UseDoconut();
  3. udržet ResourcesPath, generované URL zdrojů a klientské ResPath v souladu;
  4. při mapování UseDoconut() na větev udržet tuto větev a klientské BasePath v souladu.

MiddlewarePath je validovaná konfigurace; sama o sobě nevytváří větev ASP.NET Core. Použijte buď jednoduchý pipeline v kompilovaném příkladu výše, nebo explicitní uspořádání app.Map("/doconut", branch => branch.UseDoconut()) používané konzistentně klientem.

Konstrukce a životnost Vieweru

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

csharp
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čovým oprávněním: neukládejte jej do logů, neukládejte jej trvale ani jej neumisťujte do analytiky.

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

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

csharp
// Aktuální integrace .NET 6: Viewer pochází z DI a otevření 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:

csharp
viewer.CloseDocument(token);

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

Konfigurační třídy

Aktuální API odděluje starosti:

OblastAktuální typ
Cesty middleware, licencování, registrace pluginůDoconutOptions
Heslo, časový limit, zabezpečení, vodoznakDocOptions
Renderování formátu a DPIPdfConfig, WordConfig, ExcelConfig, a další typy BaseConfig
Výchozí nastavení widgetu prohlížečeViewerConfig nebo ekvivalentní možnosti JavaScriptu
Generovaný CSS a skriptyCssConfig a ScriptConfig

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

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

  1. vytvořte CSS Vieweru a licencované CSS Vyhledávání/Anotace pomocí ReferenceCss;
  2. vyrenderujte toolbar Vieweru vlastněný aplikací;
  3. vyrenderujte searchBarMount, annBarMount a požadované připojení Vieweru;
  4. vytvořte 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. volat 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, ne 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 s prostředky vytvořený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ě:

csharp
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 vydány jako .NET 6 pluginy. Normální Search a Annotation jsou vestavěné licencované funkce, nikoli AddPlugin<TPlugin>() balíčky.

Bezpečnost relací a dokumentů

Aktuální integrace váže dokumenty k neprůhledným tokenům a ke kešovaným relacím. S výchozím UnsafeMode = false, UseDoconut() přidává zabezpečení přístupu k dokumentům a hostitel musí nakonfigurovat ASP.NET relaci:

csharp
builder.Services.AddDistributedMemoryCache(); // session state potřebuje cache (MVC/Razor Pages již přidává jednu)
builder.Services.AddSession();
app.UseSession();

Udržujte DocOptions.IsSecured = true, pokud revizní návrh nevyžaduje jinak. Nikdy nepoužívejte UnsafeMode = true jako zkratku pro migraci. 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 migraci na jednojádrový uzel.

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ánek pod zvolenými cestami;
  • otevření dokumentu, navigaci, zoom, náhledy, tisk a explicitní uzavření;
  • vyhledávání v dokumentu obsahujícím text a nevyhledávatelný stav souboru pouze s obrázkem;
  • načítání, ukládání, export a řízení schopností anotací;
  • objevování cílů 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í po vypršení relace;
  • mobilní zařízení, tmavý režim a cesta produkčního reverse‑proxy.

Plán návratu

Uchovejte 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:

  • slot nasazení 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.

Dokumentace starších verzí

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

Uchovejte historické URL v záložkách a podpoře tiketů, dokud existují klasické instalace. Dokumentuje jinou generaci a není přesměrováno na aktuální API.

Byla tato stránka užitečná?