Beispiel für ein zusammengesetztes Steuerelement
Aktualisiert: November 2007
Dieses Beispiel zeigt, wie ein Steuerelement mit dem Namen Register erstellt wird, das die wichtigsten Schritte zur Implementierung eines zusammengesetzten ASP.NET-Serversteuerelements veranschaulicht. Ein zusammengesetztes Steuerelement erstellt mithilfe von untergeordneten Steuerelementen eine Benutzeroberfläche und führt weitere Logik aus. Da ein zusammengesetztes Steuerelement funktionell auf untergeordnete Steuerelemente angewiesen ist, können Sie wesentlich einfacher ein zusammengesetztes Steuerelement entwickeln, anstatt die gesamte Funktionalität des Steuerelements selbst zu implementieren.
In diesem Beispiel verwendet das Register-Steuerelement untergeordnete Steuerelemente, um eine Benutzeroberfläche zum Eingeben von Benutzerinformationen auf einer Website zu erstellen. Die Benutzeroberfläche besteht aus zwei TextBox-Steuerelementen, in die jeweils der Benutzername und die E-Mail-Adresse des Benutzers eingegeben werden. Ein Button-Steuerelement dient zum Übermitteln der Informationen. In Register werden den beiden TextBox-Steuerelementen zwei RequiredFieldValidator-Steuerelemente zugeordnet, um sicherzustellen, dass der Benutzer auch einen Namen und eine E-Mail-Adresse eingibt. Das Click-Ereignis des Button-Steuerelements wird als Submit-Ereignis des Register-Steuerelements ausgelöst.
Das Verhalten des Register-Steuerelements beruht auf den integrierten Features der untergeordneten Steuerelemente. Register ist beispielsweise zum Behandeln der Postbackdaten auf die TextBox-Steuerelemente, für das Postbackereignis auf das Button-Steuerelement und für die Validierung auf die RequiredFieldValidator-Steuerelemente angewiesen.
Der Code für das Register-Steuerelement wird nachfolgend im Abschnitt "Codeerläuterung" in diesem Thema beschrieben. Wenn Sie den Code für das Register-Steuerelement genauer untersuchen, werden Sie feststellen, dass sich der meiste Code auf das Erstellen und Verwalten von untergeordneten Steuerelementen bezieht.
Codeauflistung für das Register-Steuerelement
' Register.vb
Option Strict On
Imports System
Imports System.ComponentModel
Imports System.Drawing
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls
Namespace Samples.AspNet.VB.Controls
< _
AspNetHostingPermission(SecurityAction.Demand, _
Level:=AspNetHostingPermissionLevel.Minimal), _
AspNetHostingPermission(SecurityAction.InheritanceDemand, _
Level:=AspNetHostingPermissionLevel.Minimal), _
DefaultEvent("Submit"), _
DefaultProperty("ButtonText"), _
ToolboxData("<{0}:Register runat=""server""> </{0}:Register>") _
> _
Public Class Register
Inherits CompositeControl
Private submitButton As Button
Private nameTextBox As TextBox
Private nameLabel As Label
Private emailTextBox As TextBox
Private emailLabel As Label
Private emailValidator As RequiredFieldValidator
Private nameValidator As RequiredFieldValidator
Private Shared ReadOnly EventSubmitKey As New Object()
' The following properties are delegated to child controls.
< _
Bindable(True), _
Category("Appearance"), _
DefaultValue(""), _
Description("The text to display on the button.") _
> _
Public Property ButtonText() As String
Get
EnsureChildControls()
Return submitButton.Text
End Get
Set(ByVal value As String)
EnsureChildControls()
submitButton.Text = value
End Set
End Property
< _
Bindable(True), _
Category("Default"), _
DefaultValue(""), _
Description("The user name.") _
> _
Public Property Name() As String
Get
EnsureChildControls()
Return nameTextBox.Text
End Get
Set(ByVal value As String)
EnsureChildControls()
nameTextBox.Text = value
End Set
End Property
< _
Bindable(True), _
Category("Appearance"), _
DefaultValue(""), _
Description("Error message for the name validator.") _
> _
Public Property NameErrorMessage() As String
Get
EnsureChildControls()
Return nameValidator.ErrorMessage
End Get
Set(ByVal value As String)
EnsureChildControls()
nameValidator.ErrorMessage = value
nameValidator.ToolTip = value
End Set
End Property
< _
Bindable(True), _
Category("Appearance"), _
DefaultValue(""), _
Description("The text for the name label.") _
> _
Public Property NameLabelText() As String
Get
EnsureChildControls()
Return nameLabel.Text
End Get
Set(ByVal value As String)
EnsureChildControls()
nameLabel.Text = value
End Set
End Property
< _
Bindable(True), _
Category("Default"), _
DefaultValue(""), _
Description("The e-mail address.") _
> _
Public Property Email() As String
Get
EnsureChildControls()
Return emailTextBox.Text
End Get
Set(ByVal value As String)
EnsureChildControls()
emailTextBox.Text = value
End Set
End Property
< _
Bindable(True), _
Category("Appearance"), _
DefaultValue(""), _
Description("Error message for the e-mail validator.") _
> _
Public Property EmailErrorMessage() As String
Get
EnsureChildControls()
Return emailValidator.ErrorMessage
End Get
Set(ByVal value As String)
EnsureChildControls()
emailValidator.ErrorMessage = value
emailValidator.ToolTip = value
End Set
End Property
< _
Bindable(True), _
Category("Appearance"), _
DefaultValue(""), _
Description("The text for the e-mail label.") _
> _
Public Property EmailLabelText() As String
Get
EnsureChildControls()
Return emailLabel.Text
End Get
Set(ByVal value As String)
EnsureChildControls()
emailLabel.Text = value
End Set
End Property
' The Submit event.
< _
Category("Action"), _
Description("Raised when the user clicks the button.") _
> _
Public Custom Event Submit As EventHandler
AddHandler(ByVal value As EventHandler)
Events.AddHandler(EventSubmitKey, value)
End AddHandler
RemoveHandler(ByVal value As EventHandler)
Events.RemoveHandler(EventSubmitKey, value)
End RemoveHandler
RaiseEvent(ByVal sender As Object, _
ByVal e As System.EventArgs)
CType(Events(EventSubmitKey), _
EventHandler).Invoke(sender, e)
End RaiseEvent
End Event
' The method that raises the Submit event.
Protected Overridable Sub OnSubmit(ByVal e As EventArgs)
Dim submitHandler As EventHandler = _
CType(Events(EventSubmitKey), EventHandler)
If submitHandler IsNot Nothing Then
submitHandler(Me, e)
End If
End Sub
' Handles the Click event of the Button and raises
' the Submit event.
Private Sub submitButton_Click(ByVal source As Object, _
ByVal e As EventArgs)
OnSubmit(EventArgs.Empty)
End Sub
Protected Overrides Sub CreateChildControls()
Controls.Clear()
nameLabel = New Label()
nameTextBox = New TextBox()
nameTextBox.ID = "nameTextBox"
nameValidator = New RequiredFieldValidator()
nameValidator.ID = "validator1"
nameValidator.ControlToValidate = nameTextBox.ID
nameValidator.Text = "Failed validation."
nameValidator.Display = ValidatorDisplay.Static
emailLabel = New Label()
emailTextBox = New TextBox()
emailTextBox.ID = "emailTextBox"
emailValidator = New RequiredFieldValidator()
emailValidator.ID = "validator2"
emailValidator.ControlToValidate = emailTextBox.ID
emailValidator.Text = "Failed validation."
emailValidator.Display = ValidatorDisplay.Static
submitButton = New Button()
submitButton.ID = "button1"
AddHandler submitButton.Click, _
AddressOf submitButton_Click
Me.Controls.Add(nameLabel)
Me.Controls.Add(nameTextBox)
Me.Controls.Add(nameValidator)
Me.Controls.Add(emailLabel)
Me.Controls.Add(emailTextBox)
Me.Controls.Add(emailValidator)
Me.Controls.Add(submitButton)
End Sub
Protected Overrides Sub Render(ByVal writer As HtmlTextWriter)
AddAttributesToRender(writer)
writer.AddAttribute(HtmlTextWriterAttribute.Cellpadding, _
"1", False)
writer.RenderBeginTag(HtmlTextWriterTag.Table)
writer.RenderBeginTag(HtmlTextWriterTag.Tr)
writer.RenderBeginTag(HtmlTextWriterTag.Td)
nameLabel.RenderControl(writer)
writer.RenderEndTag()
writer.RenderBeginTag(HtmlTextWriterTag.Td)
nameTextBox.RenderControl(writer)
writer.RenderEndTag()
writer.RenderBeginTag(HtmlTextWriterTag.Td)
nameValidator.RenderControl(writer)
writer.RenderEndTag()
writer.RenderEndTag()
writer.RenderBeginTag(HtmlTextWriterTag.Tr)
writer.RenderBeginTag(HtmlTextWriterTag.Td)
emailLabel.RenderControl(writer)
writer.RenderEndTag()
writer.RenderBeginTag(HtmlTextWriterTag.Td)
emailTextBox.RenderControl(writer)
writer.RenderEndTag()
writer.RenderBeginTag(HtmlTextWriterTag.Td)
emailValidator.RenderControl(writer)
writer.RenderEndTag()
writer.RenderEndTag()
writer.RenderBeginTag(HtmlTextWriterTag.Tr)
writer.AddAttribute(HtmlTextWriterAttribute.Colspan, _
"2", False)
writer.AddAttribute(HtmlTextWriterAttribute.Align, _
"right", False)
writer.RenderBeginTag(HtmlTextWriterTag.Td)
submitButton.RenderControl(writer)
writer.RenderEndTag()
writer.RenderBeginTag(HtmlTextWriterTag.Td)
writer.Write(" ")
writer.RenderEndTag()
writer.RenderEndTag()
writer.RenderEndTag()
End Sub
Protected Overrides Sub RecreateChildControls()
EnsureChildControls()
End Sub
End Class
End Namespace
// Register.cs
using System;
using System.ComponentModel;
using System.Drawing;
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),
DefaultEvent("Submit"),
DefaultProperty("ButtonText"),
ToolboxData("<{0}:Register runat=\"server\"> </{0}:Register>"),
]
public class Register : CompositeControl
{
private Button submitButton;
private TextBox nameTextBox;
private Label nameLabel;
private TextBox emailTextBox;
private Label emailLabel;
private RequiredFieldValidator emailValidator;
private RequiredFieldValidator nameValidator;
private static readonly object EventSubmitKey =
new object();
// The following properties are delegated to
// child controls.
[
Bindable(true),
Category("Appearance"),
DefaultValue(""),
Description("The text to display on the button.")
]
public string ButtonText
{
get
{
EnsureChildControls();
return submitButton.Text;
}
set
{
EnsureChildControls();
submitButton.Text = value;
}
}
[
Bindable(true),
Category("Default"),
DefaultValue(""),
Description("The user name.")
]
public string Name
{
get
{
EnsureChildControls();
return nameTextBox.Text;
}
set
{
EnsureChildControls();
nameTextBox.Text = value;
}
}
[
Bindable(true),
Category("Appearance"),
DefaultValue(""),
Description(
"Error message for the name validator.")
]
public string NameErrorMessage
{
get
{
EnsureChildControls();
return nameValidator.ErrorMessage;
}
set
{
EnsureChildControls();
nameValidator.ErrorMessage = value;
nameValidator.ToolTip = value;
}
}
[
Bindable(true),
Category("Appearance"),
DefaultValue(""),
Description("The text for the name label.")
]
public string NameLabelText
{
get
{
EnsureChildControls();
return nameLabel.Text;
}
set
{
EnsureChildControls();
nameLabel.Text = value;
}
}
[
Bindable(true),
Category("Default"),
DefaultValue(""),
Description("The e-mail address.")
]
public string Email
{
get
{
EnsureChildControls();
return emailTextBox.Text;
}
set
{
EnsureChildControls();
emailTextBox.Text = value;
}
}
[
Bindable(true),
Category("Appearance"),
DefaultValue(""),
Description(
"Error message for the e-mail validator.")
]
public string EmailErrorMessage
{
get
{
EnsureChildControls();
return emailValidator.ErrorMessage;
}
set
{
EnsureChildControls();
emailValidator.ErrorMessage = value;
emailValidator.ToolTip = value;
}
}
[
Bindable(true),
Category("Appearance"),
DefaultValue(""),
Description("The text for the e-mail label.")
]
public string EmailLabelText
{
get
{
EnsureChildControls();
return emailLabel.Text;
}
set
{
EnsureChildControls();
emailLabel.Text = value;
}
}
// The Submit event.
[
Category("Action"),
Description("Raised when the user clicks the button.")
]
public event EventHandler Submit
{
add
{
Events.AddHandler(EventSubmitKey, value);
}
remove
{
Events.RemoveHandler(EventSubmitKey, value);
}
}
// The method that raises the Submit event.
protected virtual void OnSubmit(EventArgs e)
{
EventHandler SubmitHandler =
(EventHandler)Events[EventSubmitKey];
if (SubmitHandler != null)
{
SubmitHandler(this, e);
}
}
// Handles the Click event of the Button and raises
// the Submit event.
private void _button_Click(object source, EventArgs e)
{
OnSubmit(EventArgs.Empty);
}
protected override void RecreateChildControls()
{
EnsureChildControls();
}
protected override void CreateChildControls()
{
Controls.Clear();
nameLabel = new Label();
nameTextBox = new TextBox();
nameTextBox.ID = "nameTextBox";
nameValidator = new RequiredFieldValidator();
nameValidator.ID = "validator1";
nameValidator.ControlToValidate = nameTextBox.ID;
nameValidator.Text = "Failed validation.";
nameValidator.Display = ValidatorDisplay.Static;
emailLabel = new Label();
emailTextBox = new TextBox();
emailTextBox.ID = "emailTextBox";
emailValidator = new RequiredFieldValidator();
emailValidator.ID = "validator2";
emailValidator.ControlToValidate =
emailTextBox.ID;
emailValidator.Text = "Failed validation.";
emailValidator.Display = ValidatorDisplay.Static;
submitButton = new Button();
submitButton.ID = "button1";
submitButton.Click
+= new EventHandler(_button_Click);
this.Controls.Add(nameLabel);
this.Controls.Add(nameTextBox);
this.Controls.Add(nameValidator);
this.Controls.Add(emailLabel);
this.Controls.Add(emailTextBox);
this.Controls.Add(emailValidator);
this.Controls.Add(submitButton);
}
protected override void Render(HtmlTextWriter writer)
{
AddAttributesToRender(writer);
writer.AddAttribute(
HtmlTextWriterAttribute.Cellpadding,
"1", false);
writer.RenderBeginTag(HtmlTextWriterTag.Table);
writer.RenderBeginTag(HtmlTextWriterTag.Tr);
writer.RenderBeginTag(HtmlTextWriterTag.Td);
nameLabel.RenderControl(writer);
writer.RenderEndTag();
writer.RenderBeginTag(HtmlTextWriterTag.Td);
nameTextBox.RenderControl(writer);
writer.RenderEndTag();
writer.RenderBeginTag(HtmlTextWriterTag.Td);
nameValidator.RenderControl(writer);
writer.RenderEndTag();
writer.RenderEndTag();
writer.RenderBeginTag(HtmlTextWriterTag.Tr);
writer.RenderBeginTag(HtmlTextWriterTag.Td);
emailLabel.RenderControl(writer);
writer.RenderEndTag();
writer.RenderBeginTag(HtmlTextWriterTag.Td);
emailTextBox.RenderControl(writer);
writer.RenderEndTag();
writer.RenderBeginTag(HtmlTextWriterTag.Td);
emailValidator.RenderControl(writer);
writer.RenderEndTag();
writer.RenderEndTag();
writer.RenderBeginTag(HtmlTextWriterTag.Tr);
writer.AddAttribute(
HtmlTextWriterAttribute.Colspan,
"2", false);
writer.AddAttribute(
HtmlTextWriterAttribute.Align,
"right", false);
writer.RenderBeginTag(HtmlTextWriterTag.Td);
submitButton.RenderControl(writer);
writer.RenderEndTag();
writer.RenderBeginTag(HtmlTextWriterTag.Td);
writer.Write(" ");
writer.RenderEndTag();
writer.RenderEndTag();
writer.RenderEndTag();
}
}
}
Codeerläuterung
Das Register-Steuerelement führt die folgenden Aufgaben aus, die allen zusammengesetzten Steuerelementen gemeinsam sind:
Ableiten von der CompositeControl-Klasse.
Erstellen von untergeordneten Steuerelementen durch Überschreiben der CreateChildControls-Methode.
Die CompositeControl-Klasse implementiert wesentliche Funktionen, die allen zusammengesetzten Steuerelementen gemeinsam sind. Der zugeordnete Steuerelement-Designer stellt außerdem sicher, dass die untergeordneten Steuerelemente auf der Designoberfläche eines visuellen Designers angezeigt werden.
Hinweis: |
---|
Die CompositeControl-Klasse ist neu in ASP.NET 2.0. In ASP.NET 1.0 und 1.1 war es beim Erstellen eines benutzerdefinierten Steuerelements noch erforderlich, die INamingContainer-Schnittstelle zu implementieren, um damit für die untergeordneten Steuerelemente einen neuen Namensbereich zu erstellen. Außerdem musste die Controls-Eigenschaft überschrieben und die EnsureChildControls-Methode aufgerufen werden. In ASP.NET 2.0 werden diese und andere Schritte von der CompositeControl-Klasse übernommen. |
Sie sollten die untergeordneten Steuerelemente in der CreateChildControls-Methode erstellen und nicht in OnInit oder einer anderen Lebenszyklusphase. Die Serversteuerelementarchitektur ist für die Controls-Auflistung auf CreateChildControls-Aufrufe angewiesen, z. B. im Kontext einer Datenbindung.
Das Register-Steuerelement zeigt auch, wie Eigenschaften der untergeordneten Steuerelemente als Eigenschaften der obersten Ebene verfügbar gemacht werden. Dies ist nützlich, um einem Seitenentwickler den Zugriff auf die Eigenschaften eines untergeordneten Steuerelements zu ermöglichen. So macht beispielsweise Register die Text-Eigenschaft des untergeordneten Button-Steuerelements als eigene ButtonText-Eigenschaft verfügbar, wie der folgende Code aus dem Beispiel zeigt:
< _
Bindable(True), _
Category("Appearance"), _
DefaultValue(""), _
Description("The text to display on the button.") _
> _
Public Property ButtonText() As String
Get
EnsureChildControls()
Return submitButton.Text
End Get
Set(ByVal value As String)
EnsureChildControls()
submitButton.Text = value
End Set
End Property
[
Bindable(true),
Category("Appearance"),
DefaultValue(""),
Description("The text to display on the button.")
]
public string ButtonText
{
get
{
EnsureChildControls();
return submitButton.Text;
}
set
{
EnsureChildControls();
submitButton.Text = value;
}
}
Die ButtonText-Eigenschaft oder andere Eigenschaften, die an untergeordnete Eigenschaften delegiert sind, werden nicht vom Register-Steuerelement gespeichert, da untergeordnete Steuerelemente diese Eigenschaften im Ansichtszustand speichern. Informationen zum Verwalten der Zustände von Eigenschaften, die nicht an untergeordnete Steuerelementen delegiert werden, finden Sie unter Beispiel für die Eigenschaften eines Serversteuerelements. Das Thema enthält Informationen über das Verwenden des ViewState-Wörterbuchs zum Speichern einfacher Eigenschaften und zum Implementieren einer benutzerdefinierten Zustandsverwaltung für Eigenschaften mit untergeordneten Eigenschaften.
Das Register-Steuerelement zeigt, wie ein Ereignis über den Ereignishandler eines untergeordneten Steuerelements ausgelöst wird. Das Register-Steuerelement definiert ein Ereignis mit dem Namen Submit und löst das Ereignis durch Anfügen eines Handlers an das Click-Ereignis des untergeordneten Button-Steuerelements aus.
Testseite für das Register-Steuerelement
Das folgende Beispiel zeigt eine ASP.NET-Webseite, die das Register-Steuerelement verwendet.
<%@ Page Language="VB"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
Label1.Visible = False
End Sub
Sub Register_Submit(ByVal sender As Object, ByVal e As EventArgs)
' The application developer can implement
' logic here to enter registration data into
' a database or write a cookie
' on the user's computer.
' This example merely writes a message
' using the Label control on the page.
Label1.Text = String.Format( _
"Thank you, {0}! You are registered.", Register1.Name)
Label1.Visible = True
Register1.Visible = False
End Sub
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
<title>
Register Control Test Page
</title>
</head>
<body>
<form id="form1" runat="server">
<aspSample:Register ButtonText="Submit"
OnSubmit="Register_Submit" ID="Register1"
Runat="server" NameLabelText="Name:" EmailLabelText="Email:"
EmailErrorMessage="You must enter your e-mail address."
NameErrorMessage="You must enter your name." />
<br />
<asp:Label ID="Label1" Runat="server" Text="Label">
</asp:Label>
<asp:ValidationSummary ID="ValidationSummary1"
Runat="server" DisplayMode="List" />
</form>
</body>
</html>
<%@ Page Language="C#"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
void Page_Load(object sender, EventArgs e)
{
Label1.Visible = false;
}
void Register_Submit(object sender, EventArgs e)
{
// The application developer can implement
// logic here to enter registration data into
// a database or write a cookie
// on the user's computer.
// This example merely writes a message
// using the Label control on the page.
Label1.Text = String.Format(
"Thank you, {0}! You are registered.",Register1.Name);
Label1.Visible = true;
Register1.Visible = false;
}
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
<title>
Register Control Test Page
</title>
</head>
<body>
<form id="form1" runat="server">
<aspSample:Register ButtonText="Register"
OnSubmit="Register_Submit" ID="Register1"
Runat="server" NameLabelText="Name:"
EmailLabelText="Email:"
EmailErrorMessage="You must enter your e-mail address."
NameErrorMessage="You must enter your name." />
<br />
<asp:Label ID="Label1" Runat="server" Text="Label">
</asp:Label>
<asp:ValidationSummary ID="ValidationSummary1"
Runat="server" DisplayMode="List" />
</form>
</body>
</html>
Erstellen und Verwenden des Beispiels
Weitere Informationen über das Kompilieren und Verwenden der benutzerdefinierten Beispielsteuerelemente finden Sie unter Erstellen der Beispiele für benutzerdefinierte Serversteuerelemente.
Siehe auch
Weitere Ressourcen
Entwickeln von benutzerdefinierten ASP.NET-Serversteuerelementen