Deux migrations sont présentées sur cette page : mise à jour de la version du package sous .NET 8, et déplacement d’une intégration depuis un ancien framework Doconut (.NET 6, .NET Standard 2.0, .NET Framework 4.7) vers l’API .NET 8.

Mise à jour de la version du package

Mettez à jour le package (et tous les packages d’extension — maintenez les versions alignées) :

bash

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

Vérifiez la fenêtre de licence. Une licence couvre une plage de versions. Si la nouvelle version en sort, l’ouverture est bloquée — OpenDocumentAsync lève LicenseException (échec rapide) ; elle ne revient pas à un filigrane, et IsVersionValid devient false. Renouvelez, remplacez le fichier .lic, et redémarrez l’application afin que AddDoconut() charge la nouvelle licence.
Recompilez et laissez NuGet restaurer les versions des dépendances déclarées — ne re‑épinglez pas System.Text.Json ou System.Drawing.Common (voir la section Dépannage pour les erreurs exactes provoquées par une rétrogradation).
Effectuez un test de fumée d’un document par famille de format que vous utilisez.

Migration depuis .NET 6 / .NET Standard 2.0

L’API .NET 8 est une refonte autour de l’injection de dépendances (DI) et de l’asynchrone. Le tableau de correspondance :

Aspect	.NET 6 / Standard 2.0	.NET 8
Setup	Construire `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + injecter `Viewer`
License	Statique `Viewer.DoconutLicense(path)` + `SetLicensePlugin(...)` par plugin	`options.LicensePath` / `LicenseContent` / `LicenseStream` — une licence, découverte automatique des fichiers de plugin
Open	`viewer.OpenDocument(...)` (synchronisé)	`await viewer.OpenDocumentAsync(...)`
Close	`viewer.CloseDocument()` ou `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` n’est pas `IDisposable`
Lifetime	`Viewer` implémente `IDisposable`, détient le document ouvert	`Viewer` est sans état ; les sessions résident dans le cache sous forme de jetons
Converter	propriété `viewer.Converter`	Le plugin Converter (`AddPlugin<ConverterPlugin>()`) + le service `DocumentConverter`
Config classes	espaces de noms `Doconut.Configs.View.*`	Tous dans l’espace de noms `Doconut`
Middleware	Câblage manuel du gestionnaire	`app.UseDoconutResources()` + `app.UseDoconut()`

Un exemple typique avant/après :

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 });

Migration depuis .NET Framework 4.7 (Web Forms)

Le Viewer 4.7 est un WebControl ; .NET 8 remplace le modèle de contrôle par un middleware + un service DI :

Le contrôle <doconut:DocViewer runat=server> disparaît — la page héberge la paire de div du widget et votre point de terminaison renvoie le jeton (le Guide de démarrage rapide montre le modèle).
Méthodes de licence statiques → sources de licence DoconutOptions.
OpenDocument synchrone → await OpenDocumentAsync.
Viewer.ReferenceScripts() / ReferenceCss() existent dans les deux environnements — les versions .NET 8 acceptent des objets ScriptConfig/CssConfig et sont conditionnées par la licence.
Propriétés du contrôle (ShowThumbs, PageZoom, FixedZoom, …) → les mêmes noms sur ViewerConfig / les options JS docViewer.
Méthodes d’export renvoyant byte[] → les API d’annotation‑export asynchrones sur Viewer.

Planifiez cela comme une réécriture de la couche d’hébergement autour d’un concept inchangé : ouvrir → jeton → widget.

Note sur la nomenclature

Dans tous les frameworks, la classe est Viewer — si vous trouvez DocumentViewer dans d’anciens extraits ou des articles tiers, ce type n’a jamais existé dans le SDK.

Checklist de migration

Échangez les packages ; alignez les versions des packages d’extension.
Déplacez la configuration de licence dans AddDoconut() ; supprimez les appels de licence statiques.
Rendez les appels d’ouverture asynchrones ; remplacez Dispose/CloseDocument sans paramètre par CloseDocument(token).
Remplacez les utilisations de viewer.Converter par l’enregistrement du plugin Converter + DocumentConverter.
Retestez le chemin de sécurité : AddSession()/UseSession() sont désormais requis avec la sécurité par défaut.