演练：部署和使用自定义 Web 服务器控件

.NET Framework 4

其他版本

本演练演示如何创建和测试自定义 ASP.NET Web 服务器控件。

在本演练中，您将学会如何执行以下任务：

创建一个 ASP.NET Web 服务器控件。
通过向该控件添加元数据来指定安全设置和设计时行为。
在配置文件和该控件的程序集中指定一个标记前缀。
指定一个供该控件在 Visual Studio 工具箱中使用的图标。
将该控件编译为程序集并添加项目引用，以便在同一解决方案的另一个项目中使用它。
“属性”窗口或 IntelliSense 访问其属性。

Download（下载）主题附带含源代码的 Visual Studio 解决方案。

创建服务器控件

用户名!”

DefaultUserName 属性设置为“Guest”，在当用户未登录时，该控件将显示“Hello Guest!”。

创建自定义服务器控件

“新建项目”。

“新建项目”对话框。
“Web”。
“ASP.NET 服务器控件”模板。
“名称”框中输入 ServerControl1。

“新建项目”对话框与下图类似。
“确定”。

Visual Studio 会创建一个服务器控件项目，该项目具有一个名为 ServerControl1.cs 或 ServerControl1.vb 的类文件。
“服务器资源管理器”中，将 ServerControl1.cs 或 ServerControl1.vb 重命名为 WelcomeLabel.cs 或 WelcomeLabel.vb。

将出现一个对话框，询问您是否要重命名对 ServerControl1 的所有引用，如下图所示。
“是”。
打开 WelcomeLabel.cs 或 WelcomeLabel.vb。
.WebControl 继承。
ToolboxData 特性中，将显示字符串“ServerControl1”的两个位置将该字符串更改为“WelcomeLabel”。

RenderContents 方法，如下面的示例所示：

C++

JScript

复制

不支持该语言或没有可用的代码示例。

C++

JScript

复制

// WelcomeLabel.cs
using System;
using System.ComponentModel;
using System.Security.Permissions;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

namespace Samples.AspNet.CS.Controls
{
    [
    AspNetHostingPermission(SecurityAction.Demand,
        Level = AspNetHostingPermissionLevel.Minimal),
    AspNetHostingPermission(SecurityAction.InheritanceDemand, 
        Level=AspNetHostingPermissionLevel.Minimal),
    DefaultProperty("Text"),
    ToolboxData("<{0}:WelcomeLabel runat=\"server\"> </{0}:WelcomeLabel>")
    ]
    public class WelcomeLabel : WebControl
    {
        [
        Bindable(true),
        Category("Appearance"),
        DefaultValue(""),
        Description("The welcome message text."),
        Localizable(true)
        ]
        public virtual string Text
        {
            get
            {
                string s = (string)ViewState["Text"];
                return (s == null) ? String.Empty : s;
            }
            set
            {
                ViewState["Text"] = value;
            }
        }

        protected override void RenderContents(HtmlTextWriter writer)
        {
            writer.WriteEncodedText(Text);
            if (Context != null)
            {
                string s = Context.User.Identity.Name;
                if (s != null && s != String.Empty)
                {
                    string[] split = s.Split('\\');
                    int n = split.Length - 1;
                    if (split[n] != String.Empty)
                    {
                        writer.Write(", ");
                        writer.Write(split[n]);
                    }
                }
            }
            writer.Write("!");
        }
    }
}

C++

JScript

复制

using System.Drawing;
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 ServerControl1
{
    [DefaultProperty("Text")]
    [ToolboxData("<{0}:WelcomeLabel runat=server></{0}:WelcomeLabel>")]
    public class WelcomeLabel : Label
    {
        [
        Bindable(true),
        Category("Appearance"),
        DefaultValue(""),
        Description("The text to display when the user is not logged in."),
        Localizable(true)
        ]
        public virtual string DefaultUserName
        {
            get
            {
                string s = (string)ViewState["DefaultUserName"];
                return (s == null) ? String.Empty : s;
            }
            set
            {
                ViewState["DefaultUserName"] = value;
            }
        }

        protected override void RenderContents(HtmlTextWriter writer)
        {
            writer.WriteEncodedText(Text);

            string displayUserName = DefaultUserName;
            if (Context != null)
            {
                string userName = Context.User.Identity.Name;
                if (!String.IsNullOrEmpty(userName))
                {
                    displayUserName = userName;
                }
            }

            if (!String.IsNullOrEmpty(displayUserName))
            {
                writer.Write(", ");
                writer.WriteEncodedText(displayUserName);
            }

            writer.Write("!");
        }
    }
}

