Migration

Cette page couvre la mise à niveau d’une application ASP.NET existante de Doconut.NETFramework 26.8.0 ou antérieure (.NET Framework 4.7) vers 26.9.0 et ultérieure (.NET Framework 4.7.2). Le paquet d’échantillons Doconut contient le guide complet de migration et les échantillons classiques portés vers la nouvelle API — MVC 5, une ferme Web et Web Forms. Comparer votre application à l’échantillon de départ est le chemin le plus rapide.

Un seul paquet, deux versions

Les deux bibliothèques sont publiées sous le même ID de paquet, Doconut.NETFramework. La version les différencie :

Mettre à jour le paquet constitue la mise à niveau. Il n’existe aucun paquet séparé à installer et aucune couche de compatibilité : 26.9.0 possède une surface d’API différente, attendez‑vous donc à des erreurs de compilation après la mise à jour — le reste de cette page. La branche .NET Framework 4.7 est abandonnée et 26.8.0 en est la dernière version. Vous pouvez rester dessus — rien ici n’est une correction de sécurité que vous manqueriez — mais les nouvelles versions, les plugins, le mode distribué et les widgets prêts à l’emploi n’arrivent que sur 26.9.0 et ultérieur.

1. Retargeter le projet et mettre à jour le paquet

Retargetez le projet Web vers .NET Framework 4.7.2 d’abord : un projet qui cible encore 4.7 ne peut pas installer 26.9.0, et NuGet refuse la mise à jour. Ensuite, mettez à jour Doconut.NETFramework et ajoutez les paquets de plugins que vous utilisez (Doconut.NETFramework.Converter, Doconut.NETFramework.Dicom, …). Chaque plugin nécessite une licence qui le permet.

Si le projet utilise packages.config, la mise à jour exécute l’étape de désinstallation de la version précédente, qui supprime le gestionnaire DocImage de Web.config, et 26.9.0 ne le réinstalle pas. Enregistrez‑le à nouveau comme indiqué à l’étape 3 ; tant que vous ne le faites pas, DocImage.axd renvoie 404 et aucune page ne s’affiche.

2. Espaces de noms : presque tout déplacé à la racine

Les noms de types n’ont pas changé : WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, FileShareConfig et le reste sont toujours présents. Dans la plupart des fichiers, la modification consiste simplement à supprimer les lignes using.

3. Démarrage : DoconutHost.Initialize et deux entrées Web.config

La version classique du paquet créait son visualiseur à chaque requête, avec les options comme propriétés de cette instance. Le nouveau paquet possède une racine de composition, construite une fois dans Application_Start, et le visualiseur est un service que vous résolvez :

// Avant - Doconut.NETFramework 26.8.0 et antérieur, sur demande
var viewer = new Viewer
{
    ID = "ctlDoc",
    IncludeJQuery = true,
    BasePath = "/",
    FitType = "width"
};

// Doconut.NETFramework 26.9.0+ - Viewer résolu depuis DoconutHost, licence configurée une fois dans DoconutHost.Initialize()
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
var token  = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

DoconutHost.Initialize va dans Application_Start et DoconutHost.Shutdown dans Application_End, et Web.config obtient le gestionnaire DocImage.axd ainsi que le module de ressources — les deux se trouvent dans Installation. Les paramètres d’apparence par page (FitType, FixedZoom, ShowHyperlinks, …) ont été déplacés de l’instance du visualiseur vers les options du widget, ou vers un ViewerConfig transmis à Viewer.RenderViewer (voir ViewerConfig). new Viewer() se compile toujours une fois que DoconutHost.Initialize a été exécuté, de sorte que le code‑behind migré peut conserver cette ligne pendant que vous déplacez les paramètres.

La sécurité fonctionne comme avant. Ouvrir un document accorde à la session ASP.NET actuelle l’accès à ses pages, et DocImage.axd refuse tout le reste. Le paramètre d’application DoconutUnSafeMode qui désactivait cela est maintenant options.UnsafeMode dans DoconutHost.Initialize — laissez‑le false. Voir Sessions et Sécurité.

L’échec de démarrage qui fait tomber tout le site. Un plugin enregistré dont la capacité n’est accordée par aucune licence lève une exception dans Application_Start, et l’application répond alors avec un 500 vide à chaque requête — aucune page d’erreur, rien dans le journal IIS, seulement une entrée dans le journal d’événements Windows (source ASP.NET). Les licences sont lues depuis wwwroot sous la racine du site et nulle part ailleurs, et la base Doconut.Viewer.lic doit être présente sinon les licences du plugin à côté ne sont pas lues. Voir Configuration de licence.

4. Ferme Web : d’un drapeau au mode distribué

