A Ready To Use Debug Console for your HoloLens Application
This article is part of a series with best practices from projects executed by a Microsoft CSE team I’m part of. Have a look at Learnings from developing a HoloLens Application to get the overview of the other posts.
For a project I worked on where we used Unity and the Mixed Reality Toolkit for a HoloLens application, I ran into the whish for a debug console in the application at runtime. If you have the same need, read on 😏
The Unity Editor offers a very good way to see all the logs from the app. You can use Debug.Log(), Debug.LogError() and more to write to the log. But when you deploy the resulting app to a HoloLens, it is in fact a Universal Windows Platform (UWP) application. And you might have some code that is only executed in the app, not in the editor. And you might experience unexpected behavior in the app that you didn’t see before in the editor. That is the reason why I want to have a debug console for use at runtime.
I looked around, but couldn’t find a debug console prefab for MRTK. So I developed one myself that’s easy to reuse. If you just want to get that package, you can download the Unity Package for import here. It’s part of our sample repo MRTK Utilities where you can find the sources as well (and more).
When you imported the Unity package, you’ll see that the folder CSE.MRTK.Toolkit is added to your Assets folder. When you open that folder you can see the DebugConsole component there. It has some scripts, a prefab and a test scene.
Using the debug console prefab
Just drag the DebugConsole prefab from Assets\CSE.MRTK.Toolkit\ DebugConsole\Prefabs to your hierarchy. It’s enabled, but the UI is not visible. This is to handle settings as we will explain below. The settings for the DebugConsole looks like this:
The Main Controller script has these settings:
- Show on Startup — If you want to show the debug console on startup of your app, check this.
NOTE: you can also do this dynamically as explained below. - Only log when enabled — indication if we assemble logs only when the debug console is visible or always.
NOTE: be careful with enabling this. It can drain performance in the background. Only keep this unchecked when you need to investigate something during development. - Show stack trace on error — when checked and
Debug.LogErroris used, the stack trace is also written to the debug console and/or log. - Log file name — this is the filename of the log when saving to disk. Saving to disk is not default, but can be activated in the debug console.
The SettingsManager script has these settings:
- State file name — the filename to write the state of the debug console to. Settings are save here, like Save to file and Show on startup.
We’re using the UWP folder provided for the app as explained in Adding Application Settings to a Unity-based HoloLens Application. For UWP we use the LocalCacheFolder. This can be found in %localappdata%\packages \AppData\Local\[package family name]\LocalCache. The package family name can be set when you create the package in Visual Studio in the Package.appxmanifest in the project marked with (Universal Windows). Open that file and navigate to the Packaging tab. The package family name is generated by using the Package name and a generate identifier.
Saving logs to file
When you open the debug console, there is a Save to file button in the title bar. This is a toggle button that indicates if this is enabled or not. When enabled the prefab will write all Log, Error and Exception message to the log file.
It starts on enabling with the toggle button, but older logs are not written to the log file. It stops when you click the toggle button again. Switching to saving or stopping it is made visible in the debug console.
When the application restarts, the log file is removed and logging starts over.
Dynamic determine to show the debug console on startup
Sometimes you want the debug console to pop up on startup, to investigate startup behavior. The prefab remembers if it was open on closing the app. When you restart the app, the debug console is shown again in that case.
As we saw before, you can also show it on startup fixed by setting it in the inspector in Unity. But using this dynamic behavior is probably better for all developers 🤓
Conclusion
It’s just a simple helper with some additions I found useful. I hope it will help you to track runtime errors more easily with this helper prefab.
