Migrare a .NET Standard 2.1

Doconut ha due integrazioni .NET Standard distinte. Usano lo stesso nome di pacchetto Doconut.NETStandard, quindi identifica la generazione dalla versione e dalle API nell'applicazione prima di modificare pacchetti, avvio, licenze o risorse del browser.

La versione è il bivio

Entrambe le generazioni pubblicano sotto lo stesso ID pacchetto. Solo la versione le distingue:

Incrementare il numero di versione è l'aggiornamento. Non esiste un pacchetto separato da installare né uno shim di compatibilità — 26.8.0 è una superficie API diversa. Aspettati errori di compilazione dopo l'incremento; il resto di questa guida è l'elenco di essi.

Quale integrazione 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.

Controlla prima il framework host

Questo è un vincolo rigido, non una preferenza. Il pacchetto corrente mira a netstandard2.1:

.NET Framework non può fare riferimento a una libreria netstandard2.1. Se l'applicazione gira su .NET Framework, fermati qui e utilizza il pacchetto Doconut.NETFramework invece; dalla 26.9.0 richiede .NET Framework 4.7.2. Entrambe le applicazioni di riferimento per questa versione mirano a net8.0.

Prima di migrare

1. Crea un branch e un backup distribuibile dell'applicazione esistente.
2. Registra le versioni esatte dei pacchetti core e plugin.
3. Fai l'inventario di ogni chiamata new Viewer(...), chiamata InitCache(), chiamata di caricamento licenza, mappatura UseDoconutWebFarm, controller di conversione, script Doconut copiato, azione barra degli strumenti personalizzata, callback del viewer 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, la consegna delle risorse client e — se gestisci un farm — il modo in cui le pagine raggiungono il browser.

1. Namespace: quasi tutto spostato nella radice

I tipi di configurazione erano distribuiti su quattro namespace. Ora sono tutti in Doconut.

I nomi dei tipi non sono cambiati: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, CloudUploadConfig, AzureConfig, CDNConfig, FileShareConfig e il resto sono ancora presenti. Nella maggior parte dei file l'intera modifica consiste nell'eliminare due righe using.

Doconut.Configs.Editor (BaseConfigEditor, PdfConfigEditor) è stato rimosso e non ha alcuna sostituzione in questo pacchetto. Se la tua applicazione faceva riferimento a quei tipi, pianifica quella parte separatamente e non considerarla parte di questa migrazione.

2. Compatibilità di pacchetto e licenza

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 versione stabile:

dotnet add package Doconut.NETStandard

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

dotnet add package Doconut.NETStandard --version 26.8.0

Mantieni ogni plugin Doconut alla stessa versione del pacchetto core — Doconut.NETStandard.Converter e Doconut.NETStandard.Dicom. 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 complementari Doconut.Viewer.<Capability>.lic. Le precedenti chiamate statiche Viewer.DoconutLicense(...) e Viewer.SetLicensePlugin(...) non costituiscono un meccanismo di avvio attuale, così come la List<string> di percorsi di licenza accettata dal vecchio costruttore Viewer. Sposta la licenza in DoconutOptions, mantieni i file complementari insieme quando usi il rilevamento automatico, riavvia dopo aver modificato una licenza e verifica le funzionalità tramite IDoconutLicenseService.

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

3. Avvio e iniezione delle dipendenze

In precedenza il viewer veniva costruito per ogni richiesta e le opzioni venivano passate al middleware:

// Integrazione precedente — solo a scopo di confronto; non compilare questo con l'SDK corrente.
var viewer = new Viewer(_cache, _accessor);
// …
appBranch.UseDoconut(new DoconutOptions { UnSafeMode = false, ShowDoconutInfo = false });

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

builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // nota il cambiamento di ortografia: UnSafeMode → UnsafeMode
    options.ShowDoconutInfo = false;
    options.LicensePath     = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // lo stato della sessione richiede una cache (MVC/Razor Pages ne aggiungono già una)
builder.Services.AddSession();

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

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

Tre cose da mantenere:

• new Viewer(cache, accessor) è stato rimosso. Inietta Doconut.Viewer nel tuo controller, oppure usa @inject Doconut.Viewer Viewer in una vista Razor.
• UseDoconutResources() sostituisce il collegamento manuale app.UseMiddleware<EmbeddedResourceMiddleware>(), e deve essere eseguito prima del ramo del documento.
• UnSafeMode → UnsafeMode. Un rinominare di un solo carattere che il compilatore rileverà.

