Migration

Denna sida behandlar uppgradering av en befintlig ASP.NET‑applikation från Doconut.NETFramework 26.8.0 eller tidigare (.NET Framework 4.7) till 26.9.0 och senare (.NET Framework 4.7.2). Doconut‑exempelpaketet innehåller den kompletta migrationsguiden och de klassiska exemplen som har portats till det nya API‑et — MVC 5, en webbfarm och Web Forms. Att jämföra din applikation med det exempel den startade från är den snabbaste vägen.

Ett paket, två versioner

Båda biblioteken publiceras under samma paket‑ID, Doconut.NETFramework. Versionen skiljer dem åt:

Att uppdatera paketet är uppgraderingen. Det finns inget separat paket att installera och inget kompatibilitetslager: 26.9.0 har en annan API‑yta, så förvänta dig kompileringsfel efter uppdateringen — resten av denna sida. .NET Framework 4.7‑serien har avvecklats och 26.8.0 är dess sista version. Du kan stanna på den — inget här är en säkerhetsfix du skulle missa — men nya releaser, plugins, det distribuerade läget och de inbyggda widgetarna finns endast i 26.9.0 och senare.

1. Ändra mål och uppdatera paketet

Ändra först webbprojektet till .NET Framework 4.7.2: ett projekt som fortfarande riktar sig mot 4.7 kan inte installera 26.9.0, och NuGet vägrar uppdateringen. Uppdatera sedan Doconut.NETFramework och lägg till de plugin‑paket du använder (Doconut.NETFramework.Converter, Doconut.NETFramework.Dicom, …). Varje plugin kräver en licens som beviljar den.

Om projektet använder packages.config kör uppdateringen föregående versions avinstallationssteg, vilket tar bort DocImage‑hanteraren från Web.config, och 26.9.0 lägger inte till den igen. Registrera den på nytt enligt steg 3; tills du gör det svarar DocImage.axd med 404 och ingen sida renderas.

2. Namnrymder: nästan allt flyttat till roten

Typnamnen har inte ändrats: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, FileShareConfig och resten finns fortfarande där. I de flesta filer består hela ändringen av att ta bort using‑rader.

3. Start: DoconutHost.Initialize och två Web.config‑poster

Det klassiska paketet byggde sin visare per begäran, med alternativ som egenskaper på den instansen. Det nya paketet har en kompositionsrot, byggd en gång i Application_Start, och visaren är en tjänst du löser upp:

// Före - Doconut.NETFramework 26.8.0 och tidigare, på begäran
var viewer = new Viewer
{
    ID = "ctlDoc",
    IncludeJQuery = true,
    BasePath = "/",
    FitType = "width"
};

// Doconut.NETFramework 26.9.0+ - Visare hämtad från DoconutHost, licens konfigurerad en gång i DoconutHost.Initialize()
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
var token  = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

DoconutHost.Initialize går i Application_Start och DoconutHost.Shutdown i Application_End, och Web.config får DocImage.axd‑hanteraren och resursmodulen — båda finns i Installation. Inställningarna för sidans utseende per sida (FitType, FixedZoom, ShowHyperlinks, …) har flyttats från visar‑instansen till widgetens alternativ, eller till en ViewerConfig som skickas till Viewer.RenderViewer (se ViewerConfig). new Viewer() kompileras fortfarande när DoconutHost.Initialize har körts, så migrerad kod‑bakgrund kan behålla den raden medan du flyttar inställningarna.

Säkerheten fungerar som tidigare. Att öppna ett dokument ger den aktuella ASP.NET‑sessionen åtkomst till dess sidor, och DocImage.axd vägrar alla andra. App‑inställningen DoconutUnSafeMode som stängde av detta är nu options.UnsafeMode i DoconutHost.Initialize — låt den vara false. Se Sessioner & Säkerhet.

Startfelet som tar ner hela webbplatsen. Ett registrerat plugin vars funktion ingen licens beviljar kastar i Application_Start, och applikationen svarar sedan med en tom 500 på varje begäran — ingen felsida, inget i IIS‑loggen, bara en post i Windows‑händelseloggen (källa ASP.NET). Licenser läses från wwwroot under webbplatsens rot och ingen annanstans, och bas‑Doconut.Viewer.lic måste finnas eller så läses inte plugin‑licenserna bredvid den. Se Licensinställning.

