Walkthrough: Publishing a Custom Web Control

Article
04/21/2015

You can create a custom web control and distribute it as a VSIX extension. You can also create a web control project template to use as the basis for more web controls.

To distribute a VSIX extension, we recommend that you add it to the Visual Studio Gallery website because developers can use Extension Manager to browse there for new and updated extensions. You can also distribute an extension by putting it on a different server, or by burning it on a CD or other media.

This walkthrough, which is one of two related walkthroughs, teaches how to create a custom web control and then distribute it. The other walkthrough, Walkthrough: Publishing a Web Control Project Template, teaches how to create and distribute a web control project template.

This walkthrough contains these sections:

Creating a Custom Web Control
Testing the Web Control
Preparing the Web Control for Distribution
Publishing the Web Control to the Visual Studio Gallery
Installing the Web Control from the Visual Studio Gallery
Removing the Web Control

Prerequisites

To complete this walkthrough, you must understand web controls and know how to create projects, set project properties, and use the Visual Studio experimental instance. Both Visual Studio 2013 and the Visual Studio 2013 SDK must be installed on the computer.

Creating a Custom Web Control

To create a custom web control when no web control project template is available, use one of the extensibility control project templates that are included in the Visual Studio SDK. Then, modify the project.

To create a control project

In Visual Studio, on the File menu, point to New and then click Project.
In the New Project dialog box, in the left pane, expand Visual C# and then click Extensibility. In the center pane, click Windows Forms Toolbox Control. In the Name box, type MyWebControls. Select Create directory for solution. Click OK.
In Solution Explorer, right-click the MyWebControls solution, point to Add and then click New Project.
In the New Project dialog box, in the left pane, expand Visual C# and then click Web. In the center pane, click ASP.NET Server Control. In the Name box, type Temp. Click OK.

To merge the project files

In Solution Explorer, in the Temp project, right-click ServerControl1.cs and rename it ColorTextControl.cs.
In the MyWebControls project, delete ToolboxControl.cs.
In the Temp project, copy ColorTextControl.cs and paste it in the MyWebControls project.
Remove the Temp project from the solution.

To merge the project references

In Solution Explorer, in the MyWebControls project, right-click the References folder and then click Add Reference. In the Reference dialog box, on the .NET tab, select the following references and then click OK to add them to the project:
- Microsoft.CSharp
- System.Data.DataSetExtensions
- System.Web
- System.Xml.Linq
In the project, in the References folder, remove each of the following references from the project:
- System.Data
- System.Windows.Forms
- System.Xml

To create the web control

In Solution Explorer, in the MyWebControls project, double-click ColorTextControl.cs to open it in the editor.
Change the namespace value to MyWebControls.
In the ToolboxData attribute, replace both occurrences of ServerControl1 with ColorTextControl.

These values specify the opening and closing tags that are generated for the control when it is dragged from the Toolbox to a web page at design time. They must match the name of the control class, which is also the name of the control that will appear in the Toolbox.
Add a ProvideToolBoxControl attribute to the control class.

The first argument to this attribute is the name of the assembly, which is the same as the namespace when the project is generated. The color text control will appear in a category that has this name in the Toolbox.

The beginning of the control class source code should now resemble the following code.
```
namespace MyWebControls
{
    [DefaultProperty("Text")]
    [ToolboxData("<{0}:ColorTextControl runat=server></{0}:ColorTextControl>")]
    [ProvideToolboxControl("MyWebControls", false)]
    public class ColorTextControl : WebControl
    {
```
Replace the get method of the default Text property with the following code.
```
get
{
    String s = (String)ViewState["Text"];
    return "<span style='color:green'>" + s + "</span>";
}
```
This wraps the text in a span tag that colors it green.
In the Properties folder, double-click AssemblyInfo.cs to open it in the editor.
Replace the AssemblyVersion revision number with an asterisk (*).
```
[assembly: AssemblyVersion("1.0.0.*")] 
```
Custom Toolbox controls are cached and refreshed only when the assembly signature changes. By incrementing the assembly version revision number with every build, the cache is always refreshed.

Testing the Web Control

Before you distribute the web control, test it in an experimental instance of Visual Studio.

To test the web control

