How to: Use the BuildManager and BuildManagerEvents Objects

The BuildManager object is used to manage and display the portable executable (PE) files produced by running custom tools (single file generators) that generate design-time output. BuildManagerEvents events are raised when project items that generate temporary portable executables are changed or deleted.

This article details how to program against the BuildManager and BuildManagerEvents object in a Visual Studio add-in.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Customizing Development Settings in Visual Studio.

To use the BuildManager and BuildManagerEvents objects

  1. Create a Visual Studio add-in project by using Visual C#.

  2. On the Project menu, click Add Reference, click the .NET tab, select System.Windows.Forms, VSLangProj, VSLangProj2, and VSLangProj80, and then click OK.

  3. Add the following using statements to the top of the Connect.cs file.

    using VSLangProj;
    using VSLangProj2;
    using VSLangProj80;
    using System.Windows.Forms;
    
  4. Add the following declaration to the bottom of the Connect class to declare the BuildManagerEvents handler.

    private DTE2 _applicationObject;
    private AddIn _addInInstance;
    private VSLangProj.BuildManagerEvents buildMgrEvents;
    
  5. Add the following method call to the OnConnection method.

    _applicationObject = (DTE2)application;
    _addInInstance = (AddIn)addInInst;
    // Call the BuildMangerSample method.
    BuildManagerSample(_applicationObject);
    
  6. Add the BuildManagerSample method declaration directly below the OnConnection method.

    public void BuildManagerSample(DTE2 dte)
    {
    }
    
  7. Add the following declarations to the top of the BuildManagerSample method.

    Solution2 soln = (Solution2)_applicationObject.Solution;
    Project proj;
    VSProject2 vsproj;
    BuildManager bldMgr;
    
  8. Cast the project to a VSProject2 object by adding the following code to the BuildManagerSample method.

    proj = soln.Projects.Item(1);
    // Get a reference to the VSProject2 object.
    vsproj = (VSProject2)proj.Object;
    
  9. Add the code to display the monikers for the PE file in a message box by using BuildDesignTimeOutput.

    bldMgr = vsproj.BuildManager;
    Array monikers = null;
    String msg = null;
    Object obj = bldMgr.DesignTimeOutputMonikers;
    if (obj != null)
    {
        try
        {
            monikers = (System.Array)obj;
            foreach(String tempmoniker in monikers)
                {
                    msg += bldMgr.BuildDesignTimeOutput(tempmoniker) 
    + "\n";
                }
            }
        catch(Exception ex)
        {
            MessageBox.Show(ex.Message);
        }
    MessageBox.Show("The build design-time output is:" + "\n"  
    + msg, "Temporary PE Monikers");
    }
    
  10. Create the BuildManagerEvents event handlers by adding the following code to the BuildManagerSample method.

    //Hook up buildmanager events.
    buildMgrEvents = vsproj.Events.BuildManagerEvents;
    buildMgrEvents.DesignTimeOutputDeleted +=
    new _dispBuildManagerEvents_DesignTimeOutputDeletedEventHandler
    (buildMgrEvents_DesignTimeOutputDeleted);
    buildMgrEvents. DesignTimeOutputDirty +=
    new _dispBuildManagerEvents_DesignTimeOutputDirtyEventHandler(
    buildMgrEvents_DesignTimeOutputDirty);
    
  11. Add procedures for each event related to the BuildManagerEvents object.

    void buildMgrEvents_DesignTimeOutputDirty
    (string bstrOutputMoniker)
    {
        MessageBox.Show(bstrOutputMoniker + " is dirty."
    , "BuildManager Events");
    }
    
    void buildMgrEvents_DesignTimeOutputDeleted
    (string bstrOutputMoniker)
    {
        MessageBox.Show(bstrOutputMoniker + " was deleted."
    , "BuildManager Events");
    }
    
  12. Finally, disable event handling by adding the following code to the OnDisconnection method.

    public void OnDisconnection(ext_DisconnectMode disconnectMode, ref Array custom)
    {
        // If the delegate handlers have been connected, then 
        // disconnect them here. 
        // If you do not do this, the handlers may still 
        // fire because garbage collection has not removed them.
        if (buildMgrEvents != null)
        {
            buildMgrEvents.DesignTimeOutputDeleted -= 
     new _dispBuildManagerEvents_DesignTimeOutputDeletedEventHandler 
    (buildMgrEvents_DesignTimeOutputDeleted); 
            buildMgrEvents.DesignTimeOutputDirty -= 
     new _dispBuildManagerEvents_DesignTimeOutputDirtyEventHandler 
    (buildMgrEvents_DesignTimeOutputDirty);
        }
    }
    

    The complete code is listed in the Example section of this topic.

  13. To build the add-in, click Build Solution on the Build menu.

  14. Open a Visual C# or Visual Basic project in the Visual Studio integrated development environment (IDE).

  15. To add a dataset to the project click Add New Item on the Project menu. Select DataSet from the Add New Item dialog box and click OK.

    A DataSet file ensures that the project has a custom tool (single file generator) associated with it.

