-
-
-
-
-
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
-
-
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 |
- |
- |
-
-
-
-
-
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 |
-
-
-
-
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.
-
-
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.
-
-
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.
-
-
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.
-
-
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:
-
-
-
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.
-
-
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.
-
-
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.
-
-
-
-
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)
-
-
+
+
+
+
+
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
+
+
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 |
+ |
+ |
+
+
+
+
+
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 |
+
+
+
+
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.
+
+
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.
+
+
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.
+
+
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.
+
+
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:
+
+
+
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.
+
+
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.
+
+
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.
+
+
+
+
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
Better ListView
Better Thumbnail Browser
Better Thumbnail Browser
Better SplitButton
Better SplitButton
Better ListView Express
Better ListView Express
