Migrera till .NET Standard 2.1

Doconut har två separata .NET Standard-integrationer. De använder samma Doconut.NETStandard paketnamn, så identifiera generationen utifrån versionen och API:erna i applikationen innan du ändrar paket, start, licenser eller webbläsarresurser.

Versionen är vägskälet

Båda generationerna publiceras under samma paket-ID. Endast versionen skiljer dem åt:

Att öka versionsnumret är uppgraderingen. Det finns inget separat paket att installera och ingen kompatibilitetsshim — 26.8.0 är en annan API-yta. Förvänta dig kompileringsfel efter uppdateringen; resten av den här guiden är en lista över dem.

Vilken integration använder du?

Om båda kolumnerna förekommer i samma applikation, behandla migrationen som ofullständig. Skicka inte ett dokumenttoken genom resurser eller middleware från den andra generationen.

Kontrollera värdramverket först

Detta är en hård gräns, inte en preferens. Det aktuella paketet riktar sig mot netstandard2.1:

.NET Framework kan inte referera till ett netstandard2.1-bibliotek. Om applikationen körs på .NET Framework, stoppa här och använd Doconut.NETFramework-paketet istället; från 26.9.0 krävs .NET Framework 4.7.2. Båda referensapplikationerna för denna release riktar sig mot net8.0.

Innan du migrerar

1. Skapa en gren och en distribuerbar backup av den befintliga applikationen.
2. Registrera de exakta kärn- och pluginpaketversionerna.
3. Inventera varje new Viewer(...)-anrop, InitCache()-anrop, licensladdningsanrop, UseDoconutWebFarm-mappning, konverteringskontroller, kopierat Doconut-skript, anpassad verktygsfältshandling, viewer-återuppringning och dokumentöppningsendpoint.
4. Bevara de nuvarande .lic-filerna och deploymentshemligheter utanför källkontrollen.
5. Fånga ett representativt urval av PDF-, Office-, bild-, CAD-, e‑post-, DICOM-, sökbara, lösenordsskyddade och annoterade dokument.
6. Registrera den befintliga sessionstidsgränsen, säkerhetsbeteendet, typsnitten och plattformsinställningarna.

Migrera en miljö innan du ändrar produktionen. Den nuvarande integrationen ändrar tjänstelivslängd, begäranderouting, sessionsägande, leverans av klientresurser, och — om du kör en farm — hur sidor når webbläsaren över huvud taget.

1. Namnrymder: nästan allt flyttat till roten

Konfigurationstyperna var spridda över fyra namnrymder. De finns nu alla i Doconut.

Typnamnen ändrades inte: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, CloudUploadConfig, AzureConfig, CDNConfig, FileShareConfig och resten finns fortfarande kvar. I de flesta filer är hela ändringen att ta bort två using-rader.

Doconut.Configs.Editor (BaseConfigEditor, PdfConfigEditor) togs bort och har ingen ersättning i detta paket. Om din applikation refererade till dessa typer, planera den delen separat och behandla den inte som en del av denna migration.

2. Paket‑ och licenskompatibilitet

Byt ut eller uppdatera kärnpaketet medvetet; förlita dig inte på det identiska paket‑ID:t för att välja det nya API‑et. Standardkommandot installerar den senaste stabila versionen:

dotnet add package Doconut.NETStandard

För en reproducerbar migrering till den version som granskats i den här guiden, ange versionen som ett separat alternativ:

dotnet add package Doconut.NETStandard --version 26.8.0

Behåll varje Doconut‑plugin i samma version som kärnpaketet — Doconut.NETStandard.Converter och Doconut.NETStandard.Dicom. Den aktuella integrationen laddar licenser en gång under AddDoconut(), med denna prioritet:

LicenseStream > LicenseContent > LicensePath > automatic discovery

Automatisk upptäckt söker efter Doconut.Viewer.lic och tillhörande Doconut.Viewer.<Capability>.lic‑filer. De tidigare statiska anropen Viewer.DoconutLicense(...) och Viewer.SetLicensePlugin(...) är inte en aktuell uppstarts‑mekanism, och inte heller är List<string> för licensvägar som den gamla Viewer‑konstruktorn accepterade. Flytta licensen till DoconutOptions, håll tillhörande filer ihop när du använder automatisk upptäckt, starta om efter att ha ändrat en licens, och verifiera funktioner via IDoconutLicenseService.

