Migrer vers .NET Standard 2.1

Doconut propose deux intégrations distinctes de .NET Standard. Elles utilisent le même nom de package Doconut.NETStandard, il faut donc identifier la génération à partir de la version et des API présentes dans l'application avant de modifier les packages, le démarrage, les licences ou les ressources du navigateur.

Les deux générations publient sous le même ID de package. Seule la version les différencie :

La version est le point de divergence

Augmenter le numéro de version constitue la mise à jour. Il n'existe aucun package séparé à installer et aucune couche de compatibilité — 26.8.0 présente une surface d'API différente. Attendez-vous à des erreurs de compilation après la mise à jour ; le reste de ce guide en constitue la liste.

Quelle intégration utilisez‑vous ?

Si les deux colonnes apparaissent dans la même application, considérez la migration comme incomplète. N'envoyez pas un token de document à travers les ressources ou le middleware de l'autre génération.

Vérifiez d'abord le framework hôte

Il s'agit d'une contrainte stricte, pas d'une préférence. Le package actuel cible netstandard2.1 :

.NET Framework ne peut pas référencer une bibliothèque netstandard2.1. Si l'application s'exécute sous .NET Framework, arrêtez‑vous ici et utilisez le package Doconut.NETFramework à la place ; à partir de la version 26.9.0, il nécessite .NET Framework 4.7.2. Les deux applications de référence pour cette version ciblent net8.0.

Avant de migrer

1. Créez une branche et une sauvegarde déployable de l'application existante.
2. Enregistrez les versions exactes des packages core et plugin.
3. Inventoriez chaque appel new Viewer(...), appel InitCache(), appel de chargement de licence, mappage UseDoconutWebFarm, contrôleur de conversion, script Doconut copié, action de barre d'outils personnalisée, rappel du viewer et point de terminaison d'ouverture de document.
4. Conservez les fichiers .lic actuels et les secrets de déploiement en dehors du contrôle de version.
5. Capturez un ensemble représentatif de documents PDF, Office, image, CAD, e‑mail, DICOM, consultables, protégés par mot de passe et annotés.
6. Enregistrez le délai d'expiration de session existant, le comportement de sécurité, les polices et les paramètres de la plateforme.

Migrez un environnement avant de modifier la production. L'intégration actuelle modifie la durée de vie des services, le routage des requêtes, la propriété des sessions, la livraison des ressources client et — si vous exploitez un farm — la façon dont les pages atteignent le navigateur.

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

Les types de configuration étaient répartis sur quatre espaces de noms. Ils se trouvent désormais tous dans Doconut.

Les noms de type n'ont pas changé : WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, CloudUploadConfig, AzureConfig, CDNConfig, FileShareConfig et le reste est toujours présent. Dans la plupart des fichiers, la modification consiste à supprimer deux lignes using.

Doconut.Configs.Editor (BaseConfigEditor, PdfConfigEditor) a été supprimé et n'a aucun remplacement dans ce package. Si votre application faisait référence à ces types, planifiez cette partie séparément et ne la considérez pas comme faisant partie de cette migration.

2. Compatibilité des paquets et des licences

Remplacez ou mettez à jour le paquet principal de façon délibérée ; ne vous fiez pas à l’ID de paquet identique pour sélectionner la nouvelle API. La commande par défaut installe la dernière version stable :

dotnet add package Doconut.NETStandard

Pour une migration reproductible vers la version auditée par ce guide, transmettez la version en tant qu’option séparée :

dotnet add package Doconut.NETStandard --version 26.8.0

Conservez chaque plugin Doconut à la même version que le paquet principal — Doconut.NETStandard.Converter et Doconut.NETStandard.Dicom. L’intégration actuelle charge les licences une fois pendant AddDoconut(), en utilisant cette priorité :

LicenseStream > LicenseContent > LicensePath > automatic discovery

La découverte automatique recherche Doconut.Viewer.lic et les fichiers compagnons Doconut.Viewer.<Capability>.lic. Les appels statiques précédents Viewer.DoconutLicense(...) et Viewer.SetLicensePlugin(...) ne constituent pas un mécanisme de démarrage actuel, et il n’en est pas non plus du List<string> des chemins de licence que l’ancien constructeur Viewer acceptait. Déplacez la licence vers DoconutOptions, conservez les fichiers compagnons ensemble lors de l’utilisation de la découverte automatique, redémarrez après avoir modifié une licence, et vérifiez les capacités via IDoconutLicenseService.

