Better ListView
Better Thumbnail Browser
Better SplitButton
Better ListView Express
Visual Studio Toolbox Control Integration
+ +The Most Complete Guide to Visual Studio Toolbox Control Integration
+Libor +Tinka, Lead Developer, ComponentOwl.com
+ +
Contents
+1. Introduction
+2. Prerequisites
+3. Creating a Sample Control
+4. Manual Toolbox Integration
+5. Toolbox Integration using TCI
+6. Toolbox Integration using DTE
+7. Toolbox Integration using VSI Packages
+8. Toolbox Integration using VSPackages
+9. Toolbox Integration using VSIX Packages
+10. Supporting Multiple Version of .NET Framework
+11. Sample Source Code
1. Introduction
+This tutorial is intended for developers who would like to distribute their +WPF or WinForms controls and automatically put them into Visual Studio Toolbox +during installation.
+I struggled with Toolbox integration earlier because there are several possible +approaches (harder to decide between them). Each approach have its own pros and cons and +no overall comparison is provided. I wrote this tutorial to shed some light on the topic +and spare you hours, maybe days of research and experimenting with aspects of +Visual Studio (Toolbox) extensibility.
+We will first take a look on Toolbox control integration in general to get a +big picture. Each approach will be then discussed in detail and the following +question will be answered:
+-
+
- How to install control in Visual Studio Toolbox? +
- How to update the control? +
- How to uninstall/remove the control? +
- How to support multiple Visual Studio versions? +
+
There are several options on how to integrate your controls with Visual +Studio Toolbox:
+-
+
- Manual installation +
- Toolbox Control Installer (TCI) +
- Visual Studio Automation Object Model (DTE) +
- VSPackage +
- VSI package +
- VSIX package +
Manual installation
+The simplest way of adding control into Visual Studio Toolbox is from within +the IDE.
+This approach have one crucial drawback, which is that you leave Toolbox +integration to the user. Many developers are not that experienced with Visual +Studio and when your component is shipped, even if you provide appropriate +step-by-step guide, they may find it too complicated and rather try +another component which "just works". I thought that every developer using +Visual Studio is experienced enough to know how to add new items in VS Toolbox, +but I received few e-mails from users who uninstalled the product just because +the component have not appeared in the Toolbox and they thought it is broken +(without reading our documentation, of course). On the other hand, there is +a group of users who are not experienced developers, but are in charge of trying +some products in a given company (e.g. project managers). These people can +install the component, play with it and they would really appreciate if it just +works. This increases chance they will actually purchase your product.
+Advantages: zero effort
+Disadvantages: require experienced users, slows user
+producitivity, updating controls is not intuitive
Toolbox Control Installer (TCI)
+Visual Studio 2005 SDK contained a VSPackage called Toolbox Control +Installer. This package comes pre-installed with Visual Studio 2008 and newer. +Its job is to simplify the specific task of extending Visual Studio Toolbox. +This approach requires you to install your assembly in GAC (Global Assembly +Cache) and create a key in Windows Registry.
+Advantages: simple and fast component installation, updating
+and removing
+Disadvantages: requires installation in GAC (not always
+wanted), VS 2005 supported with SDK only
Visual Studio Automation Object Model (DTE)
+If you are not afraid of COM, you can try DTE (Development Tools Environment) approach. +There is already a project on CodePlex called +Visual Studio Toolbox Manager, +which solves the toolbox integration problem using a simple command-line +application. The project is outdated since it does not support Visual Studio +2010 and newer. I made a project called DteToolboxInstaller, which +is also a command-line application and does support Visual Studio 2013, 2012, 2010, +2008 and 2005. You can use the project as you like. The main disadvantage of DTE +approach is the speed. The installer have to run devenv.exe using the automation interface, create a +fake VS Solution, open Toolbox, add the stuff and then close the Solution. The +whole process take no less than 10 seconds. If you want to integrate with two or +three versions of Visual Studio, it can take well over a minute.
+Advantages: does not require updating registry or GAC, full
+control over Toolbox
+Disadvantages: very slow, separate installation required for
+every version of Visual Studio
VSPackage
+A VSPackage seems to be a natural option. VSPackages allow any type +of Visual Studio extension and you can manipulate Toolbox as well. There was a trouble +with VSPackages in providing a Package Load Key (PLK) which can be +generated only manually using web form. The requirement for PLK vanished with +Visual Studio 2010 (hooray!). The nice thing about VSPackage approcach is that it does not slow +down the installation process. The package is loaded and the controls are installed +on-demand (when the Toolbox is opened for the first time after installation). +After trying all the approaches, using VSPackage seems to be fastest and most +universal one.
+Advantages: quick installation, appearance in About box and
+other extensibility features
+Disadvantages: cmplicated setup, each component requires its
+own package if shipped separately
VSI Package
+VSI packages are quite old but you can use them for integration with Visual +Studio 2005 and newer. It have very simple structure and you can create one even +without Visual Studio. The only trouble with VSI compared to other +approaches is invoking a wizard form which cannot be suppressed. The +installation just cannot run in "quiet" mode. Another trouble with VSI is that a +digital signature is required in order to get rid of a warning dialog. Your control will be always installed under "My Controls" tab in the +Toolbox, which is not always desirable.
+Advantages: simple creation, installer provided by Visual
+Studio, automated creation and signing requires several specific steps
+Disadvantages: no quiet mode (extra steps when custom installer
+is used), manual uninstallation
VSIX Package
+VSIX packages came with Visual Studio 2010 so you can integrate with 2010 or +newer. the .VSI and .VSIX file extensions are associated with Visual Studio so +you can simply double-click it or run it via shell. You can also run +VsixInstaller.exe utility that performs the installation. Good news: No more +nag screens when VSIX is not signed - the installer only contains a dialog with +simple text: "This extension does not contain a digital signature." +Even better news: The VsixInstaller supports quiet mode!
+Please note that VSI and VSIX package installers contain features like +displaying EULA, choosing which components to install or localization. When +deploying your controls for use in Visual Studio, you won't need an installer on +top of the package.
+Advantages: installer provided by Visual Studio, quiet mode,
+fast installation
+Disadvantages: package project required, automated creation is
+complicated, no support for VS 2005 and 2008
Comparison of Approaches
+Here is a table summarizing features of the discussed approaches. As you can +see, the VSPackage approach gives you the most freedom, but is also hardest +to implement. We will discuss every approach so +that you will be able to impement the one that suits you best.
+| + | 2005 | +2008 | +2010 | +2012 | +2013 | +Speed | +Install Automation | +Uninstall automation | +
| Manual installation | + |
+ |
+ |
+ |
+ |
+ depends on user | + |
+ |
+
| TCI | + |
+ |
+ |
+ |
+ |
+ fast | + |
+  |
+
| EnvDTE | + |
+ |
+ |
+ |
+ |
+ slow | + |
+ |
+
| VSI | + |
+ |
+ |
+ |
+ |
+ moderate | + |
+ |
+
| VSIX | + |
+ |
+ |
+ |
+ |
+ moderate (faster than VSI) | + |
+ |
+
| VSPackage | + |
+ |
+ |
+ |
+ |
+ fast | + |
+ |
+
2. Prerequisites
+We will focus on integration with Visual Studio 2010, 2012 and 2013. Hence you will need:
+-
+
- Visual Studio 2010 (or 2012, 2013) +
- Visual Studio 2010 SDK (or 2012 SDK, 2013 SDK) +
- Microsoft Windows SDK +
The VS SDK contains regpkg.exe tool and project templates discussed in VSIX +and VSPackage approaches.
+The Windows SDK contains gacutil.exe, guidgen.exe, signtool.exe and other +useful tools.
+There are two kinds of versioning used for Visual Studio. One is based on the +release name (e.g. Visual Studio 2008) and the other is a classic version number +(e.g. 8.0). Both will be used, so it should be noted which version numbers +correspond to which versions of Visual Studio:
+| Release name | +Version number | +
| Visual Studio 2005 | +8.0 | +
| Visual Studio 2008 | +9.0 | +
| Visual Studio 2010 | +10.0 | +
| Visual Studio 2012 | +11.0 | +
| Visual Studio 2013 | +12.0 | +
3. Creating a Sample Control
+We will start by creating simple WinForms control for integration in VS +Toolbox.
+You can start with File - New - Project... (Control+Shift+N) and select +Windows Forms Controls Library template.
+Of course, you can also create empty Class Library project, add references to +System.Drawing and System.Windows.Forms and create a new control. In fact, any +DLL containing public classes derived from Control will +suffice.
+We want to support .NET Runtime version 4.0 and 4.5, so the control should be +built against .NET 4.0 to ensure compatibility (the lower framework version you +use, the wider range of compatible frameworks since they are backward +compatible). It should be noted that .NET 4.5 is an in-place update of .NET 4.0 +and hence the 4.5 assemblies will work on machines with 4.0 runtime installed +unless you use some feature specific to 4.5.
+If you have multiple controls in your assembly and don't want to use some of +them in Toolbox, decorate them with ToolboxItem attribute with +defaultType parameter set to false:
+
+[ToolboxItem(false)]
+public class InvisibleControl : UserControl
+{
+ ...
+}
+
+I have created a very simple control called SampleControl:
+
Finally, I set version of the assembly 3.3.0.0 (I chose just something else +than 1.0.0.0 to see where the specific version number appears).
+Custom Transparent Icon for the Toolbox
+Icons for Toolbox are 16 by 16 pixel images. Various image formats are supported +(BMP, JPEG, PNG and ICO). However, you need to +create 256-color BMP image to ensure transparency. The transparent color is determined by bottom left +pixel of the icon. Transparency works for magenta (#ff00ff):
+
The icon file should have same name as the control class (i.e. +SampleControl.BMP).
+Finally, use ToolboxBitmapAttribute to link icon with the control class:
+
+[ToolboxBitmap(typeof(SampleControl), "Resources.SampleControl.bmp")]
+public partial class SampleControl : UserControl
+{
+ ...
+}
+
+Note that icon location matters, at least in C#. Since I have added +the icon under custom folder named Resources, I need to reference +Resources.SampleControl.bmp instead of just SampleControl.bmp.
+Here is the resulting transparent icon in Toolbox:
+
Marking the Control as Toolbox Item
+We can mark control as toolbox item by adding a ToolboxItemAttribute +with defaultType parameter set to true:
++[ToolboxItem(true)] +public partial class SampleControl : UserControl +... ++
This decoration is optional since the controls within assembly are +considered toolbox items by default. However, we can mark certain control +classes with ToolboxItem(false) to hide them from Toolbox. This +comes in handy when we have multiple projects and there are too many controls in +the Toolbox because loaded from all the other projects.
+Signing the Assembly
+The assembly containing controls (SampleControl.dll in our +case) should be strongly named if we want them installed in GAC +(Global Assembly Cache) later on. This is optional in most cases, but the Toolbox Controls +Installer approach requires the assembly being installed in GAC, hence the +strong name is necessary there.
+To give an assembly a strong name, open project properties and find +Signing tab:
+
Check the "Sign the assembly" option and select "<New...>" +from the combo box. This will create a new .SNK file in your project which will +be used to sign the assembly. You can also browse for existing key file. If you +want to distribute multiple assemblies with custom controls, it is a best +practice to use same strong name key for each assembly (it is possible to have +one .SNK file located in Solution folder and put just a link to that file in +each project; when we browse for the key under the Signing tab, the link will be +used without copying the file).
+The SNK (Strong Name Key) file is basically a private key to digitally sign +your assembly. There is also a public key which can be used to verify the +assembly and its shorter variant called "public key token" for assembly +identification.
+4. Manual Toolbox Integration
+Installing
+To install component into Visual Studio Toolbox manually, open some form or +control in designer, open the Toolbox window (Control+Alt+X), right-click on the +Toolbox window and select "Choose Items...":
+
The "Choose Toolbox Items" dialog will show up:
+
You can browse for DLL file with your component by clicking the "Browse..." +button.
+This is the simplest way of putting component in the Toolbox without extra +actions required.
+This can be unpleasant for end-users since it means many clicks they have +to perform. I will explain how to integrate a component a little bit more so that it +will be visible under the ".NET Framework Components" tab in the above dialog box and +possibly show up in Toolbox automatically without extra effort of the user.
+Making the Control Visible in "Choose Toolbox Items" Dialog Box
+As you can see on the above picture, the SampleControl component is already +displayed in the dialog box under ".NET Framework Components" tab.
+This is because the folder containing our control is registered as "assembly folder" in the +registry and hence is searched when the above dialog is populated.
+You can register your own assembly this way by creating a key in registry:
+32-bit OS: HKLM\SOFTWARE\Microsoft\.NETFramework\AssemblyFolders\<your control name> +64-bit OS: HKLM\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\AssemblyFolders\<your control name>+
You can also create key for specific version of .NET runtime (this comes in +handy if you distribute different components for different versions of .NET):
+32-bit OS: HKLM\SOFTWARE\Microsoft\.NETFramework\v4.0.30319\AssemblyFoldersEx\<your control name> +64-bit OS: HKLM\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319\AssemblyFoldersEx\<your control name>+
In both cases, the default value for the key is a string with full path to +the folder with your assembly.
+You can specify Toolbox tab in which the component should show up by adding +subkey named "Toolbox" with single string value "TabName" this value has Toolbox +tab name as data. When you add such control in the Toolbox, it will reside under +new tab with the specified name:
+
+
The control should also appear in "Choose Toolbox Items" dialog box if it +is installed in Global Assembly Cache.
+The control pops up in the Toolbox automatically in +its own tab in Visual Studio 2012/2013.
+Installing the Control in GAC
+The benefit of GAC (Global Assembly Cache) is that the user needs not to +browse for your control. He will just select it form the above dialog box +without having to know where it is actually installed (the dialog is populated +by controls from "assembly folders" and from the GAC).
+The GAC have one useful feature and disadvantage at the same time: It allows +holding multiple versions of the same assembly. When user makes reference to +your control from GAC and set "Specific Version" to true in +Reference Properties window, it will be tied to that version. When you install an +"update", a new version will be added to GAC, but the user will stay with the +older one. Of course, the "Choose Toolbox Items" dialog will show both versions, +so the user can just replace old reference with the new one.
+You can make the installer removing any older versions from GAC during +installation and add/keep just the newest one. This will force the user to +replace the reference since it breaks the build.
+You can work with GAC by using tool called gacutil.exe or +from code. We will discuss both approaches.
+The gacutil.exe is located in Microsoft Windows SDK directory. There are two +such extecutables:
+c:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Bin\gacutil.exe +c:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Bin\NETFX 4.0 Tools\gacutil.exe+
The former is for .NET Framework up to version 3.5. The latter is for +.NET 4.0 and higher. This is for compatibility reasons as a separate GAC have +been introduced with .NET 4.0.
+You can install an assembly to GAC by calling:
+gacutil.exe /i SampleControl.dll+
To uninstall it, we refer to our assembly by its assembly name, not file +name:
+gacutil.exe /u SampleControl+
Finally, you can check if the assembly is installed in GAC by listing any +instances of the provided name:
+gacutil.exe /l SampleControl+
It is not wise, however, to use gacutil.exe from a custom +installer as it is located in SDK that user might not have installed. +Furthermore, the SDK license does not allow bundling gacutil.exe +with your installer.
+Some installers like Inno Setup or MSI allow installing in GAC anyway.
+You can also work with GAC using +System.EnterpriseServices.Internal.Publish class. The class have two +methods: GacInstall and GacRemove. Both +methods take just path to assembly file as a parameter, so for example:
+(new Publish()).GacInstall(assemblyPath);+
will install the specified assembly in GAC.
+Updating
+Updating the control depends on how it is installed and referenced.
+If you have added component in the Toolbox manually via "Choose Toolbox Items" +dialog box and "Browse..." button, i.e. as a file reference, the +default property of such reference is that it simply points to the specified +file no matter which version it have (unless user sets "Specific Version" to +true in reference properties window; the default is +false in this case). Simply replacing the DLL with the control by a newer +file will suffice. If the user have specified "Specific Version" to true, +the build will break because the reference is no longer valid. He needs to +replace the reference by a new one pointing on the same file which now have +newer version.
+If you have added the component from GAC (these components also appear in the +"Choose Toolbox Items" dialog box), the "Specific Version" property of the +reference is true by default:
+
This means that even if you install a newer version of the component in GAC, +the project will still reference the older version and both versions will reside +in GAC.
+If you remove all versions of the component from GAC (e.g. using +gacutil.exe) and then install just the newest one, the build will break +unless the user changed "Specific Version" property to false.
+Removing
+Removing the manually installed control consists of just reverting all the +steps done during the installation.
+In case of file references, deleting the file is sufficient.
+In case of tighter integration (GAC, registry), the registry keys need to be +deleted and the control can be removed from GAC (e.g. using gacutil.exe).
+Resetting Toolbox and Clearing the Toolbox Cache
+The Toolbox can fall into state where it does not display some items, some are +duplicate and some can be disabled. Sometimes the only remedy is to let Visual +Studio rebuild the +Toolbox from scratch.
+To do that, right-click on the Toolbox window and select "Reset +Toolbox". Visual Studio will go through all the installed packages and reloads +components into the Toolbox.
+If this won't help, you can perform hard reset of the Toolbox. Exit +Visual Studio and delete all .TBD files in the following folder:
+\Users\<user>\AppData\Local\Microsoft\VisualStudio\10.0\+
It should be up to four files:
+
Once removed, start Visual Studio again. After showing the Toolbox, all items +should load instead of loading only the cached versions.
+5. Toolbox Integration using TCI
+Installing
+Toolbox Control Installer is a VS package pre-installed in Visual Studio 2008 and +newer. It looks in Windows registry for components and loads them in the +Toolbox.
+Before using TCI, one can check if it is installed in the given version of +VS. For example, the following registry key should exist if the Visual Studio +2010 have TCI installed:
+32-bit OS: HKLM\SOFTWARE\Microsoft\VisualStudio\10.0\Packages\{2c298b35-07da-45f1-96a3-be55d91c8d7a}
+64-bit OS: HKLM\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\10.0\Packages\{2c298b35-07da-45f1-96a3-be55d91c8d7a}
+The TCI package GUID is always the same so you can make the check for any +version of Visual Studio with the above key (only change the version number from +10.0 to corresponding version number, of course).
+The only prerequisites for the assembly is that it should have strong name +(i.e. to be signed). See section "Creating the Sample Control" for more +information.
+The installation consists of putting the control in GAC (see previous +section for more information) and creating registry keys.
+Suppose we have the SampleControl installed in GAC:
+
We will make reference to this assembly from registry by creating the +following key:
+32-bit OS: HKLM\SOFTWARE\Microsoft\VisualStudio\10.0\ToolboxControlsInstaller\SampleControl, Version=3.7.0.0, Culture=neutral, PublicKeyToken=3cc4c7b61201d46c +64-bit OS: HKLM\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\10.0\ToolboxControlsInstaller\SampleControl, Version=3.7.0.0, Culture=neutral, PublicKeyToken=3cc4c7b61201d46c+
The default value for the key is the Toolbox tab name name you would like to +have for the component(s), e.g. "Component Owl".
+Installing in Visual Studio 2012 and 2013
+One extra step is required to make this work in Visual Studio 2012/2013, which is +adding the registry key also in its user config hive, i.e.:
+HKCU\Software\Microsoft\VisualStudio\11.0_Config\ToolboxControlsInstaller\SampleControl, Version=3.7.0.0, Culture=neutral, PublicKeyToken=3cc4c7b61201d46c+
for VS 2012. Use 12.0_Config for VS 2013.
+Updating
+Updating the component is very simple. Just modify the above registry keys by +changing the version number.
+Removing
+To remove the component, delete the above registry keys. You should also +remove the corresponding assembly from GAC.
+Automating Integration with TCI using TciToolboxInstaller
+I made a simple command-line application called TciToolboxInstaller +which does all the described steps. The usage is simple:
+TciToolboxInstaller.exe [install|uninstall] [vs2005|vs2008|vs2010|vs2012|vs2013] [tab name] [assembly path]+
For example, if you like to install SampleControl.dll in Visual Studio 2012 +Toolbox, just call:
+TciToolboxInstaller.exe install vs2012 "Component Owl" SampleControl.dll+
You can use quotes for the last two parameters if they contain spaces.
+The TciToolboxInstaller project is contained in sample +source code.
+6. Toolbox Integration using DTE
+Installing
+The +DTE (Development Tools Environment) approach does not require working +with GAC or registry. It remotely manipulates Visual Studio Toolbox and +adds/removes items as needed.
+The whole installation is done from (managed) code using COM wrappers. It +works in the following steps:
+-
+
- Check if an instance of Visual Studio is not running. If not, continue. +
- Retrieve an EnvDTE.DTE object corresponding to the + version of Visual Studio we want to integrate with. +
- Create a "dummy" project using the DTE object +
- Obtain Toolbox window and ToolBox object from it. +
- Find or create ToolBoxTab object. +
- Add item in the Toolbox tab (ToolBoxTab.ToolBoxItems.Add). +
- Wait until current instance of Visual Studio stops running. +
Here are some of the step/strongs in C# code - it is an excerpt from +DteToolboxInstaller project provided in sample source code:
+
+// obtain a DTE object
+Type typeDTE = Type.GetTypeFromProgID("VisualStudio.DTE.11.0");
+
+DTE dte = (DTE)Activator.CreateInstance(typeDTE, true);
+
+// create a temporary file
+string tempFile = Path.GetFileNameWithoutExtension(Path.GetTempFileName());
+string tempDirectory = string.Format("{0}{1}", Path.GetTempPath(), tempFile);
+
+// create Visual Studio Solution
+Solution4 solution = (dte.Solution as Solution4);
+
+string templatePath = solution.GetProjectTemplate(TemplateName, "CSharp");
+
+solution.AddFromTemplate(templatePath, tempDirectory, DummyProjectName, false);
+
+// get Toolbox window
+Window window = dte.Windows.Item(Constants.vsWindowKindToolbox);
+
+// get Toolbox
+ToolBox toolBox = (ToolBox)window.Object;
+
+// get Toolbox tab
+ToolBoxTab toolBoxTab = (GetToolBoxTab(toolBox.ToolBoxTabs) ?? toolBox.ToolBoxTabs.Add(this.tabName));
+
+// add new item under the Toolbox tab
+toolBoxTab.ToolBoxItems.Add(assemblyName, this.assemblyPath, vsToolBoxItemFormat.vsToolBoxItemFormatDotNETComponent);
+
+// select the Toolbox tab
+toolBoxTab.Activate();
+
+// cleanup
+dte.Solution.Close(false);
+dte.Quit();
+Marshal.ReleaseComObject(dte);
+
+// wait till Visual Studio turns off completely
+if (IsVisualStudioRunning())
+{
+ Thread.Sleep(VisualStudioProcessTimeout);
+}
+
+There are several obstacles on implementing the DTE approach.
+First of all, we need to ensure that Visual Studio is not running during the +installation - this is because we want messages sent to Visual Studio instance +will arrive in the "invisible" one ran from our code and not the one which the +user have currently opened.
+Similarly, we would like to wait a while until the instance terminates after +installation. This is necessary when integrating with multiple versions of +Visual Studio when just a single instance have to be running at a time. Doing two +installations too quickly in succession may cause the previous one to fail +because a Visual Studio instance is still running.
+The communication between our code and Visual Studio is mediated by OLE +message filter which needs to be implemented. You can take a look on +DteToolboxInstaller (see below) source code, where is a working installer +implemented that uses this approach.
+Updating and Removing
+Since we have full control over the Toolbox with this approach, updating or +removing items/tabs is done with the corresponding DTE objects.
+Automatic Integration with DTE using DteToolboxInstaller
+I made a simple command-line application called DteToolboxInstaller +which does all the necessary steps and solves the deals with the discussed +obstacles. The usage is simple:
+DteToolboxInstaller.exe [install|uninstall] [vs2005|vs2008|vs2010|vs2012|vs2013] [tab name] [assembly path]+
For example, if you like to install SampleControl.dll in Visual Studio 2012 +Toolbox, just call:
+DteToolboxInstaller.exe install vs2012 "Component Owl" SampleControl.dll+
You can use quotes for the last two parameters if they contain spaces.
+The DteToolboxInstaller project is contained in sample +source code.
+7. Toolbox Integration using VSI Packages
+Let's consider you don't have a custom installer and want to distribute your +components in some kind of simple extension package that Visual Studio +understands.
+Visual Studio contains an installer for so called VSI packages that will +do the integration work for you. If you have Visual Studio installed, the .VSI +extension is already associated with the Visual Studio Content Installer.
+Creating the VSI Package
+I have created an empty folder and copied SampleControl.dll in +it. All that is needed to make a VSI package is to create a .VSCONTENT file, +which is simply a XML file satisfying +Visual Studio Content Installer schema:
++<VSContent xmlns="http://schemas.microsoft.com/developer/vscontent/2005"> + <Content> + <FileName>SampleControl.dll</FileName> + <DisplayName>SampleControl</DisplayName> + <Description>ComponentOwl.com SampleControl</Description> + <FileContentType>Toolbox Control</FileContentType> + <ContentVersion>2.0</ContentVersion> + </Content> +</VSContent> ++
The content is readable and pretty straightforward. The +ContentVersion element can contain either "1.0" (support for Visual +Studio 2005, 2008 and 2010) or "2.0" (support for Visual Studio 2008, 2010, +2012, 2013).
+Now we zip the two files and rename extension of the archive to .VSI. We +should end up with the following three files:
+
If you double-click the SampleControl.vsi, the Visual Studio +Content Installer opens up. You can start the installer from command line as +well:
+32-bit OS: C:\Program Files\Common Files\Microsoft Shared\MSEnv\VSContentInstaller.exe SampleControl.vsi +64-bit OS: C:\Program Files (x86)\Common Files\Microsoft Shared\MSEnv\VSContentInstaller.exe SampleControl.vsi+
The installer have a form o wizard:
+
Signing the VSI Package
+By default, the VSI package is not signed. This causes showing: "Publisher: +Unknown" label on the first page of the installation wizard and an unpleasant +dialog box later on:
+
To avoid this, you need to digitally sign the VSI package. Of course, you +have to own a digital certificate (usually an X.509 certificate stored in .PFX +file).
+Because we cannot sign ZIP files, we need to convert the .VSI file (which is +actually a ZIP archive with just an altered extension) to self-extracting archive that the Visual Studio Content +Installer recognizes. There is a tool called MakeZipExe +to do this task:
+MakeZipExe.exe -zipfile:SampleControl.vsi -output:SampleControl-unsigned.vsi -overwrite+
The MakeZipExe tool is located at Visual Studio's binary +folder:
+c:\Program Files (x86)\Microsoft Visual Studio 11.0\Common7\IDE\MakeZipExe.exe+
The second step is signing the .EXE file using signtool.exe. +You can find signtool.exe in Microsoft Windows SDK, i.e.:
+c:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Bin\signtool.exe+
Here is a sample usage of signtool.exe:
+signtool.exe sign /du "http://www.componentowl.com/sample-control" /f certificate.pfx /p abc123 /t "http://timestamp.comodoca.com/authenticode" "SampleControl-signed.vsi"+
When signed, the "Publisher" and "Information URL" labels are filled in the +installer and no dialog box appears. The benefit of signing is obvious - your +users will know they are installing trusted, possibly high-quality software and there +is a higher chance of your software being used more widely (for example, the +government sector usually require such certified software).
+You can also add an EULA to your VSI package. This can be done by adding a +comment metadata in the archive by ZIP archiver that supports such feature (e.g. +WinZip).
+Uninstalling the Control from Toolbox
+As far as I know, the control cannot be removed from the Toolbox +programmatically. You need to delete the control's DLL located at
+c:\Users\<user>\Documents\Visual Studio 2010\Controls\+
the same should be done for every version of Visual Studio installed.
+In Visual Studio, right-click on Toolbox and select "Reset Toolbox". The +component will not be found and disappear. Similarly, you can just +delete the control from the Toolbox or select "Choose Items..." from context +menu and untick the control there:
+
Drawbacks of Using VSI Package
+One drawback of using VSI package is that the installer runs every version of +VS IDE you have installed and which is supported by the package. The form will +disappear eventually, but it lowers user experience.
+Another drawback is that when you want to update your control, the installer +offers whether to rename, replace or skip the file (e.g. SampleControl.dll). User have to decide to +update, which also slows down installation and requires user interaction.
+You also cannot specify custom Toolbox tab. All controls are installed under +"My Controls" tab:
+
8. Toolbox Integration using VSPackages
+This approach brings full control over the integration and other benefits. The VSPackages are loaded on-demand, so +the integration process won't slow down a custom installer.
+Although VSPackage and our sample control can be packed within the same +assembly, we will create a separate Visual Studio Package project.
+When user opens Toolbox in VS for the first time after installation, the IDE +will look in registry for any registered packages and load them (if not loaded +previously).
+Creating VSPackage Project
+We would like to have our VSPackage compatible with VS 2010, 2012 +and 2013, so we will work in Visual Studio 2010.
+Select "File - New - Project.." (Control+Shift+N) and +select the "Visual Studio Package" template:
+
This will start a "Visual Studio Package Wizard":
+
You can leave most options in the wizard on defaults. Leave all the check boxes unchecked +on "Page 3 of 7" and "Page 7 of 7":
+
Now we will take a look on the generated files. Open the Guids.cs +file:
+
+// Guids.cs
+// MUST match guids.h
+using System;
+
+namespace ComponentOwl.ToolboxIntegration
+{
+ static class GuidList
+ {
+ public const string GuidSampleVSPackagePkgString = "00000000-8fdf-48b6-98f8-4ff21a3a4def";
+ public const string GuidSampleVSPackageCmdSetString = "def6519d-5ace-4062-95d6-4ee43f4a5de9";
+
+ public static readonly Guid GuidSampleVSPackageCmdSet = new Guid(GuidSampleVSPackageCmdSetString);
+ };
+}
+
+Here are the GUIDs that +uniquely identify your package. I have edited the first four hex digits of +package identifier to "00000000" so that we can find it more easily later. This is +just for purpose of convenience in our sample project. Always use randomly generated GUID +in a real-world application. Visual Studio will generate a new GUID +whenever you create a new VSPackage project.
+You can also generate new GUIDs any time, for example using +online GUID +generator or guidgen.exe utility from Windows SDK. When these numbers are changed, your package will be different from +Visual Studio's point of view.
+Another important file here is source.extension.vsixmanifest. +If you double-click on the file in Solution Explorer, the VSIX Manifest Designer +will show up:
+
Not all the fields are mandatory, but I will fill all of them nevertheless:
+-
+
- ID - Unique product "Identity" - the ID is limited to + 100 characters and the recommended format is "Company.Product.Feature.Name". + We can leave the VSPackage's GUID here. +
- Product Name - This field is used for Toolbox Tab name, + so I will put "Component Owl Controls" here. +
- Author - Your name or company name - + "ComponentOwl.com", for example. +
- Version - This is version of the package and its + contents. The format is same as for assembly versions: + Major.Minor.Build.Revision. I will put "1.4.0.128" here. +
- Description - Speaks for itself. +
- Locale - Language for the package. +
- Supported VS Editions - Here you can specify which + editions of Visual Studio 2010 you would like to support. Of course, it can + support VS 2012/2013 as well, but for now I will just check Ultimate, Premium and + Professional editions. +
- Supported Framework Runtime - Minimum and maximum .NET + Framework Runtime versions your extension supports. Since my component will + support 4.0 and 4.5 runtime, I will put 4.0 and 4.5 here. +
Adding Support for Visual Studio 2012/2013
+We have specified supported Visual Studio Editions in VSIX Manifest Designer, +through the "Visual Studio Version and Edition" dialog box:
+
As you can see, only Visual Studio 2010 is supported here because VSIX is new +to 2010 and of course VS 2010 does not know about 2012/2013. We have to +source.extensions.vsixmanifest file for manual editing. Select the file +in Solution Explorer and press F7 (View Code):
++<?xml version="1.0" encoding="utf-8"?> +<Vsix xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" Version="1.0.0" xmlns="http://schemas.microsoft.com/developer/vsx-schema/2010"> + <Identifier Id="aaaaaaaa-8fdf-48b6-98f8-4ff21a3a4def"> + <Name>SampleVsPackage</Name> + <Author>ComponentOwl.com</Author> + <Version>1.0</Version> + <Description xml:space="preserve">Information about my package</Description> + <Locale>1033</Locale> + <InstalledByMsi>false</InstalledByMsi> + <SupportedProducts> + <VisualStudio Version="10.0"> + <Edition>Ultimate</Edition> + <Edition>Premium</Edition> + <Edition>Pro</Edition> + </VisualStudio> + </SupportedProducts> + <SupportedFrameworkRuntimeEdition MinVersion="4.0" MaxVersion="4.5" /> + </Identifier> + <References> + <Reference Id="Microsoft.VisualStudio.MPF" MinVersion="10.0"> + <Name>Visual Studio MPF</Name> + </Reference> + </References> + <Content> + <VsPackage>|%CurrentProject%;PkgdefProjectOutputGroup|</VsPackage> + </Content> +</Vsix> ++
Take a look on the Vsix/Identifier/SupportedProducts/VisualStudio +element (highlighted in bold). Copy and paste this element and modify +Version attribute on the second one to "11.0":
++<VisualStudio Version="11.0"> + <Edition>Ultimate</Edition> + <Edition>Premium</Edition> + <Edition>Pro</Edition> +</VisualStudio> ++
The edition tags are valid for version 11.0 because Visual Studio 2012 +template generates the same edition names.
+Writing Package Code
+Now we will take a look on the VSPackage code itself. Open the +SampleVSPackage.cs +file. I kept only the necessary code and added the ProvideToolboxItems attribute:
+
+[PackageRegistration(UseManagedResourcesOnly = true)]
+[InstalledProductRegistration("#110", "#112", "1.0", IconResourceID = 400)]
+[Guid(GuidList.guidSampleVsPackagePkgString)]
+[ProvideToolboxItems(1)]
+public sealed class SampleVsPackage : Package
+{
+}
+
+Our VSPackage implementation inherits from +Microsoft.VisualStudio.Shell.Package class and is decorated by three +attributes:
+-
+
- PackageRegistrationAttribute - Specifies that package + registration tool should look for additional attributes (will be discussed + later). +
- InstalledProductRegistrationAttribute - Provides + information for the Visual Studio splash screen and About box. +
- GuidAttribute - Provides custom GUID for the class + because automatic GUID is undesirable here (Visual Studio need to be able to trace our + package by its unique ID). +
- ProvideToolboxItemsAttribute - Specifies that the + package provides toolbox items. There are various uses of VSPackages, but we + are interested in intalling controls to Visual Studio Toolbox, hence this + attribute. +
The strings "#110" and "#112" in +InstalledProductRegistrationAttribute refer to keys in +VSPackage.resx. You can open this file and edit package name and +description there:
+
Now we write methods within SampleVsPackage class that work with the Toolbox:
+
+private const string ComponentFile = "SampleControl.dll";
+private const string TabName = "Component Owl";
+
+private void InstallToolboxItems()
+{
+ IToolboxService toolboxService = (IToolboxService)GetService(typeof(IToolboxService));
+
+ foreach (ToolboxItem item in ToolboxService.GetToolboxItems(GetAssemblyName()))
+ {
+ toolboxService.AddToolboxItem(item, TabName);
+ }
+}
+
+private void RemoveToolboxItems()
+{
+ IToolboxService toolboxService = (IToolboxService)GetService(typeof(IToolboxService));
+
+ foreach (ToolboxItem item in ToolboxService.GetToolboxItems(GetAssemblyName()))
+ {
+ toolboxService.RemoveToolboxItem(item);
+ }
+}
+
+private AssemblyName GetAssemblyName()
+{
+ string pathAssembly = String.Concat(
+ Path.GetDirectoryName(GetType().Assembly.Location),
+ Path.DirectorySeparatorChar,
+ ComponentFile);
+
+ return AssemblyName.GetAssemblyName(pathAssembly);
+}
+
+The method names InstallToolboxItems and +RemoveToolboxItems +speak for themselves. Both methods look for SampleControl.dll in the same +location as the VSPackage's assembly. They get all toolbox items from the +assembly and either put them under "Component Owl" tab or remove them.
+The ToolboxService class comes from +System.Drawing.Design and we need to add reference to this asssembly in +order to use ToolboxService.
+Building the Package
+Before building the SampleVsPackage project, open project +properties, find the VSIX tab and uncheck all the options:
+
Finally, build the project. Just two files, SampleVsPackage.dll +and SampleVsPackage.pdb, should be generated.
+Registering the Package
+Until the package can be loaded by Visual Studio, it needs to be +registered. +The registration is simply writing specific keys into Windows Registry.
+To do that, find the Package Registration Utility (RegPkg.exe). It should be +located in Visual Studio SDK directory, e.g.:
+32-bit OS: c:\Program Files\Microsoft Visual Studio 11.0\VSSDK\VisualStudioIntegration\Tools\Bin\RegPkg.exe +64-bit OS: c:\Program Files (x86)\Microsoft Visual Studio 11.0\VSSDK\VisualStudioIntegration\Tools\Bin\RegPkg.exe+
You can copy the tool where it suits you.
+Here is a sample usage of RegPkg:
+32-bit OS: RegPkg.exe /root:SOFTWARE\Microsoft\VisualStudio\11.0 /codebase SampleVsPackage.dll +64-bit OS: RegPkg.exe /root:SOFTWARE\Wow6432Node\Microsoft\VisualStudio\11.0 /codebase SampleVsPackage.dll+
This will write package registration information into the Windows Registry, +hence registers the package. Similar call have to be done by your custom installer in +order to register the package.
+Instead of writing into registry, RegPkg.exe can gereate a REG file (several +other formats are available) so that you can write package information into +registry using the file. To do that, use /regfile parameter:
+32-bit OS: RegPkg.exe /root:SOFTWARE\Microsoft\VisualStudio\11.0 /regfile:SampleVsPackage.ref /codebase SampleVsPackage.dll +64-bit OS: RegPkg.exe /root:SOFTWARE\Wow6432Node\Microsoft\VisualStudio\11.0 /regfile:SampleVsPackage.ref /codebase SampleVsPackage.dll+
This creates SampleVsPackge.reg file you can use any time +later instead of RegPkg.exe itself.
+There are two other options for specifying how the package will be registered: +codebase and assembly. When /codebase +parameter is used (as in the sample above), the registry will point to the location on disk where your +package is located (see + +Assembly.CodeBase property for more information).
+Another option is the /assembly parameter - this assumbes +that your VSPackage assembly is located in GAC (Global Assembly Cache). See +section Installing the Control in GAC for more information.
+You can check out the registry after the package registration:
+
Package Registration for Visual Studio 2012/2013
+Regrettably, simply registering package is not enough for Visual Studio 2012/2013 to load +it (see this + +blog post). Because of performance optimizations, VS developers removed +feature that looks for changes in VS registry root and thus we need to call
+devenv.exe /Setup+
In order to finish package registration.
+This call can be very time consuming since Visual Studio 2012/2013 goes through all +extensions and looks for changes. On the other hand, I tried running devenv.exe with /Setup +parameter on fresh install of Visual Studio 2012/2013 and it was instant. On older +installation, however, the operation took well over a minute (it behaves just +like Microsoft Windows, which progressively slows down during its lifetime).
+We can speed things up by a little hack. One of the things the /Setup +does is copying registry keys from HKLM to Visual Studio's 11.0_Config hive (or 12.0_Config, respectively). We can just write registry under this key +instead of calling devenv.exe and avoid possibly lengthy operation.
+The hive is located in +HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\11.0_Config.
+So let's open and edit the SampleVsPackage.reg file we have +generated using RegPkg.exe earlier. Here is the modified version where only the +registry root has been changed:
+
+REGEDIT4
+
+[HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\11.0_Config\InstalledProducts\SampleVsPackage]
+@="#110"
+"Package"="{00000000-8fdf-48b6-98f8-4ff21a3a4def}"
+"PID"="1.0"
+"ProductDetails"="#112"
+"LogoID"="#400"
+[HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\11.0_Config\Packages\{00000000-8fdf-48b6-98f8-4ff21a3a4def}]
+@="ComponentOwl.ToolboxIntegration.SampleVsPackage, SampleVsPackage, Version=1.0.0.0, Culture=neutral, PublicKeyToken=30782fc44cbe0af5"
+"InprocServer32"="C:\\Windows\\SYSTEM32\\MSCOREE.DLL"
+"Class"="ComponentOwl.ToolboxIntegration.SampleVsPackage"
+"CodeBase"="C:\\projects\\articles\\2012-10-22 Visual Studio Toolbox Control Integration\\ToolboxIntegration\\SampleVsPackage\\bin\\Debug\\SampleVsPackage.DLL"
+[HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\11.0_Config\Packages\{00000000-8fdf-48b6-98f8-4ff21a3a4def}]
+[HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\11.0_Config\Packages\{00000000-8fdf-48b6-98f8-4ff21a3a4def}\Toolbox]
+"Default Items"=dword:00000001
+
+The highlighted parts have been edited.
+So in addition to standard package registration, we also write in the +registry where Visual Studio 2012/2013 user config hive resides. This is sufficient +for our VSPackage to load.
+However, this is really a hack - editing of user configuration in registry +may cause Visual Studio to not load your user settings and show up as when +running for the first time. I tried this hack on my machine and it worked, but +there may be some hidden glitches. If you want to follow standard procedure, +just call "devenv.exe /Setup".
+Loading VSPackage
+If you did all the previous steps, your package should load when you open +Windows Forms Designer and show Toolbox (Cotrol+Alt+X). You can notice your +package name displaying in status bar for a while, then SampleControl should show up in the +Toolbox under "Component Owl" tab:
+
Displaying Your Extension in VS About Box
+If you want information about your extension to be visible in Visual Studio +splash screen and About Box, implement IVsInstalledProduct +interface:
+
+...
+
+public sealed class SampleVsPackage : Package, IVsInstalledProduct
+{
+
+...
+
+ int IVsInstalledProduct.IdBmpSplash(out uint pIdBmp)
+ {
+ pIdBmp = 0;
+ return 0;
+ }
+
+ int IVsInstalledProduct.IdIcoLogoForAboutbox(out uint pIdIco)
+ {
+ pIdIco = 400;
+ return 0;
+ }
+
+ int IVsInstalledProduct.OfficialName(out string pbstrName)
+ {
+ pbstrName = "ComponentOwl SampleControl";
+ return 0;
+ }
+
+ int IVsInstalledProduct.ProductDetails(out string pbstrProductDetails)
+ {
+ pbstrProductDetails = "SampleControl control.\r\nFor more information see http://www.componentowl.com";
+ return 0;
+ }
+
+ int IVsInstalledProduct.ProductID(out string pbstrPID)
+ {
+ pbstrPID = "3.3.0.0";
+ return 0;
+ }
+
+ ...
+
+}
+
+This code causes the component to show up in the list of "Installed Products" +in Visual Studio about box:
+
As for the splash screen, Visual Studio 2008 used to display extensions in +its splash screen, but later version do not:
+
+
+
Troubleshooting Package Load Failures
+You may encounter this dialog when playing with packages:
+
When you click "No", the package will be skipped later when loading packages. +You can re-enable loading all packages by running
+devenv.exe /ResetSkipPkgs+
To debug package load problem, you can do just what the dialog says. Run
+devenv.exe /log+
and then take a look on the ActivityLog.xml (path is shown +in the dialog). There you can find cause of the problem in one of the "entry" +elements:
+
+...
+<entry>
+ <record>106</record>
+ <time>2012/10/26 06:07:36.920</time>
+ <type>Error</type>
+ <source>VisualStudio</source>
+ <description>CreateInstance failed for package [ComponentOwl.ToolboxIntegration.SampleVSPackage, SampleVSPackage, Version=1.0.0.0, Culture=neutral, PublicKeyToken=87379c2b0cde9bc3]</description>
+ <guid>{761F0CB7-64C1-4695-91D2-6E3C26C12314}</guid>
+ <hr>80070002</hr>
+ <errorinfo>Could not load file or assembly 'file:///C:\projects\articles\2012-10-22 Visual Studio Toolbox Control Integration\ToolboxIntegration\SampleVSPackage\bin\SampleVSPackage.DLL' or one of its dependencies. The system cannot find the file specified.</errorinfo>
+</entry>
+...
+
+In this particular case, the problem was caused by changing output path from +"bin\SampleVSPackage.dll" to "bin\Debug\SampleVSPackage.dll" +so the file does not longer exist at the location for which it is registered. +The solution is to either change the location back or unregister the package +(i.e. remove the corresponding registry entries - the GUID is provided in the +log).
+Past Troubles with Package Load Keys
+The above problem with package load failure happened on Visual Studio 2005 +and 2008 because a Package Load Key (PLK) had to be provided by the VSPackage. +The PLK is basically a hashcode computed from metadata about package (name, +author/company, version). The PLK had to be obtained from a website provided by +Microsoft.
+I believe PLK caused many troubles and headaches to developers, including +myself.
+This is no longer relevant for Visual Studio 2010 and newer (requirement for +PLKs removed), so we won't discuss this topic in more depth
+Update Control Already Installed in Toolbox
+Suppose we have already integrated SampleControl version 3.3.0.0 in the +Visual Sudio Toolbox:
+
We would like to update this control to version 3.4.0.0.
+First of all, we update assembly information of the SampleControl +project:
+
If we "deploy" (copy) SampleControl.dll to the folder with +SampleVsPackage.dll where it is registered, the SampleControl will no longer be +visible in Toolbox, because the control in Toolbox should still be 3.3.0.0 and +this version is no longer to be found.
+You don't need to increment assembly version of the SampleVsPackage project, +but at least you have to increment parameter of the ProvideToolboxItems attribute:
+
+[PackageRegistration(UseManagedResourcesOnly = true)]
+[InstalledProductRegistration("#110", "#112", "1.0", IconResourceID = 400)]
+[Guid(GuidList.guidSampleVsPackagePkgString)]
+[ProvideToolboxItems(2)]
+public sealed class SampleVsPackage : Package, IVsInstalledProduct
+{
+ ...
+}
+
+The package need to be re-registered (see section Registering the Package) +which will effectively update just the "Default Items" value in the Toolbox key:
+
This will cause Visual Studio to update your control in the Toolbox:
+
Remove Control from the Toolbox
+Now we would like to remove control from the Visual Studio Toolbox. This +step can be done by custom uninstaller.
+One way to do that is to simply unregister the VSPackage using +RegPkg.exe:
+32-bit OS: RegPkg.exe /unregister /root:SOFTWARE\Microsoft\VisualStudio\10.0 SampleVsPackage.dll +64-bit OS: RegPkg.exe /First of all, we update assembly information of the unregisFirst of all, we update assembly information of the ter /root:SOFTWARE\Wow6432Node\Microsoft\VisualStudio\10.0 SampleVsPackage.dll+
You can also do this manually by simply removing the registry entry of the +corresponding package, e.g.:
+32-bit OS: HKLM\SOFTWARE\Microsoft\VisualStudio\10.0\Packages\{a9696de6-e209-414d-bbec-a0506fb0e924}
+64-bit OS: HKLM\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\10.0\Packages\{a9696de6-e209-414d-bbec-a0506fb0e924}
+On Visual Studio 2012/2013, the key need to be removed in user config registry +hive or call "devenv.exe /Setup" after removing the registry key in HKLM. For +more information, see section Package Registration for Visual Studio 2012/2013.
+9. Toolbox Integration using VSIX Packages
+Microsoft have removed most /po +f the drawbacks of VSI packages by introducing VSIX. The +price is that VSIX is a little bit more complicated and Visual Studio 2008 is no +longer supported.
+There are two versions of VSIX Schema. Version 1.0 is what Visual Studio 2010 +understand. There is also version 2.0 for Visual Studio 2012/2013. We want a VSIX +Package compatible with both, so we will work in Visual Studio 2010.
+Create a new Project from Template
+If you have Visual Studio 2010 SDK installed, you can create a new VSIX +package project with control from a template.
+Select "File - New - Project.." (Control+Shift+N) and +then select the "Windows Forms Toolbox Control" or "WPF +Toolbox Control" template:
+
The projects is basically a VSPackage wrapped in VSIX container after +build. The package assembly also contain the control class named +ToolboxControl.
+There are three important files generated by the template:
+-
+
- ProvideToolboxControlAttribute.cs - This is attribute + for ToolboxControl class. We will discuss it later. +
- source.extension.vsixmanifest - This is manifest XML + file for our VSIX package. It contains all information about the package and + what it contains. +
- ToolboxControl.cs - This is a sample control to be + installed in Visual Studio Toolbox. +
Create a new Project from VSPackage
+We can also start with VSPackage like the one we have already created in +previous section. I will create a new VSPackage project (as in previous +chapter), name it SampleVsixPackage and configure it according +to "Windows Forms Toolbox Control" template to show you all the differences.
+The basic configuration of source.extension.vsixmanifest is +the same as in previous chapter.
+Project properties differs from VSPackage we have created earlier on the VSIX +tab, where we have the first two check boxes checked:
+
Update the Manifest File
+Double-click on the source.extension.vsixmanifest file to +open up the VSIX Manifest Designer:
+
If you are not sure about some part of the form, please take a look on +section Create VSPackage Project, where the form is described in more +detail.
+In addition to previous VSPackage project, I have also filled the following +optional boxes:
+-
+
- License Terms - If you have EULA or other licence in + TXT or RTF format, you can browse for it. +
- Icon - You can browse for an icon representing the + extension. It should be 32x32 pixels large, PNG, BMP, JPEG or ICO image + format. +
- Preview Image - Thumbnail image representing the + extension. It should be 200x200 pixels large, PNG, BMP or JPEG image format. +
- More Info URL - URL of a website containing more + information about the extension. +
- Getting Started Guide - URL of a website with + documentation; you can also provide relative path to HTML file with the + local documentation. +
Add Control
+Let's create a new WPF control within the SampleVsixPackage +project itself. I will name it SampleWpfControl to distinguish +it from SampleControl we have created earlier.
+To ensure our control will show up in Toolbox of Visual Studio 2012/2013, we have +to decorate the SampleWpfControl class by +ProvideToolboxControlAttribute:
+
+[ProvideToolboxControl("SampleWpfControl", true)]
+public partial class SampleWpfControl : UserControl
+{
+ ...
+}
+
+You also have to provide implementation of the attribute class:
+
+[AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = true)]
+[System.Runtime.InteropServices.ComVisibleAttribute(false)]
+public sealed class ProvideToolboxControlAttribute : RegistrationAttribute
+{
+ private const string ToolboxControlsInstallerPath = "ToolboxControlsInstaller";
+
+ public ProvideToolboxControlAttribute(string name, bool isWpfControls)
+ {
+ if (name == null)
+ {
+ throw new ArgumentException("name");
+ }
+
+ this.Name = name;
+ this.IsWpfControls = isWpfControls;
+ }
+
+ private bool IsWpfControls { get; set; }
+ private string Name { get; set; }
+
+ public override void Register(RegistrationAttribute.RegistrationContext context)
+ {
+ if (context == null)
+ {
+ throw new ArgumentNullException("context");
+ }
+
+ using (Key key = context.CreateKey(String.Format(CultureInfo.InvariantCulture, "{0}\\{1}",
+ ToolboxControlsInstallerPath,
+ context.ComponentType.Assembly.FullName)))
+ {
+ key.SetValue(String.Empty, this.Name);
+ key.SetValue("Codebase", context.CodeBase);
+ if (this.IsWpfControls)
+ {
+ key.SetValue("WPFControls", "1");
+ }
+ }
+
+ }
+
+ public override void Unregister(RegistrationAttribute.RegistrationContext context)
+ {
+ if (context != null)
+ {
+ context.RemoveKey(String.Format(CultureInfo.InvariantCulture, "{0}\\{1}",
+ ToolboxControlsInstallerPath,
+ context.ComponentType.AssemblyQualifiedName));
+ }
+ }
+}
+
+This code is generated if you create project from template.
+The project in Solution Explorer should look like this:
+
+
Adding Controls from Other Projects
+What if we would like to use SampleControl.dll as in the VSI +package scenario?
+Of course, we can click "Add Content" in the VSIX Manifest designer and +simply add "Toolbox Control" content from other project:
+
However, this is possible only if the SampleControl project +itself is a package project!
+Lucklily, since the VSIX package is still just a ZIP archive, we can take a +look on how to add such external DLLs to it manually.
+Setting Up VSIX Installer
+The VSIX Installer tool (VsixInstaller.exe) is located in +Visual Studio's binary folder:
+32-bit OS: c:\Program Files\Microsoft Visual Studio 11.0\Common7\IDE\VSIXInstaller.exe +64-bit OS: c:\Program Files (x86)\Microsoft Visual Studio 11.0\Common7\IDE\VSIXInstaller.exe+
You can hit F6 and Visual Studio will build your project to create +SampleVsixPackage.vsix file. This is our VSIX package.
+The VSIX Installer should be associated with the .VSIX file extension, so it is +usually possible +to just double-click on the file and see the VSIX installer.
+The installation can fail in the very first step:
+
This problem appears if you have invalid manifest file. If this happen, open +source.extension.vsixmanifest and fill in all missing data. +Furthermore, you can check if the XML is valid according to +VSIX Extension +Schema.
+Now we are able to rebuild and run the VSIX installer again:
+
Make the VSIX Package Compatible with Visual Studio 2012/2013
+To make our VSIX package working with Visual Studio 2012 and newer, we need +to manually update the manifest file. Select the +source.extension.vsixmanifest file and press F7 (View Code):
++<?xml version="1.0" encoding="utf-8"?> +<Vsix xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" Version="1.0.0" xmlns="http://schemas.microsoft.com/developer/vsx-schema/2010"> + <Identifier Id="ComponentOwl.ToolboxControl.Express"> + <Name>Component Owl</Name> + <Author>ComponentOwl.com</Author> + <Version>1.0</Version> + <Description xml:space="preserve">Windows Forms Toolbox Control</Description> + <Locale>1033</Locale> + <MoreInfoUrl>http://www.componentowl.com/toolbox-control</MoreInfoUrl> + <License>license.rtf</License> + <GettingStartedGuide>http://www.componentowl.com/documentation/toolbox-control</GettingStartedGuide> + <Icon>icon.png</Icon> + <PreviewImage>overview.jpg</PreviewImage> + <SupportedProducts> + <VisualStudio Version="10.0"> + <Edition>Ultimate</Edition> + <Edition>Premium</Edition> + <Edition>Pro</Edition> + </VisualStudio> + <VisualStudio Version="11.0"> + <Edition>Ultimate</Edition> + <Edition>Premium</Edition> + <Edition>Pro</Edition> + </VisualStudio> + <VisualStudio Version="12.0"> + <Edition>Ultimate</Edition> + <Edition>Premium</Edition> + <Edition>Pro</Edition> + </VisualStudio> + </SupportedProducts> + <SupportedFrameworkRuntimeEdition MinVersion="4.0" MaxVersion="5.0" /> + </Identifier> + <References /> + <Content> + <ToolboxControl>|%CurrentProject%;PkgdefProjectOutputGroup|</ToolboxControl> + </Content> +</Vsix> ++
The bolded text have been added. I have simply added a new +VisualStudio element with higher version and all the editions (they are +relevant for VS 2012 and 2013 as its own template also generates these).
+The VSIX installer will show Visual Studio 2012 options as +well after this update (if installed, of course):
+
Please note that Visual Studio 2012/2013 also works with 2.0 version of the +schema, so if you create VSIX package in Visual Studio 2012/2013, it won't be +compatible with 2010. The solution is hence to use 1.0 version of the schema +and add support for newer Visual Studio as described earlier.
+A great advantage over VSI package is that installation of Toolbox control is +really fast with VSIX.
+Regrettably, the control won't show up in Visual Studio 2012/2013 Toolbox in its +default configuration. You need to enable loading-per user extensions (this +option is enabled by default in Visual Studio 2010):
+
Signing the VSIX Package
+Unlike older VSI package, there is no nag screen when the package is not +signed. Instead, a label appears informing user that the package is not +signed.
+To sign a VSIX package, we need PackageSignatureManager from +System.IO.Packaging (WindowsBase.dll). I made a simple command-line application called SignVsix (you can +find it in sample source code) that takes three arguments (VSIX file path, PFX +certificate path and password for the certificate):
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.IO.Packaging;
+using System.Security.Cryptography;
+using System.Security.Cryptography.X509Certificates;
+
+internal class Program
+{
+ private static void Main(string[] args)
+ {
+ // first argument - path to VSIX package
+ string paramPathPackage = args[0].Replace("\"", "");
+ // second argument - path to PFX certificate
+ string paramPathCertificate = args[1].Replace("\"", "");
+ // third argument - password for the certificate
+ string paramPassword = args[2];
+
+ // open VSIX package
+ Package package = Package.Open(paramPathPackage, FileMode.Open);
+
+ // load certificate
+ byte[] certificate = File.ReadAllBytes(paramPathCertificate);
+
+ // sign all parts of the package
+ var signatureManager = new PackageDigitalSignatureManager(package)
+ {
+ CertificateOption = CertificateEmbeddingOption.InSignaturePart
+ };
+
+ List<Uri> partsToSign = new List<Uri>();
+
+ foreach (PackagePart packagePart in package.GetParts())
+ {
+ partsToSign.Add(packagePart.Uri);
+ }
+
+ partsToSign.Add(PackUriHelper.GetRelationshipPartUri(signatureManager.SignatureOrigin));
+ partsToSign.Add(signatureManager.SignatureOrigin);
+ partsToSign.Add(PackUriHelper.GetRelationshipPartUri(new Uri("/", UriKind.RelativeOrAbsolute)));
+
+ try
+ {
+ signatureManager.Sign(partsToSign, new X509Certificate2(certificate, paramPassword));
+ }
+ catch (CryptographicException cryptographicException)
+ {
+ Console.WriteLine("Signing failed: {0}", cryptographicException.Message);
+ }
+ }
+}
+
+The usage is very simple:
+SignVsix.exe SampleVsixPackage.vsix certificate.pfx abc123+
When the file is signed, VSIX Installer shows label "Digital Signature: +<Author Name>" on the first page:
+
Dissecting the VSIX Package
+If you look on the project references, you can see reference to +Microsoft.VisualStudio.Shell.Immutable.10. This reference points to +Visual Studio 2010 SDK and we cannot expect this dependency present on end-user's machine. This +library contains ProvideToolboxControlAttribute class, which is +used by our ToolboxControl.
+Since a software development company may want to develop many components, it would be nice to have an +universal VSIX package which can be adjusted for any control.
+Let's take a look on the ToolboxControl.vsix. It is simply a +ZIP archive containing the manifest, resources, ToolboxControl binary and a +ToolboxControl.pkgdef file. If we look through all its content, +we easily generate our own VSIX packages on demand, even without Visual Studio. +There should also be a programmatic way on generating VSIX packages using +classes from System.IO.Packaging.
+Update Toolbox Control via VSIX Package
+If you made changes to your control and want to re-install the package, an +error message appear:
+
In order to provide an update, you need to increment version number in the +VSIX manifest:
+
You can also increment version number in the Package class attribute, but +this is not necessary for the VSIX to perform update:
+
+[InstalledProductRegistration("#110", "#112", "2.0", IconResourceID = 400)]
+[Guid(GuidList.guidSampleVsixPackagePkgString)]
+public sealed class SampleVsixPackage : Package
+{
+ ...
+}
+
+Of course, you can also increment version of the assembly.
+Uninstall the VSIX Package
+The VSIX Installer can be used to uninstall control from the Toolbox via +/uninstall parameter followed by package ID (the constant located in +Guids.cs: GuidList.guidSampleVsixPackagePkgString):
+VSIXInstaller.exe /uninstall:e3dfd099-d0ab-4b8e-b26d-639032c29ad9+
It is also possible to uninstall VSIX Package manually using +Extension Manager (Tools - Extension Manager...). In Visual Studio +2012/2013, the corresponding dialog is called Extensions and Updates +(Tools - Extensions and Updates...).
+
Quiet Mode
+Both installation and uninstallation can be performed in quiet mode by using /quiet parameter. This will suppress +user interface of the installer, which is handy when you want to automate +Toolbox control integration with your custom installer.
+10. Supporting Multiple Version of .NET Framework
+Since .NET Framework is backward-compatible, building a component on lowest +possible framework ensures compatibility with higher versions as well.
+I heard from several users that the component may not be displayed in Toolbox +although it seems that the Toolbox respects the .NET compatibility and display +.NET 2.0 component even when working in .NET 4.0 (Client Profile) project.
+There is also a scenario where you want to support additional features from +higher version of .NET (for example, drawing text using GDI+ in .NET 2.0 and +drawing text using WPF in .NET 3.5 and higher). You may also want to add +extensive Windows Forms Designer support, which is not available in Client +Profile framework.
+The solution to this is to build several DLLs, each with different features +and possibly different target frameworks. Then integrate all the assemblies.
+This does not pose a problem when DTE approach is used, +alhtough it is better to give each version of the component unique name or place +them in separate tabs (e.g. "Component Owl WinForms - .NET 2.0").
+When TCI approach is used, each version of the assembly +requires different public key token, because they have to reside in GAC +side-by-side. Furthermore, they need a separate registry key based on the public +key token.
+The VSI and VSIX approaches require +renaming the component or customizing Toolbox tab in the +ProvideToolboxControlAttribute (see part Toolbox Control Integration using +VSIX Packages for more information).
+The VSPackage approach allows you to place all the versions +in Visual Studio Toolbox under their respective tabs.
+When manual approach is used, you can of course add each +version of the assembly separately and also create separate tabs in the Toolbox.
+ +11. Sample Source Code
+ +The attached sample source is a Visual Studio 2010 Solution containing +implementations of all the presented approaches. The binaries are contained +under "bin\Release" subfolders and batch files (.CMD extension) are provided +where appropriate.
+ ++Download sample source code (212 KB) +
+ +You can find the following folders in the archive:
+DteToolboxInstaller - A command-line application for +installing/uninstalling assemblies in VS Toolbox using Visual Studio Automation +Object Model (DTE). Custom tab name and VS version can be specified. The tool +can be used in real-world application.
+SampleControl - Windows Forms control for testing the +integration.
+SampleVsixPackage - VSIX package project (basically a +VSPackage that is further packaged with the sample control), the resulting +package can be installed by VSIX Installer that comes with Visual Studio.
+SampleVsPackage - VSPackage that is able to install all +control assemblies located in its own folder. Contains batch files for package +registration/unregistration.
+SignVsix - A command-line application for signing VSIX +packages. Sample batch file is provided. Valid PFX certificate need to be +provided by the user.
+TciToolboxInstaller - A command-line application for +installing/uninstalling assemblies in VS Toolbox using Toolbox Control Installer +package (but does not depend on it). Custom tab name and VS version can be +specified. The tool can be used in real-world application.
+VSI - Basic setting for creating VSI package and a sample +VSI package created from the files. Batch file for signing the VSI package is +provided.
++ +
+Download sample source code (212 KB) +
+ +
This work is licensed under a Creative Commons Attribution 3.0 Unported License.Component Owl WinForms - .NET 2.0 +
Better ListView
+
+
+ 
Claudiu 
Libor Tinka 
+
brokey 
Göran 
Camiel Hessels 
+
Kyle Ellingworth 
Jiri Novotny 
Nish 
Orgil 
Jad Jabbour 
Cristobal 
Bipin 
Daniele 
Jeff 
Raphael 
alex 
Mr.excepter 
Luigi 
pw 
anon 
Juanjo 
Ryan 
Douglas 
Carlos López 
pat 
dario-g 
Bob 
Emanuel Landeholm 
Carl 
minime 
Amir 
Himanshu Mishra 
Foobar 
mustafa salah 
Very nice guys… With each new version, Better ListView is doing exactly that: just getting better and better!
+I am particularly keen to try putting in my own linebreaks into items in the details view.
+ +