Migrera till .NET Standard 2.1

Doconut har två distinkta .NET Standard-integrationer. De använder samma paketnamn Doconut.NETStandard, så identifiera generationen utifrån versionen och API:erna i applikationen innan du ändrar paket, start‑up, 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‑ytstruktur. Förvänta dig kompileringsfel efter uppgraderingen; 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, betraktas migrationen som ofullständig. Skicka inte en dokumenttoken genom resurser eller middleware från den andra generationen.

Kontrollera värdplattformen 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 paketet Doconut.NETFramework istället; från 26.9.0 kräver det .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 versionerna av kärn‑ och pluginpaketen.
3. Inventera varje new Viewer(...)‑anrop, InitCache()‑anrop, licensladdningsanrop, UseDoconutWebFarm‑mappning, konverteringskontroller, kopierat Doconut‑skript, anpassad verktygsfältshandling, viewer‑återuppringning och dokumentöppnings‑endpoint.
4. Bevara de nuvarande .lic‑filerna och distributionshemligheterna 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 sessionstimeouten, säkerhetsbeteendet, typsnitten och plattformsinställningarna.

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

1. Namnrymder: nästan allt flyttat till roten

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

Typnamnen har inte ändrats: 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 betraktas 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:t. 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 nuvarande integrationen laddar licenser en gång under AddDoconut(), med följande prioritet:

LicenseStream > LicenseContent > LicensePath > automatic discovery

Automatisk upptäckt letar 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 startmekanism, och inte heller är List<string> med licensvägar som den gamla Viewer‑konstruktorn accepterade. Flytta licensen till DoconutOptions, håll de tillhörande filerna tillsammans när du använder automatisk upptäckt, starta om efter att licensen har ändrats och verifiera funktioner via IDoconutLicenseService.

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

3. Start och beroendeinjektion

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

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

Den nuvarande integrationen registrerar Doconut en gång och får Viewer via beroendeinjektion:

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

app.UseSession();
app.UseDoconutResources();   // INNAN grenen
app.UseDoconut();

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

Tre saker att ta med:

• 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 manuell trådning app.UseMiddleware<EmbeddedResourceMiddleware>(), och måste köras innan dokumentgrenen.
• UnSafeMode → UnsafeMode. En en‑tecken‑omdöpning som kompilatorn kommer att fånga.

När UnsafeMode är false validerar SDK:n sessionstoken mot den ursprungliga begäran, så AddSession() / UseSession() måste fortfarande finnas i pipeline:n, UseSession() innan grenen.

Metoder som inte längre finns

4. Middleware och resursrouting

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

app.UseDoconutResources();   // INNAN grenen

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

I den aktuella pipeline:n:

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

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

5. Viewer‑konstruktion och livstid

Ta bort applikationsägda cache‑instanser 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 lever längre än 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‑credential: logga den inte, persist den inte, 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 anrop till InitCache() och flaggan som skyddar den — det finns inget att värma upp 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. Web farm → distributed: den största förändringen

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

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

// Tidigare 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 uppdelat i två explicita halvor. Skrivsida — noden som öppnar dokumentet publicerar hela artefaktsättet (sidor, dokumentinformation, sökindex, metadata) till delningen:

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

return Content(result.Token);

