Debugging an External Process
When debugging a DLL loaded by a separate process, such as .NET assemblies used in KTA processes and forms, you will need to tell Visual Studio to attach to that process. This is done by clicking “Attach to Process…” in the Debug menu.
Determining Correct Process to Debug
The process you need to debug is the process that is loading your assembly and executing the .NET activity or action that you have configured. If you are trying to debug a non-interactive activity in a process, like a .NET process activity, then this is being processed by the Core Worker Service, so you would attach the debugger to Agility.Server.Core.WorkerService.exe.
If you are debugging something that is running from an interactive form, such as a .NET form action, then this is being processed by the IIS Application Pool process, which means you would need to attach to w3wp.exe. However, it is common to have multiple IIS Application Pool processes running on a system, and it is important to attach to the correct one. To determine which process ID is the correct instance of w3wp.exe, run the following command from an elevated command prompt to see which process ID belongs to each Application Pool:
%windir%\system32\inetsrv\appcmd.exe list wp
If on a distributed installation, debugging will need to be done on the system running the relevant process.
Where is the DLL file?
If using a local reference, then the DLL file is wherever you have specified. To update it after creating a new build, it will likely be needed to restart the relevant process (Core Worker, or IIS App Pool) so the DLL can be replaced and so the new build can be loaded.
If the DLL has been added to the KTA assembly store, ensure that it has a strong name and an incrementing assembly version as documented here. Upon first use of a specific version of the DLL in the store, the DLL will be downloaded and used locally from the generated assemblies folder (C:\ProgramData\Kofax\TotalAgility\Generated Assemblies\.NET Assemblies). The name will be “OriginalName_YYYY-MM-DD hh-mm-ss.dll”
Stopping at a Breakpoint
Once Visual Studio attached to the correct process, if all else is well, the debugger will break on breakpoints in your code. Unrelated to KTA, there are many possible pitfalls that can interfere with successful debugging. Most issues will need to be approached with Visual Studio-centric troubleshooting that is beyond the scope of this article, however, the KTA specific details in this article may assist that troubleshooting.
Debugger Does Not Stop at Breakpoint
The simplest reason for the debugger to not stop at a breakpoint is that the code at that point is not actually being run. Double check configuration in KTA to ensure that it is actually running the KTA action that uses the assembly. Double check that the code execution will definitely reach your breakpoint. Consider adding a breakpoint to the first line of the top level function being called by KTA.
The simplest technical problem that prevents stopping at a breakpoint is that debug symbols, in the form of a matching PDB file, could not be loaded. The breakpoint may show an exclamation mark with the message “The breakpoint will not currently be hit. No symbols have been loaded for this document.” If the DLL has not been loaded at all, then simply initiate whatever action in KTA that would use this assembly so that it loads. If it still shows this message then this suggests that it was not able to load a matching DLL and PDB file.
Is the DLL loaded, and does the DLL match the PDB?
After attaching to a process with Visual Studio, the loaded DLLs can be seen by opening the Modules window (Debug > Windows > Modules). Sort by name to find the DLL of interest. This will also show whether the debug symbols (PDB) are loaded for the DLL, which is required for debugging to work. If they are not loaded, then more detail can be seen by right clicking on the DLL and clicking “Symbol Load Information…”. The right click menu also has a Load Symbols command which allows specifying a PDB file from a different location.
If the symbol load information specifies “PDB does not match image”, the most common problem is that the DLL has been rebuilt in Visual Studio (which produces an updated PDB file), without being updated in KTA. The debugger must have the PDB file that is an exact match for the DLL.
Example Debugging Steps
- Build a DLL with a strong name and an incrementing assembly version as documented here.
- Add or Update this DLL in KTA Assembly Store in the KTA Designer under Integration > .NET Assemblies
- Configure a button on a form to call a function from this DLL, and Release the form.
- Navigate to the form and click the button, which causes the DLL to be loaded into KTA’s IIS App Pool process
- From an elevated command prompt, run the following command to confirm the correct App Pool process
%windir%\system32\inetsrv\appcmd.exe list wp
- In Visual Studio, Debug > Attach to Process…, then select the w3wp process with the process ID of the TotalAgility App Pool.
- Open the Modules window (Debug > Windows > Modules), and sort by name to find the DLL, which should confirm that both the DLL and symbols have been loaded.
- Set a breakpoint in the function configured to be called by the form.
- Navigate to the form and click the button, which should cause the debugger to stop at the breakpoint.