Due migrazioni sono presentate in questa pagina: aggiornamento della versione del pacchetto all'interno di .NET 8, e spostamento di un'integrazione da un framework Doconut più vecchio (.NET 6, .NET Standard 2.0, .NET Framework 4.7) verso l'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

Controlla la finestra della 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 su un watermark, e IsVersionValid diventa false. Rinnova, sostituisci il file .lic e riavvia l'applicazione affinché 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 Troubleshooting per gli errori esatti che un downgrade provoca).
Esegui un smoke‑test su un documento per ogni famiglia di formati che utilizzi.

Migrazione da .NET 6 / .NET Standard 2.0

L'API .NET 8 è una riprogettazione attorno a DI e async. La mappatura:

Concern	.NET 6 / Standard 2.0	.NET 8
Setup	Costruisci `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + inietta `Viewer`
License	Statico `Viewer.DoconutLicense(path)` + `SetLicensePlugin(...)` per plugin	`options.LicensePath` / `LicenseContent` / `LicenseStream` — una licenza, scoperta automatica per i file plugin
Open	`viewer.OpenDocument(...)` (sincrono)	`await viewer.OpenDocumentAsync(...)`
Close	`viewer.CloseDocument()` o `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` non è `IDisposable`
Lifetime	`Viewer` implementa `IDisposable`, mantiene il documento aperto	`Viewer` è senza stato; le sessioni vivono nella cache sotto token
Converter	Proprietà `viewer.Converter`	Il plugin Converter (`AddPlugin<ConverterPlugin>()`) + il servizio `DocumentConverter`
Config classes	Namespace `Doconut.Configs.View.*`	Tutto nel namespace `Doconut`
Middleware	Cablaggio manuale dei gestori	`app.UseDoconutResources()` + `app.UseDoconut()`

Un tipico prima/dopo:

text

// .NET 6 (vecchia API, 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 div del widget 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 async di esportazione di annotazioni su Viewer.

Pianifica questa come una riscrittura dello strato di hosting attorno a un concetto invariato: open → 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 statiche alla licenza.
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.
Riesegui il test del percorso di sicurezza: AddSession()/UseSession() sono ora obbligatori con la sicurezza predefinita.