Elevating Programs

The following sections describe three methods for running a program with elevated privileges. The first method, using the Run As command, requires the user to take action, so it is the least desirable solution.

The second method uses a separate manifest file to tell the operating system to elevate the program when it runs. This method doesn’t require special action by the user, but it does require that the manifest be present with the executable, so it is still not a perfect solution.

The final technique embeds a manifest inside the executable program. With this method, the manifest is guaranteed to be present if the executable program is. It requires a little setup on your part, but gives the best user experience.

Run As

To elevate an application by using the Run As command, the user right-clicks the executable and selects the Run as administrator command. The operating system displays the UAC dialog box and the user can enter an administrator password.

This method is simple and requires no extra action on your part, but it does require the user to perform an extra step, so it is usually not the best solution. However, if the user runs the program only very rarely, it may make sense to require this extra step. This will discourage the user from using the command too often.

Application Manifest

An application manifest is an XML file that gives additional information about an executable program. This file typically includes information about the DLLs that the executable program should bind to at runtime. It can also include information about the privileges that the program needs to run.

Example program WriteFileSeparateManifest uses the following 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="WriteFileSeparateManifest.exe"      type="win32"/>   <!-- Identify the application security requirements. -->   <trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">     <security>       <requestedPrivileges>         <requestedExecutionLevel           level="requireAdministrator"           uiAccess="false"/>         </requestedPrivileges>        </security>   </trustInfo> </assembly>  

This file’s key to running with elevated privileges lies in the requestedExecutionLevel element. That element’s level attribute indicates that this program should run with administrator privileges.

The manifest file should have the same name as the executable program with an extra .manifest extension added at the end. For the program WriteFileSeparateManifest.exe, the file is named WriteFileSeparateManifest.exe.manifest.

The manifest file must be in the same directory as the executable program when you try to run it. Further more, the manifest must be in the program’s output directory when you compile the program in Visual Basic. Typically, that means you must put the manifest in the project’s bin\Debug or bin\Release directory. If the manifest is not present when you build the application, then the executable program does not look for the manifest file when it runs.

The WriteFileSeparateManifest program attempts to write into the file Windows\test.txt. If you build the program correctly and the manifest is present with the executable, then the system displays the UAC dialog, elevates the program’s privileges, and the program can write the file. If any part of the process fails, the program won’t have the necessary privileges to write the file.

The fact that the manifest file must be present for the application to run with elevated privileges adds a little extra complication. In the worst case, however, if the manifest file is lost, the user can always use the Run as administrator command to elevate the program.

Embedded Manifest

If you use an application manifest file as described in the previous section, there’s a chance that it will become separated from the application’s executable file. You can avoid that possibility if you embed the manifest inside the application.

Unfortunately, Visual Studio does not currently include any tools for embedding a manifest in a Visual Basic application, so you must use a command-line tool to do so. The mt.exe tool provided with the Microsoft Windows Software Development Kit (SDK) can merge the contents of the manifest file with the resources contained in the compiled executable. The following code shows the syntax for using mt.exe:

  mt.exe –manifest manifest_file –updateresource:exe_file;#1 

You must install the Microsoft Windows SDK to use the mt.exe tool. To download the SDK, go to the Microsoft download site at msdn2.microsoft.com/downloads/default.aspx and search for “Windows SDK.” Currently, the most recent Windows SDK is titled “Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components” and is located at www.microsoft.com/downloads/details.aspx?FamilyID=.

Here, you should replace manifest_file and exe_file with the names of the manifest file and the program’s executable file, respectively.

Opening a command window and entering this command isn’t too difficult, but there are a few annoying details. On my computer, the mt.exe tool is installed at C:\Program Files\Microsoft.NET\SDK\ v2.0 64bit\Bin. You either need to enter the complete path to this tool, or add this directory to your environment’s PATH variable.

To make the process a little easier, example program WriteFileEmbeddedManifest uses the batch file named MergeManifest.bat shown in the following code:

  SET MANIFEST_NAME=test.manifest SET EXE_NAME=.\bin\Debug\WriteFileEmbeddedManifest.exe PATH=C:\Program Files\Microsoft.NET\SDK\v2.0 64bit\Bin mt.exe -manifest %MANIFEST_NAME% -outputresource:%EXE_NAME%;#1 

The file starts by defining variables to hold the manifest and executable program file names. In this example, the manifest is named test.manifest and is located in the project’s source directory. The executable file created by Visual Studio is WriteFileEmbeddedManifest.exe, and is located in the project’s bin\Debug directory. For other projects, you should change the values of these file variables.

Next, the batch file sets its PATH to the location of mt.exe. If mt.exe is installed at some other location on your system, you will need to change this statement. (The file doesn’t need to add this directory to the original PATH; it simply replaces the old PATH with the new value.)

Finally, the batch file invokes the mt.exe application, passing it the appropriate parameters.

Now, the manifest information is contained inside the executable program itself, so the program cannot be separated from its privilege information.