Migrar de 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 indicarlo

Ambas generaciones se han distribuido bajo el ID de paquete Doconut.NET6. Una referencia de paquete, archivo de bloqueo o .nupkg en caché, por lo tanto, no identifica por sí sola la API de alojamiento. Registre la versión exacta del paquete y examine Program.cs, la construcción del viewer, la apertura de documentos y los scripts del navegador en conjunto.

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 central y de los plugins.
3. Inventaríe 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 documentos.
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, imágenes, 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 modifica 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 central; no confíe en que el ID de paquete idéntico seleccione 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 plugin Doconut en la misma versión que el paquete central. La integración actual carga licencias una sola vez durante AddDoconut(), usando esta precedencia:

LicenseStream > LicenseContent > LicensePath > automatic discovery

El descubrimiento automático busca Doconut.Viewer.lic y los archivos complementarios 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 complementarios 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 plugin antigua pruebe el derecho a una compilación de plugin actual. Pruebe Viewer, Search, Annotation, Converter y DICOM por separado con los artefactos de lanzamiento aprobados.

Inicio y inyección de dependencias

Las aplicaciones clásicas construyen Viewer con dependencias de caché ASP.NET y accesor de solicitud:

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

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

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 es un servicio transitorio. El gestor de sesiones 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 transició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 ResPath del cliente alineados;
4. al mapear UseDoconut() a una rama, mantenga esa rama y 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 vida útil 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 ámbito:

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 coloque en análisis.

Apertura y cierre de documentos

Reemplace OpenDocument(...) sincrónico 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 transición. Abra cada documento nuevamente a través de la API actual.

Clases de configuración

La API actual separa preocupaciones:

No transporte DocOptions.ImageResolution como control de renderizado. Está obsoleto; establezca BaseConfig.ImageResolution en la configuración específica de formato. Revise todos los valores predeterminados 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 CSS de Viewer y CSS con licencia de Búsqueda/Anotación mediante ReferenceCss;
2. renderice la barra de herramientas de Viewer propia de la aplicación;
3. renderice searchBarMount, annBarMount y el montaje de Viewer requerido;
4. emita scripts de Viewer y módulos con licencia mediante 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 capacidad.

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 de licencia estática 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 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.AddDistributedMemoryCache(); // el estado de sesión necesita una caché (MVC/Razor Pages ya añaden una)
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, token expirado y 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 necesarias para una migración normal de un solo nodo.

Pruebas de la migración

Como mínimo, verifique:

• 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 de 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 de anotaciones y control de capacidades;
• descubrimiento de objetivo del conversor, salida, descarga y estado de 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;
• modo 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 scripts actuales ni un servidor actual con llamadas clásicas a DocImage.axd.

Antes del cambio, documente:

• la ranura de despliegue o artefacto usado para la reversión;
• el impacto en la base de datos/caché, si lo hay;
• cómo se invalidarán las sesiones de documentos 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 Configuración heredada .NET 6. El nuevo Portal de integración clásica 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.