Manifest Destiny

If you are a developer, IT administrator, or application packager you should know about manifest files and how they interact with Windows to control how your applications run. Manifests were first supported with Windows XP and were commonly used to do things like turn on support for the Windows XP style themes. For instance, on Windows XP if you crack open regedit.exe in Visual Studio, you will see a resource of type RT_MANIFEST (run-time manifest) with the number 1. This reads like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<assemblyIdentity
 processorArchitecture="x86"
 version="1.0.0.0"
 name="Microsoft.Windows.Regedit" type="win32" />
<description>Registry Editor</description>
<dependency>
    <dependentAssembly>
        <assemblyIdentity
            type="win32"
            name="Microsoft.Windows.Common-Controls"
            version="6.0.0.0"
            publicKeyToken="6595b64144ccf1df"
            processorArchitecture="x86"
        />
    </dependentAssembly>
</dependency>
</assembly>

That manifest just tells Windows XP to use the "new" (version 6.x) of the Windows Common Controls instead of the default version 5. Version 5 is the default because many legacy applications won't run properly with the new, themed controls. If you are a developer, you may have provided manifests like this to allow theme support in your Visual Studio.Net applications.

You may not have realized that the manifest file can be either compiled into the EXE or just in the file system. Take the fictitous program "NoteCard.exe". If you were to place the file "NoteCard.exe.manifest" in the same folder as "NoteCard.exe", it would operate just like it would if it was compiled into the program. This gives administrators and packagers the same types of control as that available to the developers of applications. In fact, to see this in operation it is instructive to copy the XML above into Notepad and save it as a file on your system in the same folder as an application written in VB6 (Visual Basic 6). Name the file <exename>.exe.manifest. You'll normally get to see the VB6 application crash when you run it, as most VB apps can't handle the newer themed controls. This shows why Microsoft did not make the common controls 6 library the default for Windows XP. Delete or rename the manifest file and your VB6 application runs as it did before. For more information on how manifests work with common controls, see this article on MSDN.

Vista, UAC, and manifests

With Vista, the roll of the manifest grows to encompass run levels. For example, many testers have seen that an administrator on a Vista machine doesn't actually have the administrator level token unless they "elevate" or "permit" an action. (See this article on Windows Connected for information about the split token for User Account Control or UAC). Have you wondered how some applications like MMC.exe will ask you to elevate when you are a protected administrator, but won't ask when you are just a standard user? Do you think the answer is that "Windows is just smart and figures it out?" Bzzzzt. Wrong! It's the manifest.

Crack open the Vista 5270 version of MMC.exe in Visual Studio and open the resource of type RT_MANIFEST and number 1. Notice that it now has some run level information in it? It looks something like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!-- Copyright © 1981-2001 Microsoft Corporation -->
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<assemblyIdentity
 processorArchitecture="x86"
 version="5.1.0.0"
 name="Microsoft.Windows.MMC"
 type="win32"
/>
<description>Microsoft Management Console</description>
<trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
 <security>
  <requestedPrivileges>
   <requestedExecutionLevel
    level="highestAvailable"
    uiAccess="false"
   />
  </requestedPrivileges>
 </security>
</trustInfo>
</assembly>

This is telling Windows to attempt to run the application at the highest execution level that is available. In the context of a regular user, the highest available is just that lowly user level. This means there would be no prompting for a standard user. For the built-in Administrator account (which has UAC off always) there is also no prompting because the token is already administrator level. However, things are different for the accounts that have been aded to the Administrators group. These accounts are running with the split token. When Windows sees this, and sees an application manifested to run with "highestAvailable" it will throw the "ConsentUI" prompt asking you to permit or deny the application from running with the full administrator token. (Note: it is impossible to have the application automatically elevate. Consent is required!). Info on CredUI and ConsentUI is here on MSDN.

In the same way as we could put a manifest file into the file system instead of compiled into the EXE for common controls library selection, we can also do it for the run level. There are several levels available:

highestAvailable
requireAdministrator
asInvoker

Those are pretty self-explanatory, but you can see the full Microsoft documentation for this and the run level manifest here on MSDN.

Now, some of you may have noticed that on the compatibility tab of the properties sheet for an EXE, Vista has the "Run as Administrator" check box. This is equivalent to "requireAdministrator" and puts the information into the SDB file (Solution DataBase). However, the GUI there doesn't allow you to set the "highestAvailable" option. For this, you can use a manifest. Most likely down the line you will be able to use the application compatibility toolkit - we'll have to see what's in this when it ships. But for now, the solution is manifest.