Migrace

Tato stránka popisuje aktualizaci existující ASP.NET aplikace z Doconut.NETFramework 26.8.0 nebo starší (.NET Framework 4.7) na 26.9.0 a novější (.NET Framework 4.7.2). Balíček vzorových projektů Doconut obsahuje kompletní průvodce migrací a klasické vzorky převedené na nové API — MVC 5, webová farma a Web Forms. Porovnání vaší aplikace se vzorkem, ze kterého vycházela, je nejrychlejší cesta.

Jeden balíček, dvě verze

Obě knihovny jsou publikovány pod stejným ID balíčku, Doconut.NETFramework. Verze je od sebe odlišuje:

Aktualizace balíčku je samotná aktualizace. Neexistuje žádný samostatný balíček k instalaci ani vrstva kompatibility: 26.9.0 má jiný API povrch, takže po aktualizaci očekávejte chyby při kompilaci — zbytek této stránky. Řada .NET Framework 4.7 je ukončena a 26.8.0 je její poslední vydání. Můžete na ní zůstat — nic zde není bezpečnostní oprava, kterou byste postrádali — ale nové verze, pluginy, distribuovaný režim a připravené widgety jsou dostupné jen v 26.9.0 a novějších.

1. Přesměrování a aktualizace balíčku

Nejprve přesměrujte webový projekt na .NET Framework 4.7.2: projekt, který stále cílí na 4.7, nemůže nainstalovat 26.9.0 a NuGet odmítne aktualizaci. Pak aktualizujte Doconut.NETFramework a přidejte pluginové balíčky, které používáte (Doconut.NETFramework.Converter, Doconut.NETFramework.Dicom, …). Každý plugin potřebuje licenci, která mu to umožňuje.

Pokud projekt používá packages.config, aktualizace spustí odinstalační krok předchozí verze, který odstraní DocImage handler z Web.config, a 26.9.0 jej nepřidá zpět. Zaregistrujte jej znovu, jak je ukázáno ve kroku 3; dokud to neuděláte, DocImage.axd vrací 404 a žádná stránka se nezobrazí.

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

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

3. Spuštění: DoconutHost.Initialize a dva záznamy v Web.config

Klasičtí balíček vytvářel svůj prohlížeč pro každý požadavek, s možnostmi jako vlastnostmi této instance. Nový balíček má kořen kompozice, vytvořený jednou v Application_Start, a prohlížeč je služba, kterou získáte:

// Před - Doconut.NETFramework 26.8.0 a starší, na požádání
var viewer = new Viewer
{
    ID = "ctlDoc",
    IncludeJQuery = true,
    BasePath = "/",
    FitType = "width"
};

// Doconut.NETFramework 26.9.0\u002B - Prohlížeč získán z DoconutHost, licence nakonfigurována jednou v DoconutHost.Initialize()
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
var token  = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

DoconutHost.Initialize jde do Application_Start a DoconutHost.Shutdown do Application_End, a Web.config získává DocImage.axd handler a modul zdrojů — oba jsou v Installation. Nastavení vzhledu na stránku (FitType, FixedZoom, ShowHyperlinks, …) se přesunulo z instance prohlížeče do možností widgetu, nebo do ViewerConfig předávaného Viewer.RenderViewer (viz ViewerConfig). new Viewer() se stále kompiluje, jakmile DoconutHost.Initialize proběhne, takže migrovaný code-behind může zachovat tento řádek, zatímco přesouváte nastavení.

Bezpečnost funguje jako dříve. Otevření dokumentu uděluje aktuální ASP.NET relaci přístup k jeho stránkám a DocImage.axd odmítá všechny ostatní. Nastavení aplikace DoconutUnSafeMode, které toto vypínalo, je nyní options.UnsafeMode v DoconutHost.Initialize — nechte ho false. Viz Sessions & Security.

Selhání spuštění, které zcela znefunkční celý web. Registrovaný plugin, jehož funkci žádná licence nepovoluje, vyhodí výjimku v Application_Start, a aplikace pak odpovídá prázdným 500 na každý požadavek — žádná chybová stránka, nic v IIS logu, jen záznam v Windows Event Logu (source ASP.NET). Licence se čtou z wwwroot pod kořenem webu a nikde jinde, a základní Doconut.Viewer.lic musí být přítomen, jinak se licence pluginu vedle něj nečtou. Viz License Setup.

4. Web farm: od vlajky k distribuovanému režimu

Klasický model byl viewer.IsWebfarm = true plus ExportToPng(path). Nový model je registrován jednou: každý uzel sdílí jeden úložiště a jeden podpisový klíč, a podepsaný tiket vázaný na prohlížeč nahrazuje „kterýkoliv uzel odpoví“:

