Bill Koukoutsis

Home

Products

Customers

Contact

About

 

 

 

 

 

 

Anti-Spam Software

 

 

 

BKToolboxInstaller Tutorial

 

Before You Begin

To work through this tutorial your will need the release version of Microsoft Visual Studio .NET 2003.

 

Those of you who are reasonably comfortable with component creation can quickly skim through the next topic, "Creating the Installable Component", and use your own component in the final topic, "Creating the Setup Project".

 

Creating the Installable Component

This topic is split into two sections. The first section focuses on creating the installable component using C# and the second focuses on creating the installable component using VB.NET. Which section you choose to follow will depend on your language of preference.

 

C#

Create a new "Class Library" project and name it "MyComponent".

 

Remove the default class "Class1.cs":

  • Highlight the "Class1.cs" entry in the "Solution Explorer" window.

  • Select <Edit> + <Delete> from the menu.

 

Add a new component class to the project and name it "MyComponentClass.cs":

  • Select <Project> + <Add Component...> from the menu.

  • Highlight the "Component Class" template option.

  • Type the "MyComponentClass.cs" for the "Name" field and click on the [OK] button.

 

Add the "MyComponentClass_CSharp.ico" icon to the project.

  • Select <File> + <Add Existing Item...> from the menu.

  • Set the "Files of Type:" field to "All Files (*.*)".
  • Navigate to the Media folder found in the BKToolboxInstaller installation folder.

 

eg. C:\Program Files\Bill Koukoutsis\BKToolboxInstaller v1.0.0\Media

 

  • Highlight the "MyComponentClass_CSharp.ico" entry and click on the [Open] button.

  • Highlight the "MyComponentClass_CSharp.ico" entry in the "Solution Explorer" window.

  • Set the "Build Action" property in the "Property" window to "Embedded Resource".

 

Notes: This is the icon that will be displayed in the Visual Studio toolbox. It contains 2 image types. The first is 16x16 pixel (16 color) image used to display the component in the Visual Studio toolbox as well as in the designer of container components and controls. The second is a 32x32 pixel (16 color) image used to display the component in the designer of container components and controls when the designer is set to view large icons.

 

Add a reference to the "System.Drawing.dll" assembly:

  • Select <Project> + <Add Reference...> from the menu.

  • Highlight "System.Drawing.dll", click on the [Select] button and then click on the [OK] button.

 

Notes: The "ToolboxBitmapAttribute" in the "System.Drawing" assembly will allow the Visual Studio toolbox to recognise the visual association between the "MyComponentClass_CSharp.ico" icon and the component defined by "MyComponentClass.cs".

 

Open "MyComponentClass.cs" in code edit mode:

  • Highlight the "MyComponentClass.cs" entry in the "Solution Explorer" window.

  • Select <View> + <Code> from the menu.

 

Import the "System.Drawing" namespace from the referenced assembly; "System.Drawing.dll":

  • Type or copy and paste the following text above the class declaration (disregard any line breaks you might see):

 

Using System.Drawing;

 

Associate the "MyComponentClass_CSharp.ico" icon with the component defined by "MyComponentClass.cs":

  • Type or copy and paste the following text at the line above the class declaration (disregard any line breaks you might see):

 

[ToolboxBitmap(typeof(MyComponent.MyComponentClass), "MyComponentClass_CSharp.ico")]

 

You can skip the next topic and go to "Creating the Setup Project".

 

VB.NET

Create a new "Class Library" project and name it "MyComponent".

 

Remove the default class "Class1.vb":

  • Highlight the "Class1.vb" entry in the "Solution Explorer" window.

  • Select <Edit> + <Delete> from the menu.

 

Add a new component class to the project and name it "MyComponentClass.vb":

  • Select <Project> + <Add Component...> from the menu.

  • Highlight the "Component Class" template option.

  • Type the "MyComponentClass.vb" for the "Name" field and click on the [OK] button.

 