On the Tools menu, click Add-in Manager and select your add-in from the Add-In Manager dialog box. Click OK to run your add-in.

To test the BuildManagerEvents code

  • To see the BuildManagerEvents handlers firing, add a new dataset to the project, modify the properties of the dataset file, or delete the dataset file.

    To modify the properties of the dataset file:

    1. Select the dataset file in Solution Explorer.

    2. Right-click the file and select Properties from the drop-down menu.

    3. On the Properties window modify any of the fields.

    To delete the dataset:

    1. Select the dataset file in Solution Explorer.

    2. Right-click the file and select Delete from the drop-down menu.

Example

The following example is a basic Visual Studio add-in that demonstrates how to use the BuildManager and BuildManagerEvents objects by using Visual Studio automation.

using System;
using Extensibility;
using EnvDTE;
using EnvDTE80;
using VSLangProj;
using VSLangProj2;
using VSLangProj80;
using System.Windows.Forms;
namespace MyAddIn
{
public class Connect : Object, IDTExtensibility2
    {
        public Connect()
        {
        }
        public void OnConnection(object application, 
ext_ConnectMode connectMode, object addInInst, ref Array custom)
        {
            _applicationObject = (DTE2)application;
            _addInInstance = (AddIn)addInInst;
            // Call the BuildMangerSample method.
            BuildManagerSample(_applicationObject);
        }
        public void BuildManagerSample(DTE2 dte)
        {
            try
            {
                Solution2 soln =
 (Solution2)_applicationObject.Solution;
                Project proj;
                VSProject2 vsproj;
                BuildManager bldMgr;
                proj = soln.Projects.Item(1);
                // Cast to the VSProject2 object.
                vsproj = (VSProject2)proj.Object;
                bldMgr = vsproj.BuildManager;
                Array monikers = null;
                String msg = null;
                Object obj = bldMgr.DesignTimeOutputMonikers;
                if (obj != null)
                {
                    try
                    {
                        monikers = (System.Array)obj;
                        foreach(String tempmoniker in monikers)
                        {
                            msg +=
 bldMgr.BuildDesignTimeOutput(tempmoniker) + "\n";
                        }
                    }
                    catch(Exception ex)
                    {
                        MessageBox.Show(ex.Message);
                    }
                    MessageBox.Show("The build design-time output is:"
+ "\n"  + msg, "Temporary PE Monikers");
                }
                //Hook up buildmanager events.
                buildMgrEvents = vsproj.Events.BuildManagerEvents;
                buildMgrEvents.DesignTimeOutputDeleted +=new
 _dispBuildManagerEvents_DesignTimeOutputDeletedEventHandler
(buildMgrEvents_DesignTimeOutputDeleted);
                buildMgrEvents.DesignTimeOutputDirty +=new
 _dispBuildManagerEvents_DesignTimeOutputDirtyEventHandler
(buildMgrEvents_DesignTimeOutputDirty);
            }
            catch (Exception ex)
            {
                MessageBox.Show(ex.Message);
            }
        }
        void buildMgrEvents_DesignTimeOutputDirty
(string bstrOutputMoniker)
        {
            MessageBox.Show(bstrOutputMoniker + " is dirty.", 
"BuildManager Events");
        }
        void buildMgrEvents_DesignTimeOutputDeleted(
string bstrOutputMoniker)
        {
            MessageBox.Show(bstrOutputMoniker + " was deleted."
, "BuildManager Events");
        }
        public void OnDisconnection(ext_DisconnectMode disconnectMode
, ref Array custom)
        {
            // If the delegate handlers have been connected, then 
            // disconnect them here. 
            // If you do not do this, the handlers may still 
            // fire because garbage collection has not removed them.
            if (buildMgrEvents != null)
            {
                buildMgrEvents.DesignTimeOutputDeleted -= new
 _dispBuildManagerEvents_DesignTimeOutputDeletedEventHandler
(buildMgrEvents_DesignTimeOutputDeleted);
                buildMgrEvents.DesignTimeOutputDirty -= new
 _dispBuildManagerEvents_DesignTimeOutputDirtyEventHandler
(buildMgrEvents_DesignTimeOutputDirty);
            }
        }
        public void OnAddInsUpdate(ref Array custom)
        {
        }
        public void OnStartupComplete(ref Array custom)
        {
        }
        public void OnBeginShutdown(ref Array custom)
        {
        }
        private DTE2 _applicationObject;
        private AddIn _addInInstance;
        private VSLangProj.BuildManagerEvents buildMgrEvents;
    }
}
Imports System
Imports Microsoft.VisualStudio.CommandBars
Imports Extensibility
Imports EnvDTE
Imports EnvDTE80
Imports VSLangProj
Imports VSLangProj2
Imports VSLangProj80

