Migrer depuis l'intégration classique .NET 6

Doconut possède deux intégrations .NET 6 distinctes. Elles peuvent utiliser le même nom de package Doconut.NET6, il faut donc identifier la génération à partir des API dans l'application avant de modifier les packages, le démarrage, les licences ou les ressources du navigateur.

Quelle intégration .NET 6 utilisez‑vous ?

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

Pourquoi le nom du package NuGet ne vous indique pas forcément

Les deux générations ont été publiées sous l’ID de package Doconut.NET6. Une référence de package, un fichier de verrouillage ou un .nupkg mis en cache n’identifient donc pas l’API d’hébergement à eux seuls. Enregistrez la version exacte du package et examinez Program.cs, la construction du viewer, l’ouverture de documents et les scripts du navigateur ensemble.

La version actuelle auditée pour ce guide est Doconut.NET6 26.7.0. Ses packages publics optionnels sont Doconut.NET6.Converter et Doconut.NET6.Dicom, épinglés à la même version de publication que le package principal.

Avant de migrer

1. Créez une branche et une sauvegarde déployable de l’application existante.
2. Enregistrez les versions exactes du package principal et des plugins.
3. Inventoriez chaque mappage DocImage.axd, appel new Viewer(...), appel de chargement de licence, script Doconut copié, action de barre d’outils personnalisée 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 et la livraison des ressources client.

Compatibilité des packages et des licences

Remplacez ou mettez à jour le package principal délibérément ; ne comptez pas sur le même ID de package pour sélectionner la nouvelle API. La commande par défaut installe la dernière version stable :

dotnet add package Doconut.NET6

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.NET6 --version 26.7.0

Conservez chaque plugin Doconut à la même version que le package principal. 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. Un appel classique à Viewer.DoconutLicense(...) ou Viewer.SetLicensePlugin(...) n’est pas un mécanisme de démarrage actuel. 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 changé 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 Viewer, Search, Annotation, Converter et DICOM séparément avec les artefacts de version approuvés.

Démarrage et injection de dépendances

Les applications classiques construisent Viewer avec le cache ASP.NET et les dépendances d'accès aux requêtes :

// Intégration classique — contraste uniquement ; ne compilez pas ceci contre le SDK actuel.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

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

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
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 long terme, pas l'instance particulière injectée Viewer.

Middleware et routage des ressources

Supprimez la branche classique MapWhen qui détecte DocImage.axd :

// Intégration classique — à supprimer pendant la bascule.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

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. lors du mappage de UseDoconut() vers une branche, conservez cette branche et le client BasePath alignés.

MiddlewarePath est une configuration validée ; elle ne crée pas une branche ASP.NET Core par elle-même. Utilisez soit le pipeline simple dans l'exemple de compilation ci‑dessus, soit une disposition explicite app.Map("/doconut", branch => branch.UseDoconut()) utilisée de manière cohérente par le client.

Construction et durée de vie du visualiseur

Supprimez les caches appartenant à l'application des objets Viewer. Injectez Viewer dans un point de terminaison, une page Razor, un contrôleur ou un service d'application à porté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 les analyses.

Ouverture et fermeture des documents

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

// Intégration actuelle .NET 6 : le 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 facultative, un DocOptions optionnel et un jeton d'annulation. Fermez explicitement la session serveur lorsque le navigateur n'en a plus besoin :

viewer.CloseDocument(token);

Ne réutilisez pas un jeton classique après la transition. Ouvrez chaque document à nouveau via l'API actuelle.

Classes de configuration

L'API actuelle sépare les préoccupations :

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 toutes les valeurs par défaut au lieu de supposer qu'une configuration classique a le même comportement.

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 complet de page :

1. générez le CSS du visualiseur et le CSS de Recherche/Annotation sous licence avec ReferenceCss ;
2. rendez la barre d'outils du visualiseur appartenant à l'application ;
3. rendez searchBarMount, annBarMount et le montage du visualiseur requis ;
4. générez les scripts du visualiseur et du module sous licence avec ReferenceScripts ;
5. chargez le viewerToolbar.js propre à l'application ;
6. initialisez un objViewer ;
7. initialisez les rubans de Recherche et d'Annotation sous licence ;
8. appelez attach(objViewer) sur chaque ruban ;
9. ouvrez le document et appelez 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 des ressources intégrées, conditionnées par les capacités.

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

Enregistrement du plugin

Les méthodes classiques de licence de plugin statiques 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 du plugin enregistré au démarrage. Converter et DICOM sont des plugins .NET 6 publiés. Normal Search et Annotation sont des fonctionnalités sous licence intégrées, pas des packages AddPlugin<TPlugin>().

Sécurité de session et de document

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. Testez les requêtes sans jeton, avec un jeton malformé, un jeton expiré, et un jeton provenant d'une session de navigateur différente.

L'application de référence Distributed ajoute des tickets d'accès et des détails de transport. Ces API ne sont pas requises pour une migration normale à nœud unique.

Test de la migration

Au minimum, vérifiez :

• le démarrage de l'application avec la licence de production et chaque plugin enregistré ;
• les CSS/scripts du Viewer et toutes les requêtes d'images de page sous les chemins choisis ;
• l'ouverture du document, la navigation, le zoom, les miniatures, l'impression et la fermeture explicite ;
• la recherche sur un document contenant du texte et l'état non recherchable d'un fichier uniquement image ;
• le chargement, l'enregistrement, l'exportation et le contrôle d'accès des annotations ;
• la découverte des cibles du Converter, la sortie, le téléchargement et l'état du filigrane ;
• les pages, cadres et animations DICOM ; les métadonnées techniques .NET 6 ne sont pas disponibles ;
• les documents protégés par mot de passe, les polices personnalisées, le texte non latin et les délais d'attente configurés ;
• le rejet de jeton entre sessions et le comportement des sessions expirées ;
• le mobile, le mode sombre et le chemin du reverse-proxy de production.

Plan de retour en arrière

Conservez l'artifact de déploiement classique, les packages 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 classique avec les scripts actuels ou un serveur actuel avec des appels DocImage.axd classiques.

Avant la transition, documentez :

• l'emplacement ou l'artifact de déploiement utilisé pour le retour en arrière ;
• l'impact sur la base de données/le cache, le cas échéant ;
• comment les sessions de documents actives seront invalidées ;
• le contrôle de santé et le document de test utilisés pour décider du retour en arrière ;
• qui peut restaurer l'ensemble de packages et la configuration précédents.

Documentation héritée

Le manuel classique traduit reste disponible à l'adresse Configuration .NET 6 héritée. Le nouveau Passerelle d'intégration classique 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 classiques existent encore. Elle documente une génération différente et n'est pas redirigée vers l'API actuelle.