Ne supposez pas que la présence d’une ancienne licence de plugin prouve le droit d’utilisation pour une version actuelle du plugin. Testez séparément Viewer, Search, Annotation, Converter et DICOM avec les artefacts de version approuvés.

3. Démarrage et injection de dépendances

Auparavant, le visualiseur était construit par requête et les options étaient transmises au middleware :

// Intégration précédente — contraste uniquement ; ne compilez pas cela contre le SDK actuel.
var viewer = new Viewer(_cache, _accessor);
// …
appBranch.UseDoconut(new DoconutOptions { UnSafeMode = false, ShowDoconutInfo = false });

L’intégration actuelle enregistre Doconut une seule fois et reçoit Viewer via l’injection de dépendances :

builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // note le changement d'orthographe : UnSafeMode → UnsafeMode
    options.ShowDoconutInfo = false;
    options.LicensePath     = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // l'état de session nécessite un cache (MVC/Razor Pages en ajoute déjà un)
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

Viewer est un service transitoire. Le gestionnaire de session de document et son cache possèdent l’état du document à plus longue durée de vie, pas l’instance injectée spécifique Viewer.

Trois points à retenir :

• new Viewer(cache, accessor) a disparu. Injectez Doconut.Viewer dans votre contrôleur, ou utilisez @inject Doconut.Viewer Viewer dans une vue Razor.
• UseDoconutResources() remplace le câblage manuel app.UseMiddleware<EmbeddedResourceMiddleware>(), et doit s’exécuter avant la branche du document.
• UnSafeMode → UnsafeMode. Un renommage d’un caractère que le compilateur détectera.

Lorsque UnsafeMode est false, le SDK valide le jeton de session par rapport à la requête d’origine, de sorte que AddSession() / UseSession() doivent toujours être dans le pipeline, UseSession() avant la branche.

Méthodes qui n’existent plus

4. Middleware et routage des ressources

UseDoconut() ne prend désormais aucun argument. La forme de la branche MapWhen elle‑même n’a pas besoin d’être modifiée — seul le middleware qu’elle contient :

app.UseDoconutResources();   // AVANT la branche

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

Dans le pipeline actuel :

1. appelez UseSession() avant Doconut tant que la sécurité de session est activée ;
2. appelez UseDoconutResources() avant UseDoconut() ;
3. conservez ResourcesPath, les URL de ressources générées et le client ResPath alignés ;
4. conservez la branche que vous mappez et le client BasePath alignés.

MiddlewarePath est une configuration validée ; elle ne crée pas une branche ASP.NET Core d’elle-même.

5. Construction du visualiseur et durée de vie

Supprimez les caches appartenant à l'application des objets Viewer. Il ne reste rien dans un Viewer qui vaudrait la peine d'être conservé : il ne porte aucun état de document, et le cache de session possède tout ce qui survit à une requête. Injectez‑le dans un point de terminaison, une page Razor, un contrôleur ou un service d'application à portée limitée :

app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Le jeton retourné identifie une session de document côté serveur. Traitez‑le comme une preuve d'authentification : ne le consignez pas, ne le persistez pas et ne le placez pas dans l'analyse.

6. Ouverture et fermeture des documents

Remplacez le OpenDocument(...) synchrone par OpenDocumentAsync(...) :

// Intégration actuelle : Viewer provient de DI et l’ouverture du document est asynchrone.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Les surcharges actuelles acceptent un chemin de fichier ou un flux, une configuration de format optionnelle, un DocOptions optionnel, et un jeton d'annulation. Fermez explicitement la session serveur lorsque le navigateur n'en a plus besoin :

viewer.CloseDocument(token);

Supprimez tout appel InitCache() ainsi que le drapeau qui le protège — il n'y a rien à préchauffer manuellement. Ne réutilisez pas un jeton créé par la bibliothèque précédente après la transition : ouvrez chaque document à nouveau via l'API actuelle.

7. Ferme Web → distribué : le plus grand changement

UseDoconutWebFarm et WebFarmOptions n'existent plus. Si votre application les appelle, cette section constitue votre mise à jour ; sinon, passez à la §8.

Auparavant, un seul middleware faisait tout : il servait des images pré‑rendu depuis un dossier partagé, et interrogeait pendant qu'un autre nœud les écrivait encore.

// Intégration précédente — un appel, coordination implicite via le système de fichiers.
appBranch.UseDoconutWebFarm(new WebFarmOptions
{
    Path                = Path.Combine(env.WebRootPath, "webfarm"),
    PageWaitTimeSeconds = 180,
    StartWaitFromPage   = 5,
});

