Migration

Mise à niveau vers Doconut sur .NET 8

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. Mettre à jour le package (et tous les packages de plug‑in — garder les versions alignées) :
bash
dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Dicom
  1. Vérifiez la fenêtre de licence. Une licence couvre une plage de versions. Si la nouvelle version se situe en dehors de celle‑ci, l’ouverture est bloquée — OpenDocumentAsync lève LicenseException (échec immédiat) ; 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.
  2. 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 Dépannage pour les erreurs exactes qu’une rétrogradation provoque).
  3. Effectuez un test de fumée d’un document par 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 de l’asynchrone. Le tableau de correspondance :

Aspect.NET 6 / Standard 2.0.NET 8
SetupConstruire Viewer(cache, httpContextAccessor, licensePath)builder.Services.AddDoconut(options => …) + injecter Viewer
LicenseStatique Viewer.DoconutLicense(path) + SetLicensePlugin(...) par plug‑inoptions.LicensePath / LicenseContent / LicenseStream — une licence, découverte automatique des fichiers de plug‑in
Openviewer.OpenDocument(...) (synchronisé)await viewer.OpenDocumentAsync(...)
Closeviewer.CloseDocument() ou viewer.Dispose()viewer.CloseDocument(token) — Viewer n’est pas IDisposable
LifetimeViewer implémente IDisposable, détient le document ouvertViewer est sans état ; les sessions résident dans le cache sous des jetons
ConverterPropriété viewer.ConverterLe plug‑in Converter (AddPlugin<ConverterPlugin>()) + le service DocumentConverter
Config classesEspaces de noms Doconut.Configs.View.*Tous dans l’espace de noms Doconut
MiddlewareCâblage manuel du gestionnaireapp.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’exportation retournant byte[] → les API d’annotation export asynchrone 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

  1. Échanger les packages ; aligner les versions des packages de plug‑in.
  2. Déplacer la configuration de licence dans AddDoconut() ; supprimer les appels de licence statiques.
  3. Rendre les appels d’ouverture asynchrones ; remplacer Dispose/CloseDocument sans paramètre par CloseDocument(token).
  4. Remplacer les utilisations de viewer.Converter par l’enregistrement du plug‑in Converter + DocumentConverter.
  5. Retester le chemin de sécurité : AddSession()/UseSession() sont désormais requis avec la sécurité par défaut.

Cette page était-elle utile ?