Due migrazioni sono presenti in questa pagina: aggiornamento della versione del pacchetto su .NET 8, e spostamento di un'integrazione da un framework Doconut più vecchio (.NET 6, .NET Standard 2.0, .NET Framework 4.7) sull'API .NET 8.

Aggiornamento della versione del pacchetto

Aggiorna il pacchetto (e tutti i pacchetti plugin — mantieni le versioni allineate):

bash

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Dicom

Verifica la finestra di licenza. Una licenza copre un intervallo di versioni. Se la nuova versione cade al di fuori di esso, l'apertura è bloccata — OpenDocumentAsync lancia LicenseException (fail-fast); non ricade in un watermark, e IsVersionValid diventa false. Rinnova, sostituisci il file .lic e riavvia l'applicazione in modo che AddDoconut() carichi la nuova licenza.
Ricompila e lascia che NuGet ripristini le versioni delle dipendenze dichiarate — non fissare nuovamente System.Text.Json o System.Drawing.Common (vedi Risoluzione dei problemi per gli errori esatti che causa un downgrade).
Esegui un test rapido su un documento per ogni famiglia di formati che utilizzi.

Migrazione da .NET 6 / .NET Standard 2.0

L'API .NET 8 è una riprogettazione basata su DI e async. La mappatura:

Aspetto	.NET 6 / Standard 2.0	.NET 8
Configurazione	Costruisci `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + inietta `Viewer`
Licenza	Statica `Viewer.DoconutLicense(path)` + `SetLicensePlugin(...)` per plugin	`options.LicensePath` / `LicenseContent` / `LicenseStream` — una licenza, scoperta automatica dei file plugin
Apri	`viewer.OpenDocument(...)` (sincrono)	`await viewer.OpenDocumentAsync(...)`
Chiudi	`viewer.CloseDocument()` oppure `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` non è `IDisposable`
Durata	`Viewer` implementa `IDisposable`, mantiene il documento aperto	`Viewer` è senza stato; le sessioni vivono nella cache sotto i token
Convertitore	Proprietà `viewer.Converter`	Il plugin Converter (`AddPlugin<ConverterPlugin>()`) + il servizio `DocumentConverter`
Classi di configurazione	Namespace `Doconut.Configs.View.*`	Tutte nel namespace `Doconut`
Middleware	Collegamento manuale dei gestori	`app.UseDoconutResources()` + `app.UseDoconut()`

Un tipico prima/dopo:

text

// .NET 6 (API vecchia, mostrata per contrasto — non valida su .NET 8)
using var viewer = new Viewer(cache, httpContextAccessor, "wwwroot/Doconut.Viewer.lic");
var token = viewer.OpenDocument(path, new PdfConfig { AllowSearch = true }, new DocOptions());

csharp

// .NET 8 — Viewer iniettato, licenza configurata una volta in AddDoconut()
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Migrazione da .NET Framework 4.7 (Web Forms)

Il Viewer 4.7 è un WebControl; .NET 8 sostituisce il modello di controllo con middleware + un servizio DI:

Il controllo <doconut:DocViewer runat=server> scompare — la pagina ospita la coppia di widget div e il tuo endpoint restituisce il token (Quick Start mostra il pattern).
Metodi di licenza statici → fonti di licenza DoconutOptions.
OpenDocument sincrono → await OpenDocumentAsync.
Viewer.ReferenceScripts() / ReferenceCss() esistono in entrambi i mondi — le versioni .NET 8 accettano oggetti ScriptConfig/CssConfig e sono soggette a licenza.
Proprietà del controllo (ShowThumbs, PageZoom, FixedZoom, …) → gli stessi nomi su ViewerConfig / le opzioni JS docViewer.
Metodi di esportazione che restituiscono byte[] → le API di esportazione asincrona di annotazioni su Viewer.

Pianifica questo come una riscrittura del livello di hosting attorno a un concetto invariato: apri → token → widget.

Nota sui nomi

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

Checklist di migrazione

Scambia i pacchetti; allinea le versioni dei pacchetti plugin.
Sposta la configurazione della licenza in AddDoconut(); elimina le chiamate di licenza statiche.
Rendi le chiamate di apertura asincrone; sostituisci Dispose/CloseDocument senza parametri con CloseDocument(token).
Sostituisci gli utilizzi di viewer.Converter con la registrazione del plugin Converter + DocumentConverter.
Ritestare il percorso di sicurezza: AddSession()/UseSession() sono ora obbligatori con la sicurezza predefinita (oltre a AddDistributedMemoryCache() in un'app minimal-API).