Anta inte att närvaron av en gammal plugin‑licens bevisar rättighet för en aktuell plugin‑byggnad. Testa Viewer, Search, Annotation, Converter och DICOM separat med de godkända release‑artefakterna.

3. Uppstart och beroendeinjicering

Tidigare konstruerades visaren per begäran och alternativ skickades till middleware‑komponenten:

// Föregående integration — endast för jämförelse; kompilera inte detta mot den aktuella SDK:n.
var viewer = new Viewer(_cache, _accessor);
// …
appBranch.UseDoconut(new DoconutOptions { UnSafeMode = false, ShowDoconutInfo = false });

Den aktuella integrationen registrerar Doconut en gång och får Viewer via beroendeinjicering:

builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // notera stavningsändringen: UnSafeMode → UnsafeMode
    options.ShowDoconutInfo = false;
    options.LicensePath     = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // sessionstillstånd behöver en cache (MVC/Razor Pages lägger redan till en)
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

Viewer är en transient tjänst. Dokument‑sessionshanteraren och dess cache äger det längre levande dokumenttillståndet, inte den specifika injicerade Viewer‑instansen.

Tre saker att behålla:

• new Viewer(cache, accessor) är borta. Injicera Doconut.Viewer i din controller, eller använd @inject Doconut.Viewer Viewer i en Razor‑vy.
• UseDoconutResources() ersätter hand‑koppling av app.UseMiddleware<EmbeddedResourceMiddleware>(), och måste köras före dokument‑grenen.
• UnSafeMode → UnsafeMode. En en‑teckens namnändring som kompilatorn kommer att upptäcka.

När UnsafeMode är false validerar SDK:et sessionstoken mot den ursprungliga begäran, så måste AddSession() / UseSession() fortfarande finnas i pipelinen, UseSession() före grenen.

Metoder som inte längre finns

4. Middleware och resursroutning

UseDoconut() tar nu inga argument. MapWhen‑grenens form i sig behöver inte ändras — bara middleware‑komponenten inuti den:

app.UseDoconutResources();   // FÖRE grenen

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

I den aktuella pipelinen:

1. anropa UseSession() före Doconut medan sessionsäkerhet är aktiverad;
2. anropa UseDoconutResources() före UseDoconut();
3. behåll ResourcesPath, de genererade resurs‑URL:erna och klient‑ResPath i linje;
4. behåll den gren du mappar och klient‑BasePath i linje.

MiddlewarePath är en validerad konfiguration; den skapar inte en ASP.NET Core‑gren av sig själv.

5. Visarens konstruktion och livstid

Ta bort applikationsägda cachar av Viewer‑objekt. Det finns inget kvar i en Viewer som är värt att hålla på: den bär ingen dokumentstatus, och sessionscachen äger allt som överlever en begäran. Injicera den i en endpoint, Razor‑sida, controller eller en scoped applikationstjänst:

app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Den returnerade token identifierar en server‑sidig dokumentsession. Behandla den som ett bärar‑behörighet: logga inte den, spara den, eller placera den i analys.

6. Öppna och stänga dokument

Byt ut synkron OpenDocument(...) mot OpenDocumentAsync(...):

// Aktuell integration: Viewer kommer från DI och dokumentöppning är asynkron.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Aktuella överlagringar accepterar en filsökväg eller ström, en valfri formatkonfiguration, valfri DocOptions, och en avbokningstoken. Stäng server‑sessionen explicit när webbläsaren inte längre behöver den:

viewer.CloseDocument(token);

Ta bort alla InitCache()‑anrop och flaggan som skyddar dem — det finns inget att förvärma manuellt. Återanvänd inte en token som skapats av det tidigare biblioteket efter övergången: öppna varje dokument igen via det aktuella API‑et.

7. Webbfarm → distribuerad: den största förändringen

UseDoconutWebFarm och WebFarmOptions finns inte längre. Om din app anropar dem, är detta avsnitt din uppgradering; om den inte gör det, hoppa till §8.

Tidigare gjorde en middleware allt: den levererade förrenderade bilder från en delad mapp, och pollade medan en annan nod fortfarande skrev dem.

// Föregående integration — ett anrop, implicit samordning via filsystemet.
appBranch.UseDoconutWebFarm(new WebFarmOptions
{
    Path                = Path.Combine(env.WebRootPath, "webfarm"),
    PageWaitTimeSeconds = 180,
    StartWaitFromPage   = 5,
});

