Migrace na .NET Standard 2.1

Doconut má dvě odlišné integrace .NET Standard. Používají stejný název balíčku Doconut.NETStandard, takže určete generaci podle verze a API v aplikaci, než změníte balíčky, spuštění, licence nebo zdroje prohlížeče.

Verze je rozcestí

Obě generace jsou publikovány pod stejným ID balíčku. Pouze verze je odlišuje:

Zvýšení čísla verze je aktualizace. Neexistuje samostatný balíček k instalaci a žádný kompatibilní shim — 26.8.0 má odlišný povrch API. Očekávejte chyby při kompilaci po zvýšení verze; zbytek tohoto průvodce je jejich seznam.

Kterou integraci 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.

Nejprve zkontrolujte hostitelský framework

Jedná se o pevnou bariéru, ne o preferenci. Aktuální balíček cílí na netstandard2.1:

.NET Framework nemůže odkazovat na knihovnu netstandard2.1. Pokud aplikace běží na .NET Framework, zastavte zde a použijte místo toho balíček Doconut.NETFramework; od verze 26.9.0 vyžaduje .NET Framework 4.7.2. Obě referenční aplikace pro toto vydání cílí na net8.0.

Před migrací

1. Vytvořte větev a nasaditelnou zálohu existující aplikace.
2. Zaznamenejte přesné verze jádra a pluginů.
3. Inventarizujte každé volání new Viewer(...), volání InitCache(), volání načítání licence, mapování UseDoconutWebFarm, konverzní kontroler, zkopírovaný skript Doconut, vlastní akci panelu nástrojů, zpětné volání vieweru a koncový bod otevření dokumentu.
4. Zachovejte aktuální soubory .lic a nasazovací tajemství 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í, písma 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, doručování zdrojů klientovi a — pokud provozujete farmu — jak stránky vůbec dosáhnou prohlížeče.

1. Jmenné prostory: téměř vše přesunuto do kořene

Konfigurační typy byly rozprostřeny ve čtyřech jmenných prostorech. Nyní jsou všechny v Doconut.

Názvy typů se nezměnily: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, CloudUploadConfig, AzureConfig, CDNConfig, FileShareConfig a zbytek je stále přítomen. Ve většině souborů je celé úpravy odstranění dvou řádků using.

Doconut.Configs.Editor (BaseConfigEditor, PdfConfigEditor) byl odstraněn a nemá náhradu v tomto balíčku. Pokud vaše aplikace odkazovala na tyto typy, naplánujte tuto část samostatně a neberte ji jako součást této migrace.

2. Kompatibilita balíčků a licencí

Záměrně nahraďte nebo aktualizujte hlavní balíček; 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.NETStandard

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

dotnet add package Doconut.NETStandard --version 26.8.0

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

LicenseStream > LicenseContent > LicensePath > automatic discovery

Automatické vyhledávání hledá Doconut.Viewer.lic a související soubory Doconut.Viewer.<Capability>.lic. Předchozí statické volání Viewer.DoconutLicense(...) a Viewer.SetLicensePlugin(...) nejsou současným spouštěcím mechanismem a také není List<string> licenčních cest, které starý konstruktor Viewer akceptoval. Přesuňte licenci na DoconutOptions, udržujte související soubory pohromadě při použití automatického vyhledávání, po změně licence restartujte a ověřte schopnosti přes 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í.

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

V minulosti byl viewer vytvářen pro každý požadavek a možnosti byly předávány middleware:

// Předchozí integrace — pouze kontrast; nekompilujte to proti aktuálnímu SDK.
var viewer = new Viewer(_cache, _accessor);
// …
appBranch.UseDoconut(new DoconutOptions { UnSafeMode = false, ShowDoconutInfo = false });

Současná integrace zaregistruje Doconut jednou a získá Viewer z injekce závislostí:

builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // poznámka: změna pravopisu: UnSafeMode → UnsafeMode
    options.ShowDoconutInfo = false;
    options.LicensePath     = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // stav relace potřebuje mezipaměť (MVC/Razor Pages již přidávají jednu)
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.

Tři věci, které je třeba přenést:

• new Viewer(cache, accessor) už není. Injektujte Doconut.Viewer do svého kontroleru nebo použijte @inject Doconut.Viewer Viewer v Razor view.
• UseDoconutResources() nahrazuje ruční propojení app.UseMiddleware<EmbeddedResourceMiddleware>() a musí běžet před větví dokumentu.
• UnSafeMode → UnsafeMode. Přejmenování o jeden znak, které zachytí kompilátor.