4. Webbfarm: från en flagga till det distribuerade läget

Den klassiska modellen var viewer.IsWebfarm = true plus ExportToPng(path). Den nya modellen registreras en gång: varje nod delar en lagring och en signeringsnyckel, och en signerad biljett bunden till webbläsaren ersätter "vilken nod som svarar":

Doconut.DoconutHost.Initialize(
    options => options.UnsafeMode = false,
    services => services.AddDoconutDistributed(d =>
    {
        d.Store             = CloudLocation.FileShare;
        d.FileShareRootPath = @"\\fileserver\doconut-shared";   // WebfarmPath är ett alias
        d.SigningKey        = farmKey;                           // >= 32 byte, samma på varje nod
    }));

Öppna sedan dokument som vanligt, bind webbläsaren (DocOptions.BrowserId = DoconutFarmBinding.EnsureBrowserId(...)) och ge viewer.AccessToken till widgeten med token. Sessioner & Säkerhet har stegen; webbfarm‑exemplet är en komplett nod. IsWebfarm och WebfarmPath kompilerar fortfarande, men de växlar inte längre på någonting.

Två saker som ser ut som framgång men inte är det: DistributedDocumentPublisher.PublishAsync skriver ett dokuments renderade filer men öppnar ingen session, så en visare som pekas på en publicerad token får ~2 KB felbild med status 200; och en testklient utan doconut-client‑kakan får samma bild, inte en 401. Identifiera en riktig sida från felbilden efter storlek.

5. Konvertering är ett plugin, och mycket mindre

Enumen SourceFormatConverter, de tolv *ConfigConverter‑klasserna och deras nästlade mål‑enum ersätts av en enum, ConversionTarget, och ett anrop:

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

// Anta DoconutHost är redan initierad och en CancellationToken med namnet ct är tillgänglig.
var provider = DoconutHost.Services;
var converter = (DocumentConverter)provider.GetService(typeof(DocumentConverter));
Stream source = /* din inmatningsström */;
var result = await converter.ConvertAsync(source, ".dwg", ConversionTarget.Pdf, null, ct);

Källformatet kommer från den filändelse du anger. Det finns ingen kompatibilitets‑shim: varje SourceFormatConverter‑referens är ett kompileringsfel som du löser genom att ta bort den. Per‑format‑alternativobjekten överlevde inte — WordConfigConverter.HtmlOptions och CadConfigConverter.CadOptions.ShowColor har ingen motsvarighet via ConvertAsync. I Web Forms, blockera aldrig på ConvertAsync — se Konverteringsplugin.

6. Molnlagring: nå den som en delad mapp

Molnkonfigurationstyperna flyttades till Doconut.Clouds oförändrade. Moln‑request‑hanterarna är dock ASP.NET Core‑komponenter, och en klassisk applikation har ingen pipeline att köra dem i. Från en System.Web‑plats nås molnlagring som en delad mapp — på Azure, en Azure Files‑delning monterad på varje nod — adresserad via FileShareConfig.

7. Klientsidans förändringar som misslyckas tyst

Varje post nedan kompilerar, körs, loggar inget och gör fel sak:

Tre till: visaren ritar inte sin egen verktygsrad (din sida kopplar Zoom, Next, GotoPage och resten till sina egna knappar); en visare som skapas i en dold Bootstrap‑modal har måtten 0×0 och målar inget tills du ger dess behållare en explicit höjd och anpassar den på shown.bs.modal; och AllowSearch har som standard false för PDF, så ett dokument renderas perfekt medan varje sökning returnerar inget.

8. Vad försvinner

Föreslagen arbetsordning

1. Omrikta, byt paketet och få Global.asax att kompilera med DoconutHost.Initialize och de två Web.config-registreringarna. Webbplatsen bör starta.
2. En visningssida: få ett dokument att renderas, fortsätt sedan genom avsnitt 7 tills verktygsfältet, sökningen och annotationerna fungerar. Verifiera i en riktig webbläsare — inget i det avsnittet ger ett fel.
3. Konvertering (avsnitt 5): mekanisk, och de flesta kompileringsfelen.
4. De återstående sidorna, med de porterade exemplen som diff-mål.
5. Webbfarmen (avsnitt 4), om du har en. Testa med två noder och en webbläsare, eller en klient som behåller cookies.