Sample Control Designer with Action Lists and Services

Artigo
11/03/2006

The following topic describes a sample using ASP.NET control designers with services and action lists to provide a design-time user interface (UI) for custom server controls.

The following sections contain sample code that demonstrates how to create and use ASP.NET control designers for custom server controls. Specifically, this topic (combined with the related sample code topic listed below) shows the following features and tasks involved in working with designers:

Creating designers that use designer host services and action lists.
Associating a designer with a custom control.
Compiling controls and their associated designers into an assembly.
Referencing the controls on a Web page.
Working with the control designers in the Visual Studio 2005 Design view.

There are two versions of the sample code for designers, one written in Visual Basic, the other in C#. The sample illustrates custom control designers that use host services and action lists. You can find the sample code in the topic How to: Use Services and Action Lists with Control Designers. There are four custom controls in the code sample, all of which are simple, created only to illustrate the use of designers. Three of the custom controls derive from the Panel class; the fourth is a custom Button control. Each of the panel controls in the source code also has an associated custom designer control. These designers use services to allow the control to interact with a host environment such as Visual Studio 2005. In a visual design environment (Design view, in Visual Studio 2005), these designers provide the code to enable you to create design-time menus with various tasks for configuring the controls.

Compiling a Sample

The Visual Basic sample and the C# sample have the same functionality, so you can choose the sample in the programming language you prefer.

To use the sample you prefer, you compile it as a library and place the resulting assembly into the Bin directory of your Web application.

The following code example shows how to compile the sample from a command prompt.

vbc /r:System.dll /r:System.Design.dll /r:System.Drawing.dll /debug+ /r:System.Web.dll /t:library /out:DesignerServicesAndListsVB.dll DesignerServicesAndLists.vb

csc /r:System.dll /r:System.Design.dll /r:System.Drawing.dll /debug+ /r:System.Web.dll /t:library /out: DesignerServicesAndListsCS.dll DesignerServicesAndLists.cs

After compiling the sample, remember to copy the resulting DesignerServicesAndListsVB.dll or DesignerServicesAndListsCS.dll file to your Web site's Bin folder.

Required XML Files

In addition to the assembly with the controls and designers, the sample is dependent on three separate XML files. These XML files contain basic style information that demonstrates how designers can utilize services provided by the host environment. In this case, the designers dynamically load style data from the XML files at design time, and use that data to change the appearance of controls on the design surface. This example demonstrates the use of designer host services, and is not meant as a recommendation for implementing style definitions.

The XML files for this sample reside in the same folder as the ASP.NET Web page on which you will host the controls. The content for the files, RedStyle.xml, BlueStyle.xml, and GreenStyle.xml, is provided below.

RedStyle.xml

<?xml version="1.0" encoding="utf-8" ?>
<styles>
    <style name="BackColor" value="red"></style>
    <style name="ForeColor" value="white"></style>
</styles>

BlueStyle.xml

<?xml version="1.0" encoding="utf-8" ?>
<styles>
    <style name="BackColor" value="blue"></style>
    <style name="ForeColor" value="white"></style>
</styles>

GreenStyle.xml

<?xml version="1.0" encoding="utf-8" ?>
<styles>
    <style name="BackColor" value="green"></style>
    <style name="ForeColor" value="white"></style>
</styles>

Using the Sample Controls and Designers in an ASP.NET Page

To work with the sample controls and designers, you must put the controls into an ASP.NET Web page that you can use in a designer such as Visual Studio 2005. For the purpose of this sample, you must add an ASP.NET Web page to your Web site in Visual Studio 2005. First, create a new Web page. Then, in Source view, delete the default page content, and add the Page and Register directives shown in the following code example.

<%@ page language="VB" %>
<%@ register tagprefix="aspSample" 
    assembly="DesignerServicesAndListsVB" 
    namespace="Samples.AspNet.VB.Controls" %>

<%@ page language="C#" %>
<%@ register tagprefix="aspSample" 
    assembly="DesignerServicesAndListsCS" 
    namespace="Samples.AspNet.CS.Controls" %>

Note
The only difference between the directives for Visual Basic and C# is the language attribute in the Page directive and the extension of the assembly name in the Register directive.

You must also copy the following markup code below the Register directive. (This code is the same whether you are using Visual Basic or C#.)

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
    
<head id="Head1" runat="server">
    <title>Designer Samples</title>
</head>
<body>
  <form id="form1" runat="server">
      <p style="font-family:tahoma;font-size:larger;
      font-weight:bold">
        Using Action Lists and Designer Host Services</p>
      <div style="font-family:tahoma;font-size:x-small">
        <span style="font-size: 10pt">Control #1 (ControlWithStyleTasksDesigner):
        PanelContainerDesigner using a DesignerActionList, which
        obtains a list of XML files in the project and sets 
        the style using the XML element
        definitions.</span><p />
      </div>
      <aspSample:ControlWithStyleTasks id="ctl1" 
        runat="server" 
        backcolor="Red" forecolor="White">
          Hello there.</aspSample:ControlWithStyleTasks>
      <br />
      <div style="font-family:tahoma;font-size:x-small">
        <span style="font-size: 10pt">Control #2 (ControlWithConfigurationSettingDesigner):
        PanelContainerDesigner using configuration settings
        to obtain 
        the FrameCaption value.</span><p />
      </div>
      <aspSample:ControlWithConfigurationSetting 
        id="ctl2" runat="server">
        Hello There
      </aspSample:ControlWithConfigurationSetting>
      <br />
      <div style="font-family:tahoma;font-size:x-small">
        <span style="font-size: 10pt">Control #3 (ControlWithButtonTasksDesigner):
        PanelContainerDesigner using a smart-task action 
        item to insert a new button on the Web Forms page.</span><p />
      </div>
      <aspSample:ControlWithButtonTasks 
        id="ctl3" runat="server">
        Hello There
      </aspSample:ControlWithButtonTasks>
      &nbsp; &nbsp;
  </form>
</body>
</html>

Configuration Settings for the Sample

One of the designers in this sample uses a configuration file entry to dynamically display a title for the Design view on one of the custom controls. You must open your Web site's Web.config file, or create one if it does not exist, and add a key to the <appSettings> element, as shown in the following code example.

<appSettings>
  <add key="ContainerControlTitle" value="Title from Config File"/>
</appSettings>

Testing the Control Designers in Visual Studio 2005

After adding the compiled assembly .dll file to your Web site's Bin folder, adding the XML files, adding a host page with the custom controls referenced on it, and creating the entry in the Web.config file, you can work with the controls in the designer. Make sure the page is open in Design view in Visual Studio 2005. Note that there are three panel controls on the page. If you click the control, a region you can edit is outlined.

Testing Designer Services and Action Lists

You can test the first control's designer by positioning the mouse pointer over the upper right-hand corner of the control, and then clicking the action list button. The following screen shot shows the control with the action list displayed.

Control with action list displayed

VS Designer for a PanelContainer control

In the Configure Xml text box on the action list, you can select from the XML files you created earlier. Selecting one of the existing XML files updates the design-time style of the control with the style information from that XML file. You can try the same technique using the names of the other XML files.

Clicking the action list button for the third control displays an action list like the one shown in the following screen shot.

Third control action list

VS Designer with custom tasks to add buttons

The Add a Button command adds a Button control to the design-time view. The Add a custom button command adds an instance of a custom button control to the page.

Testing Designer Services and Editable Regions

The second control displays the caption Title Added From Config. The designer uses designer services to extract this setting from the Web.config file and add it to the design-time view.

The control also presents an editable region on the control. You can click the editable area to type new content. The content is persisted to the page's source code.

Compartilhar via