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 changer 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. Ne transmettez pas un jeton de document via les ressources ou le middleware de l'autre génération.

Pourquoi le nom du package NuGet ne vous indique pas toujours

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'identifie donc pas l'API d'hébergement à elle seule. Notez la version exacte du package et inspectez 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, verrouillé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. Notez 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. Notez 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 du service, le routage des requêtes, la propriété de la session et la livraison des ressources côté client.

Compatibilité des packages et licences

Remplacez ou mettez à jour le package principal de façon délibérée ; ne comptez pas sur l'ID de package identique 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, indiquez la version comme 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 les fichiers 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 d'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 à la requête :

// Intégration classique — uniquement à titre de contraste ; ne pas compiler ceci avec le SDK actuel.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

L'intégration actuelle enregistre Doconut une seule 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.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, et non l'instance particulière de Viewer injectée.

Middleware et routage des ressources

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

// Intégration classique — à supprimer lors de la migration.
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 ResPath client alignés ;
4. lors du mappage de UseDoconut() vers une branche, conservez cette branche et le BasePath client 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 un arrangement explicite app.Map("/doconut", branch => branch.UseDoconut()) utilisé de manière cohérente par le client.

Construction et durée de vie du Viewer

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 un jeton 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 .NET 6 actuelle : le Viewer provient de l'injection de dépendances 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, des DocOptions optionnels, 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 migration. 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 Viewer, Recherche et Annotation

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

1. émettez le CSS du Viewer et le CSS sous licence Search/Annotation avec ReferenceCss ;
2. rendez la barre d'outils du Viewer appartenant à l'application ;
3. rendez searchBarMount, annBarMount et le montage du Viewer requis ;
4. émettez les scripts du Viewer et des modules sous licence avec ReferenceScripts ;
5. chargez le viewerToolbar.js propre à l'application ;
6. initialisez un objViewer ;
7. initialisez les rubans Search et Annotation sous licence ;
8. appelez attach(objViewer) sur chaque ruban ;
9. ouvrez le document et appelez objViewer.View(token).

Search et Annotation sont des modules attachés au même Viewer, et non des barres d'outils indépendantes. La barre d'outils principale appartient à l'application hôte ; les rubans Search et 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 émises 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 des plugins enregistrés 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 la session et du document

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

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 dans un document contenant du texte et l'état non recherchable d'un fichier uniquement image ;
• le chargement, l'enregistrement, l'exportation des annotations et le contrôle des capacités ;
• la découverte des cibles du Converter, la sortie, le téléchargement et l'état du filigrane ;
• les pages DICOM, les trames et l'animation ; 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 change toute la génération de l'application ; il ne mélange pas un serveur classique avec les scripts actuels ou un serveur actuel avec les appels classiques DocImage.axd.

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é 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 Legacy .NET 6. 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. Elle documente une génération différente et n'est pas redirigée vers l'API actuelle.