Läsida — vilken nod som helst serverar 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 = /* samma 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 innebar "blockera i upp till tre minuter i hopp om att sidan dyker upp". Ersättningen är explicit: med FirstPagePriority = true är sida 1 serverbar omedelbart och senare sidor svarar med HTTP 202 Accepted tills de är skrivna. Den inbyggda viewern 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 och 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 — borttagen. Skicka filändelsen som en sträng, med punkt inkluderad.
• De per‑familj *ConfigConverter‑typerna (WordConfigConverter, ExcelConfigConverter, …), var och en med en inbäddad EnTargetFormat‑enum — borttagen. Det finns nu en ConversionTarget‑enum för varje familj.
• viewer.Converter.GetConverter() — borttagen. Injicera Doconut.DocumentConverter.

ConvertAsync returnerar en sökbar ström, så return File(result, mime, name) fungerar direkt — kopian av MemoryStream som den gamla koden behövde är onödig. I det medföljande exemplet raderades en 68‑falls filändelse‑switch och tio nästan identiska kontroller.

Se Konverteringsplugin för hela ytan.

9. Molnleverantörer

UseDoconutCloud blev generisk. Leverantören är typargumentet istället för ett Location‑värde som växlades 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 namnrymden (Doconut.Configs.Cloud → Doconut.Clouds): AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig, FTPConfig, samt den nya FileShareConfig. Handlare heter <Provider>CloudHandler.

CDN‑handlaren ä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 aktuella API:et separerar också ansvarsområden mer strikt än det tidigare, så kontrollera att varje inställning finns på det objekt som nu äger den:

Flytta inte vidare DocOptions.ImageResolution som renderingskontroll. Den är föråldrad; sätt BaseConfig.ImageResolution på den format‑specifika konfigurationen. Granska alla standardvärden 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 felfritt. Ditt dokument renderas, sidan ser rätt ut, och inget visas i webbläsarens konsol. Läs detta avsnitt även om din C# kompileras 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:t. 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({
    // ... your existing options ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // was found by name
    onViewerReady:    ctlDoc_OnViewerReady,     // was found by name
    onCopy:           ctlDoc_Copy,              // was ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // was ctlDoc_AutoLoadStatus(page)
});

Varför detta är besvärligt: det gamla anropet var omslutet av en tom catch, som sväljde allt. Nu körs dina funktioner helt enkelt aldrig och inget rapporterar ett fel. Det vanliga symptomet är en roterande indikator som aldrig slutar — eftersom 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: hantering av hyperlänkar är inbyggd, driven av showHyperlinks.

ResPath måste peka på resurs‑prefixet

ResPath: '',                      // FÖRE — resurser kom från applikationsroten
ResPath: 'doconut-res/images',    // NU    — prefixet UseDoconutResources() monteras

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

12. Viewer‑verktygsfält, sökning och annotering

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

1. skicka Viewer‑CSS och licensierad sök‑/annoterings‑CSS med ReferenceCss;
2. rendera det applikationsägda Viewer‑verktygsfältet;
3. rendera searchBarMount, annBarMount och den nödvändiga Viewer‑montern;
4. skicka Viewer‑ och licensierade modulscripter med ReferenceScripts;
5. ladda applikationens egna verktygsfältshjälpskript;
6. initiera ett objViewer;
7. initiera de licensierade sök‑ och annoterings‑ribbons;
8. anropa attach(objViewer) på varje Ribbon;
9. öppna dokumentet och anropa objViewer.View(token).

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

Ta bort manuellt kopierade filer som documentLinks.js och docViewer.UI.js först när den aktuella sidan fungerar med resurser som skickas 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‑funktioner vid uppstart. Converter och DICOM är de släppta .NET Standard‑plugins. Normal sökning och annotering är inbyggda licensierade funktioner, inte AddPlugin<TPlugin>()‑paket.

14. Session‑ och dokument‑säkerhet

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

builder.Services.AddDistributedMemoryCache(); // sessionstillståndet 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 en felaktig token, en 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‑session‑kontrollen skulle avvisa den. Det är det enda fallet där UnsafeMode = true är korrekt — och det måste kombineras med signerade åtkomstbiljetter via AddDoconutDistributedDocumentSecurity, inte levereras ensamt. 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 webbfarmen, 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 förä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 ingenting här: licensiering, plugin‑registrering, resurs‑sökvägen och viewer‑återuppringningar misslyckas bara vid körning. För en farm, verifiera att ett dokument som publicerats av en nod serveras av en annan.

Testa migreringen

På minsta nivå, verifiera:

• applikationsstart med produktionslicensen och alla registrerade tillägg;
• Viewer CSS/skript och alla sid‑bildförfrågningar under de valda sökvägarna;
• dokumentöppning, navigering, zoom, miniatyrer, 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 funktionsbegränsning;
• Konverterarens målupptäckt, utdata, nedladdning och vattenstämmningsstatus;
• 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;
• avslag av token över sessioner och beteende vid utgången session;
• för en farm: publicera på en nod, begär en sen sida från en annan, och bekräfta att visaren försöker igen på 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 den tidigare distributionsartefakten, matchande paket, licensfiler och kopierade webbläsarresurser tillsammans. En säker återställning byter hela applikationsgenerationen; den blandar inte en tidigare generationens 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 tidigare webb‑farmens 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å Äldre .NET Standard-setup. Föregående integrationsgateway förklarar samma identifieringssignaler och länkar tillbaka till denna migrationsguide.

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.