Using Manifest Maker with Visual Studio 2005/2008

advanced topics | home

You may wish to first read Visual Studio 2005/2008 Integration and Command Line Manifest Maker to get an overview of the topic.

The command line Manifest Maker sxs32cmd.exe is specifically designed to perform a build of a side-by-side project in an automated environment. It has been extensively tested in Visual Studio 2005 and 2008 but can be adopted to practically any build environment. The build process implemented by sxs32cmd.exe is exactly the same as in the interactive sxs32mm.exe with the added ability to override certain settings prior to starting the build.

Depending on whether the build environment uses the Microsoft Manifest Tool and Linker, the project should be built as a complete manifest or as a manifest fragment.

The major differences between a 'complete' build and a 'fragment' build is that a complete build arranges all files into a predefined directory structure while a fragment build does not move any files or copy any DLLs. It may copy private and library manifests to the build intermediate files' directory in order to be able to verify the manifest correctness and, possibly, fix the manifest. The result is that you are responsible for making sure that any private manifests used by the program being built are available to the program during execution. A common way to ensure this is to build any required private assemblies in the build output directory and to copy any DLLs referenced by the application manifest into that same directory. If the DLL (or DLLs) is an output from another project in the same solution it will be placed (if Visual Studio 2005 defaults are used) in the same output directory.

Normally the manifest is written to the target folder specified in the side-by-side project. This may need to be changed when the project is built in an automated environment. The target folder may need to be specified depending on the type of the build (Debug / Release) and on other project properties.

When Manifest Maker builds a manifest, it also performs validity checking and attempts to fix the manifest, if it is not valid. If the project contains references to DLLs or private assemblies, those assemblies need to be available while the manifest is tested.

The way the manifest is built is controlled by three parameters (see Command Line):

/f:<path>

Build a manifest fragment, path: full path to the manifest file.

This options turns on the manifest fragment build. If this option is not specified the manifest is built based on the build type saved in the project. The path specifies the full path to the created manifest file. In the Visual Studio environment this normally points to the intermediate directory for the current build type. The included sxs32.rules file defines this path as $(IntDir)\$(InputName).manifest. Normally this option is used together with the /r: option.

/r:<path>

Manifest search root folder, default: project target folder.

This is the path where all the necessary DLLs and private assemblies are located. If this project only uses shared assemblies, this parameter is not necessary. Otherwise it is required for the manifest validation process. The example project targetProgram included in the vs2005.sln solution defines this value as $(OutDir). The reason is that the required assemblies are built by the other two projects in the solution and they are created in the Debug or Release folders depending on the build. If project dependencies are pre-built and are in a fixed location -- just use that location for this value. Normally this option is used together with the /f: option.

/d:<path>

Destination folder: overrides the folder saved in the project.

This option is not used when building a manifest for a Visual C++ program. It is normally used in a normal, complete, build step to override the target directory stored in the project file. If this option is not specified, the output assembly or application manifest is created in the folder saved with the project. This is frequently not useful when building a project because the project output directory varies depending on the build type. Both the windowsDLL and the serverDLL projects in the example vs2005.sln solution use this option and define it as: /d:$(OutDir) to create the output in the project output folder.

You may wish to turn on program tracing to make it easier to diagnose build configuration. Use the /z:, /t: and /l: options for that purpose. Example settings could be:

sxs32cmd /z:1 /l:9 /t:$(IntDir)\sxs32cmd.log ...other option here...

Project Files and Automated Build

Command line Manifest Maker uses project files created using the Manifest Maker UI. Typically you would create and test your project using the UI then specify the saved project on the sxs32cmd.exe command line.

The project file is a well formed XML file. It is possible to build the project file automatically using a script or some other tool. The most common approach is to build the project file using the UI, test it then remove all or some file references and save as a template. At build time a script reads the template, populates with the desired file names and options and saves as input for a subsequent Manifest Maker build step.

It is our intention to maintain project file backward compatibility so subsequent versions of Manifest Maker accept older files and process them in a compatible manner. The opposite is not true. A project file created with a newer version of Manifest Maker may be rejected by an older version of the program.