Doconut.DoconutHost.Initialize(
    options => options.UnsafeMode = false,
    services => services.AddDoconutDistributed(d =>
    {
        d.Store             = CloudLocation.FileShare;
        d.FileShareRootPath = @"\\fileserver\doconut-shared";   // WebfarmPath je alias
        d.SigningKey        = farmKey;                           // >= 32 bytes, stejný na každém uzlu
    }));

Pak otevřete dokumenty normálně, svázáním prohlížeče (DocOptions.BrowserId = DoconutFarmBinding.EnsureBrowserId(...)) a předáním viewer.AccessToken widgetu s tokenem. Relace a zabezpečení má kroky; ukázka web-farmy je kompletní uzel. IsWebfarm a WebfarmPath stále kompilují, ale již nic neaktivují.

Dvě věci, které vypadají jako úspěch, ale nejsou: DistributedDocumentPublisher.PublishAsync zapisuje vykreslené soubory dokumentu, ale neotevírá žádnou relaci, takže prohlížeč nasměrovaný na publikovaný token získá ~2 KB chybový obrázek se stavem 200; a testovací klient bez cookie doconut-client získá stejný obrázek, ne 401. Rozlište skutečnou stránku od chybového obrázku podle velikosti.

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

Enum SourceFormatConverter, dvanáct tříd *ConfigConverter a jejich vnořené cílové výčty jsou nahrazeny jedním výčtem, ConversionTarget, a jedním voláním:

using System.IO;
using System.Threading;
using Doconut;
using Doconut.Configs.Conversion;

// Předpokládejte, že DoconutHost je již inicializován a CancellationToken pojmenovaný ct je k dispozici.
var provider = DoconutHost.Services;
var converter = (DocumentConverter)provider.GetService(typeof(DocumentConverter));
Stream source = /* váš vstupní stream */;
var result = await converter.ConvertAsync(source, ".dwg", ConversionTarget.Pdf, null, ct);

Zdrojový formát pochází z přípony, kterou předáte. Neexistuje žádná kompatibilní vrstva: každá reference SourceFormatConverter je kompilátorová chyba, kterou vyřešíte jejím smazáním. Objektům možností pro jednotlivé formáty to nepřežilo — WordConfigConverter.HtmlOptions a CadConfigConverter.CadOptions.ShowColor nemají ekvivalent přes ConvertAsync. Ve Web Forms nikdy neblokujte na ConvertAsync — viz Plugin převodníku.

6. Cloudové úložiště: přístup jako sdílený adresář

Typy konfigurace cloudu se přesunuly do Doconut.Clouds beze změny. Manipulátory požadavků cloudu jsou však komponenty ASP.NET Core a klasická aplikace nemá pipeline, ve které by je mohla spustit. Z webu System.Web přistupujte k cloudovému úložišti jako k sdílenému adresáři — na Azure, sdílení Azure Files připojené na každý uzel — adresováno přes FileShareConfig.

7. Změny na straně klienta, které selhávají tiše

Každá položka níže se kompiluje, běží, nic neloguje a dělá špatnou věc:

Tři další: prohlížeč nevykresluje vlastní panel nástrojů (vaše stránka připojuje Zoom, Next, GotoPage a zbytek k jejím vlastním tlačítkům); prohlížeč vytvořený uvnitř skrytého Bootstrap modálu má rozměry 0×0 a nic nevykresluje, dokud nedáte jeho kontejneru explicitní výšku a nepřizpůsobíte jej na shown.bs.modal; a AllowSearch má jako výchozí nastavení false pro PDF, takže dokument se vykresluje perfektně, zatímco každé hledání nic nevrací.

8. Co zmizí

Navrhovaný postup práce

1. Změňte cíl, vyměňte balíček a nechte Global.asax kompilovat s DoconutHost.Initialize a dvěma registracemi Web.config. Stránka by měla startovat.
2. Jedna stránka prohlížeče: načtěte dokument k vykreslení, pak projděte sekci 7, dokud nebudou fungovat panel nástrojů, vyhledávání a anotace. Ověřte ve skutečném prohlížeči — v té sekci se nevyskytne žádná chyba.
3. Konverze (sekce 5): mechanická, a většina kompilátorových chyb.
4. Zbývající stránky, s použitím přenesených vzorků jako cíle rozdílu.
5. Webová farma (sekce 4), pokud ji máte. Otestujte se dvěma uzly a prohlížečem, nebo klientem, který uchovává cookies.