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 beroendeinjektionAktuell 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

  1. Skapa en gren och en distribuerbar backup av den befintliga applikationen.
  2. Registrera de exakta kärn‑ och pluginpaketversionerna.
  3. Inventera varje DocImage.axd‑mappning, new Viewer(...)‑anrop, licensladdningsanrop, kopierat Doconut‑skript, anpassad verktygsfältsåtgärd 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 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:

bash
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:

bash
dotnet add package Doconut.NET6 --version 26.9.0

Behåll varje Doconut‑plugin på samma version som kärnpaketet. Den aktuella integrationen laddar licenser en gång under AddDoconut(), med denna prioritet:

text
LicenseStream > LicenseContent > LicensePath > automatic discovery

Automatisk 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:

csharp
// 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:

csharp
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:

csharp
// 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:

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

csharp
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(...):

csharp
// 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:

csharp
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:

ConcernCurrent type
Middleware‑vägar, licensiering, plugin‑registreringDoconutOptions
Lösenord, timeout, säkerhet, vattenstämpelDocOptions
Formatrendering och DPIPdfConfig, WordConfig, ExcelConfig, och andra BaseConfig‑typer
Standardinställningar för webbläsar‑widgetViewerConfig eller motsvarande JavaScript‑alternativ
Genererad CSS och skriptCssConfig 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:

  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 erforderliga Viewer‑monteringen;
  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 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:

csharp
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:

csharp
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?