Migrer depuis l'intégration .NET 6 classique

Doconut propose deux intégrations .NET 6 distinctes. Elles peuvent toutes deux utiliser le même nom de package Doconut.NET6, il faut donc identifier la génération à partir des API présentes 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. 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 suffit pas à identifier

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. Notez la version exacte du package et inspectez Program.cs, la construction du viewer, l’ouverture de documents et les scripts du navigateur conjointement.

La version 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 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. Dressez l’inventaire de 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 ainsi que les secrets de déploiement hors du contrôle de source.
5. Capturez un jeu représentatif de documents PDF, Office, image, CAO, e‑mail, DICOM, recherchables, protégés par mot de passe et annotés.
6. Notez le délai d’expiration de session actuel, le comportement de sécurité, les polices et les paramètres de 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 session et la livraison des ressources côté client.

Compatibilité des packages et des 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, passez la version en 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 lors de AddDoconut(), selon la priorité suivante :

LicenseStream > LicenseContent > LicensePath > découverte automatique

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 plus un mécanisme de démarrage actuel. Déplacez la licence vers DoconutOptions, conservez les fichiers compagnons ensemble lorsqu’on utilise la découverte automatique, redémarrez après modification d’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’utiliser une version de plugin actuelle. Testez séparément Viewer, Search, Annotation, Converter et DICOM avec les artefacts de version approuvés.

Démarrage et injection de dépendances

Les applications classiques construisent le Viewer avec le cache ASP.NET et les dépendances d’accès à la requête :

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

L’intégration actuelle enregistre Doconut une seule fois et récupère le 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, pas l’instance Viewer injectée en particulier.

Middleware et routage des ressources

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

// Intégration classique — à supprimer lors du basculement.
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. maintenez ResourcesPath, les URL de ressources générées et le ResPath client alignés ;
4. lors du mappage de UseDoconut() sur une branche, gardez cette branche et le BasePath client alignés.

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

Construction du Viewer et durée de vie

Supprimez les caches appartenant à l’application contenant des objets Viewer. Injectez le 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 de documents

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

// Intégration .NET 6 actuelle : le Viewer provient de l’injection et l’ouverture de 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 le basculement. 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 ; utilisez 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 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 package 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 Viewer requis ;
4. émettez les scripts du Viewer et les 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, pas 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 des plugins

Les méthodes statiques classiques 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 des plugins .NET 6 publiés. Search et Annotation classiques sont des fonctionnalités sous licence intégrées, pas des packages AddPlugin<TPlugin>().

Sécurité des sessions et des documents

L’intégration actuelle lie les documents à des jetons opaques et à des sessions en cache. Avec 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.AddSession();
app.UseSession();

Conservez DocOptions.IsSecured = true sauf conception révisée indiquant le contraire. N’utilisez jamais UnsafeMode = true comme raccourci de migration. Testez les requêtes sans jeton, avec un jeton mal formé, 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 mono‑noeud.

Tests de la migration

Au minimum, vérifiez :

• le démarrage de l’application avec la licence de production et chaque plugin enregistré  ;
• le CSS/les 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 image‑seul  ;
• le chargement, la sauvegarde, l’exportation et le conditionnement des capacités d’annotation  ;
• la découverte de cibles du Converter, la sortie, le téléchargement et l’état du filigrane  ;
• les pages DICOM, les images‑cadres 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 de session expirée  ;
• la compatibilité mobile, le mode sombre et le chemin du reverse‑proxy de production.

Plan de retour arrière

Conservez l’artéfact de déploiement classique, les packages correspondants, les fichiers de licence et les ressources du navigateur copiées ensemble. Un retour arrière sûr bascule toute la génération de l’application ; il ne mélange pas un serveur classique avec des scripts actuels ni un serveur actuel avec des appels classiques DocImage.axd.

Avant le basculement, documentez :

• le slot ou l’artéfact de déploiement utilisé pour le retour arrière  ;
• l’impact sur la base de données/le cache, le cas échéant  ;
• la façon dont les sessions de documents actives seront invalidées  ;
• le contrôle de santé et le document de test utilisé pour décider du retour arrière  ;
• qui peut restaurer l’ensemble précédent de packages et la configuration.

Documentation héritée

Le manuel classique traduit reste disponible à 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 des installations classiques existent. Elle documente une génération différente et n’est pas redirigée vers l’API actuelle.