Migrera från den klassiska .NET 6-integrationen

Doconut har två separata .NET 6-integrationer. De kan använda samma Doconut.NET6 paketnamn, så identifiera generationen från API:erna i applikationen innan du ändrar paket, start, 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 dokumenttoken genom resurser eller middleware från den andra generationen.

Varför NuGet-paketnamnet kanske inte berättar det för dig

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:n i sig. Registrera den exakta paketversionen och inspektera Program.cs, viewer‑konstruktion, dokumentöppning och webbläsarskript tillsammans.

Den aktuella versionen som granskats för den här guiden är Doconut.NET6 26.7.0. Dess valfria offentliga paket är Doconut.NET6.Converter och Doconut.NET6.Dicom, fastspända till samma versionsnummer som kärnpaketet.

Innan du migrerar

1. Skapa en gren och en distribuerbar backup av den befintliga applikationen.
2. Registrera de exakta kärn- och plugin‑paketversionerna.
3. Inventera varje DocImage.axd‑mappning, new Viewer(...)‑anrop, licensladdningsanrop, kopierat Doconut‑skript, anpassad verktygsfältshandling 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 produktion. Den aktuella integrationen ä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:t. Standardkommandot installerar den senaste stabila versionen:

dotnet add package Doconut.NET6

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.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 söker 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 startmekanism. Flytta licensen till DoconutOptions, håll tillhörande filer tillsammans 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ätt till en aktuell plugin‑byggnad. Testa Viewer, Sök, Annotering, Konverterare och DICOM separat med de godkända release‑artefakterna.

Start och beroendeinjektion

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

// Classic integration — contrast only; do not compile this against the current SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

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

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

// Classic integration — remove during the cutover.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

I den aktuella pipelinen:

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 synk;
4. när du mappar UseDoconut() till en gren, håll den grenen och klientens BasePath i synk.

MiddlewarePath är en validerad konfiguration; den skapar inte en ASP.NET Core‑gren av sig själv. Använd antingen den enkla pipelinen i kompileringsexemplet 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 dokument‑session. Behandla den som en bärartoken: logga den inte, lagra den inte och placera den inte i analysverktyg.

Öppna och stänga dokument

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

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
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

Den aktuella API:n 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 ett i taget. De aktuella referensapplikationerna sammansätter 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 vid samma Viewer, inte oberoende verktygsfält. Huvudverktygsfältet tillhör värdapplikationen; Search‑ och Annotation‑ribbons är inbäddade, kapacitetsstyrda 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 sökning och annotering ä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.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‑nod‑migration.

Testa migrationen

Minst bör du verifiera:

• applikationsstart med produktionslicensen och alla registrerade plugins;
• Viewer‑CSS/scripts och alla sid‑bild‑förfrågningar under de valda sökvägarna;
• dokumentöppning, navigation, 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;
• laddning, sparande, export och funktionstillgång för annotering;
• upptäckt, utdata, nedladdning och vattenstämpelstatus för Converter;
• 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 vid utgången session;
• mobil, mörkt läge och produktions‑reverse‑proxy‑sökväg.

Återställningsplan

Behåll det 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:

• distributionsslotten eller artefakten som används för återställning;
• databas‑/cache‑på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 tidigare 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 den aktuella API:n.