Add the "MyComponentClass_VBNET.ico" icon to the project.

  • Select <File> + <Add Existing Item...> from the menu.

  • Set the "Files of Type:" field to "All Files (*.*)".
  • Navigate to the Media folder found in the BKToolboxInstaller installation folder.

 

eg. C:\Program Files\Bill Koukoutsis\BKToolboxInstaller v1.0.0\Media

 

  • Highlight the "MyComponentClass_VBNET.ico" entry and click on the [Open] button.

  • Highlight the "MyComponentClass_VBNET.ico" entry in the "Solution Explorer" window.

  • Set the "Build Action" property in the "Property" window to "Embedded Resource".

 

Notes: This is the icon that will be displayed in the Visual Studio toolbox. It contains 2 image types. The first is 16x16 pixel (16 color) image used to display the component in the Visual Studio toolbox as well as in the designer of container components and controls. The second is a 32x32 pixel (16 color) image used to display the component in the designer of container components and controls when the designer is set to view large icons.

 

Add a reference to the "System.Drawing.dll" assembly:

  • Select <Project> + <Add Reference...> from the menu.

  • Highlight "System.Drawing.dll", click on the [Select] button and then click on the [OK] button.

 

Notes: The "ToolboxBitmapAttribute" in the "System.Drawing" assembly will allow the Visual Studio toolbox to recognise the visual association between the "MyComponentClass_VBNET.ico" icon and the component defined by "MyComponentClass.vb".

 

Open "MyComponentClass.vb" in code edit mode:

  • Highlight the "MyComponentClass.vb" entry in the "Solution Explorer" window.

  • Select <View> + <Code> from the menu.

 

Import the "System.Drawing" namespace from the referenced assembly; "System.Drawing.dll":

  • Type or copy and paste the following text 3 lines above the class declaration (disregard any line breaks you might see):

 

Imports System.Drawing

 

Associate the "MyComponentClass_VBNET.ico" icon with the component defined by "MyComponentClass.vb":

  • Type or copy and paste the following text at the line above the class declaration (disregard any line breaks you might see):

 

<ToolboxBitmap(GetType(MyComponent.MyComponentClass),

"MyComponentClass_VBNET.ico")> _

 

Creating the Setup Project

Add a "Setup" project to your solution:

  • Select <File> + <Add Project> + <New Project...> from the menu.

  • Select the "Setup and Deployment Project" option in the "Project Types:" list.

  • Select the "Setup Project" option in the "Templates:" list.

  • Type "MySetup" for the "Name:" field and click on the [OK] button.

 

Configure the "MySetup" project:

  • Type "MyComponent" for the "Product Name" field in the "Properties" window.

  • Type "MyComponent" for the "Title" field in the "Properties" window.

 

Add the "BKToolboxInstaller" assembly to the "Setup" project's target "Application Folder":

  • Highlight the "Application Folder" folder in the "File System" pane.

  • Select <Project> + <Add> + <Assembly...> from the menu.

  • Select "BKToolboxInstaller" from the .NET "Component Selector" list, click on the [Select] button, then click on the [OK] button.

 

Add the "MyComponent" project output to the "Setup" project's target "Application Folder":

  • Highlight the "Application Folder" folder in the "File System" editor.

  • Select <Project> + <Add> + <Project Output...> from the menu.

  • Select "MyComponent" from the "Project:" field.

  • Select "Primary Output" from the list.

  • Select "(Active)" from the "Configuration:" field.

  • Click on the [OK] button.

 

Open the "Custom Actions" editor:

  • Select <View> + <Editor> + <Custom Actions> from the menu.

 

Set the "Install" "Custom Action" using the "BKToolboxInstaller" assembly:

  • Highlight the "Install" folder in the "Custom Action" editor.

  • Select <Action> + <Add Custom Action...> from the menu.

  • Double click on the "Application" folder in the "Select Item in Project" dialog.

  • Highlight the "BKToolboxInstaller.dll" entry and click on the [OK] button.

  • Type or copy and paste the following text in the "CustomActionData" field of the "Properties" window:

 