Quando UnsafeMode è false l'SDK valida il token di sessione rispetto alla richiesta di origine, quindi AddSession() / UseSession() devono comunque trovarsi nella pipeline, UseSession() prima del ramo.

Metodi che non esistono più

4. Middleware e routing delle risorse

UseDoconut() ora non accetta argomenti. La forma del ramo MapWhen stessa non deve cambiare — solo il middleware al suo interno:

app.UseDoconutResources();   // PRIMA del ramo

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

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 il ResPath del client allineati;
4. mantieni il ramo che mappi e il BasePath del client allineati.

MiddlewarePath è una configurazione validata; non crea un ramo ASP.NET Core da solo.

5. Costruzione e durata del Viewer

Rimuovi le cache possedute dall'applicazione degli oggetti Viewer. Non rimane nulla in un Viewer che valga la pena conservare: non contiene stato del documento e la cache di sessione possiede tutto ciò che sopravvive a una richiesta. Iniettalo 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 di documento lato server. Trattalo come una credenziale di tipo bearer: non registrarlo, non persisterlo e non inserirlo in analisi.

6. Apertura e chiusura dei documenti

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

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

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

viewer.CloseDocument(token);

Elimina qualsiasi chiamata a InitCache() e la relativa bandiera di protezione — non c'è nulla da riscaldare manualmente. Non riutilizzare un token generato dalla libreria precedente dopo la migrazione: apri nuovamente ogni documento tramite l'API corrente.

7. Web farm → distribuito: il cambiamento più grande

UseDoconutWebFarm e WebFarmOptions non esistono più. Se la tua app li chiama, questa sezione è il tuo aggiornamento; se non lo fa, passa alla §8.

In precedenza un unico middleware gestiva tutto: serviva immagini pre‑renderizzate da una cartella condivisa, e interrogava mentre un altro nodo le stava ancora scrivendo.

// Integrazione precedente — una chiamata, coordinamento implicito tramite il filesystem.
appBranch.UseDoconutWebFarm(new WebFarmOptions
{
    Path                = Path.Combine(env.WebRootPath, "webfarm"),
    PageWaitTimeSeconds = 180,
    StartWaitFromPage   = 5,
});

Lo stesso compito ora è suddiviso in due metà esplicite. Lato scrittura — il nodo che apre il documento pubblica l'intero set di artefatti (pagine, informazioni sul documento, indice di ricerca, metadati) nella condivisione:

var result = await _publisher.PublishAsync(          // DistributedDocumentPublisher, injected from DI
    pathToFile,
    new FileShareConfig
    {
        Location              = CloudLocation.FileShare,
        RootPath              = @"\\fileserver\doconut",   // the same folder you use today
        UsePerTokenSubfolders = true,
    },
    config,
    documentOptions,
    new DistributedDocumentPublishOptions
    {
        CleanUpStagingDirectory = true,
        FirstPagePriority       = true,
    });

return Content(result.Token);

Lato lettura — qualsiasi nodo serve dalla condivisione:

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = /* the SAME FileShareConfig as above */;
    }, "/"));

La tua topologia non cambia. Imposta RootPath sulla stessa condivisione UNC e ogni nodo continuerà a funzionare come oggi. Ciò che cambia è che la pubblicazione è un'operazione che chiami, invece di un effetto collaterale del rendering.

Entrambe le metà devono concordare. Se RootPath o UsePerTokenSubfolders differiscono tra il publisher e l'handler, l'altro nodo risponde 404. Costruisci la configurazione in un unico helper e richiamala da entrambi i lati.

PageWaitTimeSeconds = 180 significava "bloccare fino a tre minuti sperando che la pagina appaia". La sostituzione è esplicita: con FirstPagePriority = true, la pagina 1 è servibile immediatamente e le pagine successive rispondono HTTP 202 Accepted finché non sono scritte. Il viewer integrato riprova automaticamente quando retryOn409 è impostato. Un client che non riprova mostrerà tasselli interrotti per le pagine ancora in rendering.

L'intera configurazione, inclusa la pubblicazione in background e i ticket di accesso, è descritta in Distribuzioni distribuite.

8. La conversione è un plugin, ed è molto più piccola

Registra il plugin, poi inietta la facciata DocumentConverter:

builder.Services.AddDoconut(o => o.AddPlugin<ConverterPlugin>());

// Integrazione precedente
var converter = viewer.Converter.GetConverter();
var config    = new WordConfigConverter { TargetFormat = WordConfigConverter.EnTargetFormat.PDF };
var result    = converter.Convert(stream, SourceFormatConverter.DOCX, config);

