Convertir texto entre Hexadecimal y Unicode en Business Central con un ControlAddin

En algunos proyectos con Business Central, me he encontrado con la necesidad de trabajar directamente con cadenas codificadas en hexadecimal. Esto es especialmente común cuando integro Business Central con sistemas externos o manejo codificaciones como UTF-16LE. Para resolverlo de manera cómoda, he creado un pequeño Control Add-in que permite convertir de texto Unicode a hexadecimal y viceversa, todo desde una página del sistema.

En el ejemplo que voy a mostrar, utilizo una cadena que contiene caracteres chinos junto con texto latino. Es una forma perfecta de probar cómo se comportan las conversiones con caracteres multilingües. Pero esto no se queda ahí: este desarrollo es fácilmente ampliable a otros formatos de codificación Unicode si necesitas algo más específico.

¡Vamos manos a la obra! 😎

---

🧩 El controladdin que lo hace posible

Empiezo por la definición del controladdin en AL. Aquí indico el script JavaScript que voy a usar y declaro los métodos que se invocarán desde AL, así como los eventos para recibir respuestas desde JavaScript:

controladdin "ConvertHexAndUnicode"
{
    RequestedHeight = 1;
    RequestedWidth = 1;
    Scripts = 'ConvertHexAndUnicode\src\controladdin\ConvertHexAndUnicode\js\script.js';

    event MyEvent()

    procedure hexToUnicode(hex: Text);
    procedure unicodeToHex(unicode: Text);

    event OnHexToUnicode(Result: Text);
    event OnUnicodeToHex(Result: Text);

}

Este controladdin es bastante compacto. Al no tener interfaz visual, lo dejo con tamaño mínimo. Los métodos hexToUnicode y unicodeToHex los puedo llamar desde la página, y los eventos OnHexToUnicode y OnUnicodeToHex me permiten capturar el resultado del lado de AL.

---

🧠 Lógica en JavaScript: trabajando con UTF-16LE

En el script JavaScript es donde realmente sucede la conversión. Aquí explico cada función.

// Convierte texto hexadecimal (UTF-16LE) a texto Unicode legible
function hexToUnicode(hex) {
    const bytes = [];
    for (let i = 0; i < hex.length; i += 2) {
      bytes.push(parseInt(hex.substr(i, 2), 16));
    }

    const buffer = new Uint8Array(bytes).buffer;
    const decoded = new TextDecoder('utf-16le').decode(buffer);

    // Dispara evento a Business Central con el resultado
    Microsoft.Dynamics.NAV.InvokeExtensibilityMethod('OnHexToUnicode', [decoded]);
}

Esta función toma una cadena hexadecimal, que representa caracteres codificados en UTF-16LE. Recorro la cadena de dos en dos caracteres para reconstruir cada byte, y luego los convierto en un ArrayBuffer. Utilizo TextDecoder con la codificación utf-16le para transformar esos bytes en texto legible. Finalmente, devuelvo el resultado usando un evento de extensibilidad que capturo en AL.

// Convierte texto Unicode legible a hexadecimal (UTF-16LE)
function unicodeToHex(text) {
    const buffer = new ArrayBuffer(text.length * 2);
    const view = new DataView(buffer);
    for (let i = 0; i < text.length; i++) {
      view.setUint16(i * 2, text.charCodeAt(i), true); // little-endian
    }

    let hex = '';
    for (let i = 0; i < buffer.byteLength; i++) {
      hex += view.getUint8(i).toString(16).padStart(2, '0');
    }

    // Dispara evento a Business Central con el resultado
    Microsoft.Dynamics.NAV.InvokeExtensibilityMethod('OnUnicodeToHex', [hex.toUpperCase()]);
}

En esta otra función, parto del texto Unicode. Utilizo un ArrayBuffer para guardar cada carácter en dos bytes en formato little-endian. Recorro el buffer y convierto cada byte en una representación hexadecimal. De nuevo, disparo el resultado con InvokeExtensibilityMethod. Todo el proceso está pensado para trabajar directamente con UTF-16LE, que es compatible con la mayoría de sistemas externos que me he encontrado.

---

🧪 Página de pruebas: lanzando conversiones desde Business Central

Para probar el controladdin de forma práctica, he montado una página tipo Card con dos acciones: una para convertir hexadecimal a texto y otra para hacer lo contrario.

page 55000 "Pruebas Unicode - Hex"
{
    ApplicationArea = All;
    Caption = 'Pruebas Unicode - Hex';
    PageType = Card;
    UsageCategory = Administration;
    Editable = false;

    layout
    {
        area(content)
        {
            usercontrol(Convert; "ConvertHexAndUnicode")
            {
                ApplicationArea = All;

                trigger OnHexToUnicode(Result: Text)
                begin
                    Message('Texto convertido desde Hex: %1', Result);
                end;

                trigger OnUnicodeToHex(Result: Text)
                begin
                    Message('Texto convertido a Hex: %1', Result);
                end;
            }
        }
    }

    actions
    {
        area(processing)
        {
            action("jbc ConvertirHex")
            {
                Caption = ' Hex ➝ Unicode';
                ApplicationArea = All;
                ToolTip = ' ';
                trigger OnAction()
                begin
                    CurrPage.Convert.hexToUnicode('11629C55226B200041006500730076006100');
                end;
            }

            action("jbc ConvertirTexto")
            {
                Caption = ' Unicode ➝ Hex';
                ApplicationArea = All;
                ToolTip = ' ';
                trigger OnAction()
                begin
                    CurrPage.Convert.unicodeToHex('我喜欢 Aesva'); // Me gusta Aesva
                end;
            }
        }
    }
}

Con estas dos acciones, puedo ver directamente cómo se transforma una cadena hexadecimal en caracteres Unicode (en este caso: 我喜欢 Aesva), y cómo esa misma cadena vuelve a convertirse a hexadecimal. Es un buen ejemplo para ver cómo se codifican los caracteres chinos y los latinos de forma conjunta. Además, lo puedo usar como base para extenderlo a otros tipos de codificación si lo necesito en el futuro.

---

🚀 Aplicaciones prácticas y posibles extensiones

Este controladdin me resulta útil en varios contextos:

• Validación de codificación: para comprobar que los datos que recibo o envío están correctamente codificados.
• Integraciones: cuando trabajo con APIs o sistemas externos que requieren texto codificado en hexadecimal.
• Análisis: cuando tengo que interpretar errores o registros que vienen en formato hex.
• Formación y aprendizaje: porque es una forma práctica de ver cómo funciona UTF-16LE en la práctica.
• Ampliaciones: el ejemplo está basado en UTF-16LE, pero puedo modificar el JavaScript para soportar UTF-8 o cualquier otro formato si lo necesito.

---

✅ Conclusión

Con este ejemplo he querido mostrar cómo integrar un conversor entre texto y hexadecimal en Business Central de forma sencilla y funcional. La combinación de un pequeño controladdin con JavaScript me permite gestionar conversiones de texto Unicode sin depender de herramientas externas.

Si quieres ver el código completo, está en GitHub.

¡Gracias por leer! Espero que te resulte útil en tus próximos desarrollos.