Samma arbete är nu delat i två explicita halvor. Skrivsida — noden som öppnar dokumentet publicerar hela artefaktsatsen (sidor, dokumentinformation, sökindex, metadata) till delningen:

var result = await _publisher.PublishAsync(          // DistributedDocumentPublisher, injicerad från DI
    pathToFile,
    new FileShareConfig
    {
        Location              = CloudLocation.FileShare,
        RootPath              = @"\\fileserver\doconut",   // samma mapp som du använder idag
        UsePerTokenSubfolders = true,
    },
    config,
    documentOptions,
    new DistributedDocumentPublishOptions
    {
        CleanUpStagingDirectory = true,
        FirstPagePriority       = true,
    });

return Content(result.Token);

Läsida — vilken nod som helst levererar från delningen:

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = /* SAME FileShareConfig som ovan */;
    }, "/"));

Din topologi förändras inte. Peka RootPath på samma UNC‑delning och varje nod fortsätter att fungera på samma sätt som idag. Det som förändras är att publicering är en operation du anropar, istället för en bieffekt av rendering.

Båda halvorna måste vara överens. Om RootPath eller UsePerTokenSubfolders skiljer sig mellan
publiceraren och hanteraren, svarar den andra noden med 404. Bygg konfigurationen i en hjälpfunktion
och anropa den från båda sidor.

PageWaitTimeSeconds = 180 betydde "blockera upp till tre minuter i hopp om att sidan visas". Ersättningen är explicit: med FirstPagePriority = true är sida 1 omedelbart serverbar och senare sidor svarar HTTP 202 Accepted tills de är skrivna. Den medföljande visaren försöker automatiskt igen när retryOn409 är satt. En klient som inte försöker igen kommer att visa trasiga rutor för sidor som fortfarande renderas.

Den fullständiga arrangemanget, inklusive bakgrundspublicering och åtkomstbiljetter, finns på Distribuerade distributioner.

8. Konvertering är ett plugin, och mycket mindre

Registrera pluginet, injicera sedan DocumentConverter-fasaden:

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

// Föregående integration
var converter = viewer.Converter.GetConverter();
var config    = new WordConfigConverter { TargetFormat = WordConfigConverter.EnTargetFormat.PDF };
var result    = converter.Convert(stream, SourceFormatConverter.DOCX, config);

// Aktuell integration
var result = await _converter.ConvertAsync(stream, ".docx", ConversionTarget.Pdf, null, ct);

Vad det ersätter:

• SourceFormatConverter — borta. Skicka filändelsen som en sträng, med punkt inkluderad.
• De per‑familj *ConfigConverter typerna (WordConfigConverter, ExcelConfigConverter, …), varje med en inbäddad EnTargetFormat enum — borta. Det finns nu en ConversionTarget enum för varje familj.
• viewer.Converter.GetConverter() — borta. Injicera Doconut.DocumentConverter.

ConvertAsync returnerar en sökbar ström, så return File(result, mime, name) fungerar direkt — den MemoryStream kopian av den gamla kod som behövdes är onödig. I den levererade exemplet raderade detta en 68‑faldig filändelse‑switch och tio nästan identiska kontroller.

Se Konverteringsplugin för hela funktionaliteten.

9. Molnleverantörer

UseDoconutCloud blev generisk. Leverantören är typargumentet istället för en Location‑värde som växlas på i middleware:

// Föregående integration
appBranch.UseDoconutCloud(new CloudOptions { Location = CloudLocation.CDN, ... });

// Aktuell integration
branch.UseDoconutCloud<CDNCloudHandler>(options =>
{
    options.Location          = CloudLocation.CDN;
    options.CloudUploadConfig = new CDNConfig { DoconutCdnUrl = "..." };
}, "/");

Konfigurationsklasserna är oförändrade förutom namnutrymmet (Doconut.Configs.Cloud → Doconut.Clouds): AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig, FTPConfig, samt den nya FileShareConfig. Handlers heter <Provider>CloudHandler.

CDN‑hanteraren är skrivskyddad — den levererar det som redan finns på CDN; den laddar inte upp.

10. Konfigurationsobjekt som bytte namn

DocOptions får också IsSecured.

Det nuvarande API:et separerar också ansvarsområden striktare än det tidigare, så kontrollera att varje inställning ligger på det objekt som nu äger den:

