Blazor - Web protocol

The Blazor - Web protocol extends web capabilities for Microsoft Blazor applications, by decoding SignalR MessagePack traffic into a human-readable format for recording and replay.

Note: The Blazor - Web protocol is supported from version 26.3.

Overview

Blazor is a web development tool for building web applications using C# and .NET. Blazor applications generally uses WebSocket connections with binary payloads for client-server communication. The HTTP and WebSocket body buffers are encoded using a SignalR wrapper over MessagePack, which means they are non-human-readable, and represented as byte arrays.

The VuGen Blazor - Web protocol is built on top of the standard web protocol, and extends it with automatic handling of the SignalR MessagePack-encoded buffers. The protocol adds Blazor-specific decoding, replay, and correlation support for supported traffic.

When you record a Blazor application with this protocol, VuGen attempts to decode traffic that matches the Blazor SignalR MessagePack wrapper. Most Blazor websites that use this message format can be decoded correctly, including important initialization traffic required for replay. If traffic does not use the expected MessagePack format, it is handled as regular web traffic and may remain encoded.

If a recording does not contain Blazor-specific messages, the generated script behaves like a regular web script.

After decoding, the script contains human-readable representation of the buffers, thereby improving usability and debugging for Blazor HTTP and WebSocket requests.

The Blazor protocol behaves almost identically to the standard Web protocol. Blazor scripts are always generated in C. Unlike the standard web protocol, JavaScript is not supported as a script language.

Decoding process

Most buffers appear as arguments in web_websocket_send. With the standard Web - HTTP/HTML protocol, these messages appear as raw binary. The Blazor protocol decodes them and automatically wraps them in blazor_convert_from_formatted.

This conversion is generated automatically for supported buffers; no manual conversion step is required for the recorded message.

Only buffers located in the Action section are decoded automatically. Buffers stored in Extra Files, such as WebSocketBuffer.h, remain encoded.

The Blazor conversion APIs ( blazor_convert_from_formatted, blazor_convert_to_formatted, blazor_convert_to_formatted_ex can also be used to convert message content when manually editing script logic. If you have a human-readable payload, you can convert it into the encoded format required for replay. If you have an encoded payload, you can decode it into readable text for inspection or editing. For details, see Blazor - Web functions in the Function Reference.

Example

The following example shows how the same message appears with standard Web - HTTP/HTML recording (encoded buffer) and with Blazor - Web recording (formatted payload plus send call).

Standard Web - HTTP/HTML (encoded):

Copy code 
web_websocket_send("ID=0",
    "Buffer/Bin=\x19\x95\x01\x80\xC0\xB1\x4F\x6F\x52\x65\x6E\x64\x65\x72\x43\x6F\x6D\x70\x6C\x65\x74\x65\x64\x92\x02\xC0",
    "IsBinary=1",
    LAST);

Blazor - Web (decoded and wrapped):

Copy code 
blazor_convert_from_formatted("FormattedData="
    "["
        "1,"
        "{},"
        "null,"
        "\"OnRenderCompleted\","
        "["
            "2,"
            "null"
        "]"
    "]",
    "TargetParam=SIGNALR_MSGPCK_BUFFER_3",
    LAST);

web_websocket_send("ID=0",
    "Buffer/Bin={SIGNALR_MSGPCK_BUFFER_3}",
    "IsBinary=1",
    LAST);

Recording options and runtime settings

The Blazor - Web protocol follows standard web protocol behavior and defaults. It also introduces a set of configuration options that affect how scripts are recorded and regenerated.

Adjust buffer size limit

A new configuration file, blazor.ini, is located in your installation directory (\config\blazor.ini). When a WebSocket send buffer argument exceeds 1,024 bytes, it is automatically moved out of the main Action script file and into a separate header file called WebSocketBuffer.h. Buffers stored in this header file are not decoded.

To keep large buffers in the Action file and have them decoded, increase the size threshold in blazor.ini. You should keep the file in that location and modify its value there, the change will apply for all Blazer scripts. After saving the change, regenerate the script, there is no need to re-record.

Enable Blazor correlation rules

Some IDs and tokens used in Blazor - Web scripts must be correlated to ensure a successful replay. To enable this, select the Blazor checkbox in Recording Options > Correlations > Rules.

Known issues and limitations

Note the following limitations for Blazor - Web scripts:

  • Correlation applies to decoded buffers. If a buffer is not decoded, its content remains in encoded form and cannot be correlated in the generated script.

  • When a decoded value is later correlated, pretty-print formatting may no longer be applied correctly.

  • Some Blazor applications generate dynamic prerender IDs. For example, during recording, the initialization process may include a request containing two prerender IDs, while during replay the application expects three prerender IDs.

    Although the recorded IDs are correlated during replay, the script cannot generate additional dynamic IDs that were not captured during recording. As a result, replay errors may occur, and WebSocket communication with the server may fail.

  • The application performs correlations only on data available in snapshots, and snapshots are not available for WebSocket requests. In some websites, certain dynamic values that require correlation are received through WebSocket responses. Due to current implementation limitations, these values cannot be automatically correlated.

  • Currently, only messages up to 2,097,151 bytes (approximately 2 MB) are supported for encoding and decoding.

  • WebSocket responses received during replay, through callbacks such as OnMessageCB in WebSocketCB.c, can be decoded manually by calling blazor_convert_from_formatted. In some cases, however, manual decoding may fail, when multiple messages are concatenated into a single buffer.

    To decode such messages correctly, they must be separated. However, the separation pattern is not always consistent or predictable, making it difficult to reliably separate concatenated messages. For example, a single buffer may contain a message prefixed with a size byte, followed by a message without a size byte, followed again by a message with a size byte.

    Future improvements may include investigating why messages are concatenated, and identifying methods to prevent or better handle this behavior.

See also