Creating ASP.NET Server Control project
In order to create new ASP.NET Server Control, use File – New – Project from Visual Studio 2008 menu to open the New Project dialog box. From the Web project type, choose ASP.NET Server Control.
Figure 1. The New Project Window for ASP.NET Server Control
The phrase “ASP.NET Server Control” has three words in it. The word ‘Control’ refers a piece of functionality with appropriate UI that can be plugged into your application without much work.
The word ‘Server’ refers to the fact that this control works on the server side. A web application has two distinct places where the processing can occur. One is on the client side (i.e. in the browser). This client side code is written in JavaScript, since all the popular browsers understand JavaScript. And then there is the server-side processing, which means, the processing occurs on the web server (or on the machines/places that the web server can access.
And finally, ‘ASP.NET’ refers to the fact that this server side control is written using the functionality available in ASP.NET. With that we will be able to use any language that ASP.NET supports – the popular ones being C# and Visual Basic.
Generated Files
When you click OK in the New Project dialog box, Visual Studio will create the FirstServerControl solution.
A server control solution has fewer files than some of the other project types. The reason for this is that everything in the server control comes from the code – meaning, unlike the Web Application, you won’t be able to draw the user interface.
Server Controls can (and most of them do) contain user interface – it’s just that you will have to write the appropriate code to render that user interface. You will make up this user interface using the HTML tags.
Figure 2. The Server Control in the Solution Explorer
Let’s look at the files generated as a part of this solution.
FirstServerControl.sln and FirstServerControl.suo
These are the Visual Studio solution files. The .sln file is text based and contains the information about this solution (e.g. the projects that are part of this solution). And the .suo file is binary and contains the user/developer-specific preferences.
FirstServerControl.csproj
This is the project file; and contains the project related information like the included files and references.
Note that the output type here is: Library. Meaning, a dll will be created when this project is compiled. That also means, you will need another application that calls this library and uses the functionality provided here.
ServerControl1.cs
This is the only server control specific file in this solution. This contains the code for this server control. Needless to say, you can create and use additional files to split the code.
The code in this file is discussed in a section below.
AssemblyInfo.cs
Just like any other .NET project (which eventually compiles into an assembly), this project also has an assembly info file. This file contains information like title, description, company, version, etc. of the assembly.
Analyzing the Code
Let’s take a look at the code in the ServerControl1.cs file.
Code Listing 1. ServerControl1.cs
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Linq;
using System.Text;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
namespace FirstServerControl
{
[DefaultProperty("Text")]
[ToolboxData("<{0}:ServerControl1 runat=server></{0}:ServerControl1>")]
public class ServerControl1 : WebControl
{
[Bindable(true)]
[Category("Appearance")]
[DefaultValue("")]
[Localizable(true)]
public string Text
{
get
{
String s = (String)ViewState["Text"];
return ((s == null) ? "[" + this.ID + "]" : s);
}
set
{
ViewState["Text"] = value;
}
}
protected override void RenderContents(HtmlTextWriter output)
{
output.Write(Text);
}
}
}
This code can be broken up following three parts:
- The Control
- Properties
- Rendering and Functionality
The Control
Code Listing 2. The Server Control class
[DefaultProperty("Text")]
[ToolboxData("<{0}:ServerControl1 runat=server></{0}:ServerControl1>")]
public class ServerControl1 : WebControl
{
}
The main class for this server control is derived from the .NET Framework class called WebControl. There are several classes from which a server control can be derived from. They all will eventually be derived from a .NET Framework class called Control. However, WebControl (which is also derived from the Control class) is a popular choice to derive the ASP.NET Server Control classes.
In the Code Listing 2, you can see a [ToolboxData] attribute; this tells the designer (Visual Studio), what declarative piece of code is to be used to include this server control.
Then there is also a [DefaultProperty] attribute. Properties are a perfect way to set and get information in and out of a server control. These public properties (which are discussed below) are shown in the Properties window of Visual Studio. Here Text is the default property.
Properties
Code Listing 3. The Text Property
[Bindable(true)]
[Category("Appearance")]
[DefaultValue("")]
[Localizable(true)]
public string Text
{
get
{
String s = (String)ViewState["Text"];
return ((s == null) ? "[" + this.ID + "]" : s);
}
set
{
ViewState["Text"] = value;
}
}
Like any C# property, you can define the getters and setters for a given property. In this case, you can obtain the value of the Text property or you can set it to a string value.
This public property has a few attributes at the top. This property shows up under the “Appearance” category in the Properties box in Visual Studio. It’s default value there would be “”. And this property is both bindable and localizable.
Rendering and Functionality
Code Listing 4. RenderContents()
protected override void RenderContents(HtmlTextWriter output)
{
output.Write(Text);
}
Finally, this control has to do something and has some user interface where it does that something. Here the RenderContents() method does the job of rendering the user interface. It simply writes the Text (from the Text property) to the control location on the page where this control is embedded in.
Obviously, this is a very simple server control. You can add sophisticated user interface and respond to the events generated there.
Running the ASP.NET Server Control
If you run this program (by pressing F5), you will get a message from Visual Studio, saying: “A project with an Output Type of Class Library cannot be started directly”.
Meaning, this assembly is a dll – and you need a web application where you embed this to run it.
Add a Web Application
In order to test this server control, add a web application project called FirstServerControlTest to this solution.
Figure 3. A project to test the server control
As you can see in Figure 3, the test project has a Default.aspx web page, to which we will add the server control.
Add the server control
You might not see the ServerControl1 in the toolbox; building the solution would show the control in the toolbox.
Figure 4. The server control inside a web application
As you can see in Figure 4, the server control shows up in the toolbox with its default icon (the gears). When you drag it on to the design surface, you can see the Text property in the Properties window under the Appearance category.
Run the web application
Now if you set the FirstServerControlTest project as the startup project (by right-clicking and choosing ‘Set as Startup Project’) and run the web application, you will see the text you typed in the Text property in the browser.