Le même travail est maintenant divisé en deux moitiés explicites. Côté écriture — le nœud qui ouvre le document publie l'ensemble complet des artefacts (pages, informations du document, index de recherche, métadonnées) dans le partage :

var result = await _publisher.PublishAsync(          // DistributedDocumentPublisher, injecté depuis DI
    pathToFile,
    new FileShareConfig
    {
        Location              = CloudLocation.FileShare,
        RootPath              = @"\\fileserver\doconut",   // le même dossier que vous utilisez aujourd’hui
        UsePerTokenSubfolders = true,
    },
    config,
    documentOptions,
    new DistributedDocumentPublishOptions
    {
        CleanUpStagingDirectory = true,
        FirstPagePriority       = true,
    });

return Content(result.Token);

Côté lecture — tout nœud sert depuis le partage :

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = /* le même FileShareConfig que ci‑dessus */;
    }, "/"));

Votre topologie ne change pas. Pointez RootPath vers le même partage UNC et chaque nœud continue de fonctionner comme aujourd'hui. Ce qui change, c'est que la publication est une opération que vous appelez, au lieu d'un effet secondaire du rendu.

Les deux moitiés doivent être d'accord. Si RootPath ou UsePerTokenSubfolders diffèrent entre le
éditeur et le gestionnaire, l'autre nœud répond 404. Construisez la configuration dans un seul helper
et appelez‑la depuis les deux côtés.

PageWaitTimeSeconds = 180 signifiait « bloquer jusqu'à trois minutes en espérant que la page apparaisse ». Le remplacement est explicite : avec FirstPagePriority = true, la page 1 est immédiatement disponible et les pages suivantes répondent HTTP 202 Accepted jusqu'à ce qu'elles soient écrites. Le visualiseur intégré réessaie automatiquement lorsque retryOn409 est défini. Un client qui ne réessaye pas affichera des tuiles cassées pour les pages encore en cours de rendu.

Le dispositif complet, incluant la publication en arrière‑plan et les tickets d'accès, se trouve dans Déploiements distribués.

8. La conversion est un plugin, et beaucoup plus petit

Enregistrez le plugin, puis injectez la façade DocumentConverter :

builder.Services.AddDoconut(o => o.AddPlugin<ConverterPlugin>());

// Intégration précédente
var converter = viewer.Converter.GetConverter();
var config    = new WordConfigConverter { TargetFormat = WordConfigConverter.EnTargetFormat.PDF };
var result    = converter.Convert(stream, SourceFormatConverter.DOCX, config);

// Intégration actuelle
var result = await _converter.ConvertAsync(stream, ".docx", ConversionTarget.Pdf, null, ct);

Ce que cela remplace :

• SourceFormatConverter — supprimé. Passez l'extension du fichier en tant que chaîne, point inclus.
• Les types *ConfigConverter par famille (WordConfigConverter, ExcelConfigConverter, …), chacun avec une énumération EnTargetFormat imbriquée — supprimé. Il existe maintenant une énumération ConversionTarget pour chaque famille.
• viewer.Converter.GetConverter() — supprimé. Injectez Doconut.DocumentConverter.

ConvertAsync renvoie un flux recherchable, donc return File(result, mime, name) fonctionne directement — la copie MemoryStream du code ancien n'est plus nécessaire. Dans l'exemple fourni, cela a supprimé un commutateur d'extension de 68 cas et dix contrôleurs quasi-identiques.

Voir Plugin de conversion pour l'ensemble complet.

9. Fournisseurs de cloud

UseDoconutCloud est devenu générique. Le fournisseur est l'argument de type au lieu d'une valeur Location évaluée à l'intérieur du middleware :

// Intégration précédente
appBranch.UseDoconutCloud(new CloudOptions { Location = CloudLocation.CDN, ... });

// Intégration actuelle
branch.UseDoconutCloud<CDNCloudHandler>(options =>
{
    options.Location          = CloudLocation.CDN;
    options.CloudUploadConfig = new CDNConfig { DoconutCdnUrl = "..." };
}, "/");

Les classes de configuration sont inchangées à part le namespace (Doconut.Configs.Cloud → Doconut.Clouds) : AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig, FTPConfig, plus le nouveau FileShareConfig. Les gestionnaires sont nommés <Provider>CloudHandler.

Le gestionnaire CDN est en lecture seule — il sert ce qui est déjà sur le CDN ; il ne téléverse rien.

10. Objets de configuration qui ont changé de nom

DocOptions gagne également IsSecured.

