Migra 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 utilizzando?

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 indicarti

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

La versione corrente verificata per questa guida è Doconut.NET6 26.7.0. I suoi pacchetti pubblici opzionali sono Doconut.NET6.Converter e Doconut.NET6.Dicom, vincolati 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 del pacchetto 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 documenti PDF, Office, immagine, CAD, email, DICOM, ricercabili, protetti da password e annotati.
6. Registra il timeout di sessione esistente, 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 alla versione verificata 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 volta durante AddDoconut(), usando questa precedenza:

LicenseStream > LicenseContent > LicensePath > automatic discovery

Il rilevamento automatico 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, mantieni i file companion 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 licenza plugin vecchia dimostri il diritto per una build plugin corrente. Testa Viewer, Search, Annotation, Converter e DICOM separatamente con gli artefatti di rilascio approvati.

Avvio e iniezione delle dipendenze

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

// Integrazione classica — solo a scopo comparativo; non compilare questo con l'SDK corrente.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

L'integrazione corrente registra Doconut una sola volta e riceve Viewer tramite iniezione delle dipendenze:

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

Middleware e routing delle risorse

Rimuovere il ramo classico MapWhen che rileva DocImage.axd:

// Integrazione classica — rimuovere durante la migrazione.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

Nella 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 validata; non crea un ramo ASP.NET Core da solo. Usa la pipeline semplice nell'esempio di compilazione sopra o un arrangiamento esplicito app.Map("/doconut", branch => branch.UseDoconut()) usato costantemente dal client.

Costruzione e durata di Viewer

Rimuovere le cache possedute dall'applicazione degli oggetti Viewer. Iniettare Viewer in un endpoint, pagina Razor, controller o servizio applicativo a scopo limitato:

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 una credenziale di tipo bearer: non registrarlo nei log, non conservarlo né inserirlo in analisi.

Apertura e chiusura dei documenti

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

// Integrazione .NET 6 corrente: Viewer proviene da DI e l'apertura del documento è asincrona.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Le overload correnti accettano un percorso file o 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 trasferire DocOptions.ImageResolution come controllo di rendering. È obsoleto; impostare BaseConfig.ImageResolution nella configurazione specifica del formato. Rivedere tutte le impostazioni predefinite invece di presumere che una configurazione classica abbia lo stesso comportamento.

Barra degli strumenti di Viewer, Ricerca e Annotazione

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

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

Search e Annotation sono moduli collegati allo stesso Viewer, non barre degli strumenti indipendenti. La barra degli strumenti principale appartiene all'applicazione host; i Ribbon di Search e Annotation sono risorse incorporate, con accesso limitato alle 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() convalida le capacità dei plugin registrati all’avvio. Converter e DICOM sono plugin .NET 6 rilasciati. Ricerca normale e Annotazione sono funzionalità con licenza integrata, non pacchetti AddPlugin<TPlugin>().

Sicurezza della sessione e del documento

L’integrazione corrente associa i documenti a token opachi e sessioni memorizzate nella cache. Con il valore predefinito UnsafeMode = false, UseDoconut() aggiunge la sicurezza di accesso al documento e l’host deve configurare la sessione ASP.NET:

builder.Services.AddDistributedMemoryCache(); // lo stato della sessione richiede una cache (MVC/Razor Pages ne aggiunge già una)
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, con token scaduto e con un 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 su singolo nodo.

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 e controllo delle capacità dell’Annotazione;
• scoperta del target del Converter, output, download e stato del watermark;
• pagine, fotogrammi e animazione DICOM; i metadati tecnici .NET 6 non sono disponibili;
• documenti protetti da password, caratteri personalizzati, testo non latino e timeout configurati;
• rifiuto del token tra sessioni e comportamento della sessione scaduta;
• modalità mobile, modalità scura e il 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 del browser copiate insieme. Un rollback sicuro scambia l’intera generazione dell’applicazione; non mescola un server classico con script attuali né un server attuale con chiamate DocImage.axd classiche.

Prima del taglio, documenta:

• lo slot o l’artefatto di distribuzione usato per il rollback;
• l’impatto su database/cache, se presente;
• come le sessioni documento attive saranno invalidate;
• il controllo di integrità 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 corrente.