“我的项目”，然后打开 AssemblyInfo.cs 或 AssemblyInfo.vb。
在文件开头添加下面的行：
VB

C#

C++

F#

JScript
复制
Using System.Web.UI;
VB

C#

C++

F#

JScript
复制
不支持该语言或没有可用的代码示例。
TagPrefixAttribute 特性需要此命名空间。
在文件末尾添加下面的行：
VB

C#

C++

F#

JScript
复制
[assembly: TagPrefix("ServerControl1", "aspSample")]
VB

C#

C++

F#

JScript
复制
不支持该语言或没有可用的代码示例。
aspSample 之间创建映射。
保存 WelcomeLabel.cs 或 WelcomeLabel.vb 文件。

代码讨论

以下各节说明了您在上一过程中创建的代码。

从 WebControl 类继承

WebControl 派生的控件也自行参与到 ASP.NET 的主题功能。

DefaultUserName 属性

ASP.NET 状态管理概述。

RenderContents 方法

HtmlTextWriter 类型的对象，是具有呈现 HTML 的方法的类。

字符串串联需要时间和内存来创建字符串，然后写入流。

Web 控件呈现示例。

控件的特性

WelcomeLabel ：

在可视化设计器中，当页开发人员在设计图面上单击控件时，属性浏览器通常突出显示此默认属性。

WelcomeLabel，该字符串创建以下元素：

复制

<aspSample:WelcomeLabel runat="server"> </aspSample:WelcomeLabel>

ToolboxDataAttribute 特性共同使用，这样可将子元素解释为属性，并将属性作为特性保留。

DefaultUserName 属性的特性

DefaultUserName 属性的特性是设计时特性，通常会将它们应用于控件的所有公共属性：

Bindable(false)。
可以指定一个对应于属性浏览器中的现有类别的字符串参数，也可以创建自己的类别。
“属性”窗口底部显示选定的属性的描述。
“重置”按钮将属性值重置为其默认值。
对控件轮询可本地化的属性时，设计器会将此属性值保存到非特定于区域性的资源文件或另一个本地化源中。

自定义服务器控件的元数据特性。

标记前缀

@ Register 指令，页开发人员可提供标记前缀/命名空间映射，如以下示例所示：

复制

<%@ Register Assembly="ServerControl" TagPrefix="aspSample" 
        Namespace="ServerControl"%>

ServerControl1 程序集的标记前缀。

复制

<?xml version="1.0"?>
<configuration>
  <system.web>    
   <pages>
     <controls>
       <add tagPrefix="aspSample" Assembly="ServerControl" 
         namespace="ServerControl">
       </add>
     </controls>
   </pages>
  </system.web>
</configuration>

测试自定义服务器控件

在下面的过程中，您将完成以下任务：

创建一个网站，您将使用此网站测试在上一过程中创建的服务器控件。
将网站项目中的引用添加到服务器控件项目。
“工具箱”中。
WelcomeLabel 控件的实例添加到 Default.aspx 页中。
WelcomeLabel 控件的工作情况。

首先，创建可用于测试的网站。

Web 应用程序项目与网站项目。

创建网站项目以测试自定义服务器控件

“新建网站”。

“新建网站”对话框。
“ASP.NET 网站”模板。
将网站命名为 TestWebSite，并将它保存在 ServerControl1 解决方案文件夹下的一个新文件夹中。

“新建网站”对话框与下图类似：
“确定”。

“源”视图中打开 Default.aspx 页。
“设为启动项目”。
“添加引用”。

“添加引用”对话框。
“添加引用”对话框：

