Introduction to the BuildManager Object

  • Article

The BuildManager object is used by third-party developers to manage the portable executable (PE) files. PE files are compiled from custom tools that indicate to the project system that their output is to be compiled into a temporary PE.

The BuildManager object and custom tools are used in the development of visual designers. A designer in Visual Studio provides a graphical user interface for a file. In order to create the user interface, the designer may need to be able to instantiate the types described in the project item files. Temporary PE files 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 good example of this is the Custom Tool that generates classes from an XSD file. Visual designers need to sometimes instantiate the generated classes in order to discover what is proffered through a data set in order to provide UI for enabling design-time support for features such as data binding.

Custom Tools

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:

  1. The user or a designer sets the CustomTool property of a project item.

  2. 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.

  3. Together with the project references, the custom tool output is compiled into a portable executable (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.

  4. A description of the PE is available by calling the BuildManager object's BuildDesignTimeOutput method.

    The temporary PE output returned by BuildDesignTimeOutput is as follows:

    <root>
    <Application private_binpath="full output path to temporary PE,
excluding the name"/>
    <Assembly
        codebase = "filename of the temporary PE, e.g., sample.dll""
        name = "name of the temporary PE == filename without the 
extension, e.g., "sample""
        version = "always "0.0.0.0""
        snapshot_id = "unique ID number" 
        replaceable = "currently unused; always set to "True""
    />
</root>

The BuildManager Object

The BuildManager object 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 BuildManagerEventsClass 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 (single file generator) that generates a temporary PE is run. All single file generators in a project are run when:

  • A project is opened immediately after an upgrade.

  • The root namespace has changed.

Individual single file generators are run when:

  • The document with a single file generator is saved (for example, a dataset).

  • The document with a single file generator is open and dirty, and the user switches to a different document within Visual Studio.

  • A file in the project with a single file generator is renamed or moved.

  • The user has symbolically renamed a type that is used within the output file of a single file generator. For example, if the user invokes symbolic rename on type 'Type' and that type id used in dataset1.vb (the output of a dataset), the single file generator gets invoked after the rename operation completes.

Click on the link in the following table for a demonstration of how to program using the BuildManager object.

To

See

Display the monikers for the temporary PE files, and to monitor BuildManagerEvents.

How to: Use the BuildManager and BuildManagerEvents Objects

Third-Party Vendors

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 property and BuildDesignTimeOutput method. For more information, see Spectrum of Visual Studio Automation.