Migrar desde la integración clásica .NET 6

Doconut tiene dos integraciones distintas de .NET 6. Pueden usar el mismo nombre de paquete Doconut.NET6, así que identifique la generación a partir de las API en la aplicación antes de cambiar paquetes, inicio, licencias o recursos del navegador.

¿Qué integración .NET 6 está utilizando?

Si ambas columnas aparecen en la misma aplicación, trate la migración como incompleta. No envíe un token de documento a través de recursos o middleware de la otra generación.

Por qué el nombre del paquete NuGet puede no indicarle

Ambas generaciones se han distribuido bajo el ID de paquete Doconut.NET6. Por lo tanto, una referencia de paquete, archivo de bloqueo o .nupkg en caché no identifica por sí mismo la API de alojamiento. Registre la versión exacta del paquete e inspeccione Program.cs, la construcción del visor, la apertura de documentos y los scripts del navegador juntos.

La versión actual auditada para esta guía es Doconut.NET6 26.7.0. Sus paquetes públicos opcionales son Doconut.NET6.Converter y Doconut.NET6.Dicom, fijados a la misma versión de lanzamiento que el paquete principal.

Antes de migrar

1. Cree una rama y una copia de seguridad desplegable de la aplicación existente.
2. Registre las versiones exactas del paquete principal y de los complementos.
3. Inventarice cada mapeo DocImage.axd, llamada new Viewer(...), llamada de carga de licencia, script Doconut copiado, acción de barra de herramientas personalizada y punto final de apertura de documento.
4. Preserve los archivos .lic actuales y los secretos de despliegue fuera del control de versiones.
5. Capture un conjunto representativo de documentos PDF, Office, imagen, CAD, correo electrónico, DICOM, buscables, protegidos con contraseña y anotados.
6. Registre el tiempo de expiración de sesión existente, el comportamiento de seguridad, las fuentes y la configuración de la plataforma.

Migre un entorno antes de cambiar la producción. La integración actual cambia la vida útil del servicio, el enrutamiento de solicitudes, la propiedad de la sesión y la entrega de recursos al cliente.

Compatibilidad de paquetes y licencias

Reemplace o actualice deliberadamente el paquete principal; no confíe en el ID de paquete idéntico para seleccionar la nueva API. El comando predeterminado instala la última versión estable:

dotnet add package Doconut.NET6

Para una migración reproducible a la versión auditada por esta guía, pase la versión como una opción separada:

dotnet add package Doconut.NET6 --version 26.7.0

Mantenga cada complemento Doconut en la misma versión que el paquete principal. La integración actual carga licencias una vez durante AddDoconut(), usando esta precedencia:

LicenseStream > LicenseContent > LicensePath > descubrimiento automático

El descubrimiento automático busca archivos Doconut.Viewer.lic y sus compañeros Doconut.Viewer.<Capability>.lic. Una llamada clásica a Viewer.DoconutLicense(...) o Viewer.SetLicensePlugin(...) no es un mecanismo de inicio actual. Mueva la licencia a DoconutOptions, mantenga los archivos compañeros juntos al usar el descubrimiento automático, reinicie después de cambiar una licencia y verifique las capacidades a través de IDoconutLicenseService.

No asuma que la presencia de una licencia de complemento antigua prueba la elegibilidad para una compilación de complemento actual. Pruebe Visor, Búsqueda, Anotación, Convertidor y DICOM por separado con los artefactos de la versión aprobada.

Inicio e inyección de dependencias

Las aplicaciones clásicas construyen Viewer con caché de ASP.NET y dependencias de request-accessor:

// Integración clásica — solo para contraste; no compile esto con el SDK actual.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

La integración actual registra Doconut una vez y recibe Viewer mediante inyección de dependencias:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddSession();

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

Viewer es un servicio transitorio. El gestor de sesión de documentos y su caché poseen el estado del documento de mayor duración, no la instancia inyectada específica de Viewer.

Middleware y enrutamiento de recursos

Elimine la rama clásica MapWhen que detecta DocImage.axd:

// Integración clásica — eliminar durante la migración.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

En la canalización actual:

1. llame a UseSession() antes de Doconut mientras la seguridad de sesión está habilitada;
2. llame a UseDoconutResources() antes de UseDoconut();
3. mantenga ResourcesPath, las URL de recursos generadas y el ResPath del cliente alineados;
4. al mapear UseDoconut() a una rama, mantenga esa rama y el BasePath del cliente alineados.

MiddlewarePath es una configuración validada; no crea una rama de ASP.NET Core por sí mismo. Use ya sea la canalización simple en el ejemplo de compilación anterior o una disposición explícita app.Map("/doconut", branch => branch.UseDoconut()) utilizada de forma consistente por el cliente.

Construcción y ciclo de vida de Viewer

Elimine las cachés de la aplicación que poseen objetos Viewer. Inyecte Viewer en un endpoint, página Razor, controlador o servicio de aplicación con alcance:

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

El token devuelto identifica una sesión de documento del lado del servidor. Trátelo como una credencial portadora: no lo registre, no lo persista ni lo incluya en análisis.

Apertura y cierre de documentos

