Getting Started
Architecture
NServiceBus
Transports
Persistence
ServiceInsight
ServiceControl
Monitoring
Samples

Fixing malformed messages

Component: ServicePulse

If a message cannot be successfully retried it is possible to fix the malformed message prior to retrying it. Both the headers and the body of a message can be edited. This capability can be accessed when looking at an individual message.

Edit Malformed Messages

Enabling the feature

The feature in ServicePulse is enabled via the configuration file for ServiceControl:

  1. Find the ServiceControl installation directory using ServiceControl Management Utility.
  2. Edit the ServiceControl configuration file ServiceControl.exe.config with elevated privileges.
  3. Add the following entry in the <appSettings> section of the file:
    <add key="ServiceControl/AllowMessageEditing" value="true" />
    
  4. Restart ServiceControl.

Headers

Headers on all failed messages can be edited using this feature. There are three categories of headers, each with different editing restrictions.

Editing Headers

  • Locked headers: Headers that are critical to the operation of NServiceBus cannot be edited. These headers will have a lock image next to their name.

  • Sensitive headers: Headers that, when their values change, may result in unexpected or unwanted behavior are categorized as "Sensitive". When these headers are modified, the ⚠️ icon indicates their sensitive nature to the user.

  • Custom headers: Any headers that have not been been categorized as Locked or Sensitive will be fully editable. This will include headers created as part of a system customization. It is also possible to delete (and retrieve) these headers during the editing process. Once a message has been edited and retried, any deleted headers will be lost forever.

Editing the message body

Message bodies can be edited before they are retried. This is only possible for message bodies that are serialized using unencrypted JSON or XML.

Retrying edited messages

When retrying an edited message it is possible that the original failed message will have been resolved by another user, retried successfully by another user, or expired as part of the automated processes. In those scenarios, the retry of the edited message will fail.

As soon as a message has been dispatched for retrying the originally failing message will be marked as resolved. If the retry message subsequently fails it will appear as a new failed message in the user interface. That new failed message will be marked as having been edited and also have a link to the original message.

Limitations and restrictions

A failed message must not have been resolved by a user, successfully retried, or expired as part of the automated processes for edit and retry to function.

The bodies of messages with encrypted properties cannot be edited.

The edited message will be assigned a new message ID before dispatching. The new message ID is automatically generated and is a GUID stored as a string in the edited message's headers.