Migrare dall'integrazione classica .NET 6

Doconut ha due integrazioni .NET 6 distinte. Possono utilizzare lo stesso nome di pacchetto Doconut.NET6, quindi identifica la generazione dalle API nell'applicazione prima di modificare pacchetti, avvio, licenze o risorse del browser.

Quale integrazione .NET 6 stai usando?

Se entrambe le colonne compaiono nella stessa applicazione, considera la migrazione incompleta. Non inviare un token documento attraverso risorse o middleware della generazione opposta.

Perché il nome del pacchetto NuGet potrebbe non dirti

Entrambe le generazioni sono state distribuite sotto l'ID pacchetto Doconut.NET6. Un riferimento al pacchetto, un file di lock o un .nupkg memorizzato quindi non identificano l'API di hosting da solo. Registra la versione esatta del pacchetto e ispeziona Program.cs, la costruzione del viewer, l'apertura del documento e gli script del browser insieme.

L'attuale release auditata per questa guida è Doconut.NET6 26.7.0. I suoi pacchetti pubblici opzionali sono Doconut.NET6.Converter e Doconut.NET6.Dicom, bloccati alla stessa versione di rilascio del pacchetto core.

Prima di migrare

1. Crea un branch e un backup distribuibile dell'applicazione esistente.
2. Registra le versioni esatte dei pacchetti core e dei plugin.
3. Inventaria ogni mapping DocImage.axd, chiamata new Viewer(...), chiamata di caricamento licenza, script Doconut copiato, azione della barra degli strumenti personalizzata e endpoint di apertura documento.
4. Conserva i file .lic attuali e i segreti di distribuzione al di fuori del controllo sorgente.
5. Acquisisci un set rappresentativo di PDF, Office, immagini, CAD, email, DICOM, documenti ricercabili, protetti da password e annotati.
6. Registra il timeout della sessione esistente, il comportamento di sicurezza, i font e le impostazioni della piattaforma.

Migra un ambiente prima di modificare la produzione. L'integrazione attuale cambia la durata del servizio, il routing delle richieste, la proprietà della sessione e la consegna delle risorse client.

Compatibilità dei pacchetti e delle licenze

Sostituisci o aggiorna deliberatamente il pacchetto core; non fare affidamento sull'ID pacchetto identico per selezionare la nuova API. Il comando predefinito installa l'ultima release stabile:

dotnet add package Doconut.NET6

Per una migrazione riproducibile alla release auditata da questa guida, passa la versione come opzione separata:

dotnet add package Doconut.NET6 --version 26.7.0

Mantieni ogni plugin Doconut alla stessa versione del pacchetto core. L'integrazione attuale carica le licenze una sola volta durante AddDoconut(), usando questa precedenza:

LicenseStream > LicenseContent > LicensePath > automatic discovery

Il rilevamento automatico cerca i file Doconut.Viewer.lic e i file compagni Doconut.Viewer.<Capability>.lic. Una chiamata classica a Viewer.DoconutLicense(...) o Viewer.SetLicensePlugin(...) non è un meccanismo di avvio attuale. Sposta la licenza in DoconutOptions, mantieni i file compagni insieme quando usi il rilevamento automatico, riavvia dopo aver cambiato una licenza e verifica le capacità tramite IDoconutLicenseService.

Non presumere che la presenza di una vecchia licenza plugin provi il diritto a una build plugin attuale. Testa Viewer, Search, Annotation, Converter e DICOM separatamente con gli artefatti di release approvati.

Avvio e iniezione delle dipendenze

Le applicazioni classiche costruiscono Viewer con dipendenze di cache ASP.NET e request‑accessor:

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

L'integrazione attuale registra Doconut una sola volta e riceve Viewer dall'iniezione delle dipendenze:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

Viewer è un servizio transiente. Il gestore della sessione documento e la sua cache possiedono lo stato documento a vita più lunga, non l'istanza Viewer iniettata specifica.

Middleware e routing delle risorse

Rimuovi il ramo classico MapWhen che rileva DocImage.axd:

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

Nella pipeline attuale:

1. chiama UseSession() prima di Doconut mentre la sicurezza della sessione è abilitata;
2. chiama UseDoconutResources() prima di UseDoconut();
3. mantieni ResourcesPath, gli URL delle risorse generate e ResPath client allineati;
4. quando mappi UseDoconut() a un ramo, mantieni quel ramo e BasePath client allineati.

MiddlewarePath è una configurazione validata; non crea un ramo ASP.NET Core da solo. Usa la pipeline semplice nel campione di compilazione sopra o un arrangiamento esplicito app.Map("/doconut", branch => branch.UseDoconut()) usato costantemente dal client.

Costruzione e durata del Viewer

Rimuovi le cache di proprietà dell'applicazione degli oggetti Viewer. Inietta Viewer in un endpoint, pagina Razor, controller o servizio applicativo con ambito:

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

Il token restituito identifica una sessione documento lato server. Trattalo come credenziale di tipo bearer: non registrarlo, non persisterlo e non inserirlo in analytics.

Apertura e chiusura dei documenti