Bär inte vidare DocOptions.ImageResolution som renderingskontrollen. Den är föråldrad; sätt BaseConfig.ImageResolution på den format‑specifika konfigurationen. Granska alla standardinställningar istället för att anta att en tidigare konfiguration har samma beteende.

11. Klient‑sidans visare — två förändringar som misslyckas TYST

Båda dessa låter servern fungera perfekt. Ditt dokument renderas, sidan ser rätt ut, och inget visas i webbläsarens konsol. Läs detta avsnitt även om ditt C# kompilerar på första försöket.

Visar‑återuppringningar är nu alternativ, inte globala funktioner

Den tidigare visaren anropade dina hanterare efter namn, genom att härleda det globala funktionsnamnet från container‑id. Att deklarera function ctlDoc_OnViewerReady() på en sida med <div id="div_ctlDoc"> var tillräckligt. Den nuvarande visaren tar explicita återuppringningar i options‑objektet och letar inte längre efter dessa globala funktioner:

objctlDoc = $("#div_ctlDoc").docViewer({
    // ... dina befintliga alternativ ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // hittades med namn
    onViewerReady:    ctlDoc_OnViewerReady,     // hittades med namn
    onCopy:           ctlDoc_Copy,              // var ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // var ctlDoc_AutoLoadStatus(page)
});

Varför detta är besvärligt: det gamla anropet var inbäddat i en tom catch, som slukade allt. Nu kör dina funktioner helt enkelt aldrig och inget rapporterar ett fel. Det vanliga symptomet är en aktiv spinner som aldrig slutar — för att funktionen som gömde den var ctlDoc_OnViewerReady. Dokumentet bakom den är i ordning.

Den fullständiga alternativlistan är onPageLoading, onPageLoaded, onThumbnailClicked, onPageClicked, onDoubleClick, onViewerBusy, onViewerReady, onViewerError, onCopy, onAnnSaved, onAnnSaveError, onAnnLoaded, onAnnClosed, onAutoLoadStatus, onThumbsShown, och onError. Det finns ingen återuppringning för länkklick: hyperlänkshantering är inbyggd, driven av showHyperlinks.

ResPath måste peka på resursprefixet

ResPath: '',                      // FÖRE — resurser kom från applikationens rot
ResPath: 'doconut-res/images',    // NU    — prefixen UseDoconutResources() monterar

Om du ändrade prefixet via DoconutOptions.ResourcesPath, använd det värdet istället.

12. Visningsverktygsfält, sökning och annotation

Migrera inte de gamla skripten ett i taget. De nuvarande referensapplikationerna sammansätter ett komplett sidpaket:

1. sänd Viewer‑CSS och licensierad sök‑/annotations‑CSS med ReferenceCss;
2. rendera det applikationsägda Viewer‑verktygsfältet;
3. rendera searchBarMount, annBarMount och den erforderliga Viewer‑monteringen;
4. sänd Viewer‑ och licensierade modulscripter med ReferenceScripts;
5. läs in applikationens egna verktygsfältshjälpskript;
6. initiera en objViewer;
7. initiera de licensierade sök‑ och annotations‑ribbons;
8. anropa attach(objViewer) på varje Ribbon;
9. öppna dokumentet och anropa objViewer.View(token).

Sökning och annotation är moduler som är kopplade till samma Viewer, inte oberoende verktygsfält. Huvudverktygsfältet tillhör värdapplikationen; sök‑ och annotations‑ribbons är inbäddade, funktionsstyrda resurser.

Ta bort manuellt kopierade filer som documentLinks.js och docViewer.UI.js endast efter att den aktuella sidan fungerar med resurser som sänds av ReferenceCss och ReferenceScripts.

13. Plugin‑registrering

Statiska plugin‑licensmetoder registrerar inte aktuella plugins. Installera och registrera varje släppt paket explicit:

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() validerar registrerade plugin‑kapaciteter vid start. Converter och DICOM är de släppta .NET Standard‑plugins. Normal sökning och annotation är inbyggda licensierade funktioner, inte AddPlugin<TPlugin>()‑paket.

14. Session‑ och dokument‑säkerhet

Den nuvarande integrationen binder dokument till oklara token och cachade sessioner. Med standard‑UnsafeMode = false lägger UseDoconut() till dokumentåtkomst‑säkerhet och värden måste konfigurera ASP.NET‑session:

