Beispiel für das Rendering eines Webserversteuerelements

Článek
10/22/2014

Aktualisiert: November 2007

Dieses Beispiel zeigt, wie ein Steuerelement mit dem Namen MailLink erstellt wird, das einen E-Mail-Link auf einer Webseite erstellt, indem es ein Hyperlinkelement (<a>-Element) mit einem mailto:-URI wiedergibt. Das Steuerelement veranschaulicht die Aufgaben, die Sie im Allgemeinen durchführen, wenn Sie ein Steuerelement rendern, das von der WebControl-Klasse abgeleitet ist.

Das MailLink-Steuerelement macht eine Email-Eigenschaft für die E-Mail-Adresse und eine Text-Eigenschaft für das Anzeigen des Texts im Hyperlink verfügbar. Ein Entwickler kann diese Eigenschaften festlegen, wie im markierten Text gezeigt wird:

<aspSample:MailLink id="maillink1" Email="someone@example.com" 
    runat="server">
  Mail Webmaster
</aspSample:MailLink>

Wenn das vom Steuerelement gerenderte Markup auf dem Client angezeigt wird, sieht es wie folgt aus:

<a id="maillink1" href="mailto:someone@example.com">
  Mail Webmaster
</a>

Das Verhalten eines mailto:-URI kann in verschiedenen Browsern unterschiedlich sein. Wenn ein Benutzer in Internet Explorer auf einen mailto:-Hyperlink klickt, startet der Browser den vom Benutzer standardmäßig festgelegten E-Mail-Client (wenn der E-Mail-Client installiert und mit dem Browser kompatibel ist). Der Code für das MailLink-Steuerelement wird nachfolgend im Abschnitt "Codeerläuterung" in diesem Thema beschrieben.

Codeauflistung für das MailLink-Steuerelement

' MailLink.vb
Option Strict On
Imports System
Imports System.ComponentModel
Imports System.Security
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), _
    DefaultProperty("Email"), _
    ParseChildren(True, "Text"), _
    ToolboxData("<{0}:MailLink runat=""server""> </{0}:MailLink>") _
    > _
    Public Class MailLink
        Inherits WebControl
        < _
        Bindable(True), _
        Category("Appearance"), _
        DefaultValue(""), _
        Description("The e-mail address.") _
        > _
        Public Overridable Property Email() As String
            Get
                Dim s As String = CStr(ViewState("Email"))
                If s Is Nothing Then s = String.Empty
                Return s
            End Get
            Set(ByVal value As String)
                ViewState("Email") = value
            End Set
        End Property

        < _
        Bindable(True), _
        Category("Appearance"), _
        DefaultValue(""), _
        Description("The text to display on the link."), _
        Localizable(True), _
        PersistenceMode(PersistenceMode.InnerDefaultProperty) _
        > _
        Public Overridable Property Text() As String
            Get
                Dim s As String = CStr(ViewState("Text"))
                If s Is Nothing Then s = String.Empty
                Return s
            End Get
            Set(ByVal value As String)
                ViewState("Text") = value
            End Set
        End Property

        Protected Overrides ReadOnly Property TagKey() _
            As HtmlTextWriterTag
            Get
                Return HtmlTextWriterTag.A
            End Get
        End Property


        Protected Overrides Sub AddAttributesToRender( _
            ByVal writer As HtmlTextWriter)
            MyBase.AddAttributesToRender(writer)
            writer.AddAttribute(HtmlTextWriterAttribute.Href, _
                "mailto:" & Email)
        End Sub

        Protected Overrides Sub RenderContents( _
            ByVal writer As HtmlTextWriter)
            If (Text = String.Empty) Then
                Text = Email
            End If
            writer.WriteEncodedText(Text)
        End Sub

    End Class
End Namespace