Sostituisci OpenDocument(...) sincrono con OpenDocumentAsync(...):

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Le overload attuali accettano un percorso file o stream, una configurazione di formato opzionale, DocOptions opzionali e un token di cancellazione. Chiudi esplicitamente la sessione server quando il browser non ne ha più bisogno:

viewer.CloseDocument(token);

Non riutilizzare un token classico dopo il cutover. Apri nuovamente ogni documento tramite l'API attuale.

Classi di configurazione

L'API attuale separa le preoccupazioni:

Non trasferire DocOptions.ImageResolution come controllo di rendering. È obsoleta; imposta BaseConfig.ImageResolution sulla configurazione specifica del formato. Rivedi tutti i valori predefiniti invece di presumere che una configurazione classica abbia lo stesso comportamento.

Barra degli strumenti del Viewer, Ricerca e Annotazione

Non migrare gli script vecchi uno per uno. Le applicazioni di riferimento attuali compongono un pacchetto pagina completo:

1. emetti CSS del Viewer e CSS licenziati di Search/Annotation con ReferenceCss;
2. rendi la barra degli strumenti del Viewer di proprietà dell'applicazione;
3. rendi searchBarMount, annBarMount e il mount del Viewer richiesto;
4. emetti script del Viewer e dei moduli licenziati con ReferenceScripts;
5. carica il proprio viewerToolbar.js dell'applicazione;
6. inizializza un objViewer;
7. inizializza i Ribbon licenziati di Search e Annotation;
8. chiama attach(objViewer) su ogni Ribbon;
9. apri il documento e chiama objViewer.View(token).

Search e Annotation sono moduli collegati allo stesso Viewer, non barre degli strumenti indipendenti. La barra principale appartiene all'applicazione host; i Ribbon di Search e Annotation sono risorse incorporate, con gating di capacità.

Rimuovi i file classici copiati manualmente come documentLinks.js e docViewer.UI.js solo dopo che la pagina attuale funziona con le risorse emesse da ReferenceCss e ReferenceScripts.

Registrazione dei plugin

I metodi statici classici di licenza plugin non registrano i plugin attuali. Installa e registra ogni pacchetto rilasciato esplicitamente:

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() valida le capacità dei plugin registrati all'avvio. Converter e DICOM sono plugin .NET 6 rilasciati. Search e Annotation normali sono funzionalità licenziate integrate, non pacchetti AddPlugin<TPlugin>().

Sicurezza della sessione e del documento

L'integrazione attuale lega i documenti a token opachi e sessioni cache. Con UnsafeMode = false predefinito, UseDoconut() aggiunge la sicurezza di accesso al documento e l'host deve configurare la sessione ASP.NET:

builder.Services.AddSession();
app.UseSession();

Mantieni DocOptions.IsSecured = true a meno che un progetto revisionato non richieda diversamente. Non usare mai UnsafeMode = true come scorciatoia di migrazione. Testa le richieste senza token, con token malformato, token scaduto e token da una sessione browser diversa.

L'applicazione di riferimento Distributed aggiunge ticket di accesso e dettagli di trasporto. Quelle API non sono richieste per una migrazione normale a nodo singolo.

Testare la migrazione

Al minimo, verifica:

• avvio dell'applicazione con la licenza di produzione e tutti i plugin registrati;
• CSS/script del Viewer e tutte le richieste di immagini di pagina nei percorsi scelti;
• apertura documento, navigazione, zoom, miniature, stampa e chiusura esplicita;
• ricerca su un documento con testo e lo stato non ricercabile di un file solo immagine;
• caricamento, salvataggio, esportazione e gating di capacità dell'annotazione;
• scoperta del target del Converter, output, download e stato del watermark;
• pagine DICOM, frame e animazione; i metadati tecnici .NET 6 non sono disponibili;
• documenti protetti da password, font personalizzati, testo non latino e timeout configurati;
• rifiuto del token tra sessioni e comportamento di sessione scaduta;
• mobile, modalità scura e percorso del reverse‑proxy di produzione.

Piano di rollback

Conserva l'artefatto di distribuzione classico, i pacchetti corrispondenti, i file di licenza e le risorse browser copiate insieme. Un rollback sicuro commuta l'intera generazione dell'applicazione; non mescola un server classico con script attuali né un server attuale con chiamate classiche DocImage.axd.

Prima del cutover, documenta:

• lo slot di distribuzione o l'artefatto usato per il rollback;
• l'impatto su database/cache, se presente;
• come le sessioni documento attive saranno invalidate;
• il controllo di salute e il documento di prova usati per decidere il rollback;
• chi può ripristinare il set di pacchetti e la configurazione precedenti.

Documentazione legacy

Il manuale classico tradotto rimane disponibile su Configurazione Legacy .NET 6. Il nuovo Gateway di integrazione classica spiega gli stessi segnali di identificazione e rimanda a questa guida di migrazione.

Mantieni l'URL storico nei segnalibri e nei ticket di supporto finché le installazioni classiche esistono. Documenta una generazione diversa e non viene reindirizzato all'API attuale.