下一个步骤是将服务器控件添加到工具箱中，以便您能在测试网站的网页中使用它。

将 WelcomeLabel 控件添加到工具箱中

“生成解决方案”。

Visual Studio 将编译该解决方案，并将 ServerControl1 项目创建的程序集复制到 TestWebSite 项目的 Bin 文件夹中。
“工具箱”窗口。
“添加选项卡”。
将新选项卡命名为 Server Control1。
“选择项”。
“浏览”，然后浏览到 TestWebSite 项目的 Bin 文件夹。
“打开”。

“.NET Framework 组件”选项卡，如下图所示：
“确定”。

“Server Control1”选项卡中。

现在可以将该服务器控件添加到一个网页中，然后对该网页进行测试。

测试 WelcomeLabel 控件

WelcomeLabel 控件拖动到该位置。
DefaultUserName 特性添加到 WelcomeLabel 控件的标记中，并将其设置为“Welcome”，如下面的示例所示：
复制
<aspSample:WelcomeLabel ID="WelcomeLabel1" runat="server" Text="Welcome" DefaultUserName="Guest"> </aspSample:WelcomeLabel>
按 Ctrl-F5 在浏览器中显示该网页。

WelcomeLabel 控件显示“Welcome!”，如下图所示：
“登录”超链接。

“登录”页。
“注册”超链接。

“创建新帐户”页，如下图所示。
“创建用户”按钮。

WelcomeLabel 控件现在显示“Welcome, newuser!”，如下图所示：

为工具箱指定一个图标

Visual Studio 通常在工具箱中使用默认图标来显示控件，如下图所示：

作为控件的一个选项，可以通过在控件的程序集中嵌入一个 16*16 像素的位图来自定义控件在工具箱中的外观。

为工具箱指定一个图标

创建或获取一个 16*16 像素的位图，将其作为控件的工具箱图标。
将该位图命名为 WelcomeLabel.bmp。
“添加现有项”，然后选择位图文件。
“嵌入的资源”。
“添加新项”。

“添加新项”对话框。
“添加”。

打开 ResourceFinder.cs 或 Resourcefinder.vb 文件。

NotInheritable），如下面的示例所示。

C++

JScript

复制

不支持该语言或没有可用的代码示例。

C++

JScript

复制

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace ServerControl1
{
    internal sealed class ResourceFinder
    {
    }
}

C++

JScript

复制

<%@ Page Language="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>WelcomeLabel Test</title>
  </head>
  <body>
    <form id="form1" runat="server">
      <div>
        <aspSample:WelcomeLabel Text="Hello" ID="WelcomeLabel1" 
          runat="server" BackColor="Wheat" ForeColor="SaddleBrown" />
      </div>
    </form>
  </body>
</html>

保存并关闭文件。
打开 WelcomeLabel.cs 或 WelcomeLabel.vb 文件，然后将以下行添加到文件的开头：
VB

C#

C++

F#

JScript
复制
Using System.Drawing;
ToolboxBitmapAttribute 特性需要此命名空间。

ToolboxBitmapAttribute 特性，并指定具有 ServerControl1 命名空间前缀的 WelcomeLabel.bmp 文件名，如下面的示例所示：

C++

JScript

复制

[DefaultProperty("Text")]
[ToolboxData("<{0}:WelcomeLabel runat=server></{0}:WelcomeLabel>")]
[ToolboxBitmap(typeof(ResourceFinder), "ServerControl1.WelcomeLabel.bmp")]
public class WelcomeLabel : Label

保存并关闭文件。
“生成解决方案”。
“TestWebSite”项目中，打开 Default.aspx 文件。
“删除”。
“选择项”。
“浏览”，然后浏览到 TestWebSite 项目的 Bin 文件夹。
“打开”。

“.NET Framework 组件”选项卡中。
“确定”。

“WelcomeLabel”的左侧，如下图所示。

后续步骤

开发自定义 ASP.NET 服务器控件。

ASP.NET 控件设计器概述。

请参见

其他资源

开发自定义 ASP.NET 服务器控件

Web Custom Control Behavior and Authoring