Když je UnsafeMode false, SDK ověřuje token relace vůči původnímu požadavku, takže AddSession() / UseSession() musí být stále v pipeline, UseSession() před větví.

Metody, které již neexistují

4. Middleware a směrování zdrojů

UseDoconut() nyní nepřijímá žádné argumenty. Tvar větve MapWhen se sám nemusí měnit — pouze middleware uvnitř ní:

app.UseDoconutResources();   // PŘED větví

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

V aktuální pipeline:

1. volat UseSession() před Doconut, když je zabezpečení relace povoleno;
2. volat UseDoconutResources() před UseDoconut();
3. udržovat ResourcesPath, generované URL zdrojů a klientské ResPath v souladu;
4. udržovat mapovanou větev a klientské BasePath v souladu.

MiddlewarePath je validovaná konfigurace; sama nevytváří větev ASP.NET Core.

5. Konstrukce a životnost prohlížeče

Odstraňte mezipaměti vlastněné aplikací pro objekty Viewer.
V Viewer už nezůstává nic, co by stálo za zachování: neobsahuje žádný stav dokumentu a cache relace vlastní vše, co přežije požadavek.
Vložte jej 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 nositelský pověření: neukládejte jej do logů, neukládejte jej trvale ani jej neumisťujte do analytiky.

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

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

// Aktuální integrace: 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);

Odstraňte jakékoli volání InitCache() a příslušný příznak — není nic, co by se mělo ručně připravovat.
Po přechodu nepoužívejte token vytvořený předchozí knihovnou: otevřete každý dokument znovu pomocí aktuálního API.

7. Webová farma → distribuované: největší změna

UseDoconutWebFarm a WebFarmOptions již neexistují. Pokud je vaše aplikace volá, tato sekce je vaše aktualizace; pokud ne, přejděte na §8.

Dříve jedno middleware dělalo vše: poskytovalo předrenderované obrázky ze sdílené složky a dotazovalo se, zatímco jiný uzel je stále zapisoval.

// Předchozí integrace — jedno volání, implicitní koordinace přes souborový systém.
appBranch.UseDoconutWebFarm(new WebFarmOptions
{
    Path                = Path.Combine(env.WebRootPath, "webfarm"),
    PageWaitTimeSeconds = 180,
    StartWaitFromPage   = 5,
});

Stejný úkol je nyní rozdělen na dvě explicitní části. Strana zápisu — uzel, který otevírá dokument, zveřejňuje celý soubor artefaktů (stránky, informace o dokumentu, index vyhledávání, metadata) do sdíleného úložiště:

var result = await _publisher.PublishAsync(          // DistributedDocumentPublisher, injektováno z DI
    pathToFile,
    new FileShareConfig
    {
        Location              = CloudLocation.FileShare,
        RootPath              = @"\\fileserver\doconut",   // stejná složka, kterou používáte dnes
        UsePerTokenSubfolders = true,
    },
    config,
    documentOptions,
    new DistributedDocumentPublishOptions
    {
        CleanUpStagingDirectory = true,
        FirstPagePriority       = true,
    });

return Content(result.Token);

Strana čtení — libovolný uzel poskytuje ze sdíleného úložiště:

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = /* stejný FileShareConfig jako výše */;
    }, "/"));

Vaše topologie se nemění. Nasmerujte RootPath na stejný UNC share a každý uzel bude fungovat tak, jak funguje dnes. Co se mění, je to, že publikování je operace, kterou voláte, místo vedlejšího efektu renderování.

Obě strany se musí shodovat.
Pokud se RootPath nebo UsePerTokenSubfolders liší mezi vydavatelem a obslužným programem, druhý uzel odpoví 404.
Vytvořte konfiguraci v jednom pomocném nástroji a zavolejte ji z obou stran.

PageWaitTimeSeconds = 180 znamenalo „blokovat až tři minuty v naději, že se stránka objeví“. Náhrada je explicitní: s FirstPagePriority = true je stránka 1 servírována okamžitě a pozdější stránky odpovídají HTTP 202 Accepted, dokud nejsou zapsány. Vložený prohlížeč se automaticky pokusí znovu, když je nastaveno retryOn409. Klient, který se nepokouší znovu, zobrazí poškozené dlaždice pro stránky, které se stále renderují.

Úplné uspořádání, včetně publikování na pozadí a přístupových lístků, je na Distribuovaná nasazení.

8. Převod je plugin a je mnohem menší

Zaregistrujte plugin a poté vložte fasádu DocumentConverter:

builder.Services.AddDoconut(o => o.AddPlugin<ConverterPlugin>());

