Exemplo de Processamento de Controle Web

Artigo
10/15/2014

Este exemplo mostra como criar um controle denominado MailLink quecria um link de email em uma página da Web, renderização de um hiperlink (<a>) elemento com um mailto: URI. O controle demonstra as tarefas que você geralmente executará ao processar um controle que é derivado da classe WebControl.

O controle MailLink expõe uma propriedade Email para o e-mail e uma propriedade Text para o texto a ser exibido no hiperlink.Um desenvolvedor de página pode definir essas propriedades conforme mostrado pelo texto realçado:

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

Se a marcação processada pelo controle é exibida no cliente, ele será exibido como o seguinte:

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

O comportamento de uma URI mailto: pode ser diferente em diferentes navegadores.No Internet Explorer, quando um usuário clica em um hiperlink mailto:, o navegador inicia o cliente do usuário padrão e-mail (se o cliente e-mail estiver instalado e compatível com o navegador).O código para o controle MailLink é descrito na seção "Discussão do Código" posteriormente neste tópico.

Listagem de Código para o Controle MailLink

' 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);
        }
    }
}

Discussão de Código

O controle MailLink exemplo ilustra essas tarefas:

Processar um elemento não padrão para o controle.
Processamento de atributos em marcas de abertura do controle.
Processar conteúdo dentro das marcas de controle.

O controle MailLink substitui a propriedade TagKey para processar um elemento <a>, em vez do elemento padrão <span> processado pela classe WebControl.Você deve substituir a propriedade TagKey se o elemento desejado para processar for um membro da enumeração HtmlTextWriterTag.Muitas marcas comuns de elemento HTML são mapeadas para valores da enumeração HtmlTextWriterTag.Por exemplo, HtmlTextWriterTag.A corresponde a um elemento <a> e HtmlTextWriterTag.Table corresponde a um elemento <table>.Se o elemento desejado para processar não é representado por um membro da enumeração HtmlTextWriterTag, substituir a propriedade TagName e retornar a string a ser processada como o elemento.

O controle MailLink substitui os seguintes métodos de processamento da classe WebControl:

AddAttributesToRender Para adicionar um atributo href sobre o marca de abertura processada pelo controle.Ao substituir AddAttributesToRender, você sempre deve chamar o método correspondente da classe base, como demonstra o controle MailLink.O método AddAttributesToRender da classe WebControl implementa a lógica para adicionar estilos e outros atributos no elemento processado pelo controle da Web e é chamado pelo método RenderBeginTag de WebControl.Atributos devem ser adicionados antes da marca de abertura ser processada.Isso significa que chamadas para AddAttributesToRender ou AddAttribute vêm antes de chamadas para RenderBeginTag.
RenderContents Para escrever o texto para o hiperlink (especificado pela propriedade Text) dentro das marcas de controle.O controle MailLink chama o método WriteEncodedText da instância HtmlTextWriter para a codificação HTML do texto inserido pelo desenvolvedor de página.Em geral, para segurança, você deve codificacar em HTML o texto fornecido por usuários.

The MailLink controle também demonstra a persistência de texto interno. MailLink permite que um desenvolvedor de página especificar o Text propriedade sistema autônomo Rótulos do controle, conforme mostrado no texto realçado:

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

A persistência interna está em contraste com a persistência padrão do controle marca de abertura, como neste exemplo:

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

Persistência padrão e persistência interna são funcionalmente idênticas.Para ativar persistência interna, MailLink é marcado com o atributo ParseChildren(true, "Text") .O primeiro argumento do construtor ParseChildrenAttribute especifica que o analisador da página deve analisar conteúdo dentro das marcas de controle como propriedades em vez de como os controles filho.O segundo argumento fornece o nome da propriedade interna padrão do controle (no exemplo, Text).Quando o construtor ParseChildrenAttribute é chamado com esses dois parâmetros, o conteúdo nas marcas do controle deve corresponder à propriedade interna padrão.O atributo PersistenceMode(PersistenceMode.InnerDefaultProperty) sobre a propriedade Text especifica que um designer visual deve serializar a propriedade como conteúdo interno dentro das marcas decontrole.

WebControl está marcado com os atributos PersistChildren(false) e ParseChildren(true), que controlam propriedade em tempo de design e persistência em tempo de análise.Elas são herdadas com o controle e precisa ser aplicada somente se você desejar alterar as configurações herdadas.O PersistChildrenAttribute informa o designer se os controles filho de uma controle de servidor devem ser persistentes como controles internos aninhados.O argumento false indica que o conteúdo interno corresponde a propriedades e não a controles filho.O ParseChildrenAttribute foi descrito no parágrafo anterior.Se a persistência do tempo de design e tempo de análise da classe WebControl for apropriada para o controle, você não tem que substituir PersistChildrenAttribute e atributos ParseChildrenAttribute herdados de WebControl.

Testar Página para o Controle MailLink

O exemplo a seguir mostra uma página da Web do ASP.NET (arquivo .aspx) que usa o controle MailLink.

<%@ 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" >
  <title>MailLink test page</title>
</head>
<body>
  <form id="Form1" >
    <aspSample:MailLink id="maillink1" Font-Bold="true" 
      ForeColor="Green" Email="someone@example.com" >
      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" >
  <title>MailLink test page</title>
</head>
<body>
  <form id="Form1" >
    <aspSample:MailLink id="maillink1" Font-Bold="true" 
      ForeColor="Green" Email="someone@example.com" >
      Mail Webmaster
    </aspSample:MailLink>
  </form>
</body>
</html>

Construindo e Usando o Exemplo

Para mais informações a respeito da construção do controle e uso dele em uma página, consulte Construindo os Exemplos de Controle de Servidor Personalizado.

Consulte também

Outros recursos

Desenvolvendo Controles Personalizados ASP.NET Server

Partilhar via