In Visual Studio, press F5 to open an experimental instance of Visual Studio.
On the Tools menu, click Extension Manager. The MyWebControls extension should appear in the center pane and be enabled.
Close Extension Manager.
In the New Project dialog box, in the left pane, expand Visual C# and then click Web. In the center pane, use the ASP.NET Web Application template to create a project.
In the project, open Default.aspx. Make sure that Source view is displayed.
Open the Toolbox. The ColorTextControl control should be displayed in the MyWebControls category.
Drag a ColorTextControl somewhere in the body tag of the web page.
In the ColorTextControl tag, add a Text attribute and make its value Think Green!. The resulting tag should resemble the following one.
```
<cc1:ColorTextControl ID="ColorTextControl1" Text="Think Green!" runat="server" />
```
Press F5 to start the ASP.NET Development Server.

The display of the ColorTextControl should resemble the following picture.
Close the ASP.NET Development Server.
On the Tools menu, click Extension Manager.
Select MyWebControls, and then click Uninstall.
Close Extension Manager.
Close the experimental instance of Visual Studio.

Preparing the Web Control for Distribution

Before you publish your web control to the Visual Studio Gallery, add an icon to help identify it in Extension Manager and an image to illustrate what it does.

To add identifying images to the web control

If you already have an icon file, add it to the project as an existing item. Otherwise, create an icon file and then add it. This walkthrough uses an icon file named Color.bmp, which shows the letter A on a yellow field.
If you already have an image file, add it to the project as an existing item. Otherwise, create an image file, for example, a screen capture, and then add it. This walkthrough uses an image file named ScreenShot.bmp, which shows the control as it appears in a web page.
Open source.extension.vsixmanifest.
In the Description box, change the value to Color Text Web Control.
Set Icon to Color.bmp and Preview Image to ScreenShot.bmp.
You can change Author and Version if you want to.
Save source.extension.vsixmanifest and close it. Rebuild the project as a Release build.

Publishing the Web Control to the Visual Studio Gallery

The web control is now ready to be published to the Visual Studio Gallery.

To publish the web control to the Visual Studio Gallery

In a web browser, open the Visual Studio Gallery website.
In the upper-right corner, click sign in.
Use your Microsoft account to sign in. If you do not have a Microsoft account, you can create one here.
Click Upload.
In Step 1: Extension Type, select Control and then click Next.
In Step 2: Upload, select I would like to upload my control. The Select your control box appears.
Click Browse and then, in the \bin\Release folder of the project, select MyWebControls.vsix. Click Next.
In Step 3: Basic Information, information from the source.extension.vsixmanifest file is displayed.
Set Category to ASP.NET and Tags to toolbox, web control. You can also type a more detailed description.
Read the Contribution Agreement and agree to it, and then in the box, type the text that is displayed.
Click Create Contribution. This displays a message that the page has not yet been published.
Click Publish.
Search the Visual Studio Gallery for MyWebControls. The listing for the MyWebControls extension should appear.

Installing the Web Control from the Visual Studio Gallery

Now that the web control is published, install it in Visual Studio and test it there.

To install the web control in Visual Studio

In Visual Studio, on the Tools menu, click Extension Manager.
Click Online Gallery and then search for MyWebControls. The listing for the MyWebControls extension should appear.
Click Download. After the extension is downloaded, click Install.
To complete the installation, restart Visual Studio.
Create an ASP.NET web application project.
In the project, open Default.aspx. Make sure that Source view is displayed.
Open the Toolbox. The ColorTextControl control should be displayed in the MyWebControls category.

Removing the Web Control

You can remove the web control from the Visual Studio Gallery and from your computer. These removals are required if you want to complete the related walkthrough, Walkthrough: Publishing a Web Control Project Template.

To remove the web control from the Visual Studio Gallery

Open the Visual Studio Gallery website.
In the upper-right corner, click My Contributions. The listing for MyWebControls listing is displayed.
To remove the web control, click Delete.

To remove the web control from your computer

In Visual Studio, on the Tools menu, click Extension Manager.
Select MyWebControls and then click Uninstall.
To complete the uninstallation, restart Visual Studio.

Next Steps

Walkthrough: Publishing a Web Control Project Template shows how to create a web control project template that is based on the web control from this walkthrough, and also shows how to distribute the template.