Migrera från den klassiska .NET 6-integrationen

Doconut har två separata .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, licenser eller webbläsarresurser.

Vilken .NET 6-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.

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:t i sig. Notera 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, låsta till samma versionsnummer som kärnpaketet.

Innan du migrerar

1. Skapa en gren och en distribuerbar backup av den befintliga applikationen.
2. Notera de exakta versionerna för kärn- och pluginpaketen.
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 distributionshemligheter 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. Notera 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 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 migration 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 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 startmekanism. Flytta licensen till DoconutOptions, håll tillhörande filer tillsammans när du använder automatisk upptäckt, starta om efter att licensen ä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.

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 resursrouting

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 pipeline:n:

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

MiddlewarePath är validerad konfiguration; den skapar inte en ASP.NET Core-gren i sig. Använd antingen den enkla pipeline:n i det kompilerande exemplet ovan eller en explicit app.Map("/doconut", branch => branch.UseDoconut())-uppsättning 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 scoped applikationstjänst:

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

Det returnerade tokenet identifierar en server‑sidig dokumentsession. Behandla det som ett bärartoken: logga det inte, lagra det inte och placera det inte i analyser.

Öppna och stänga dokument

Byt ut synkron OpenDocument(...) mot 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 ett avbokningstoken. Stäng server‑sessionen explicit när webbläsaren inte längre behöver den:

viewer.CloseDocument(token);

Återanvänd inte ett klassiskt token efter övergången. Öppna varje dokument igen via det aktuella API:t.

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, Search 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 en 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, funktionsstyrda resurser.

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

Plugin‑registrering

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. Vanlig Search och Annotation är inbyggda licensierade funktioner, inte AddPlugin<TPlugin>()‑paket.

Session‑ och dokument­säkerhet

Den aktuella 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.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 felaktigt token, med utgånget token och med 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

Verifiera åtminstone:

• applikationsstart med produktionslicensen och alla registrerade plugins;
• Viewer‑CSS/skript och alla sid‑bild‑förfrågningar under de valda vägarna;
• dokumentöppning, navigation, zoom, miniatyrer, utskrift och explicit stängning;
• Search på ett textbärande dokument och det icke‑sökbara tillståndet för en enbart bildfil;
• Annotation‑laddning, sparande, export och funktionsstyrning;
• Converter‑målupptäckt, output, nedladdning och vattenstämplingstillstånd;
• DICOM‑sidor, ramar och animation; .NET 6‑teknisk metadata är ej tillgänglig;
• lösenordsskyddade dokument, anpassade typsnitt, icke‑latinsk text och konfigurerade timeouts;
• avslag av token över sessioner och beteende vid utgången session;
• mobil, mörkt läge och produktions‑reverse‑proxy‑väg.

Å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‑/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 setup. Den nya Classic integration gateway 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:t.