The Case of the Misbehaving Manifest File

We recently helped a client move his commercial software product from a traditional install and maintain deployment model to a cloud SaaS model. While the transition seemed to go relatively well, the client began reporting visual display issues with some of the forms. After a bit of analysis we were able to identify that the problem primarily affected check box, radio button, and combo box controls. Issues ranged from disappearing labels when the control got focus to dropdown list boxes never appearing.

Our first inclination was to suspect the RDP configuration. However, after a thorough review of the various client and server side settings this seemed unlikely to be the culprit. Our next thread to follow was our own technology. Perhaps the SRP Tree or SRP Subclass controls were causing unintended display anomalies. The easiest way to disprove this was to log into the SYSPROG application and run a system utility. Yet again we were led to a dead end as this was what we observed:

As we continued our study of these forms another oddity began to reveal itself. All forms, regardless of what kind of controls they contained, were suspiciously rendered in a Windows Classic theme rather than the modern theme of the OS. This was a valuable clue that put us on the correct trail and brought back to memory something which has been a part of OpenInsight for nearly 11 years: Manifest files.

When Microsoft released Windows XP in 2001, software applications were able to take advantage of new visual styling known as Luna. However, this was not an automatic benefit. Applications needed to notify Windows of their intent to use the newer style library. Consequently, OpenInsight applications still looked very much as they did in previous versions of Windows. In 2004, Sprezzatura published an article titled OpenInsight XP in which they explained how adding a simple XML document known as a “manifest file” could magically enable OpenInsight applications to take advantage of the Luna theme (and, by extension, all other themes that later versions of Windows would provide.) A version of this manifest file was officially added to OpenInsight v7.1.1 in 2005. Since then it has always been a part of the product, ever present but easily forgotten over time.

Having a working hypothesis we were able to perform a few quick tests by removing the manifest file (oinsight.exe.manifest) from a visually working copy of OpenInsight and then cataloged our observations. Sure enough, every visual problem that we observed in the client’s hosted application was replicated. This seemed conclusive. For some unknown reason the manifest file was simply being ignored by the client’s copy of OpenInsight.

Before too long we were able to put our finger on the missing piece of the puzzle. It had to do with the way our client’s OpenInsight shortcuts were configured. Many hosted applications rely upon a single multi-user license to provide access to multiple customers and their respective users. Our client wanted to prevent his customers from accessing the system more than their service agreement would grant them. Consequently, rather than relying on a single license he requested that we set up different licenses for each customer. As many developers already know, this can be done by creating a “split folder” configuration. That is, all of the system files are kept in the Revboot folder whereas copies of the EXE and DLL files (which includes the customer’s unique OENGINE.dll file) are stored in sub-folders. Shortcuts are then configured so that the Target path points to the sub-folder whereas the Start in path points to Revboot.

While light had finally be shed upon this little mystery, it still did not lead us to a resolution. Our client’s concerns had still not been remedied. All efforts to force OINSIGHT.exe to make use of the manifest file failed. We needed to tackle this differently. Once again our persistence paid off but in a slightly unexpected but clever way. Rather than struggle to get OpenInsight to make use of the external manifest file, we cut the proverbial Gordian knot by modifying OINSIGHT.exe so that the manifest file was now embedded. Once this was done, the problem instantly resolved itself.

Split folder environments, admittedly, are not very common and they are becoming even less common as old school runtime licenses are being converted to network user licenses. Thus, the need to maintain runtime licenses for end users and developer class licenses for programmers has been virtually rendered moot since OpenInsight v9.0. Yet, split folder configurations can still serve a purpose so this solution may prove of some value to our readers. Therefore, we are very grateful to Revelation Software for granting us permission to publish this PSA (public service announcement) and a link to download a v9.4.0 version of OINSIGHT.exe with the manifest file already embedded. Of course, for those who are curious about how to do this yourselves you will need access to MT.exe which comes with Visual Studio. With this tool in your belt you can follow the guidelines in this MSDN article.

As this case file is brought to a close, thanks and credit go to SRP team members Jared Bratu and Kevin Fournier for their expertise in Windows Server, remote desktop, and C++ application technologies, all of which were essential to identifying the cause and resolution to this perplexing problem.