Migrate from the classic .NET 6 integration

Doconut har två distinkta .NET 6‑integrationer. De kan använda samma paketnamn Doconut.NET6, så identifiera generationen från API‑erna i applikationen innan du ändrar paket, start‑up, licenser eller webbläsarresurser.

Vilken .NET 6‑integration använder du?

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

Varför NuGet‑paketnamnet kanske inte avslöjar detta

Båda generationerna har levererats under paket‑ID‑t Doconut.NET6. En paketreferens, låsfil eller cachad .nupkg identifierar därför inte värd‑API‑et i sig. Notera den exakta paketversionen och inspektera Program.cs, viewer‑konstruktion, dokumentöppning och webbläsarskript tillsammans.

Den aktuella utgåvan som granskats för den här guiden är Doconut.NET6 26.7.0. Dess valfria publika paket är Doconut.NET6.Converter och Doconut.NET6.Dicom, fastspända till samma utgåve‑version som kärnpaketet.

Innan du migrerar

1. Skapa en gren och en distribuerbar säkerhetskopia av den befintliga applikationen.
2. Notera de exakta versionerna för kärn‑ och plugin‑paketen.
3. Inventera varje DocImage.axd‑mappning, new Viewer(...)‑anrop, licens‑laddningsanrop, kopierat Doconut‑skript, anpassad verktygsfältsåtgärd och dokument‑öppnings‑endpoint.
4. Bevara de nuvarande .lic‑filerna och distributionshemligheterna utanför versionskontrollen.
5. Samla ett representativt urval av PDF‑, Office‑, bild‑, CAD‑, e‑post‑, DICOM‑, sökbara, lösenordsskyddade och annoterade dokument.
6. Notera den befintliga session‑timeouten, säkerhetsbeteendet, teckensnitten och plattformsinställningarna.

Migrera en miljö innan du ändrar produktion. Den aktuella integrationen förändrar tjänstelivslängd, begäranderouting, sessionsägarskap och leverans av klientresurser.

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 utgåvan:

dotnet add package Doconut.NET6

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

dotnet add package Doconut.NET6 --version 26.7.0

Behåll varje Doconut‑plugin på samma version som kärnpaketet. Den aktuella 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. Ett klassiskt anrop till Viewer.DoconutLicense(...) eller Viewer.SetLicensePlugin(...) är inte en aktuell start‑up‑mekanism. Flytta licensen till DoconutOptions, håll tillhörande filer tillsammans när du använder automatisk upptäckt, starta om efter att en licens ä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 utgivningsartefakterna.

Uppstart och beroendeinjektion

Klassiska applikationer konstruerar Viewer med ASP.NET-cache och request‑accessor‑beroenden:

// Klassisk integration — endast för jämförelse; kompilera inte detta mot den aktuella SDK:n.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

Den aktuella integrationen registrerar Doconut en gång och får Viewer från beroendeinjektion:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
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.

Middleware och resursroutning

Ta bort den klassiska MapWhen‑grenen som upptäcker DocImage.axd:

// Klassisk integration — ta bort under övergången.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

I den aktuella pipeline:n:

1. anropa UseSession() före Doconut medan sessionssäkerhet är aktiverad;
2. anropa UseDoconutResources() före UseDoconut();
3. behåll ResourcesPath, de genererade resurs‑URL:erna och klientens ResPath i synk;
4. vid mappning av UseDoconut() till en gren, håll den grenen och klientens BasePath i synk.

MiddlewarePath är validerad konfiguration; den skapar inte en ASP.NET Core‑gren av sig själv. Använd antingen den enkla pipeline:n i kodexemplet ovan eller en explicit app.Map("/doconut", branch => branch.UseDoconut())‑arrangemang som används konsekvent av klienten.

Viewer‑konstruktion och livstid

Ta bort applikationsägda cachar av Viewer‑objekt. Injicera Viewer 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 en bärartoken: logga den inte, lagra den inte och placera den inte i analys.

Öppna och stänga dokument

Ersätt synkron OpenDocument(...) med OpenDocumentAsync(...):

// Aktuell .NET 6-integration: Viewer hämtas via 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);

Återanvänd inte en klassisk token efter övergången. Öppna varje dokument igen via det aktuella API‑et.

Konfigurationsklasser

Det aktuella API:t separerar ansvarsområden:

Flytta inte DocOptions.ImageResolution vidare 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 klassisk konfiguration har samma beteende.

Viewer‑verktygsfält, sökning och annotation

Migrera inte de gamla skripten en efter en. De aktuella referensapplikationerna bygger ett komplett sidpaket:

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

Search och Annotation är moduler som är fästa på samma Viewer, inte oberoende verktygsfält. Huvudverktygsfältet tillhör värdapplikationen; Search‑ och Annotation‑ribbons är inbäddade, funktionsstyrda resurser.

Ta bort manuellt kopierade klassiska filer såsom documentLinks.js och docViewer.UI.js först när den aktuella sidan fungerar med resurser som genereras av ReferenceCss och ReferenceScripts.

Pluginregistrering

Klassiska 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 start. Converter och DICOM är släppta .NET 6‑plugins. Normal Search och Annotation är inbyggda licensierade funktioner, inte AddPlugin<TPlugin>()‑paket.

Session- och dokumentssäkerhet

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

builder.Services.AddDistributedMemoryCache(); // sessionsstatus 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. Testa förfrågningar utan token, med en felaktig token, en utgången token och en token från en annan webbläsarsession.

Den distribuerade referensapplikationen lägger till åtkomstbiljetter och transportdetaljer. Dessa API:er krävs inte för en normal en‑nodsmigration.

Testa migrationen

Som 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, miniatyrer, utskrift och explicit stängning;
• Sökning i ett textbärande dokument och det icke‑sökbara tillståndet för en enbart bildfil;
• Annotation laddning, sparning, export och funktionsstyrning;
• Converter‑målsökning, utdata, nedladdning och vattenstämpelstatus;
• DICOM‑sidor, ramar och animation; .NET 6 teknisk metadata är otillgänglig;
• lösenordsskyddade dokument, anpassade typsnitt, icke‑latinsk text och konfigurerade tidsgränser;
• avslag av token över sessioner och beteende för utgångna sessioner;
• mobil, mörkt läge och produktions‑reverse‑proxy‑sökvägen.

Återställningsplan

Behåll den klassiska distributionsartefakten, matchande paket, licensfiler och kopierade webbläsarresurser tillsammans. En säker återställning byter hela applikationsgenerationen; den blandar inte en klassisk server med aktuella skript eller en aktuell server med klassiska DocImage.axd‑anrop.

Innan övergången, dokumentera:

• distributionsslotet eller artefakten som används för återställning;
• databas-/cachepåverkan, om någon;
• hur aktiva dokumentsessioner kommer att ogiltigförklaras;
• hälsokontrollen och testdokumentet som används för att besluta återställning;
• vem som kan återställa den föregående paketuppsättningen och konfigurationen.

Äldre dokumentation

Den översatta klassiska manualen finns fortfarande tillgänglig på Legacy .NET 6‑installation. Den nya Klassisk 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 klassiska installationer fortfarande finns. Den dokumenterar en annan generation och omdirigeras inte till det aktuella API:et.