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

Mover una aplicación existente de Doconut.NET6 a la DI actual y la API asíncrona

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 de .NET 6 está utilizando?

Si el proyecto contiene…Generación
app.MapWhen(... "DocImage.axd" ...)Legado / clásico
new Viewer(_cache, _accessor, ...)Legado / clásico
Viewer.DoconutLicense(...) o Viewer.SetLicensePlugin(...)Legado / clásico
Copiados manualmente docViewer.js, documentLinks.js, o docViewer.UI.jsLegado / clásico
builder.Services.AddDoconut(...)Integración actual
app.UseDoconutResources() más app.UseDoconut()Integración actual
Viewer suministrado por inyección de dependenciasIntegración actual
await viewer.OpenDocumentAsync(...)Integración actual

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. Por lo tanto, una referencia de paquete, archivo de bloqueo o .nupkg en caché no identifica la API de alojamiento por sí sola. 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 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 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:

bash
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:

bash
dotnet add package Doconut.NET6 --version 26.9.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:

text
LicenseStream > LicenseContent > LicensePath > automatic discovery

El descubrimiento automático busca Doconut.Viewer.lic y 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 complemento antigua prueba la autorización para una compilación de complemento actual. Pruebe Viewer, Search, Annotation, Converter y DICOM por separado con los artefactos de la versión aprobada.

Inicio y inyección de dependencias

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

csharp
// Integración clásica — solo contraste; no compile esto contra 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:

csharp
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 sesión de documentos y su caché poseen el estado del documento de mayor duración, no la instancia inyectada Viewer en particular.

Middleware y enrutamiento de recursos

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

csharp
// 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 el cliente ResPath alineados;
  4. al mapear UseDoconut() a una rama, mantenga esa rama y el cliente BasePath alineados.

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

Construcción y tiempo de vida del visor

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

csharp
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(...) síncrono con OpenDocumentAsync(...):

csharp
// 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 lo necesite:

csharp
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 las preocupaciones:

PreocupaciónTipo actual
Rutas de middleware, licencias, registro de complementosDoconutOptions
Contraseña, tiempo de espera, seguridad, marca de aguaDocOptions
Renderizado de formato y DPIPdfConfig, WordConfig, ExcelConfig, y otros tipos BaseConfig
Valores predeterminados del widget del navegadorViewerConfig o las opciones JavaScript equivalentes
CSS y scripts generadosCssConfig y ScriptConfig

No lleve DocOptions.ImageResolution adelante como el 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 visor, 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 del visor y CSS licenciado de Búsqueda/Anotación con ReferenceCss;
  2. renderice la barra de herramientas del visor propiedad de la aplicación;
  3. renderice searchBarMount, annBarMount y el montaje requerido del visor;
  4. emita scripts del visor 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 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 visor, 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 embebidas, recursos con acceso controlado 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 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:

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

AddDoconut() valida las capacidades de complementos registradas al iniciar. Converter y DICOM son complementos .NET 6 publicados. 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 UnsafeMode = false predeterminado, UseDoconut() agrega seguridad de acceso a documentos y el host debe configurar la sesión ASP.NET:

csharp
builder.Services.AddDistributedMemoryCache(); // el estado de sesión necesita una caché (MVC/Razor Pages ya agrega 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 un atajo de migración. Pruebe solicitudes sin token, con un token malformado, un token expirado y un token de una sesión de navegador diferente.

La aplicación de referencia distribuida agrega tickets de acceso y detalles de transporte. esas APIs no son necesarias 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 cada complemento registrado;
  • 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 capacidades de anotaciones;
  • descubrimiento del objetivo del conversor, 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 scripts actuales o un servidor actual con llamadas clásicas DocImage.axd.

Antes de la conmutació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 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 de .NET 6. El nuevo Puerta de enlace de integración clásica explica las mismas señales de identificación y enlaza de regreso 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.

¿Fue útil esta página?