Migrare dall'integrazione classica .NET 6

Doconut ha due integrazioni .NET 6 distinte. Possono utilizzare lo stesso nome pacchetto Doconut.NET6, quindi è necessario identificare la generazione dalle API presenti 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 tutto

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

Il rilascio corrente auditato 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. Fai l'inventario di 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 versione.
5. Acquisisci un set rappresentativo di PDF, Office, immagini, CAD, email, DICOM, documenti ricercabili, protetti da password e annotati.
6. Registra il timeout di sessione corrente, il comportamento di sicurezza, i font e le impostazioni della piattaforma.

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

Compatibilità di pacchetti e licenze

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

dotnet add package Doconut.NET6

Per una migrazione riproducibile al rilascio auditato 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 corrente carica le licenze una sola volta durante AddDoconut(), usando questa precedenza:

LicenseStream > LicenseContent > LicensePath > scoperta automatica

La scoperta automatica cerca i file Doconut.Viewer.lic e i file companion Doconut.Viewer.<Capability>.lic. Una chiamata classica a Viewer.DoconutLicense(...) o Viewer.SetLicensePlugin(...) non è un meccanismo di avvio corrente. Sposta la licenza in DoconutOptions, conserva i file companion insieme quando usi la scoperta automatica, riavvia dopo aver modificato una licenza e verifica le capacità tramite IDoconutLicenseService.

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

Avvio e iniezione delle dipendenze

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

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

L'integrazione corrente 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 transitorio. Il gestore della sessione documento e la sua cache possiedono lo stato del documento a vita più lunga, non l'istanza Viewer iniettata specifica.

Middleware e routing delle risorse

Rimuovere 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()));

Nel pipeline corrente:

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

MiddlewarePath è una configurazione convalidata; non crea un ramo ASP.NET Core da solo. Utilizzare sia il semplice pipeline nell'esempio di compilazione sopra, sia una disposizione esplicita app.Map("/doconut", branch => branch.UseDoconut()) usata in modo coerente dal client.

Costruzione e durata di Viewer

Rimuovere le cache di proprietà dell'applicazione degli oggetti Viewer. Iniettare Viewer in un endpoint, pagina Razor, controller o servizio applicativo a portata limitata:

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. Trattarlo come credenziale di tipo bearer: non registrarlo, non conservarlo e non inserirlo in analisi.

Apertura e chiusura dei documenti

Sostituire 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 correnti accettano un percorso file o uno stream, una configurazione di formato opzionale, DocOptions opzionale e un token di cancellazione. Chiudere esplicitamente la sessione server quando il browser non ne ha più bisogno:

viewer.CloseDocument(token);

Non riutilizzare un token classico dopo la migrazione. Aprire nuovamente ogni documento tramite l'API corrente.

Classi di configurazione

L'API corrente separa le preoccupazioni:

Non trasportare DocOptions.ImageResolution come controllo di rendering. È obsoleta; impostare BaseConfig.ImageResolution nella configurazione specifica del formato. Rivedere tutti i valori predefiniti invece di presumere che una configurazione classica abbia lo stesso comportamento.

Barra degli strumenti Viewer, Ricerca e Annotazione

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

1. emettere CSS di Viewer e CSS con licenza per Ricerca/Annotazione con ReferenceCss;
2. renderizzare la barra degli strumenti Viewer di proprietà dell'applicazione;
3. renderizzare searchBarMount, annBarMount e il mount Viewer richiesto;
4. emettere script di Viewer e moduli con licenza con ReferenceScripts;
5. caricare il proprio viewerToolbar.js dell'applicazione;
6. inizializzare un objViewer;
7. inizializzare i Ribbon di Ricerca e Annotazione con licenza;
8. chiamare attach(objViewer) su ciascun Ribbon;
9. aprire il documento e chiamare objViewer.View(token).

Ricerca e Annotazione sono moduli collegati allo stesso Viewer, non barre degli strumenti indipendenti. La barra degli strumenti principale appartiene all'applicazione host; i Ribbon di Ricerca e Annotazione sono risorse incorporate, soggette a capacità.

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

Registrazione del plugin

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

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. Normal Search e Annotation sono funzionalità con licenza integrate, non pacchetti AddPlugin<TPlugin>().

Sicurezza della sessione e del documento

L'integrazione attuale associa i documenti a token opachi e sessioni memorizzate nella cache. Con il valore predefinito UnsafeMode = false, UseDoconut() aggiunge la sicurezza di accesso ai documenti 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 utilizzare mai UnsafeMode = true come scorciatoia di migrazione. Testa le richieste senza token, con token malformato, token scaduto e token proveniente da una sessione del browser diversa.

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

Test della migrazione

Come 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 del 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 dell'annotazione e controllo delle capacità;
• Scoperta del target del Converter, output, download e stato del watermark;
• Pagine DICOM, fotogrammi 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 della sessione scaduta;
• mobile, modalità scura e percorso del reverse-proxy di produzione.

Piano di rollback

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

Prima del taglio, documenta:

• lo slot di distribuzione o l'artefatto usato per il rollback;
• l'impatto sul 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 Legacy .NET 6 setup. Il nuovo Classic integration gateway 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 è reindirizzato all'API corrente.