Due migrazioni sono presenti 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) 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

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 genera 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 ciascuna 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	Construct `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + inject `Viewer`
Licenza	Static `Viewer.DoconutLicense(path)` + `SetLicensePlugin(...)` per plugin	`options.LicensePath` / `LicenseContent` / `LicenseStream` — one license, auto-discovery for plugin files
Apertura	`viewer.OpenDocument(...)` (synchronous)	`await viewer.OpenDocumentAsync(...)`
Chiusura	`viewer.CloseDocument()` or `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` is not `IDisposable`
Durata	`Viewer` implements `IDisposable`, holds the open document	`Viewer` is stateless; sessions live in the cache under tokens
Convertitore	`viewer.Converter` property	The Converter plugin (`AddPlugin<ConverterPlugin>()`) + the `DocumentConverter` service
Classi di configurazione	`Doconut.Configs.View.*` namespaces	All in the `Doconut` namespace
Middleware	Manual handler wiring	`app.UseDoconutResources()` + `app.UseDoconut()`

Un tipico prima/dopo:

text

// .NET 6 (old API, shown for contrast — not valid on .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 injected, license configured once 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 modello).
I 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 protette da 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 delle annotazioni su Viewer.

Pianifica questo come una riscrittura dello strato 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 Convertitore + DocumentConverter.
Riesegui il test del percorso di sicurezza: AddSession()/UseSession() sono ora richiesti con la sicurezza predefinita.