Introduction to the BuildManager Object
The BuildManager object is used by third-party developers to manage the portable executable (PE) files produced by running custom tools.
The BuildManager object and custom tools are used in the development of designers. A designer in Visual Studio provides a graphical user interface for a file. In order to create the user interface, the designer must be able to instantiate the types described in the project item files. The designer might need to load types from assembly files. Temporary PEs from custom tools are assembly files that encapsulate types described in project items that are outputs of a custom tool. Thus, designers and custom tools often work together to generate the design-time user interface.
A custom tool takes as input the contents of a project item file and generates a new project item file that may or may not be compiled subsequently. A typical sequence of events is:
- The user sets the CustomTool property of a project item.
- The custom tool is run with the project item contents as input. If the custom tool does not recognize the input, errors are reported to the user as determined by the custom tool. For more information, see RunCustomTool Method.
- Together with the project references, the custom tool output is compiled into a portable executable, also called a temporary PE.
Note The output is only compiled into a temporary PE if the custom tool is registered with the GeneratesDesignTimeOutput registry value set to 1.
- A description of the PE is available by calling the BuildManager object's BuildDesignTimeOutput method.
The BuildManager Object
Properties and Methods
The BuildManager provides access to the temporary PEs. The DesignTimeOutputMonikers property is an array of all the PE monikers (names) in the project. The project system assigns PE monikers based on the project hierarchy. For example, if there were an XML designer file SomeData.xsd in Folder1 of Project1 that generated output SomeData.cs, then the moniker would be
"Project1\Folder1\SomeData.cs". The BuildDesignTimeOutput method takes a moniker as a parameter and returns a description of the PE in an XML string.
The BuildManager object's DesignTimeOutputDeleted event is raised when a project item file that generates a PE is deleted from the project. The DesignTimeOutputDirty event is raised whenever a custom tool that generates a temporary PE is run. The custom tool is run when:
- The custom tool property is set or changed for a project item,
- The project item file is saved, or
- The custom tool namespace property changes.
Much of the BuildManager object's functionality may also be accessed through the ITypeResolutionService interface. However, third-party vendors that want a comprehensive designer must use the DesignTimeOutputMonikers and BuildDesignTimeOutput methods. For more information, see The Spectrum of Visual Studio .NET Automation.