// MailLink.cs
using System;
using System.ComponentModel;
using System.Security;
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("Email"),
    ParseChildren(true, "Text"),
    ToolboxData("<{0}:MailLink runat=\"server\"> </{0}:MailLink>")
    ]
    public class MailLink : WebControl
    {
        [
        Bindable(true),
        Category("Appearance"),
        DefaultValue(""),
        Description("The e-mail address.")
        ]
        public virtual string Email
        {
            get
            {
                string s = (string)ViewState["Email"];
                return (s == null) ? String.Empty : s;
            }
            set
            {
                ViewState["Email"] = value;
            }
        }

        [
        Bindable(true),
        Category("Appearance"),
        DefaultValue(""),
        Description("The text to display on the link."),
        Localizable(true),
        PersistenceMode(PersistenceMode.InnerDefaultProperty)
        ]
        public virtual string Text
        {
            get
            {
                string s = (string)ViewState["Text"];
                return (s == null) ? String.Empty : s;
            }
            set
            {
                ViewState["Text"] = value;
            }
        }

        protected override HtmlTextWriterTag TagKey
        {
            get
            {
                return HtmlTextWriterTag.A;
            }
        }

        protected override void AddAttributesToRender(
            HtmlTextWriter writer)
        {
            base.AddAttributesToRender(writer);
            writer.AddAttribute(HtmlTextWriterAttribute.Href, 
                "mailto:" + Email);
        }

        protected override void RenderContents(HtmlTextWriter writer)
        {
            if (Text == String.Empty)
            {
                Text = Email;
            }
            writer.WriteEncodedText(Text);
        }
    }
}

Codeerläuterung

Das MailLink-Steuerelementbeispiel veranschaulicht die folgenden Aufgaben:

Das Rendern von einem nicht standardmäßigen Element des Steuerelements.
Das Rendern von Attributen auf dem Starttag des Steuerelements.
Die Wiedergabe von Inhalt innerhalb der Steuerelementtags.

Das MailLink-Steuerelement überschreibt die TagKey-Eigenschaft, um ein <a>-Element anstelle eines standardmäßigen <span>-Elements wiederzugeben, das von der WebControl-Klasse gerendert wurde. Sie sollten die TagKey-Eigenschaft überschreiben, wenn das Element, das Sie darstellen möchten, ein Member der HtmlTextWriterTag-Enumeration ist. Viele allgemeine HTML-Elementtags werden Werten der HtmlTextWriterTag-Enumeration zugeordnet. Zum Beispiel entspricht HtmlTextWriterTag.A einem <a>-Element, und HtmlTextWriterTag.Table entspricht einem <table>-Element. Falls das Element, das Sie wiedergeben möchten, nicht von einem Member der HtmlTextWriterTag-Enumeration dargestellt wird, überschreiben Sie die TagName-Eigenschaft, und geben Sie zur Darstellung als Element die Zeichenfolge zurück.

Das MailLink-Steuerelement überschreibt die folgenden Darstellungsmethoden der WebControl-Klasse:

AddAttributesToRender, um dem vom Steuerelement gerenderten Starttag ein href-Attribut hinzuzufügen. Wenn Sie AddAttributesToRender überschreiben, sollten Sie immer die entsprechende Methode der Basisklasse aufrufen, wie das MailLink-Steuerelement demonstriert. Die AddAttributesToRender-Methode der WebControl-Klasse implementiert eine Logik, um dem mit dem Websteuerelement gerenderten Element Formate und andere Attribute hinzuzufügen. Diese Methode wird mit der RenderBeginTag-Methode von WebControl aufgerufen. Attribute müssen hinzugefügt werden, bevor das Starttag gerendert wird. Dies bedeutet, dass AddAttributesToRender oder AddAttribute vor RenderBeginTag aufgerufen werden.
RenderContents, um den Text für den Hyperlink (angegeben durch die Text-Eigenschaft) innerhalb der Steuerelementtags zu schreiben. Das MailLink-Steuerelement ruft die WriteEncodedText-Methode der HtmlTextWriter-Instanz auf, um den Text, der vom Entwickler der Seite eingegeben wurde, als HTML zu codieren. Generell sollten Sie den von Benutzern eingegebenen Text aus Sicherheitsgründen als HTML codieren.

