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.js | Legacy / klasická |
builder.Services.AddDoconut(...) | Aktuální integrace |
app.UseDoconutResources() plus app.UseDoconut() | Aktuální integrace |
Viewer poskytnuté pomocí dependency injection | Aktuá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í
- Vytvořte větev a nasaditelnou zálohu existující aplikace.
- Zaznamenejte přesné verze hlavního a pluginového balíčku.
- 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. - Zachovejte aktuální soubory
.lica tajné údaje nasazení mimo správu verzí. - 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ů.
- 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:
dotnet add package Doconut.NET6Pro reprodukovatelnou migraci na verzi auditovanou tímto průvodcem předávejte verzi jako samostatnou volbu:
dotnet add package Doconut.NET6 --version 26.9.0Udrž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í:
LicenseStream > LicenseContent > LicensePath > automatic discoveryAutomatické 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:
// 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í:
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:
// 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:
- volat
UseSession()před Doconut, když je zabezpečení relace povoleno; - volat
UseDoconutResources()předUseDoconut(); - udržet
ResourcesPath, generované URL zdrojů a klientskéResPathv souladu; - při mapování
UseDoconut()na větev udržet tuto větev a klientskéBasePathv 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:
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(...):
// 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:
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:
| Oblast | Aktuální typ |
|---|---|
| Cesty middleware, licencování, registrace pluginů | DoconutOptions |
| Heslo, časový limit, zabezpečení, vodoznak | DocOptions |
| Renderování formátu a DPI | PdfConfig, WordConfig, ExcelConfig, a další typy BaseConfig |
| Výchozí nastavení widgetu prohlížeče | ViewerConfig nebo ekvivalentní možnosti JavaScriptu |
| Generovaný CSS a skripty | CssConfig 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:
- vytvořte CSS Vieweru a licencované CSS Vyhledávání/Anotace pomocí
ReferenceCss; - vyrenderujte toolbar Vieweru vlastněný aplikací;
- vyrenderujte
searchBarMount,annBarMounta požadované připojení Vieweru; - vytvořte skripty Vieweru a licencovaných modulů pomocí
ReferenceScripts; - načtěte vlastní
viewerToolbar.jsaplikace; - inicializujte jeden
objViewer; - inicializujte licencované pásky Vyhledávání a Anotace;
- volat
attach(objViewer)na každé pásce; - 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ě:
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:
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á?