/AssemblyFile="[TARGETDIR]MyComponent.dll"

/VisualStudioVersionInstall="2003"

/ToolBoxTabName="MyComponent"

/AssemblyShareMethod="gac"

 

Notes: This tells the "BKToolboxInstaller.dll" assembly to install the "MyComponent.dll" assembly into the Visual Studio 2003 toolbox under the tab name of "MyComponent" and share the assembly through the GAC (Global Assembly Cache). See "Appendix A" for further details on available "CustomActionData" properties and options using the "BKToolboxInstaller.dll" assembly.

 

Set the "Uninstall" "Custom Action" using the "BKToolboxInstaller" assembly:

  • Highlight the "Uninstall" folder in the "Custom Action" editor.

  • Select <Action> + <Add Custom Action...> from the menu.

  • Double click on the "Application" folder in the "Select Item in Project" dialog.

  • Highlight the "BKToolboxInstaller.dll" entry and click on the [OK] button.

  • Type or copy and paste the following text in the "CustomActionData" field of the "Properties" window:

 

/AssemblyFile="[TARGETDIR]MyComponent.dll"

/VisualStudioVersionInstall="2003"

/ToolBoxTabName="MyComponent"

/AssemblyShareMethod="gac"

 

Notes: This tells the "BKToolboxInstaller.dll" assembly to uninstall the "MyComponent.dll" assembly from the Visual Studio 2003 toolbox which is under the tab name of "MyComponent" and un-share the assembly which has been shared through the GAC (Global Assembly Cache). See "Appendix A" for further details on available "CustomActionData" properties and options using the "BKToolboxInstaller.dll" assembly.

 

Build the solution and run the "Setup" project:

  • Select <Build> + <Build Solution> from the menu.

  • Highlight "MySetup" from the "Solution Explorer" window.

  • Select <Project> + <Install> from the menu.

 

Appendix A : CustomActionData Properties and Options

There are currently 4 parameters that can be passed to BKToolboxInstaller.dll assembly via the custom action data of the install or uninstall process:

 

1. AssemblyFile

 

This is the fully qualified name of the assembly file containing the components and/or controls to install into the Visual Studio .NET toolbox.

 

This parameter is mandatory.

 

2. VisualStudioVersionInstall

 

This is the version of Visual Studio, and subsequently the IDE's toolbox, to install the components and/or controls into.

 

Valid Values are:

 

"all"

Install into all available versions of Visual Studio .NET (currently supports Visual Studio .NET 2002 and 2003).

"2002"

Install into the Visual Studio .NET 2002 toolbox (if available).

"2003"

Install into the Visual Studio .NET 2003 toolbox (if available).

 

Values are not case sensitive ("all" = "All" = "ALL").

 

The default value is "all".

 

3. ToolboxTabName

 

The name of the new Visual Studio .NET toolbox tab to install the components and/or controls into.

 

The default value is the name of the assembly file (less its file extension) containing the components and/or controls to install into the Visual Studio .NET toolbox.

 

For example, if the name of the assembly file is "MyComponents.dll" then by default, the name of the Visual Studio .NET toolbox tab will be "MyComponents".

 

4. AssemblyShareMethod

 

Valid Values are:

 

"gac"

Share the assembly by installing it into the GAC (Global Assembly Cache). This method is only valid if installing the assembly on a Windows 2000, Windows XP or Windows 2003 operating system and the assembly has a strong name. If the above criteria are not met then the assembly is shared through the registry ("reg").

"reg"

Share the assembly through the Windows registry.

 

Values are not case sensitive ("gac" = "Gac" = "GAC" and "reg" = "Reg" = "REG").

 

The default value is "reg".