Le modèle classique était viewer.IsWebfarm = true plus ExportToPng(path). Le nouveau modèle est enregistré une seule fois : chaque nœud partage un magasin et une clé de signature, et un ticket signé lié au navigateur remplace « n’importe quel nœud qui répond » :

Doconut.DoconutHost.Initialize(
    options => options.UnsafeMode = false,
    services => services.AddDoconutDistributed(d =>
    {
        d.Store             = CloudLocation.FileShare;
        d.FileShareRootPath = @"\\fileserver\doconut-shared";   // WebfarmPath est un alias
        d.SigningKey        = farmKey;                           // >= 32 octets, le même sur chaque nœud
    }));

Ensuite, ouvrez les documents normalement, en liant le navigateur (DocOptions.BrowserId = DoconutFarmBinding.EnsureBrowserId(...)) et en transmettant viewer.AccessToken au widget avec le jeton. Sessions et Sécurité décrit les étapes ; l’exemple de ferme Web est un nœud complet. IsWebfarm et WebfarmPath se compilent toujours, mais ils n’activent plus rien.

Deux choses qui semblent être un succès mais ne le sont pas : DistributedDocumentPublisher.PublishAsync écrit les fichiers rendus d’un document mais n’ouvre aucune session, ainsi un visualiseur pointé sur un jeton publié obtient l’image d’erreur d’environ 2 KB avec le statut 200 ; et un client de test sans le cookie doconut-client reçoit la même image, pas un 401. Distinguez une vraie page de l’image d’erreur par sa taille.

5. La conversion est un plugin, et beaucoup plus petite

L’énumération SourceFormatConverter, les douze classes *ConfigConverter, et leurs énumérations cibles imbriquées sont remplacées par une seule énumération, ConversionTarget, et un appel :

using System.IO;
using System.Threading;
using Doconut;
using Doconut.Configs.Conversion;

// Supposez que DoconutHost est déjà initialisé et qu'un CancellationToken nommé ct est disponible.
var provider = DoconutHost.Services;
var converter = (DocumentConverter)provider.GetService(typeof(DocumentConverter));
Stream source = /* votre flux d'entrée */;
var result = await converter.ConvertAsync(source, ".dwg", ConversionTarget.Pdf, null, ct);

Le format source provient de l’extension que vous transmettez. Il n’existe aucun shim de compatibilité : chaque référence SourceFormatConverter génère une erreur de compilation que vous résolvez en la supprimant. Les objets d’options par format n’ont pas survécu — WordConfigConverter.HtmlOptions et CadConfigConverter.CadOptions.ShowColor n’ont aucun équivalent via ConvertAsync. Dans Web Forms, ne bloquez jamais sur ConvertAsync — voir le Plugin de conversion.

6. Stockage cloud : y accéder comme un dossier partagé

Les types de configuration cloud ont été déplacés vers Doconut.Clouds sans modification. Les gestionnaires de requêtes cloud, cependant, sont des composants ASP.NET Core, et une application classique n’a aucun pipeline pour les exécuter. Depuis un site System.Web, accédez au stockage cloud comme un dossier partagé — sur Azure, un partage Azure Files monté sur chaque nœud — accessible via FileShareConfig.

7. Les changements côté client qui échouent silencieusement

Chaque élément ci‑dessus se compile, s’exécute, ne consigne rien et fait la mauvaise chose :

Trois de plus : le visualiseur ne dessine pas sa propre barre d’outils (votre page connecte Zoom, Next, GotoPage et le reste à ses propres boutons) ; un visualiseur créé à l’intérieur d’une modale Bootstrap cachée mesure 0 × 0 et n’affiche rien tant que vous ne donnez pas à son conteneur une hauteur explicite et ne le réajustez pas sur shown.bs.modal ; et AllowSearch utilise par défaut false pour le PDF, de sorte qu’un document s’affiche parfaitement alors que chaque recherche ne renvoie rien.

8. Ce qui disparaît

Ordre de travail suggéré

1. Rediriger, remplacer le paquet, et faire compiler Global.asax avec DoconutHost.Initialize et les deux enregistrements Web.config. Le site devrait démarrer.
2. Une page de visionneuse : obtenir un document à rendre, puis travailler à travers la section 7 jusqu'à ce que la barre d'outils, la recherche et les annotations fonctionnent. Vérifier dans un vrai navigateur — rien dans cette section ne génère d'erreur.
3. Conversion (section 5) : mécanique, et la plupart des erreurs de compilation.
4. Les pages restantes, en utilisant les exemples portés comme cible de diff.
5. Le parc web (section 4), si vous en avez un. Tester avec deux nœuds et un navigateur, ou un client qui conserve les cookies.