How to debug?

[zoidbergthepopularone]

Let's say that I want to install a mod but that mod fails to work. What can and/or should I do to gather as much information as possible for the mod's developer to be able to help me (assuming that they are willing to do it)?

For example, I am very much interested in using @m417z's taskbar-grouping mod in Windows 11. I could install it, I could run Windhawk with it, but as far as I can tell, the mod is not doing anything. Now the mod is using Windhawk's logging, so presumably I should be able to see some record of its work, and also presumably it would be much more useful for the developer if I could give them that log rather than a generic message of "it doesn't work".

Unfortunately, I was unable to find any documentation on how to activate logging in Windhawk. A search through the settings files reveals multiple LoggingVerbosity=0 entries in various log files, but it's unclear what values I should use (presumably zero stands for "disabled", but what's "log everything that you can"?). A quick look through the binary suggests that perhaps the logging is done via the OutputDebugString function, but running Windhawk through x64dbg did not reveal any relevant output either, which could just as well mean that I did not setup the logging correctly as that it works fine but the mod never reaches any point where it should perform logging.

Basically, what I am looking for are some suggestions on how to get useful output out of Windhawk so that the developer can help me in cases like this. Or even, something that I myself can use to help myself (e.g. if I should see that access was denied while trying to inject explorer.exe, I can start searching why didn't Windhawk have sufficient privileges even though I started it under an administrative account.)

[m417z]

Making it easier to troubleshoot problems with mods is high on my task list. I plan to make improvements in this area in the next version of Windhawk. For now, you can try the following:

• Open Windhawk.
• Disable the taskbar-grouping mod.
• Fork the mod.
• Enable logging.
• Click on Show Log Output.
• Click on Compile Mod.

You should see log output at the bottom of the window. Post the log that you're getting. Let me know if you need help with one of the steps.

If the log won't be enough, I can add more logs to the mod. You can see how inconvenient it can be here, for example, and that's why that's something I'd like to improve soon.

A search through the settings files reveals multiple LoggingVerbosity=0 entries in various log files, but it's unclear what values I should use (presumably zero stands for "disabled", but what's "log everything that you can"?).

It's undocumented and I wouldn't want users to have to fiddle with the registry for basic troubleshooting, but if you're wondering: 0/1/2 are the possible values for off/errors/verbose logging. There's LoggingVerbosity for the Windhawk program, and there's LoggingVerbosity for the the Windhawk engine (which is injected into other programs and loads mods). And then, there's the LoggingEnabled value for each mod, which can be 0 or 1.

A quick look through the binary suggests that perhaps the logging is done via the OutputDebugString function, but running Windhawk through x64dbg did not reveal any relevant output either

The taskbar-grouping mod loads inside the explorer.exe process. Attaching x64dbg is possible, but a more convenient way is using an utility such as DebugView of Windows Sysinternals.

[zoidbergthepopularone]

I did not see anything relevant with the default log level. After setting all LoggingVerbosity to 2, I did get some log. Only two relevant lines, though, everything else concerns other processes or is simply a standard informational message:

19:20:48.344 5588 explorer.exe  [WH] [local@taskbar-grouping-fork] [133:Wh_ModInit]: Init
19:20:48.349 5588 explorer.exe  [WH] [Mod::FindFirstSymbol]: Mod local@taskbar-grouping-fork error: engine\symbol_enum.cpp(19)\windhawk.dll!00007FF8B18A9DAC: (caller: 00007FF8B1899AB4) Exception(3) tid(2fb4) 806D0005 

This gets repeated when I try the process again. The same problem also appears for taskbar-clock-customization

[m417z]

The mod is getting the 806D0005 (E_PDB_NOT_FOUND) error while trying to download symbols from the Microsoft server. There are two options here: Either there's an internet connection problem (e.g. a restrictive firewall), or you're using an insider version of Windows for which no symbols were published. If that's the latter, unfortunately, there's not much that can be done. Not all mods require symbols (for example Taskbar Volume Control, Dark Mode for Notepad don't), but many do.

[zoidbergthepopularone]

That's quite possible - I do use a restrictive firewall. I thought I enabled it for Windhawk after seeing the message because I thought it might be something like that, but perhaps WH didn't try to download the necessary files? Is there some command-line argument to tell WH to (re)download the necessary files right now? Seeing as the PDB is likely to change with just about every single patch of Windows, an option to download it on-demand would be very useful (e.g. I could update Windows and immediately tell WH to get the new file).

In the meantime, I will try to convince Windhawk and the firewall to cooperate and download the file for me.

[m417z]

The symbol files are downloaded by the mod that is injected into the target program, in this case, explorer.exe. You can disable and re-enable the mod (or restart explorer) to make it try to download the symbols again.

an option to download it on-demand would be very useful

That would be an advanced option most users won't need, but I can tell you how to do it. Here's one way:

• Install WinDbg Preview from the Microsoft Store.
• Go to settings, and change the symbols path to C:\ProgramData\Windhawk\Engine\Symbols.
• Open the relevant dll file in WinDbg, symbols will be downloaded automatically.

You can look at the mod's code to see which symbols it loads. For the taskbar-grouping mod, that would be appresolver.dll.

[zoidbergthepopularone]

Right, I got the files to download.

However, I would very much recommend a change here: It should always be Windhawk itself who downloads the symbols, not the injected process - for many processes, and most particularly explorer.exe, it's really not a good idea to give it any access to the internet.

[m417z]

I'm using a Microsoft library for handling (downloading and loading) the symbols. What you're suggesting makes sense, but it will require some non-trivial development. Right now, the mods have minimal communication with Windhawk itself, which has benefits regarding stability and ease of implementation. Changing it is not a priority, but I'll keep your suggestion in mind.