L'API actuelle sépare également les préoccupations de façon plus stricte que la précédente, donc vérifiez que chaque paramètre se trouve sur l'objet qui le possède maintenant :

Ne propagez pas DocOptions.ImageResolution comme contrôle de rendu. Il est obsolète ; définissez BaseConfig.ImageResolution sur la configuration spécifique au format. Passez en revue tous les paramètres par défaut au lieu de supposer qu'une configuration précédente a le même comportement.

11. Le visualiseur côté client — deux changements qui échouent SILENCIEUSEMENT

Tous deux laissent le serveur fonctionner parfaitement. Votre document s'affiche, la page a l'air correcte, et rien n'apparaît dans la console du navigateur. Lisez cette section même si votre C# compile du premier coup.

Les rappels du visualiseur sont désormais des options, pas des fonctions globales

Le visualiseur précédent appelait vos gestionnaires par nom, en dérivant le nom de fonction globale à partir de l'ID du conteneur. Déclarer function ctlDoc_OnViewerReady() sur une page avec <div id="div_ctlDoc"> suffisait. Le visualiseur actuel accepte des rappels explicites dans l'objet options et ne recherche plus ces fonctions globales :

objctlDoc = $("#div_ctlDoc").docViewer({
    // ... vos options existantes ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // a été trouvé par nom
    onViewerReady:    ctlDoc_OnViewerReady,     // a été trouvé par nom
    onCopy:           ctlDoc_Copy,              // était ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // était ctlDoc_AutoLoadStatus(page)
});

Pourquoi c'est problématique : l'ancien appel était enveloppé dans un catch vide, qui avalait tout. Maintenant vos fonctions ne s'exécutent tout simplement jamais et rien ne signale d'erreur. Le symptôme habituel est un indicateur de chargement qui ne s'arrête jamais — parce que la fonction qui le cachait était ctlDoc_OnViewerReady. Le document derrière est correct.

La liste complète des options est onPageLoading, onPageLoaded, onThumbnailClicked, onPageClicked, onDoubleClick, onViewerBusy, onViewerReady, onViewerError, onCopy, onAnnSaved, onAnnSaveError, onAnnLoaded, onAnnClosed, onAutoLoadStatus, onThumbsShown, et onError. Il n'y a pas de rappel de clic sur les liens : la gestion des hyperliens est intégrée, pilotée par showHyperlinks.

ResPath doit pointer vers le préfixe de ressource

ResPath: '',                      // AVANT — les ressources provenaient de la racine de l'application
ResPath: 'doconut-res/images',    // MAINTENANT    — le préfixe UseDoconutResources() monte

Si vous avez modifié le préfixe via DoconutOptions.ResourcesPath, utilisez cette valeur à la place.

12. Barre d’outils du visualiseur, Recherche et Annotation

Ne migrez pas les anciens scripts un par un. Les applications de référence actuelles composent un package de page complet :

1. émettre le CSS du visualiseur et le CSS de Recherche/Annotation sous licence avec ReferenceCss ;
2. rendre la barre d’outils du visualiseur appartenant à l’application ;
3. rendre searchBarMount, annBarMount et le montage du visualiseur requis ;
4. émettre les scripts du visualiseur et des modules sous licence avec ReferenceScripts ;
5. charger le script d’aide de la barre d’outils propre à l’application ;
6. initialiser un objViewer ;
7. initialiser les rubans de Recherche et d’Annotation sous licence ;
8. appeler attach(objViewer) sur chaque ruban ;
9. ouvrir le document et appeler objViewer.View(token).

Recherche et Annotation sont des modules attachés au même visualiseur, pas des barres d’outils indépendantes. La barre d’outils principale appartient à l’application hôte ; les rubans de Recherche et d’Annotation sont intégrés, des ressources conditionnées par les capacités.

Supprimez les fichiers copiés manuellement tels que documentLinks.js et docViewer.UI.js uniquement après que la page actuelle fonctionne avec les ressources émises par ReferenceCss et ReferenceScripts.

13. Enregistrement des plugins

Les méthodes statiques de licence de plugin n’enregistrent pas les plugins actuels. Installez et enregistrez chaque package publié explicitement :

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() valide les capacités des plugins enregistrés au démarrage. Converter et DICOM sont les plugins .NET Standard publiés. La Recherche et l’Annotation normales sont des fonctionnalités sous licence intégrées, pas des packages AddPlugin<TPlugin>().

14. Sécurité des sessions et des documents