// Předchozí integrace
var converter = viewer.Converter.GetConverter();
var config    = new WordConfigConverter { TargetFormat = WordConfigConverter.EnTargetFormat.PDF };
var result    = converter.Convert(stream, SourceFormatConverter.DOCX, config);

// Aktuální integrace
var result = await _converter.ConvertAsync(stream, ".docx", ConversionTarget.Pdf, null, ct);

Co to nahrazuje:

• SourceFormatConverter — odstraněno. Předávejte příponu souboru jako řetězec, včetně tečky.
• Typy *ConfigConverter podle rodiny (WordConfigConverter, ExcelConfigConverter, …), každá s vnořeným výčtem EnTargetFormat — odstraněno. Nyní existuje jeden výčet ConversionTarget pro každou rodinu.
• viewer.Converter.GetConverter() — odstraněno. Vložte Doconut.DocumentConverter.

ConvertAsync vrací vyhledávatelný stream, takže return File(result, mime, name) funguje přímo — kopie starého kódu MemoryStream není potřeba. V dodaném příkladu to odstranilo 68‑položkový přepínač rozšíření a deset téměř identických řadičů.

Viz Plugin převodníku pro kompletní rozhraní.

9. Poskytovatelé cloudu

UseDoconutCloud se stal obecný. Poskytovatel je typový argument místo Location hodnoty, která se přepíná uvnitř middleware:

// Předchozí integrace
appBranch.UseDoconutCloud(new CloudOptions { Location = CloudLocation.CDN, ... });

// Aktuální integrace
branch.UseDoconutCloud<CDNCloudHandler>(options =>
{
    options.Location          = CloudLocation.CDN;
    options.CloudUploadConfig = new CDNConfig { DoconutCdnUrl = "..." };
}, "/");

Konfigurační třídy jsou nezměněny kromě jmenného prostoru (Doconut.Configs.Cloud → Doconut.Clouds): AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig, FTPConfig, plus nový FileShareConfig. Handlery se jmenují <Provider>CloudHandler.

Handler CDN je pouze pro čtení — poskytuje to, co je již na CDN; nenahrává.

10. Konfigurační objekty, které změnily název

DocOptions také získává IsSecured.

Aktuální API také odděluje odpovědnosti přísněji než předchozí, takže zkontrolujte, že každé nastavení je na objektu, který jej nyní vlastní:

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

11. Klientský prohlížeč — dva změny, které selžou TICHU

Obě tyto změny ponechají server fungovat perfektně. Váš dokument se vykresluje, stránka vypadá správně a v konzoli prohlížeče se nic neobjeví. Přečtěte si tuto sekci i když se váš C# zkompiluje na první pokus.

Callbacky prohlížeče jsou nyní volby, ne globální funkce

Předchozí prohlížeč volal vaše handlery podle jména, odvozujíc globální název funkce z ID kontejneru. Deklarace function ctlDoc_OnViewerReady() na stránce s <div id="div_ctlDoc"> stačila. Současný prohlížeč přijímá explicitní callbacky v objektu možností a již nevyhledává tyto globály:

objctlDoc = $("#div_ctlDoc").docViewer({
    // ... vaše existující možnosti ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // byl nalezen podle názvu
    onViewerReady:    ctlDoc_OnViewerReady,     // byl nalezen podle názvu
    onCopy:           ctlDoc_Copy,              // byl ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // byl ctlDoc_AutoLoadStatus(page)
});

Proč je to nepříjemné: staré volání bylo zabaleno do prázdného catch, který pohltil vše. Nyní vaše funkce jednoduše nikdy neběží a nic nehlásí chybu. Běžný symptom je neustále se točící spinner, který nikdy nezastaví — protože funkce, která jej skrývala, byla ctlDoc_OnViewerReady. Dokument za ní je v pořádku.

Úplný seznam možností je onPageLoading, onPageLoaded, onThumbnailClicked, onPageClicked, onDoubleClick, onViewerBusy, onViewerReady, onViewerError, onCopy, onAnnSaved, onAnnSaveError, onAnnLoaded, onAnnClosed, onAutoLoadStatus, onThumbsShown a onError. Neexistuje callback pro kliknutí na odkaz: zpracování hyperodkazů je vestavěné, řízené pomocí showHyperlinks.

ResPath musí ukazovat na předponu zdroje

ResPath: '',                      // BEFORE — zdroje pocházely z kořene aplikace
ResPath: 'doconut-res/images',    // NOW    — prefix UseDoconutResources() se připojuje

Pokud jste změnili předponu pomocí DoconutOptions.ResourcesPath, použijte tuto hodnotu místo toho.

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

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