Reemplace OpenDocument(...) síncrono con OpenDocumentAsync(...):

// Integración actual de .NET 6: Viewer proviene de DI y la apertura del documento es asíncrona.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Las sobrecargas actuales aceptan una ruta de archivo o flujo, una configuración de formato opcional, DocOptions opcional y un token de cancelación. Cierre la sesión del servidor explícitamente cuando el navegador ya no la necesite:

viewer.CloseDocument(token);

No reutilice un token clásico después de la migración. Abra cada documento nuevamente a través de la API actual.

Clases de configuración

La API actual separa las preocupaciones:

No transfiera DocOptions.ImageResolution como control de renderizado. Está obsoleto; establezca BaseConfig.ImageResolution en la configuración específica del formato. Revise todas las configuraciones predeterminadas en lugar de asumir que una configuración clásica tiene el mismo comportamiento.

Barra de herramientas de Viewer, Búsqueda y Anotación

No migre los scripts antiguos uno por uno. Las aplicaciones de referencia actuales componen un paquete de página completo:

1. emita el CSS de Viewer y el CSS con licencia de Búsqueda/Anotación con ReferenceCss;
2. renderice la barra de herramientas de Viewer propiedad de la aplicación;
3. renderice searchBarMount, annBarMount y el montaje requerido de Viewer;
4. emita los scripts de Viewer y los módulos con licencia con ReferenceScripts;
5. cargue el propio viewerToolbar.js de la aplicación;
6. inicialice un objViewer;
7. inicialice las cintas con licencia de Búsqueda y Anotación;
8. llame a attach(objViewer) en cada cinta;
9. abra el documento y llame a objViewer.View(token).

Búsqueda y Anotación son módulos adjuntos al mismo Viewer, no barras de herramientas independientes. La barra de herramientas principal pertenece a la aplicación anfitriona; las cintas de Búsqueda y Anotación están incrustadas, recursos con control de capacidades.

Elimine los archivos clásicos copiados manualmente como documentLinks.js y docViewer.UI.js solo después de que la página actual funcione con los recursos emitidos por ReferenceCss y ReferenceScripts.

Registro de complementos

Los métodos clásicos estáticos de licencia de complementos no registran los complementos actuales. Instale y registre cada paquete lanzado explícitamente:

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

AddDoconut() valida las capacidades de los complementos registrados al iniciar. Converter y DICOM son complementos .NET 6 lanzados. Búsqueda Normal y Anotación son funciones con licencia incorporadas, no paquetes AddPlugin<TPlugin>().

Seguridad de sesión y documento

La integración actual vincula los documentos a tokens opacos y sesiones en caché. Con el valor predeterminado UnsafeMode = false, UseDoconut() agrega seguridad de acceso a documentos y el host debe configurar la sesión de ASP.NET:

builder.Services.AddSession();
app.UseSession();

Mantenga DocOptions.IsSecured = true a menos que un diseño revisado requiera lo contrario. Nunca use UnsafeMode = true como atajo de migración. Pruebe solicitudes sin token, con token malformado, con token expirado y con un token de una sesión de navegador diferente.

La aplicación de referencia Distributed agrega tickets de acceso y detalles de transporte. esas API no son requeridas para una migración normal de un solo nodo.

Pruebas de la migración

Como mínimo, verifique:

• el inicio de la aplicación con la licencia de producción y todos los complementos registrados;
• CSS/scripts del visor y todas las solicitudes de página‑imagen bajo las rutas elegidas;
• apertura del documento, navegación, zoom, miniaturas, impresión y cierre explícito;
• búsqueda en un documento con texto y el estado no buscable de un archivo solo de imagen;
• carga, guardado, exportación y control de capacidad de anotaciones;
• descubrimiento del objetivo del convertidor, salida, descarga y estado de la marca de agua;
• páginas, fotogramas y animación DICOM; los metadatos técnicos de .NET 6 no están disponibles;
• documentos protegidos con contraseña, fuentes personalizadas, texto no latino y tiempos de espera configurados;
• rechazo de token entre sesiones y comportamiento de sesión expirada;
• móvil, modo oscuro y la ruta del proxy inverso de producción.

Plan de reversión

Mantenga el artefacto de despliegue clásico, los paquetes coincidentes, los archivos de licencia y los recursos del navegador copiados juntos. Una reversión segura cambia toda la generación de la aplicación; no mezcla un servidor clásico con los scripts actuales ni un servidor actual con llamadas clásicas DocImage.axd.

Antes de la transición, documente:

• la ranura o artefacto de despliegue usado para la reversión;
• el impacto en la base de datos/caché, si lo hay;
• cómo se invalidarán las sesiones de documento activas;
• la verificación de salud y el documento de prueba usado para decidir la reversión;
• quién puede restaurar el conjunto de paquetes y la configuración anteriores.

Documentación heredada

El manual clásico traducido sigue disponible en Legacy .NET 6 setup. El nuevo Classic integration gateway explica las mismas señales de identificación y enlaza de nuevo a esta guía de migración.

Mantenga la URL histórica en marcadores y tickets de soporte mientras las instalaciones clásicas aún existan. Documenta una generación diferente y no se redirige a la API actual.