Public Class Connect
    Implements IDTExtensibility2
    Dim _applicationObject As DTE2
    Dim _addInInstance As AddIn
    Public WithEvents buildMgrEvents As VSLangProj.BuildManagerEvents
    Public Sub New()
    End Sub
    Public Sub OnConnection(ByVal application As Object, ByVal _
    connectMode As ext_ConnectMode, ByVal addInInst As Object, _
    ByRef custom As Array) Implements IDTExtensibility2.OnConnection
        _applicationObject = CType(application, DTE2)
        _addInInstance = CType(addInInst, AddIn)
        BuildManagerSample(_applicationObject)
    End Sub
    Sub BuildManagerSample(ByVal dte As DTE2)
        Try
            Dim soln As Solution2 = CType(_applicationObject.Solution _
            , Solution2)
            Dim proj As Project
            Dim vsproj As VSProject2
            Dim bldMgr As BuildManager
            proj = soln.Projects.Item(1)
            ' Cast the project to a VSProject2.
            vsproj = CType(proj.Object, VSProject2)
            bldMgr = vsproj.BuildManager
            Dim monikers As String() = Nothing
            Dim moniker As String = Nothing
            Dim msg As String = ""
            Dim obj As Object = bldMgr.DesignTimeOutputMonikers
            If Not obj Is Nothing Then
                Try
                    monikers = CType(obj, String())
                    For Each moniker In monikers
                        msg &= bldMgr.BuildDesignTimeOutput(moniker)  _
                        + vbCr
                    Next
                Catch ex As System.Exception
                    MsgBox(ex.ToString)
                End Try
                MsgBox("The build design-time output is:" + vbCr  _
                + msg, MsgBoxStyle.Information _
                , "BuildManager Monikers")
            End If
            buildMgrEvents = vsproj.Events.BuildManagerEvents
            AddHandler buildMgrEvents.DesignTimeOutputDeleted _
            , AddressOf OutputDeleted
            AddHandler buildMgrEvents.DesignTimeOutputDirty _
            , AddressOf OutputDirty
        Catch ex As System.Exception
            MsgBox(ex.ToString)
        End Try
    End Sub
    Sub OutputDeleted(ByVal deletedMoniker As String)
        MsgBox(deletedMoniker & " was deleted." _
        , MsgBoxStyle.Information, "BuildManagerEvents Information")
    End Sub
    Sub OutputDirty(ByVal dirtyMoniker As String)
        MsgBox(dirtyMoniker & " is dirty." _
        , MsgBoxStyle.Information, "BuildManagerEvents Information")
    End Sub
    Public Sub OnDisconnection(ByVal disconnectMode  _
    As ext_DisconnectMode, ByRef custom As Array)  _
    Implements IDTExtensibility2.OnDisconnection
        ' Turns off BuildManager event handling when the 
        ' add-in shuts down.
        buildMgrEvents = Nothing
    End Sub
    Public Sub OnAddInsUpdate(ByRef custom As Array)  _
    Implements IDTExtensibility2.OnAddInsUpdate
    End Sub
    Public Sub OnStartupComplete(ByRef custom As Array)  _
    Implements IDTExtensibility2.OnStartupComplete
    End Sub
    Public Sub OnBeginShutdown(ByRef custom As Array)  _
    Implements IDTExtensibility2.OnBeginShutdown
    End Sub
End Class

Compiling the Code

To compile this code, create a new Visual Studio Add-in project and replace the code of the Connect class with the code in the example. Before running the add-in, open a Visual C# or Visual Basic  project in the Visual Studio IDE. For information about how to run an add-in, see How to: Control Add-Ins By Using the Add-In Manager.

See Also

Concepts

Introduction to the BuildManager Object

Introduction to Project Extensibility

Other Resources

Automation and Extensibility for Visual Studio