// Integrazione corrente
var result = await _converter.ConvertAsync(stream, ".docx", ConversionTarget.Pdf, null, ct);

Ciò che sostituisce:

• SourceFormatConverter — rimosso. Passare l'estensione del file come stringa, punto incluso.
• I tipi *ConfigConverter per famiglia (WordConfigConverter, ExcelConfigConverter, …), ciascuno con un enum annidato EnTargetFormat — rimosso. Ora esiste un unico enum ConversionTarget per ogni famiglia.
• viewer.Converter.GetConverter() — rimosso. Inietta Doconut.DocumentConverter.

ConvertAsync restituisce uno stream ricercabile, quindi return File(result, mime, name) funziona direttamente — la copia MemoryStream necessaria nel vecchio codice è superflua. Nell'esempio fornito questo ha eliminato uno switch di estensioni con 68 casi e dieci controller quasi identici.

Vedi Plugin di conversione per tutti i dettagli.

9. Provider cloud

UseDoconutCloud è diventato generico. Il provider è l'argomento di tipo invece di un valore Location selezionato all'interno del middleware:

// Integrazione precedente
appBranch.UseDoconutCloud(new CloudOptions { Location = CloudLocation.CDN, ... });

// Integrazione corrente
branch.UseDoconutCloud<CDNCloudHandler>(options =>
{
    options.Location          = CloudLocation.CDN;
    options.CloudUploadConfig = new CDNConfig { DoconutCdnUrl = "..." };
}, "/");

Le classi di configurazione sono invariate, tranne per lo spazio dei nomi (Doconut.Configs.Cloud → Doconut.Clouds): AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig, FTPConfig, più il nuovo FileShareConfig. I gestori sono nominati <Provider>CloudHandler.

Il gestore CDN è sola lettura — serve ciò che è già sul CDN; non effettua upload.

10. Oggetti di configurazione che hanno cambiato nome

DocOptions guadagna anche IsSecured.

L'API attuale separa anche più rigorosamente le preoccupazioni rispetto a quella precedente, quindi verifica che ogni impostazione sia sull'oggetto che ora la possiede:

Non trasferire DocOptions.ImageResolution come controllo di rendering. È obsoleta; imposta BaseConfig.ImageResolution sulla configurazione specifica del formato. Rivedi tutte le impostazioni predefinite invece di presumere che una configurazione precedente abbia lo stesso comportamento.

11. Il visualizzatore lato client — due modifiche che falliscono SILENZIOSAMENTE

Entrambe queste lasciano il server funzionante perfettamente. Il tuo documento viene renderizzato, la pagina appare corretta e nulla compare nella console del browser. Leggi questa sezione anche se il tuo C# compila al primo tentativo.

I callback del visualizzatore sono ora opzioni, non funzioni globali

Il visualizzatore precedente chiamava i tuoi gestori per nome, derivando il nome della funzione globale dall'ID del contenitore. Dichiarare function ctlDoc_OnViewerReady() su una pagina con <div id="div_ctlDoc"> era sufficiente. Il visualizzatore attuale accetta callback esplicite nell'oggetto delle opzioni e non cerca più quelle funzioni globali:

objctlDoc = $("#div_ctlDoc").docViewer({
    // ... le tue opzioni esistenti ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // era trovato per nome
    onViewerReady:    ctlDoc_OnViewerReady,     // era trovato per nome
    onCopy:           ctlDoc_Copy,              // era ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // era ctlDoc_AutoLoadStatus(page)
});

Perché è problematico: la vecchia chiamata era avvolta in un catch vuoto, che inghiottiva tutto. Ora le tue funzioni semplicemente non vengono mai eseguite e nulla segnala un errore. Il sintomo tipico è uno spinner di caricamento che non si ferma mai — perché la funzione che lo nascondeva era ctlDoc_OnViewerReady. Il documento dietro di esso è corretto.

L'elenco completo delle opzioni è onPageLoading, onPageLoaded, onThumbnailClicked, onPageClicked, onDoubleClick, onViewerBusy, onViewerReady, onViewerError, onCopy, onAnnSaved, onAnnSaveError, onAnnLoaded, onAnnClosed, onAutoLoadStatus, onThumbsShown e onError. Non esiste un callback per il click sui link: la gestione degli hyperlink è integrata, gestita da showHyperlinks.

ResPath deve puntare al prefisso della risorsa

ResPath: '',                      // PRIMA — le risorse provenivano dalla radice dell'applicazione
ResPath: 'doconut-res/images',    // ORA — il prefisso montato da UseDoconutResources()

Se hai modificato il prefisso tramite DoconutOptions.ResourcesPath, usa quel valore al suo posto.

