Debugging an Agent

Agents can be traced and debugged once they are added and used in a Data Stream. This is particularly useful when testing if an agent is working as intended and troubleshooting agent issues along the way.

Setup Before Debugging

• Package the agent using this guide. Make sure that the Agent is packaged as non-virtual. If the Agent is required to be virtual, temporarily set it to non-virtual during development and just repackage it to virtual when releasing.

Only non-virtual agents could trigger all breakpoints inside the Agent's code. This will also allow you to access any local environment (database, server, etc.) that you will use for testing.

• Add the Packaged Agent in the Data Stream Designer by following the Adding an Agent article.
• Install the XMPro Stream Host by following the Install a Stream Host article. Within the installation wizard, select Console Application as the Host Type.

• Create a new Data Stream for testing the agent and select the collection profile you used during Installation of Stream Host.

• Add the created Agent in the Data Stream and Save.

• Run the Stream Host as Admin and Publish the Data Stream for the first time. A cache folder will be created inside the Stream Host folder which will be used later on.

Steps to Debug an Agent

• Build the Agent Project to generate a dll. If built using the Debug configuration, the dll usually would be found inside the folder [Project folder]/bin/Debug/netstandard2.1.

Built dll location

• Replace the Agent dll on the Stream Host installation folder under Cache/[Agent Id]/[Agent Version] with the one generated.

Destination folder

• To determine an Agent's id, export a JSON from the XMP file of the agent via Package Manager and determine the value from the Id property.

• Run Stream Host as Admin.

• Run Visual Studio as Admin and open Agent solution.

• Add a breakpoint in the Agent's code.

• Attach XMPro.StreamHost.Console.exe to process. By default, Visual Studio shortcut is ctrl + alt + p.

• Publish the test Data Stream on the Data Stream Designer to initiate debugging.

Common Issues

Issue: 'Access to Path is denied' when publishing a Data Stream

• Make sure that Stream Host is ran in Administrator Mode

Issue: Breakpoint doesn't fire

• Make sure the Agent is packaged as Non-Virtual.

• This can also be an issue with testing out multiple versions of the agent. Ensure that the agent dll is copied to the folder with the correct agent id and version.

• Alternatively, one can refresh the Cache folder by:

  • Deleting the Cache folder

  • Running Stream Host

  • Publishing the Data Stream

  • Copying the Agent dll to the appropriate folder

• Potential issue can lie in dll not containing the expected changes. Cleaning and rebuilding the agent may solve this issue.

Issue: 'Sorry, something went wrong.' error when configuring an agent

• Make sure that stream host is running for non-virtual agents.

• If the agent is supposedly virtual, repackage the agent as non-virtual temporarily to be able to access your local environment settings

• Ensure that agent settings are configured in line with the agent's code. Things to note for:

  • Ensure that the key when packaging agents match the key used in code (case-sensitive)

  • Ensure that all key names are unique for both group and variables.

  • For value fields (eg. Token Box, Dropdown), ensure that default/configured values match the expected values in code. Take note that this is also case-sensitive

  • Alternatively, adding a breakpoint and debugging in GetConfigurationTemplate can help determine the setting/property that is causing the error

Issue: 'Could not complete Integrity check. undefined' when running integrity check

• This can be caused by missing properties within the settings when packaging an agent. Ensure that the expected configurations within the agent's code are properly configured within the settings in package manager.