Step 6: Create and Embed an Application Manifest (UAC)

Step Six: Create and Embed an Application Manifest with Your Application

In Windows Vista®, the correct way to mark your applications is to embed an application manifest within your program that tells the operating system what the application needs. In the Windows Vista release, there are provisions to allow non-manifested or unsigned code to run with a full administrative access token.

Application Manifest Schema

Application manifests are not new to the Windows Vista release. Manifests were used in Windows XP to help application developers identify such things as which versions of DLLs the application was tested with. Providing the execution level is an extension to that existing application manifest schema.

The Windows Vista application manifest has been enhanced with attributes that permit developers to mark their applications with a requested execution level. The following is the format for this:

<requestedExecutionLevel
level="asInvoker|highestAvailable|requireAdministrator"
uiAccess="true|false"/>

Requested Execution Levels

Possible requested execution level values

System behavior

Application Manifest Marking and Application Launch Behavior

This section details the behavior of the elevation prompt depending on the parent process access token, the setting for the User Account Control: Behavior of the elevation prompt for administrators in Admin Approval Mode policy and the User Account Control: Behavior of the elevation prompt for standard users policy, and the requested execution level marking for the application.

Whether an application can run and which user rights and administrative Windows privileges it can obtain are dependent upon the combination of the application’s requested execution level in the application compatibility database and the administrative privileges available to the user account that launched the application. The following tables identify the possible run-time behavior based on such possible combinations.

Application launch behavior for a member of the local Administrators group

Application launch behavior for a standard user account

Application launch behavior for a standard user with additional privileges (e.g., Backup Operator)

uiAccess Values

Possible uiAccess values

How to Create an Embedded Manifest with Microsoft Visual Studio®

Visual Studio® provides the capability to automatically embed an XML application manifest file within the resource section of the Portable Executable (PE) image. This section addresses how to use Visual Studio to create a signed PE image containing an application manifest. This application manifest can therefore include the necessary requestedExecutionLevel attributes, allowing the application to run with the desired privilege level on Windows Vista. When the program is launched, the application manifest information will be extracted from the resource section of the PE and used by the operating system. It is not necessary to use the Visual Studio graphical user interface (GUI) to include a manifest. Once the necessary changes are in the source code, compiling and linking using command-line tools will also include the application manifest in the resulting PE image.

Manifest File

To mark your application with a requestedExecutionLevel, first create an application manifest file to use with the target application. This file can be created by using any text editor. The application manifest file should have the same name as the target executable file with a .manifest extension. For example: IsUserAdmin.exe.manifest.

Example

Executable: IsUserAdmin.exe 
Manifest:IsUserAdmin.exe.manifest
Sample application manifest file:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0"> 
  <assemblyIdentity version="1.0.0.0"
     processorArchitecture="X86"
     name="IsUserAdmin"
     type="win32"/> 
  <description>Description of your application</description> 
  <!-- Identify the application security requirements. -->
  <trustInfo xmlns="urn:schemas-microsoft-com:asm.v2">
    <security>
      <requestedPrivileges>
        <requestedExecutionLevel
          level="requireAdministrator"
          uiAccess="false"/>
        </requestedPrivileges>
       </security>
  </trustInfo>
</assembly>

The parts of the manifest that need to be adjusted for your application are marked in bold. They include the following:

• The assembly identity

• The name

• The type

• The description

• The attributes in the requestedExecutionLevel

Building Application Manifests Within C/C++ Code with Visual Studio® 2005 for Windows Vista-Only Applications

Next, you have to attach the application manifest to the executable by adding a line in the resource file of the application (the .rc file) to have Microsoft Visual Studio embed your manifest within the resource section of the PE file. To accomplish this, place the application manifest in the same directory as the source code for the project you are building and edit the resource file to include the following lines:

#define MANIFEST_RESOURCE_ID 1
MANIFEST_RESOURCE_ID RT_MANIFEST "IsUserAdmin.exe.manifest"

Replace IsUserAdmin.exe.manifest with the name of your application's manifest. After rebuilding the application, the application manifest should be embedded in the resource section of the executable.

Building and Embedding a Manifest with Microsoft Visual Studio® 2005 for Windows XP and Windows Vista Applications

In Visual Studio 2005, the C/C++ integrated development environment (IDE) interface that permits the inclusion of additional manifest files in a target executable file does some processing on the XML, which inserts a duplicate xmlns tag. Because of this, the previously documented method on how to include an application manifest in a Visual Studio 2005 C++ project cannot be used if the application should run on both Windows Vista and Windows XP. The following procedures are modified to include explicit version tags in the trustInfo section.

A fix is planned for the mt.exe tool to address the problem where it generates the duplicate namespace declaration in the XML. Until a new version of mt.exe is available, you can avoid the problem of merging application manifests by explicitly adding in version tags into the trustinfo section of the manifest. A sample application manifest is shown below:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
   <ms_asmv2:trustInfo xmlns:ms_asmv2="urn:schemas-microsoft- 
     com:asm.v2">
      <ms_asmv2:security>
         <ms_asmv2:requestedPrivileges>
            <ms_asmv2:requestedExecutionLevel level="asInvoker">
            </ms_asmv2:requestedExecutionLevel>
         </ms_asmv2:requestedPrivileges>
      </ms_asmv2:security>
   </ms_asmv2:trustInfo>
</assembly>

C or C++ Project

The following procedure details how to create an application manifest for a C or C++ project type in Visual Studio 2005.

To create a manifest for a C or C++ project in Microsoft Visual Studio 2005

1. Open your project in Microsoft Visual Studio 2005.

2. Under Project, select Properties.

3. In Properties, select Manifest Tool, and then select Input and Output.

4. Add in the name of your application manifest file under Additional manifest files.

5. Rebuild your application.

Note   The updated manifests that include explicit version tags will permit the application to run correctly on both Windows Vista and Windows XP.

Managed Code (C#, J# and Visual Basic)

Visual Studio does not currently embed a default application manifest into managed code. For managed code, the developer should insert a default application manifest into the target executable using mt.exe. The following procedure details this process.

To insert a default manifest file into the target executable with mt.exe

1. Use a text editor, such as Windows Notepad, to create a default manifest file, temp.manifest.

2. Use mt.exe to insert the manifest.  The command would be: mt.exe –manifest temp.manifest –outputresource:YourApp.exe;#1.

Adding the Application Manifest as a Step in Visual Studio Post-Build

Adding the application manifest can be automated as a post-build step as well. This option is available for C/C++ and for the two managed code languages of C# and J#.

To automate the addition of the application manifest as a post-build step, place the following line as a post build task in your Visual Studio project's Project Properties:

mt.exe -manifest "$(ProjectDir)$(TargetName).exe.manifest" -updateresource:"$(TargetDir)$(TargetName).exe;#1"

See Also

Concepts

Designing UAC Applications for Windows Vista