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. Una referencia de paquete, archivo de bloqueo o .nupkg en caché, por lo tanto, no identifica la API de alojamiento por sí sola. Registre la versión exacta del paquete e inspeccione Program.cs, la construcción del viewer, la apertura de documentos y los scripts del navegador en conjunto.

La versión 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 central.

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, cada llamada new Viewer(...), cada llamada de carga de licencia, cada script Doconut copiado, cada acción personalizada de barra de herramientas y cada 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 actual, el comportamiento de seguridad, las fuentes y la configuración de la plataforma.

Migre un entorno antes de cambiar 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 > descubrimiento automático

El descubrimiento automático busca archivos Doconut.Viewer.lic y Doconut.Viewer.<Capability>.lic asociados. 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 asociados juntos cuando use descubrimiento automático, reinicie después de cambiar una licencia y verifique las capacidades mediante 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 de acceso a la solicitud:

// Integración clásica — solo como contraste; no compile esto contra 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.AddSession();

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

Viewer es un servicio transitorio. El gestor de sesiones de documento y su caché poseen el estado del documento a más largo plazo, 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 URLs 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 la canalización simple del 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 del Viewer

Elimine las cachés de objetos Viewer propiedad de la aplicación. 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 y no lo incluya en análisis.

Apertura y cierre de documentos

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

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

Las sobrecargas actuales aceptan una ruta de archivo o stream, 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 transfiera DocOptions.ImageResolution como control de renderizado. Está obsoleto; establezca BaseConfig.ImageResolution en la configuración específica del formato. Revise todos los valores predeterminados en lugar de asumir que una configuración clásica tiene el mismo comportamiento.

Barra de herramientas del Viewer, Search y Annotation

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

1. emita CSS del Viewer y CSS licenciado de Search/Annotation con ReferenceCss;
2. renderice la barra de herramientas del Viewer propiedad de la aplicación;
3. renderice searchBarMount, annBarMount y el montaje requerido del Viewer;
4. emita scripts del Viewer y módulos licenciados con ReferenceScripts;
5. cargue el propio viewerToolbar.js de la aplicación;
6. inicialice un objViewer;
7. inicialice las Cintas licenciadas de Search y Annotation;
8. llame a attach(objViewer) en cada Cinta;
9. abra el documento y llame a objViewer.View(token).

Search y Annotation son módulos adjuntos al mismo Viewer, no barras de herramientas independientes. La barra de herramientas principal pertenece a la aplicación host; las Cintas de Search y Annotation son recursos incrustados y controlados por 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 plugins

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

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

AddDoconut() valida las capacidades de los plugins registrados en el inicio. Converter y DICOM son plugins .NET 6 liberados. Search y Annotation normales son funciones licenciadas integradas, no paquetes AddPlugin<TPlugin>().

Seguridad de sesión y documento

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

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

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

La aplicación de referencia Distributed añade tickets de acceso y detalles de transporte. esas API no son obligatorias 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 plugins registrados;
• CSS/scripts del Viewer y todas las solicitudes de imágenes de página bajo las rutas elegidas;
• apertura de documento, navegación, zoom, miniaturas, impresión y cierre explícito;
• Search en un documento con texto y el estado no buscable de un archivo solo de imagen;
• carga, guardado, exportación y control de capacidades de Annotation;
• descubrimiento de objetivo del Converter, salida, descarga y estado de marca de agua;
• páginas DICOM, fotogramas y animación; los metadatos técnicos de .NET 6 no están disponibles;
• documentos protegidos con contraseña, fuentes personalizadas, texto no latino y tiempos de expiración configurados;
• rechazo de token entre sesiones y comportamiento de sesión expirada;
• dispositivos móviles, modo oscuro y la ruta del proxy inverso de producción.

Plan de reversión

Conserve 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 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 existan instalaciones clásicas. Documenta una generación diferente y no redirige a la API actual.