Migration

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

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

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

2. Vérifiez la fenêtre de licence. Une licence couvre une plage de versions. Si la nouvelle version se situe en dehors de cette plage, l’ouverture est bloquée — OpenDocumentAsync lève LicenseException (échec immédiat) ; il n’y a pas de retour à un filigrane, et IsVersionValid devient false. Renouvelez, remplacez le fichier .lic, puis redémarrez l’application afin que AddDoconut() charge la nouvelle licence.

3. Recompilez et laissez NuGet restaurer les versions de dépendances déclarées — ne réépinglez pas System.Text.Json ou System.Drawing.Common (voir la section Dépannage pour les erreurs exactes provoquées par une rétrogradation).

4. Effectuez un test de fumée sur un document de chaque famille de formats 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 du modèle asynchrone. Le tableau de correspondance :

Un exemple typique avant/après :

// .NET 6 (ancienne API, affichée à titre de contraste — non valide sur .NET 8)
using var viewer = new Viewer(cache, httpContextAccessor, "wwwroot/Doconut.Viewer.lic");
var token = viewer.OpenDocument(path, new PdfConfig { AllowSearch = true }, new DocOptions());

// .NET 8 — Viewer injecté, licence configurée une seule fois dans 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 d’éléments div du widget et votre point de terminaison renvoie le token (le Quick Start montre le schéma).
• Les méthodes de licence statiques → les sources de licence DoconutOptions.
• OpenDocument synchrone → await OpenDocumentAsync.
• Viewer.ReferenceScripts() / ReferenceCss() existent dans les deux mondes — les versions .NET 8 acceptent des objets ScriptConfig/CssConfig et sont soumises à la licence.
• Propriétés du contrôle (ShowThumbs, PageZoom, FixedZoom, …) → les mêmes noms sur ViewerConfig / les options JS docViewer.
• Méthodes d’exportation retournant byte[] → les API d’exportation d’annotations asynchrones sur Viewer.

Planifiez cette migration comme une réécriture de la couche d’hébergement autour d’un concept inchangé : ouvrir → token → 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

1. Remplacez les packages ; alignez les versions des packages d’extension.
2. Déplacez la configuration de licence dans AddDoconut() ; supprimez les appels de licence statiques.
3. Rendre les appels d’ouverture asynchrones ; remplacez Dispose/CloseDocument sans paramètre par CloseDocument(token).
4. Remplacez les utilisations de viewer.Converter par l’enregistrement du plugin Convertisseur + DocumentConverter.
5. Re‑testez le chemin de sécurité : AddSession()/UseSession() sont désormais obligatoires avec la sécurité par défaut (plus AddDistributedMemoryCache() dans une application minimal‑API).