L’intégration actuelle lie les documents à des jetons opaques et à des sessions en cache. Avec le UnsafeMode = false par défaut, UseDoconut() ajoute la sécurité d’accès aux documents et l’hôte doit configurer la session ASP.NET :

builder.Services.AddDistributedMemoryCache(); // l'état de session nécessite un cache (MVC/Razor Pages en ajoute déjà un)
builder.Services.AddSession();
app.UseSession();

Conservez DocOptions.IsSecured = true sauf si une conception révisée l’exige autrement. N’utilisez jamais UnsafeMode = true comme raccourci de migration sur un seul nœud. Testez les requêtes sans jeton, avec un jeton malformé, un jeton expiré et un jeton provenant d’une session de navigateur différente.

Dans un farm, la requête de page peut aboutir sur un nœud qui n’a jamais vu la requête d’ouverture, de sorte que la vérification par session la rejetterait. C’est le seul cas où UnsafeMode = true est correct — et il doit être associé à des tickets d’accès signés via AddDoconutDistributedDocumentSecurity, pas fourni seul. Voir Déploiements distribués.

Note de nommage

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.

15. Ordre de travail suggéré

1. Confirmez que le framework hôte peut consommer netstandard2.1. S’il ne le peut pas, arrêtez.
2. Mettez à jour le package vers 26.8.0 et compilez. Traitez les erreurs de compilation — la plupart sont les lignes using dans §1.
3. Déplacez le démarrage vers AddDoconut() et les appels middleware dans leur nouvel ordre (§3, §4).
4. Injectez Viewer là où vous le construisiez, rendez OpenDocument asynchrone, et supprimez InitCache() (§5, §6).
5. Si vous utilisez le farm web, effectuez §7 — la seule partie qui est une refonte plutôt qu’un renommage.
6. Si vous convertissez des documents, effectuez §8.
7. Effectuez §11 — les changements côté client. Ce sont ceux qui ne s’annonceront pas eux-mêmes.
8. Ouvrez un vrai document dans un navigateur et observez le spinner d’attente. Une construction verte ne prouve rien ici : la licence, l’enregistrement des plugins, le chemin de ressource et les rappels du visualiseur échouent tous uniquement à l’exécution. Pour un farm, vérifiez qu’un document publié par un nœud est servi par un autre.

Test de la migration

Au minimum, vérifier :

• démarrage de l'application avec la licence de production et chaque plugin enregistré ;
• CSS/scripts du Viewer et toutes les requêtes d'images de page sous les chemins choisis ;
• ouverture du document, navigation, zoom, vignettes, impression et fermeture explicite ;
• Recherche dans un document contenant du texte et l'état non recherchable d'un fichier uniquement image ;
• Chargement, sauvegarde, exportation des annotations et contrôle des capacités ;
• Découverte des cibles du convertisseur, sortie, téléchargement et état du filigrane ;
• Pages DICOM, trames et animation ; les métadonnées techniques ne sont pas disponibles dans ce paquet ;
• documents protégés par mot de passe, polices personnalisées, texte non latin et délais d'attente configurés ;
• rejet de jeton entre sessions et comportement de session expirée ;
• pour un farm : publier sur un nœud, demander une page tardive depuis un autre, et confirmer que le viewer relance les réponses 202 au lieu d'afficher des tuiles cassées ;
• mobile, mode sombre et le chemin du reverse-proxy de production.

Plan de retour en arrière

Conservez l'artifact de déploiement précédent, les paquets correspondants, les fichiers de licence et les ressources du navigateur copiées ensemble. Un retour en arrière sûr bascule toute la génération d'application ; il ne mélange pas un serveur de génération précédente avec les scripts actuels, ni un serveur actuel avec les sites d'appel new Viewer(...).

Avant la bascule, documentez :

• l'emplacement ou l'artefact de déploiement utilisé pour le retour en arrière ;
• l'impact du stockage partagé, le cas échéant — les artefacts publiés par la version 26.8.0 ne sont pas consommés par le middleware du web-farm précédent ;
• comment les sessions de documents actives seront invalidées ;
• le contrôle de santé et le document de test utilisé pour décider du retour en arrière ;
• qui peut restaurer l'ensemble de paquets et la configuration précédents.

Documentation historique

Le manuel précédent traduit reste disponible à l'adresse Configuration .NET Standard Legacy. La Passerelle d'intégration précédente explique les mêmes signaux d'identification et renvoie à ce guide de migration.

Conservez l'URL historique dans les favoris et les tickets de support tant que les installations netstandard2.0 existent. Elle documente une génération différente et n'est pas redirigée vers l'API actuelle.