Walkthrough: Using a Custom Action to Display a Message at Installation

Article
11/01/2012

The following walkthrough demonstrates how to use a custom action to take user input and pass it to a message box that appears during installation. This is a simple demonstration of custom actions, which are useful for many other tasks. For example, a custom action could take as user input the location of the Setup.exe file and use it to launch the application after installing it.

This walkthrough demonstrates passing data to a dynamic property using a custom action, and how to use an installer class and the CustomActionData property.

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 Visual Studio Settings.

To create a custom action

On the File menu, point to New, and then click Project.
In the New Project dialog box, select Visual Basic in the Project Types pane, and then choose Class Library in the Templates pane. In the Name box, type PassData.

The project is added to Solution Explorer.

To create an installer class

On the Project menu, click Add Class.

In the Add New Item dialog box, choose Installer Class. Accept the default name.
When the installer class appears on the design surface, right-click the design surface and click View Code to view the file contents in the code editor.

Add the following procedure to override the Install, Commit, Rollback, and Uninstall procedures of the base class.

Public Overrides Sub Install(ByVal stateSaver As System.Collections.IDictionary)
    MyBase.Install(stateSaver)
    Dim myInput As String = Me.Context.Parameters.Item("Message")
    If myInput Is Nothing Then
        myInput = "There was no message specified"
    End If
    MsgBox(myInput)
End Sub

Public Overrides Sub Commit(ByVal savedState As System.Collections.IDictionary)
    MyBase.Commit(savedState)
End Sub

Public Overrides Sub Rollback(ByVal savedState As System.Collections.IDictionary)
    MyBase.Rollback(savedState)
End Sub

Public Overrides Sub Uninstall(ByVal savedState As System.Collections.IDictionary)
    MyBase.Uninstall(savedState)
End Sub

public override void Install(System.Collections.IDictionary stateSaver)
{
    base.Install(stateSaver);
    string myInput = Context.Parameters["message"];
    if (myInput == null)
    {
        myInput = "There was no message specified";
    }
    MessageBox.Show(myInput);
}

public override void Commit(IDictionary savedState)
{
    base.Commit(savedState);
}

public override void Rollback(IDictionary savedState)
{
    base.Rollback(savedState);
}

public override void Uninstall(IDictionary savedState)
{
    base.Uninstall(savedState);
}

Note

If you type Public Overrides, then type space, Intellisense will provide a list of methods and properties; you can select Install from the list and get the complete declaration.

In Solution Explorer, right-click the Class1 code file and select Delete (because it is unnecessary).

To create a deployment project

On the File menu, point to Add, and then click New Project.
In the Add New Project dialog box, in the Project Type pane, expand the Other Project Types node and select Setup and Deployment, then choose Setup Project in the Templates pane. In the Name box, type PassData Installer.
In the Properties window, select the ProductName property and type PassData.

Also, select the Manufacturer property and type My Company.
In the File System Editor, select the Application Folder node. On the Action menu, point to Add, then click Project Output.
In the Add Project Output Group dialog box, select the primary output for the PassData project.

Primary output from PassData (Active) appears in the File System Editor.

To add a custom action

Select the PassData Installer project in Solution Explorer. On the View menu, point to Editor, and then click Custom Actions.
In the Custom Actions Editor, select the (top-level) Install node. On the Action menu, click Add Custom Action.
In the Select item in Project dialog box, double-click the Application Folder.
Select Primary output from PassData (Active) to add the PassData custom action to the Install node.
In the Properties window, select the CustomActionData property and type /Message="[MESSAGE]".
Make sure the InstallerClass property is set to True (this is the default).

To customize the installation user interface

Select the Setup project in Solution Explorer. On the View menu, point to Editor, and then click User Interface.
In the User Interface Editor, select the Start node under Install. On the Action menu, click Add Dialog.
In the Add Dialog dialog box, select the Textboxes (A) dialog.
On the Action menu, click Move Up. Repeat until the Textboxes (A) dialog is above the Installation Folder node.
In the Properties window, select the BannerText property and type:

What is your message?
Select the BodyText property and type:

Enter your message here.
Select the Edit1Label property and type:

Message:
Select the Edit1Property property and type:

MESSAGE
Select the Edit2Visible, Edit3Visible, and Edit4Visible properties and set them to False.
On the Build menu, click Build Pass Data Installer.

To install on your development computer

Select the PassData Installer project in Solution Explorer. On the Project menu, click Install.

This will run the installer on your development computer. In the What is your Message? installation dialog box, type Hello World!.

Note

You must have install permissions on the computer in order to run the installer.

To deploy to another computer

In Windows Explorer, navigate to your project directory and find the built installer. The default project configuration is either Debug or Release.
Copy PassData Installer.msi, Setup.exe, and all other files and subdirectories in the directory to another computer.

Note

To install on a computer that is not on a network, copy the files to traditional media such as CD-ROM.

On the target computer, double-click Setup.exe to run the installer. In the What is your Message? installation dialog box, type Hello World!.

Note

You must have install permissions on the computer in order to run the installer.

To test the installation

Run the application and verify that the text box contains the text 'Hello World!', which you entered during installation.

To uninstall the application

In Windows Control Panel, double-click Add or Remove Programs or Programs and Features.
Select PassData Installer and click Remove or Uninstall, then click OK to close the dialog box.

Tip

To uninstall from your development computer, on the Project menu, click Uninstall.