Das MailLink-Steuerelement veranschaulicht auch die innere Textdauerhaftigkeit. Mit dem MailLink-Steuerelement kann ein Entwickler einer Seite die Text-Eigenschaft innerhalb der Steuerelementtags angeben, wie im hervorgehobenen Text gezeigt wird:

<aspSample:MailLink id="maillink1" Email="someone@example.com" 
    runat="server">
  Mail Webmaster
</aspSample:MailLink>

Die innere Dauerhaftigkeit steht im Gegensatz zur Standarddauerhaftigkeit des Steuerelementstarttags, wie dieses Beispiel zeigt:

<aspSample:MailLink Text="Mail Webmaster" runat="server" />

Die Standarddauerhaftigkeit und die innere Dauerhaftigkeit sind in ihrer Funktion identisch. Um die innere Dauerhaftigkeit zu aktivieren, wird MailLink mit dem ParseChildren(true, "Text") -Attribut gekennzeichnet. Das erste Argument des ParseChildrenAttribute-Konstruktors gibt an, dass der Seitenparser den Inhalt innerhalb der Steuerelementtags als Eigenschaften und nicht als untergeordnete Steuerelemente analysieren soll. Das zweite Argument stellt den Namen der inneren Standardeigenschaft des Steuerelements bereit (in diesem Beispiel ist das Text). Wenn der ParseChildrenAttribute-Konstruktor mit diesen beiden Parametern aufgerufen wird, muss der Inhalt innerhalb der Steuerelementtags mit der inneren Standardeigenschaft übereinstimmen. Das PersistenceMode(PersistenceMode.InnerDefaultProperty)-Attribut der Text-Eigenschaft legt fest, dass ein visueller Designer die Eigenschaft als inneren Inhalt innerhalb der Steuerelementtags serialisieren soll.

WebControl wird mit dem PersistChildren(false)-Attribut und dem ParseChildren(true)-Attribut gekennzeichnet. Diese Attribute legen die Dauerhaftigkeit der Eigenschaften zur Entwurfszeit und zur Analysezeit fest. Die Attribute werden mit dem Steuerelement geerbt und müssen nur dann angewendet werden, wenn Sie die geerbten Einstellungen ändern möchten. Das PersistChildrenAttribute gibt dem Designer an, ob die untergeordneten Steuerelemente eines Serversteuerelements als geschachtelte innere Steuerelemente beibehalten werden sollen. Das Argument false gibt an, dass der innere Inhalt den Eigenschaften und nicht den untergeordneten Steuerelementen entspricht. Das ParseChildrenAttribute wurde im vorherigen Absatz beschrieben. Wenn die Dauerhaftigkeit der WebControl-Klasse während der Entwurfszeit und der Analysezeit für das Steuerelement angemessen ist, müssen Sie das PersistChildrenAttribute-Attribut und das ParseChildrenAttribute-Attribut, die von WebControl vererbt wurden, nicht überschreiben.

Testseite für das MailLink-Steuerelement

Im folgenden Beispiel wird eine ASP.NET-Webseite (ASPX-Datei) dargestellt, die das MailLink-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">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
  <title>MailLink test page</title>
</head>
<body>
  <form id="Form1" runat="server">
    <aspSample:MailLink id="maillink1" Font-Bold="true" 
      ForeColor="Green" Email="someone@example.com" runat="server">
      Mail Webmaster
    </aspSample:MailLink>
  </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">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
  <title>MailLink test page</title>
</head>
<body>
  <form id="Form1" runat="server">
    <aspSample:MailLink id="maillink1" Font-Bold="true" 
      ForeColor="Green" Email="someone@example.com" runat="server">
      Mail Webmaster
    </aspSample:MailLink>
  </form>
</body>
</html>

Erstellen und Verwenden des Beispiels

Informationen über das Erstellen eines Steuerelements und dessen Verwendung auf einer Seite finden Sie unter Erstellen der Beispiele für benutzerdefinierte Serversteuerelemente.

Siehe auch

Weitere Ressourcen

Entwickeln von benutzerdefinierten ASP.NET-Serversteuerelementen

Sdílet prostřednictvím