Migrera från den klassiska .NET 6-integrationen
Flytta en befintlig Doconut.NET6-applikation till den aktuella DI- och async-API:n
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 projektet innehåller… | Generation |
|---|---|
app.MapWhen(... "DocImage.axd" ...) | Äldre / klassisk |
new Viewer(_cache, _accessor, ...) | Äldre / klassisk |
Viewer.DoconutLicense(...) eller Viewer.SetLicensePlugin(...) | Äldre / klassisk |
Manuellt kopierade docViewer.js, documentLinks.js eller docViewer.UI.js | Äldre / klassisk |
builder.Services.AddDoconut(...) | Aktuell integration |
app.UseDoconutResources() plus app.UseDoconut() | Aktuell integration |
Viewer levereras via beroendeinjektion | Aktuell integration |
await viewer.OpenDocumentAsync(...) | Aktuell integration |
Om båda kolumnerna förekommer i samma applikation, behandla migreringen som ofullständig. Skicka inte en 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 Doconut.NET6 paket-ID. En paketreferens, låsfil eller cachad .nupkg identifierar därför inte värd-API:t 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, låsta till samma releasedatum som kärnpaketet.
Innan du migrerar
- Skapa en gren och en distribuerbar backup av den befintliga applikationen.
- Registrera de exakta kärn‑ och pluginpaketversionerna.
- Inventera varje
DocImage.axd‑mappning,new Viewer(...)‑anrop, licensladdningsanrop, kopierat Doconut‑skript, anpassad verktygsfältsåtgärd och dokumentöppnings‑endpoint. - Bevara de nuvarande
.lic‑filerna och distributionshemligheterna utanför källkontrollen. - Fånga ett representativt urval av PDF‑, Office‑, bild‑, CAD‑, e‑post‑, DICOM‑, sökbara, lösenordsskyddade och annoterade dokument.
- Registrera den befintliga sessionstidsgränsen, säkerhetsbeteendet, typsnitten och plattformsinställningarna.
Migrera en miljö innan du ändrar produktion. Den aktuella integrationen ändrar tjänstelivslängd, begäranserouting, 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.NET6Fö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.9.0Behåll varje Doconut‑plugin på samma version som kärnpaketet. Den aktuella integrationen laddar licenser en gång under AddDoconut(), med denna prioritet:
LicenseStream > LicenseContent > LicensePath > automatic discoveryAutomatisk upptäckt söker efter Doconut.Viewer.lic och medföljande 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 medföljande 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, Search, Annotation, Converter och DICOM separat med de godkända release‑artefakterna.
Uppstart och beroendeinjektion
Klassiska applikationer konstruerar Viewer med ASP.NET-cache och request‑accessor‑beroenden:
// Klassisk integration — endast kontrast; kompilera inte detta mot den aktuella SDK:n.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);Den aktuella integrationen registrerar Doconut en gång och mottar Viewer via beroendeinjicering:
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 resursrouting
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 pipelinen:
- anropa
UseSession()före Doconut medan sessionsäkerhet är aktiverad; - anropa
UseDoconutResources()föreUseDoconut(); - håll
ResourcesPath, de genererade resurs‑URL:erna och klient‑ResPathi linje; - när du mappar
UseDoconut()till en gren, håll den grenen och klient‑BasePathi linje.
MiddlewarePath är validerad konfiguration; den skapar inte en ASP.NET Core‑gren på egen hand. Använd antingen den enkla pipelinen i det kompilerade exemplet 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 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ärarbehörighet: logga den inte, spara den inte eller placera den i analys.
Öppna och stänga dokument
Ersätt synkron OpenDocument(...) med OpenDocumentAsync(...):
// Aktuell .NET 6-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);Återanvänd inte en klassisk token efter övergången. Öppna varje dokument igen via den aktuella API:n.
Konfigurationsklasser
Den aktuella API:n separerar ansvarsområden:
| Concern | Current type |
|---|---|
| Middleware‑vägar, licensiering, plugin‑registrering | DoconutOptions |
| Lösenord, timeout, säkerhet, vattenstämpel | DocOptions |
| Formatrendering och DPI | PdfConfig, WordConfig, ExcelConfig, och andra BaseConfig‑typer |
| Standardinställningar för webbläsar‑widget | ViewerConfig eller motsvarande JavaScript‑alternativ |
| Genererad CSS och skript | CssConfig och ScriptConfig |
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 klassisk konfiguration har samma beteende.
Viewer‑verktygsfält, sökning och annotation
Migrera inte de gamla skripten en efter en. De aktuella referensapplikationerna sammansätter ett komplett sidpaket:
- generera Viewer‑CSS och licensierad Search/Annotation‑CSS med
ReferenceCss; - rendera det applikationsägda Viewer‑verktygsfältet;
- rendera
searchBarMount,annBarMountoch den erforderliga Viewer‑monteringen; - generera Viewer‑ och licensierade modulscripter med
ReferenceScripts; - ladda applikationens egna
viewerToolbar.js; - initiera en
objViewer; - initiera de licensierade Search‑ och Annotation‑ribbons;
- anropa
attach(objViewer)på varje Ribbon; - ö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 såsom documentLinks.js och docViewer.UI.js endast efter att 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 standard UnsafeMode = false, lägger UseDoconut() till dokumentåtkomstsäkerhet och värden måste konfigurera ASP.NET‑session:
builder.Services.AddDistributedMemoryCache(); // session state behöver en cache (MVC/Razor Pages lägger redan till en)
builder.Services.AddSession();
app.UseSession();Behåll DocOptions.IsSecured = true om en granskad design inte 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 migreringen
Verifiera minst:
- applikationsstart med produktionslicensen och varje registrerad plugin;
- Viewer‑CSS/scripts och alla sid‑bild‑fö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, sparande, export och funktionsstyrning;
- Converter‑målupptäckt, utdata, nedladdning och vattenstämmningsstatus;
- 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ången session;
- mobil, mörkt läge och produktions‑reverse‑proxy‑sökvä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:
- den distributionsplats eller artefakt 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å Äldre .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.
Var den här sidan hjälpsam?