builder.Services.AddDistributedMemoryCache(); // sessiontillstånd behöver en cache (MVC/Razor Pages lägger redan till en)
builder.Services.AddSession();
app.UseSession();

Behåll DocOptions.IsSecured = true såvida inte en granskad design kräver annat. Använd aldrig UnsafeMode = true som en migrationsgenväg på en enskild nod. Testa förfrågningar utan token, med felaktig token, utgången token och en token från en annan webbläsarsession.

I en farm kan sidförfrågan hamna på en nod som aldrig såg den ursprungliga förfrågan, så per‑sessionskontrollen skulle avvisa den. Det är det enda fallet där UnsafeMode = true är korrekt — och den måste paras med signerade åtkomstbiljetter via AddDoconutDistributedDocumentSecurity, inte levereras ensam. Se Distribuerade distributioner.

Namnnotering

I alla ramverk är klassen Viewer. Om du hittar DocumentViewer i gamla kodsnuttar eller tredjepartsartiklar, har den typen aldrig funnits i SDK:n.

15. Föreslagen arbetsordning

1. Bekräfta att värdramverket kan konsumera netstandard2.1. Om det inte kan, stoppa.
2. Uppgradera paketet till 26.8.0 och bygg. Arbeta igenom kompileringsfelen — de flesta är using‑raderna i §1.
3. Flytta startupp till AddDoconut() och middleware‑anropen till deras nya ordning (§3, §4).
4. Injicera Viewer där du konstruerade det, gör OpenDocument asynkron och ta bort InitCache() (§5, §6).
5. Om du använder webb‑farmen, gör §7 — den enda delen som är en omdesign snarare än ett namnbyte.
6. Om du konverterar dokument, gör §8.
7. Gör §11 — klient‑sidans ändringar. De är de som inte kommer att meddela sig själva.
8. Öppna ett riktigt dokument i en webbläsare och observera den upptagna indikatorn. En grön byggnad bevisar inget här: licensiering, plugin‑registrering, resursvägen och viewer‑återuppringningarna misslyckas bara vid körning. För en farm, verifiera att ett dokument som publicerats av en nod levereras av en annan.

Testa migreringen

På minimum, verifiera:

• applikationsstart med produktionslicensen och alla registrerade plugins;
• Viewer CSS/skript och alla sid‑bildförfrågningar under de valda sökvägarna;
• dokumentöppning, navigering, zoom, miniatyrbilder, utskrift och explicit stängning;
• Sökning i ett textinnehållande dokument och det icke‑sökbara tillståndet för en enbart bildfil;
• Annotation laddning, sparning, export och funktionsstyrning;
• Konverterarens målupptäckt, utdata, nedladdning och vattenstämpelns tillstånd;
• DICOM‑sidor, ramar och animation; teknisk metadata är inte tillgänglig i detta paket;
• lösenordsskyddade dokument, anpassade typsnitt, icke‑latinsk text och konfigurerade tidsgränser;
• avvisning av token över sessioner och beteende vid utgången session;
• för en farm: publicera på en nod, begära en sen sida från en annan, och bekräfta att viewer försöker igen med 202 svar istället för att visa trasiga rutor;
• mobil, mörkt läge och produktions‑reverse‑proxy‑sökvägen.

Återställningsplan

Behåll det tidigare distributionsartefakten, matchande paket, licensfiler och kopierade webbläsarresurser tillsammans. En säker återställning byter hela applikationsgenerationen; den blandar inte en föregående generations server med aktuella skript, eller en aktuell server med new Viewer(...) anropsställen.

Innan övergången, dokumentera:

• distributionsslotten eller artefakten som används för återställning;
• påverkan på delat lagringsutrymme, om någon — artefakter publicerade av 26.8.0 konsumeras inte av den föregående webbfarmens middleware;
• hur aktiva dokumentsessioner kommer att ogiltigförklaras;
• hälsokontrollen och rökdokumentet som används för att besluta återställning;
• vem som kan återställa den tidigare paketuppsättningen och konfigurationen.

Äldre dokumentation

Den översatta tidigare manualen finns fortfarande tillgänglig på Legacy .NET Standard-setup. Föregående integrationsgateway förklarar samma identifieringssignaler och länkar tillbaka till den här migrationsguiden.

Behåll den historiska URL:en i bokmärken och supportärenden medan netstandard2.0‑installationer fortfarande finns. Den dokumenterar en annan generation och omdirigeras inte till det aktuella API:et.