Customizing the Windows Application Manifest File

Go Up to Types of Multi-Device Applications You Can Create

Go Up to Deploying Applications - Overview

When you build a project for a Windows target platform, RAD Studio automatically includes an application manifest file. You can use the default application manifest file as a base for your custom application manifest file:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
 <dependency>
   <dependentAssembly>
     <assemblyIdentity
       type="win32"
       name="Microsoft.Windows.Common-Controls"
       version="6.0.0.0"
       publicKeyToken="6595b64144ccf1df"
       language="*"
       processorArchitecture="*"/>
   </dependentAssembly>
 </dependency>
 <trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
   <security>
     <requestedPrivileges>
       <requestedExecutionLevel
         level="asInvoker"
         uiAccess="false"/>
       </requestedPrivileges>
   </security>
 </trustInfo>
</assembly>

The default application manifest file defines:

• Support for Windows Common Controls version
• The elevation level of the application that matches the parent process.

Creating a Custom Application Manifest File

1. Create a blank text file.
2. Copy the default application manifest into it.
3. Add or modify the dependencies (such as the required elevation level or DPI awareness).
4. Save the text file with the extension .manifest.

Declaring the Required Elevation Level

The default application manifest declares the required elevation level as asInvoker. That means that your application will have the same elevation level as its parent process. If you wish to elevate your application to the Windows Administrator privilege level, simply change the value of the level attribute in the requestedExecutionLevel tag from asInvoker to requireAdministrator.

Note: The user will still need administrator privileges or credentials in order to run the application with the Administrator privilege level.

The following table provides information about the behavior of the application in some common scenarios in relation to the required elevation level that you declare in the application manifest and the level of the parent process of the application:

Level Declared in Application Manifest	Level of parent process	Behavior
asInvoker	Standard user	Application launches as a standard user
asInvoker	Administrator	Application launches with a full administrative access
highestAvailable	Standard user	Application launches as a standard user
highestAvailable	Administrator	Application launches with a full administrative access
requireAdministrator	Standard user	Prompt for administrator credentials before running application
requireAdministrator	Administrator	Application launches with a full administrative access

For more detailed information on the behavior of applications under different settings, see MSDN: Create and Embed an Application Manifest (UAC)

Declaring DPI Awareness

In order to create a DPI-aware application, you need to declare DPI awareness in the application manifest. For example, to declare that your application is per-monitor DPI-aware, add the following before the closing </assembly> tag:

<asmv3:application xmlns:asmv3="urn:schemas-microsoft-com:asm.v3">
   <asmv3:windowsSettings
        xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">
     <dpiAware>True/PM</dpiAware>
   </asmv3:windowsSettings>
</asmv3:application>

For more detailed information, application examples and code snippets on the topic of DPI awareness, see the Delphi Developers Guide 4K.pdf.

Adding the Custom Manifest File to Your Application

1. Go to Project > Options > Application to open the Application Options page.
2. Choose the target platform-configuration pair.
3. Select Custom from the Auto Generate drop-down combo box.
4. Click the ellipsis button [...] of the Custom manifest field to browse for your custom .manifest file.

Note: The application options are specific for each platform-configuration pair. You need to explicitly set the custom manifest for each platform-configuration pair (it may be the same .manifest file).

Troubleshooting

Testing the Administration Privileges

The following code snippet can serve as a quick test whether your application requires (and is properly granted) the Administrator level privileges. Declare the required elevation level of your application as requireAdministrator and execute the following procedure:

Delphi:

uses
System.Win.Registry, Winapi.Windows;

procedure isAdmin();
var
  reg: TRegistry;
  openResult: Boolean;
begin
  reg := TRegistry.Create(KEY_READ);
  reg.RootKey := HKEY_LOCAL_MACHINE;
  reg.Access := KEY_WRITE;
  openResult := reg.OpenKey('Software\MyCompanyName\MyApplication\',True);
  if not openResult = True then
    begin
    MessageDlg('Unable to write to registry. Your application does NOT have Administrator level privileges.',
                TMsgDlgType.mtError, mbOKCancel, 0);
    end
  else
    begin
    MessageDlg('Write to registry permitted. Your application has Administrator level privileges.',
                TMsgDlgType.mtInformation, mbOKCancel, 0);
    end;
  reg.CloseKey();
  reg.Free;
end;

C++:

#include <System.Win.Registry.hpp>
#include <Winapi.Windows.hpp>

void __fastcall isAdmin(TObject *Sender){
	TRegistry *reg;
	bool openResult;
	reg = new TRegistry(KEY_READ);
	reg->RootKey = HKEY_LOCAL_MACHINE;
	reg->Access = KEY_WRITE;
	openResult = reg->OpenKey("Software\\MyCompanyName\\MyApplication\\" , true);
	if (openResult != true){
		MessageDlg("Unable to write to registry. Your application does NOT have Administrator level privileges.",
					TMsgDlgType::mtError, mbOKCancel, 0);
	}else{
		MessageDlg("Write to registry permitted. Your application has Administrator level privileges.",
					TMsgDlgType::mtInformation, mbOKCancel, 0);
	}
	reg->CloseKey();
	reg->Free;
}

The application displays one of the following messages:

• Unable to write to registry. Your application does NOT have Administrator level privileges.
• Write to registry permitted. Your application has Administrator level privileges.

This test works because you need Administrator level privileges in order to write to the HKEY_LOCAL_MACHINE\Software part of the registry. The snippet does not actually write anything to the registry, it just requests the write permission.

Make sure that you build your application and then execute it outside of the IDE, because the IDE will debug the application with Administrator level privileges by default (not respecting your application manifest).

Errors

Unable to create process: The application has failed to start because its side-by-side configuration is incorrect. Please see the application event log or use the command-line sxstrace.exe tool for more detail.

• This error usually means that you have entered an incorrect value somewhere in the application manifest. Make sure that the manifest is correctly formatted and that all the provided values are correct.

  Note: Build your application after changing the application manifest to apply the changes.

Unable to create process. The requested operation requires elevation

• This error shows if you run the IDE as standard user and you try to debug an application that requires Administrator level privileges. The only way to debug an application that requires Administrator level privileges is to run the IDE as Administrator.

See Also

• API (ApplicationName.manifest)

• Applications Options for Desktop Platforms

• MSDN: Application Manifests

• MSDN: Create and Embed an Application Manifest (UAC)

• Delphi Developers Guide 4K.pdf (Solving DPI problems, creating a custom manifest.)