OnlyOffice Editor (WebForms) — comportamiento real del control

Este proyecto expone un UserControl reutilizable para incrustar OnlyOffice Document Server en ASP.NET WebForms (.NET Framework 4.7.2).

La integración actual funciona así:

1. El servidor guarda/expone el archivo fuente en App_Data/uploads.
2. El control genera document.url, editorConfig.callbackUrl y token JWT.
3. En PreRender, el control registra scripts e inicializa DocsAPI.DocEditor.
4. Para obtener el editado, el cliente llama downloadAs() y recibe una URL temporal (onDownloadAs).
5. Si se requiere postback WebForms, esa descarga se convierte a base64 y se guarda en un HiddenField.

Importante: el endpoint callback no persiste automáticamente la versión editada; solo responde {"error":0}.

Estructura relevante

Controls/
  OnlyOfficeEditor.ascx
  OnlyOfficeEditor.ascx.cs

Scripts/
  OnlyOfficeEditor.js

Handlers/
  OnlyOfficeHandler.ashx
  OnlyOfficeHandler.ashx.cs

App_Code/
  OnlyOfficeJwt.cs

Flujo del control

1) Cargar documento

Puedes cargar desde bytes, archivo físico o fileId existente:

docEditor.SetDocumentFromBytes(fileBytes, "contrato.docx");
// o
docEditor.SetDocumentFromFile(@"C:\docs\contrato.docx");
// o
docEditor.SetDocumentFromUpload(fileId, "contrato.docx");

SetDocumentFromBytes guarda el archivo en App_Data/uploads/<fileId>.<ext> y configura:

• DocumentUrl = .../Handlers/OnlyOfficeHandler.ashx?action=download&fileId=...
• CallbackUrl = .../Handlers/OnlyOfficeHandler.ashx?action=callback&fileId=...
• DocumentKey derivada de fileId

2) Render e inicialización

En Page_PreRender:

• Se construye ConfigJson firmado con JWT (OnlyOfficeJwt.Create(...)).
• Se registra OnlyOfficeApiUrl (script api.js de Document Server).
• Se registra ~/Scripts/OnlyOfficeEditor.js.
• Se registra window.__onlyOfficeProxyUrl apuntando a action=proxy.
• Se ejecuta OnlyOfficeEditorModule.init(containerId, config).

3) Obtener el documento editado

El módulo JS no lee el archivo desde callback. El flujo real es:

• getEditedDocumentUrl(containerId) llama editor.downloadAs().
• OnlyOffice dispara onDownloadAs con la URL temporal del archivo editado.
• getEditedDocumentBlob(containerId) descarga ese URL usando action=proxy (server-to-server) para evitar CORS del browser.

4) Captura para postback WebForms

Si defines CaptureTriggerId, el control intercepta el click del botón indicado:

1. Ejecuta OnlyOfficeEditorModule.captureToHiddenField(...).
2. Convierte el blob a base64.
3. Lo guarda en hfEditedDocumentBase64.
4. Dispara __doPostBack al control origen.

En el evento del botón del servidor puedes hacer:

var bytes = docEditor.GetEditedDocumentBytes();
if (bytes != null)
{
    // guardar o descargar
    docEditor.ClearEditedDocument();
}

Propiedades del control

Configurables

Solo lectura / estado

API JavaScript disponible (Scripts/OnlyOfficeEditor.js)

Todas reciben containerId como primer parámetro.

• init(containerId, config, options?)
• getEditedDocumentUrl(containerId) : Promise<string>
• getEditedDocumentBlob(containerId) : Promise<Blob>
• downloadDocument(containerId, fileName?) : Promise<string>
• captureToHiddenField(containerId, hiddenFieldId, options?) : Promise<string>
• getEditor(containerId)
• destroy(containerId)
• setBusy(containerId, isBusy)

captureToHiddenField es la base del flujo WebForms de “capturar y luego procesar en OnClick”.

Endpoints del handler (OnlyOfficeHandler.ashx)

Ejemplo real del proyecto (Default.aspx)

<oo:Editor ID="docEditor" runat="server" CaptureTriggerId="btnDescargar" />

• btnUpload_Click: llama SetDocumentFromBytes(...).
• btnDescargar_Click: lee GetEditedDocumentBytes() y responde descarga HTTP.

Este patrón ya está implementado en la página principal del repositorio.

Configuración mínima para que funcione

1. OnlyOfficeApiUrl debe apuntar al api.js real de tu Document Server.
2. PublicBaseUrl debe ser alcanzable desde Document Server.
3. JwtSecret debe coincidir en app y Document Server.
4. Asegura permisos de escritura en App_Data/uploads.

Limitaciones actuales

• No hay limpieza automática de App_Data/uploads.
• callback no descarga/guarda la versión final (si lo necesitas, debes implementarlo ahí).
• El control inyecta defaults de personalización UI en JS (compactToolbar, hideRightMenu, etc.).
• Los defaults de URL/secreto están hardcodeados para entorno local; mover a Web.config antes de producción.