12. Barra degli strumenti del Viewer, Ricerca e Annotazione

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

1. emettere il CSS del Viewer e il CSS con licenza per Ricerca/Annotazione con ReferenceCss;
2. renderizzare la barra degli strumenti del Viewer di proprietà dell'applicazione;
3. renderizzare searchBarMount, annBarMount e il Viewer richiesto;
4. emettere gli script del Viewer e dei moduli con licenza con ReferenceScripts;
5. caricare lo script di supporto della barra degli strumenti dell'applicazione;
6. inizializzare un objViewer;
7. inizializzare i Ribbon di Ricerca e Annotazione con licenza;
8. chiamare attach(objViewer) su ogni 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, con accesso limitato in base alle capacità.

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

13. Registrazione dei plugin

I metodi statici di licenza dei plugin non registrano i plugin correnti. 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 i plugin .NET Standard rilasciati. Ricerca e Annotazione normali sono funzionalità con licenza integrate, non pacchetti AddPlugin<TPlugin>().

14. Sicurezza di sessione e 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 ai documenti e l'host deve configurare la sessione ASP.NET:

builder.Services.AddDistributedMemoryCache(); // lo stato della sessione richiede una cache (MVC/Razor Pages ne aggiungono 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 su un singolo nodo. Testa le richieste senza token, con un token malformato, un token scaduto e un token proveniente da una sessione del browser diversa.

In un farm, la richiesta della pagina può arrivare su un nodo che non ha mai visto la richiesta di apertura, quindi il controllo per sessione la rifiuterebbe. Questo è l'unico caso in cui UnsafeMode = true è corretto — e deve essere abbinato a ticket di accesso firmati tramite AddDoconutDistributedDocumentSecurity, non distribuito da solo. Vedi Distribuzioni distribuite.

Nota sulla denominazione

In tutti i framework la classe è Viewer. Se trovi DocumentViewer in vecchi snippet o articoli di terze parti, quel tipo non è mai esistito nell'SDK.

15. Ordine di lavoro suggerito

1. Conferma che il framework host possa consumare netstandard2.1. Se non può, interrompi.
2. Aggiorna il pacchetto alla 26.8.0 e compila. Risolvi gli errori di compilazione — la maggior parte sono le righe using nella §1.
3. Sposta l'avvio a AddDoconut() e le chiamate middleware nel nuovo ordine (§3, §4).
4. Inietta Viewer dove lo stavi costruendo, rendi OpenDocument asincrono e elimina InitCache() (§5, §6).
5. Se usi il web farm, esegui la §7 — l'unica parte che è una riprogettazione piuttosto che una rinomina.
6. Se converti documenti, esegui la §8.
7. Esegui la §11 — le modifiche lato client. Sono quelle che non si annunceranno da sole.
8. Apri un documento reale in un browser e osserva lo spinner di caricamento. Un build verde non dimostra nulla qui: licenze, registrazione dei plugin, il percorso della risorsa e le callback del viewer falliscono solo a runtime. Per un farm, verifica che un documento pubblicato da un nodo sia servito da un altro.

Test della migrazione

Al minimo, verificare:

• 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 contenente testo e lo stato non ricercabile di un file solo immagine;
• Caricamento, salvataggio, esportazione delle annotazioni e controllo delle capacità;
• Scoperta del target del convertitore, output, download e stato del watermark;
• Pagine DICOM, fotogrammi e animazione; i metadati tecnici non sono disponibili in questo pacchetto;
• documenti protetti da password, font personalizzati, testo non latino e timeout configurati;
• rifiuto del token cross‑session e comportamento della sessione scaduta;
• per un farm: pubblicare su un nodo, richiedere una pagina tardiva da un altro e confermare che il viewer ritenta le risposte 202 invece di mostrare tile rotti;
• mobile, modalità scura e il percorso reverse‑proxy di produzione.

Piano di rollback

Mantenere insieme l'artefatto di distribuzione precedente, 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 di generazione precedente con gli script attuali, né un server attuale con i punti di chiamata new Viewer(...).

Prima del taglio, documentare:

• lo slot di distribuzione o l'artefatto usato per il rollback;
• l'impatto dello storage condiviso, se presente — gli artefatti pubblicati da 26.8.0 non sono consumati dal middleware del web‑farm precedente;
• come le sessioni di 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 precedente tradotto è ancora disponibile su Impostazione Legacy .NET Standard. Il Gateway di integrazione precedente 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 netstandard2.0 esistono. Documenta una generazione diversa e non è reindirizzato all'API corrente.