1. vydat CSS Vieweru a licencované CSS Vyhledávání/Anotace pomocí ReferenceCss;
2. vyrenderovat panel nástrojů Vieweru vlastněný aplikací;
3. vyrenderovat searchBarMount, annBarMount a požadované připojení Vieweru;
4. vydat skripty Vieweru a licencovaných modulů pomocí ReferenceScripts;
5. načíst pomocný skript panelu nástrojů aplikace;
6. inicializovat jeden objViewer;
7. inicializovat licencované pásky Vyhledávání a Anotace;
8. volat attach(objViewer) na každé pásce;
9. otevřít dokument a zavolat 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é, na schopnosti omezené zdroje.

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

13. Registrace pluginů

Statické metody plugin‑licencí nezaregistrují 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 Standard pluginy. Normální Vyhledávání a Anotace jsou vestavěné licencované funkce, ne AddPlugin<TPlugin>() balíčky.

14. Bezpečnost relace a dokumentu

Současná 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 dokumentu a hostitel musí nakonfigurovat ASP.NET relaci:

builder.Services.AddDistributedMemoryCache(); // stav relace potřebuje mezipaměť (MVC/Razor Pages již přidává jednu)
builder.Services.AddSession();
app.UseSession();

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

V farmě může požadavek na stránku dopadnout na uzel, který nikdy neviděl úvodní požadavek, takže kontrola na úrovni relace by ho odmítla. To je jediný případ, kdy je UnsafeMode = true správný — a musí být spárován s podepsanými přístupovými lístky přes AddDoconutDistributedDocumentSecurity, nikoli distribuován samostatně. Viz Distribuovaná nasazení.

Poznámka k pojmenování

Ve všech rámcích je třída Viewer. Pokud najdete DocumentViewer ve starých úryvcích nebo článcích třetích stran, tento typ v SDK nikdy neexistoval.

15. Navrhované pořadí práce

1. Potvrďte, že hostitelský rámec může konzumovat netstandard2.1. Pokud ne, zastavte.
2. Zvyšte verzi balíčku na 26.8.0 a sestavte. Projděte kompilacemi chyb — většina jsou řádky using v §1.
3. Přesuňte spuštění na AddDoconut() a volání middleware do nového pořadí (§3, §4).
4. Vložte Viewer tam, kde jste jej konstruovali, udělejte OpenDocument asynchronní a odstraňte InitCache() (§5, §6).
5. Pokud používáte webovou farmu, proveďte §7 — jedinou část, která je redesignem místo přejmenování.
6. Pokud převádíte dokumenty, proveďte §8.
7. Proveďte §11 — změny na straně klienta. To jsou ty, které se neoznámí samy.
8. Otevřete skutečný dokument v prohlížeči a sledujte zaneprázdněný spinner. Zelená sestava zde nic neprokazuje: licencování, registrace pluginů, cesta ke zdroji a zpětné volání Vieweru selhávají pouze za běhu. Pro farmu ověřte, že dokument publikovaný jedním uzlem je poskytován jiným.

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, navigace, přiblížení, miniatury, tisk a explicitní zavření;
• vyhledávání v dokumentu obsahujícím text a nevyhledávatelný stav souboru jen s obrázkem;
• načítání, ukládání, export anotací a řízení schopností;
• zjišťování cíle konvertoru, výstup, stažení a stav vodoznaku;
• DICOM stránky, snímky a animace; technická metadata nejsou v tomto balíčku 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;
• pro farmu: publikovat na jednom uzlu, požádat o pozdější stránku z jiného a potvrdit, že viewer znovu požaduje 202 odpovědi místo zobrazování poškozených dlaždic;
• mobilní zařízení, tmavý režim a cesta produkčního reverse‑proxy.

Plán návratu

Uchovejte předchozí artefakt nasazení, odpovídající balíčky, licenční soubory a zkopírované prohlížečové zdroje společně. Bezpečný návrat přepíná celou generaci aplikace; neprovádí smíchání serveru předchozí generace s aktuálními skripty ani aktuálního serveru s new Viewer(...) místy volání.

• slot nasazení nebo artefakt použitý pro návrat;
• dopad sdíleného úložiště, pokud existuje — artefakty publikované verzí 26.8.0 nejsou spotřebovány předchozím middlewarem web‑farmy;
• jak budou neplatné aktivní relace dokumentů;
• kontrola zdraví a testovací dokument použitý pro rozhodnutí o návratu;
• kdo může obnovit předchozí sadu balíčků a konfiguraci.

Legacy dokumentace

Přeložený předchozí manuál je nadále k dispozici na Legacy .NET Standard setup. Previous 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 instalace netstandard2.0 stále existují. Dokumentuje jinou generaci a není přesměrováno na aktuální API.