{"id":8077,"date":"2023-03-30T16:08:53","date_gmt":"2023-03-30T23:08:53","guid":{"rendered":"https:\/\/visualgdb.com\/w\/?p=8077"},"modified":"2023-04-04T10:56:50","modified_gmt":"2023-04-04T17:56:50","slug":"creating-custom-live-watch-nodes-via-live-watch-plugins","status":"publish","type":"post","link":"https:\/\/visualgdb.com\/tutorials\/extensibility\/livewatch\/nodes\/","title":{"rendered":"Creating Custom Live Watch Nodes via Live Watch Plugins"},"content":{"rendered":"

This tutorial shows how to use the Live Watch Plugin API to create custom Live Watch nodes showing various information about the debugged program. We will show how to create a “Counter” node displaying the name and value of a counter inside the program. We will also explain how to make the custom nodes plottable and how to optimize the memory reading performance when using Live Watch.<\/p>\n

Before you begin, follow this tutorial<\/a> or clone this Git tag<\/a> to get a basic Live Watch plugin that creates 2 simple, but not very functional nodes. Once you got the basic setup working, make sure you open the plugin project in Visual Studio and follow the steps below to add functionality to it:<\/p>\n

    \n
  1. In the previous tutorial<\/a> we have implemented a basic ILiveWatchNode<\/a> showing an empty counter list. In this tutorial we will update it to have actual counter nodes corresponding to instances of the “Counter<\/strong>” struct in the code. Replace the original empty GetChildren()<\/strong> method with the following code that finds a single counter instance called g_Counter<\/strong> and creates a node for it if it was found (see the next tutorial for examples of locating multiple variables automatically):\n
    ILiveWatchEngine _Engine;\r\n\r\npublic CounterListNode(ILiveWatchEngine engine)\r\n{\r\n\t_Engine = engine;\r\n}\r\n\r\npublic ILiveWatchNode[] GetChildren(LiveWatchChildrenRequestReason reason)\r\n{\r\n\tvar result = new List<ILiveWatchNode>();\r\n\tvar counter = _Engine.Symbols.LookupVariable(\"g_Counter\");\r\n\tif (counter != null)\r\n\t\tresult.Add(new CounterNode(_Engine, counter));\r\n\treturn result.ToArray();\r\n}<\/pre>\n
    Then, go to the CounterNode<\/strong> word, press Ctrl+. and select “Generate class ‘CounterNode’<\/strong>“:
    \n    \"\"<\/a><\/li>\n
  2. Go back to the CounterNode<\/strong> instantiation and generate a constructor with fields:\"\"<\/a><\/li>\n
  3. Finally, click on the ILiveWatchNode<\/a> interface name near the generated CounterNode declaration and have Visual Studio implement it for you. You can then tweak<\/a> the generated implementation to look as shown below:\n
    internal class CounterNode : ILiveWatchNode\r\n{\r\n\tprivate ILiveWatchEngine _Engine;\r\n\tprivate IPinnedVariable _Counter;\r\n\r\n\tpublic CounterNode(ILiveWatchEngine engine, IPinnedVariable counter)\r\n\t{\r\n\t\t_Engine = engine;\r\n\t\t_Counter = counter;\r\n\t}\r\n\r\n\tpublic string UniqueID => \"counter:\" + _Counter.UserFriendlyName;\r\n\tpublic string RawType => \"Sample Counter\";\r\n\tpublic string Name => _Counter.UserFriendlyName + \" from \" + Path.GetFileName(_Counter.SourceLocation.File ?? \"\");\r\n\tpublic LiveWatchCapabilities Capabilities => LiveWatchCapabilities.CanHaveChildren;\r\n\r\n\tpublic LiveWatchPhysicalLocation Location\r\n\t{\r\n\t\tget\r\n\t\t{\r\n\t\t\treturn new LiveWatchPhysicalLocation(_Counter.Address,\r\n\t\t\t\t_Counter.SourceLocation.File,\r\n\t\t\t\t_Counter.SourceLocation.Line);\r\n\t\t}\r\n\t}\r\n\r\n\tpublic void Dispose()\r\n\t{\r\n\t}\r\n\r\n\tpublic ILiveWatchNode[] GetChildren(LiveWatchChildrenRequestReason reason)\r\n\t{\r\n\t\treturn null;\r\n\t}\r\n\r\n\tpublic void SetSuspendState(LiveWatchNodeSuspendState state)\r\n\t{\r\n\t}\r\n\r\n\tpublic void SetValueAsString(string newValue)\r\n\t{\r\n\t\tthrow new NotSupportedException();\r\n\t}\r\n\r\n\tpublic LiveWatchNodeState UpdateState(LiveWatchUpdateContext context)\r\n\t{\r\n\t\treturn default;\r\n\t}\r\n}<\/pre>\n
    \"\"<\/a><\/li>\n
  4. Note that we designed the CounterNode<\/strong> class to keep a reference to the ILiveWatchEngine<\/a> instance (.Net will automatically take care of reference counting and deallocation), and hence needed to pass it to CounterListNode<\/strong>. Update the SampleLiveWatchNodeSource()<\/strong> constructor to take a reference to it and use it when instantiating CounterListNode()<\/strong>. You can let Visual Studio do it for you, or simply add it manually:\"\"<\/a><\/li>\n
  5. Finally, update the CreateNodeSource()<\/strong> method to pass the engine reference to SimpleLiveWatchNodeSource<\/strong>:\"\"<\/a><\/li>\n
  6. Now you can build and run the plugin. This will open another Visual Studio instance where you can start debugging your embedded project and will see the counter node in the Live Watch<\/strong> view:\"\"<\/a><\/li>\n
  7. If you set a breakpoint inside the CounterListNode.GetChildren()<\/strong> method before<\/strong><\/span> the child node is created for the first time, you can inspect the value of counter<\/strong> in the debugger. See how VisualGDB automatically determined the address and size of the variable based on the DWARF debugging symbols:\"\"<\/a>If you set the breakpoint after the variable was already shown, simply restart the embedded debug session (not the plugin debugging session) and it will be queried again.<\/li>\n
  8. Now we will modify the counter node to display the actual counter value. Set a breakpoint in its constructor, restart the embedded debug session, and once the breakpoint hits, add the following code to the constructor:\n
                var countField = counter.LookupChildRecursively(\"Count\");\r\n            if (countField != null)\r\n            {\r\n                _LiveVar = _Engine.CreateLiveVariable(countField);\r\n            }<\/pre>\n
    You can let Visual Studio generate the definition of _LiveVar<\/strong> field for you, or simply define it as “private readonly ILiveVariable _LiveVar;<\/strong>“.\"\"<\/a><\/li>\n
  9. If you step over the CreateLiveVarible() call, you will see how the live variable object knows the address and size of the variable, but doesn’t know anything about the type or layout. This is intentional – VisualGDB handles the target symbols via the ILiveSymbolParser<\/a> interface (engine.Symbols<\/strong>) and the actual target memory via ILiveMemoryManager<\/a> (engine.Memory<\/strong>):\"\"<\/a><\/li>\n
  10. Set a breakpoint in the UpdateState()<\/strong> method and once it triggers, add the following code there:\n
            public LiveWatchNodeState UpdateState(LiveWatchUpdateContext context)\r\n        {\r\n            var state = new LiveWatchNodeState();\r\n            var value = _LiveVar.GetValue();\r\n            if (value.IsValid)\r\n                state.Value = value.ToUlong().ToString();\r\n\r\n            return state;\r\n        }<\/pre>\n
    Step through it to see how the value of the variable is just a raw array of bytes with a timestamp:\"\"<\/a><\/li>\n
  11. Remove the breakpoint and resume the execution. The counter value will now appear in the “Value<\/strong>” column for the node:\"\"<\/a><\/li>\n
  12. Before we go any further, try collapsing the Counters<\/strong> list and take a note of the active variable count below:\"\"<\/a>Despite having hidden the CounterNode<\/strong>, the underlying live variable is still being queried. This is not a problem for 1 node, but if your program had 1000 counters and you were only observing one of them, it would lower the performance quite a bit!<\/li>\n
  13. In order to avoid it, we will need to add some logic to the SetSuspendState()<\/strong> method. Set a breakpoint there and try collapsing the Counters<\/strong> list again:\"\"<\/a>Note how SetSuspendState()<\/strong> got called, indicating that the node is hidden. VisualGDB distinguishes visible nodes, hidden nodes (e.g. if they are scrolled out), hidden nodes with visible children, and hidden but otherwise monitorred (e.g. plotted) nodes. In most cases, you can rely on the SuspendRegularUpdates<\/strong> and SuspendDirectValueUpdates<\/strong> properties. If the node is not directly visible and not plotted, the SuspendDirectValueUpdates<\/strong> will be set to true.<\/strong> If none of the node’s children are visible either, SuspendRegularUpdates<\/strong> will turn to true as well. You can use these fields to set the SuspendUpdating<\/strong><\/a> field of the live variable:\n
            public void SetSuspendState(LiveWatchNodeSuspendState state)\r\n        {\r\n            if (_LiveVar != null)\r\n                _LiveVar.SuspendUpdating = state.SuspendRegularUpdates;\r\n        }<\/pre>\n
    If you resume the program now, collapsing the counter list will automatically reduce the number of active variables to 0:\"\"<\/a>It is also recommended to dispose of the _LiveVar<\/strong> variable in the CounterNode’s Dispose()<\/strong> method (“?.<\/strong>” stands for “do it if _LiveVar<\/strong> is not null<\/strong>“):<\/p>\n
            public void Dispose()\r\n        {\r\n            _LiveVar?.Dispose();\r\n        }<\/pre>\n
    VisualGDB will call the node’s Dispose()<\/strong> method when the node was permanently deleted, and calling _LiveVar.Dispose() <\/strong>will remove the variable from the updated variable list. In this tutorial, however, it is not strictly necessary: the list of counters does not change throughout the debug session, and disposing of the live variable at the end of the debug session will not change anything anymore, as VisualGDB stops polling the target memory at that time.<\/li>\n
  14. Now we will change the CounterNode<\/strong> logic to show the original live variable (of type “struct SampleCounter<\/strong>“) with all of its fields. This can be done by calling CreateNodeForPinnedVariable()<\/a> and returning it from the list of children as shown below:\n
            public ILiveWatchNode[] GetChildren(LiveWatchChildrenRequestReason reason)\r\n        {\r\n            var result = new List<ILiveWatchNode>();\r\n            var node = _Engine.CreateNodeForPinnedVariable(_Counter,\r\n                new LiveWatchNodeOverrides\r\n                {\r\n                    Name = \"[raw object]\"\r\n                });\r\n\r\n            if (node != null)\r\n                result.Add(node);\r\n\r\n            return result.ToArray();\r\n        }<\/pre>\n
    Nodes created via this interface will automatically handle suspension, plotting, cleanup, etc, so you won’t need to worry about it:\"\"<\/a><\/li>\n
  15. Resume the debug session. Note how the Live Watch<\/strong> window now contains 4 nodes: the counter list node, the counter node, and the raw g_Counter<\/strong> node (with the name overridden to [raw object]<\/strong>) that is automatically managed by VisualGDB and creates its children when expanded:\"\"<\/a><\/li>\n
  16. If you are frequently using Live Watch, consider setting it to activate at the beginning of each session via the Tool Window Behavior Configurator<\/strong>:\"\"<\/a><\/li>\n
  17. Showing the value of the only structure field in a custom Live Watch node won’t help the debugging a lot, however combining the values of multiple fields in a meaningful summary line could. We will demonstrate it by parsing and showing custom names for the counter objects. First, add a Name<\/strong> field to the SampleCounter<\/strong> struct and set it to “Test counter<\/strong>” inside main():\"\"<\/a><\/li>\n
  18. Then, go to the constructor of CounterNode()<\/strong>, locate the Name<\/strong> field and create a live variable if it is found:\n
                if (counter.LookupChildRecursively(\"Name\") is IPinnedVariable nameField)\r\n                _NameVar = _Engine.CreateLiveVariable(nameField);<\/pre>\n
    If you are new to C#, the “if (<…> is IPinnedVariable nameField)<\/strong>” is just a shorthand for declaring the nameField variable and checking that it’s not null<\/strong> in one statement.\"\"<\/a><\/li>\n
  19. Add the _LastKnownNamePtr<\/strong> and _LastKnownName<\/strong> fields as shown below and update the UpdateState()<\/strong> method to read the name from the ‘Name’ field:\n
                var namePtr = _NameVar.GetValue().ToUlong();\r\n            if (namePtr != _LastKnownNamePtr)\r\n            {\r\n                _LastKnownNamePtr = namePtr;\r\n                _LastKnownName = _Engine.Memory.ReadMemory(namePtr, 128).ToNullTerminatedString();\r\n            }\r\n            state.NewName = _LastKnownName;<\/pre>\n
    \"\"<\/a>Note that the actual memory accesses on the target will look as follows:<\/p>\n