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
Create a Visual Studio add-in project by using Visual C#.
On the Project menu, click Add Reference, click the .NET tab, select System.Windows.Forms, VSLangProj, VSLangProj2, and VSLangProj80, and then click OK.
Add the following using statements to the top of the Connect.cs file.
using VSLangProj; using VSLangProj2; using VSLangProj80; using System.Windows.Forms;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;Add the following method call to the OnConnection method.
_applicationObject = (DTE2)application; _addInInstance = (AddIn)addInInst; // Call the BuildMangerSample method. BuildManagerSample(_applicationObject);Add the BuildManagerSample method declaration directly below the OnConnection method.
public void BuildManagerSample(DTE2 dte) { }Add the following declarations to the top of the BuildManagerSample method.
Solution2 soln = (Solution2)_applicationObject.Solution; Project proj; VSProject2 vsproj; BuildManager bldMgr;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;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"); }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);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"); }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.
To build the add-in, click Build Solution on the Build menu.
Open a Visual C# or Visual Basic project in the Visual Studio integrated development environment (IDE).
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:
Select the dataset file in Solution Explorer.
Right-click the file and select Properties from the drop-down menu.
On the Properties window modify any of the fields.
To delete the dataset:
Select the dataset file in Solution Explorer.
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