Introduction
If you have ever tried to write a user control in Visual Studio.NET, you'll already know that the process is bittersweet. On one hand, writing the control itself is painless and Visual Studio 2005 has greatly improved the process of making controls work on multiple .NET platforms via design-time attributes and "asmmeta" assemblies. On the other hand, however, deploying controls and adding them to the Toolbox is a process rife with errors. It is definitely not a matter of adding a registry key (as I would have liked to see).
After getting a lot of e-mails from customers asking me how to add real-time GPS controls to their Toolbox, I decided that I needed to come up with some kind of utility to get the job done. Visual Studio 2005 does already have some mechanisms for installing user controls, such as ".vsi" files, but unfortunately this approach typically results in a "Package Load Failure" and does not have a guarantee to work on every VS2005 installation. Fortunately, Chetan Chudasama generously gave out source code in his blog which explains how to add or remove Toolbox controls using code and the "DTE" (Design-Time Environment) for Visual Studio. Thanks to his efforts, I was able to turn the code into a command-line utility which is well-suited for installers (which is usually when Toolbox controls are installed).
This article describes how to use the utility and integrate it into your own installers. You are welcome to redistribute this utility and I consider it freeware.
Usage
The Toolbox utility is a single executable which processes one or more tasks via the command-line. Since the Toolbox itself can change depending on whether you are working with Desktop Framework 2.0 or Compact Framework 2.0 applications, different commands exist which let you add desktop or mobile device controls. I have optimized the utility to minimize the calls to the DTE and it runs a couple of seconds faster than Chetan's code if you have multiple assemblies to install.
When the utility runs, the following window will appear. Since the utility must launch a hidden instance of Visual Studio 2005 (devenv.exe), this can be a time-consuming process. A progress bar helps to show that something is actually happening during Toolbox modifications:
I kept the window free from company logos and branding so it will look like your own utility. The command line must follow the following syntax:
Toolbox.exe [/silent] /installdesktop assembly toolbox_tab [...]
Toolbox.exe [/silent] /installpocketpc assembly toolbox_tab [...]
Toolbox.exe [/silent] /installcustom template assembly toolbox_tab [...]
Toolbox.exe [/silent] /uninstall toolbox_tab [...]
... each command is as follows:
/silent Suppresses all output during installation or uninstallation.
/installdesktop Installs controls written for Desktop Framework 2.0 to the toolbox.
/installpocketpc Installs controls written for Compact Framework 2.0 to the toolbox.
/installcustom Installs controls written for a specific kind of device project to the toolbox.
/uninstall Removes an entire Toolbox tab.
[...] Multiple install commands can be appended to install/uninstall multiple controls at one time.
... and the parameters for each command are:
"assembly" is the absolute path to an assembly containing user controls.
"toolbox_tab" is the name of the Toolbox Tab where control should be installed.
"template" is the name of a ZIP file from the Templates folder indicating a specific kind of project.
The utility can install or uninstall any number of controls in one call, which is important since about 3-5 seconds are required just to launch and shut down Visual Studio 2005. The commands will vary depending on which Toolbox you need to modify.
Installing Desktop User Controls
To install desktop controls, you must use the
/installdesktop command and pass in the path to an assembly as well as the name of the Toolbox tab to add the control to:
Toolbox.exe /installdesktop "C:\MyUserControl.dll" "My Toolbox Tab Name"
Installing PocketPC User Controls
To install mobile device controls, such as PocketPC controls for Windows Mobile 2003, you must use the
/installpocketpc command and pass in the path to an assembly as well as the name of the Toolbox tab to add the control to:
Toolbox.exe /installpocketpc "C:\MyUserControl.PocketPC.dll" "My Toolbox Tab Name (PocketPC)"
... if you provide the same user controls for multiple platforms, you should add "(PocketPC)" to the Toolbox tab name to keep the controls separated.
Installing User Controls for Custom Toolboxes
To install controls for platforms not yet released at the time of this article, you must use the
/installcustom command and pass in a "template name" along with the path to an assembly, as well as the name of the Toolbox tab to add the control to. The template is the filename of a template ZIP file. You can typically find ZIP files here:
\Program Files\Microsoft Visual Studio 8\Common7\IDE\ProjectTemplates\CSharp\
... you don't need the name of the directory since Visual Studio 2005 keeps all of the ZIP file names unique. The following example installs controls for Smartphone:
Toolbox.exe /installcustom "Smartphone2003-WindowsApplication.zip"
"C:\MyUserControl.Smartphone.dll" "My Toolbox Tab Name (Smartphone)"
Uninstalling Controls
There is no mechanism for uninstalling a single control from the Toolbox; entire Toolbox tabs are deleted at one time. This is another reason why it's a good idea to add text to the Toolbox tab name to keep controls separate per platform. To uninstall a Toolbox tab, specify the full tab name:
Toolbox.exe /uninstall "My Toolbox Tab"
Clean Re-Installation of Controls
The Toolbox is not smart enough to know when controls already exist in a tab. This can cause problems because the same control would get added multiple times! To solve this problem, begin the command line with an
/uninstall command immediately before an install command. This will cleanly re-install the toolbox controls:
Toolbox.exe /uninstall "My Toolbox Tab" /installdesktop "C:\MyUserControl.dll" "My Toolbox Tab"
Silent Operation
If for some reason you don't want the progress bar to display, add the
/silent command to the command line:
Toolbox.exe /silent /uninstall "My Toolbox Tab" /uninstall "Another Toolbox Tab"
Summary
The experience of designing user controls for Visual Studio 2005 has improved greatly over Visual Studio 2003, but the process of installing a custom user control is still tedius. Perhaps the folks at Microsoft could use the registry to search for and install custom user controls, much like the
AssemblyFolders registry key is used to locate custom assemblies. This change would vastly simplify installation of custom user controls in the future.
If you find any bugs or wish to see improvements, you can post in the thread on my web site for this utility, located here: Toolbox Utility Forum.
