Gewusst wie: Verwenden von benutzerdefinierten ASP.NET-Serversteuerelementen in Visual Studio

Článek
10/22/2014

Aktualisiert: November 2007

Sie können benutzerdefinierte Serversteuerelemente in der Visual Studio-Toolbox verfügbar machen, indem Sie die vom visuellen Designer zu verwendenden Entwurfszeitattribute definieren. In den folgenden Verfahren wird beschrieben, wie Sie ein einfaches Steuerelement namens MailLink erstellen, zur Toolbox hinzufügen und zum Erstellen eines E-Mail-Links in einer Webseite verwenden, indem Sie ein <a>-Linkelement mit einer mailto:-URL rendern.

So erstellen Sie ein benutzerdefiniertes Steuerelement mit Entwurfszeitattributen

Erstellen Sie in Visual Studio ein Bibliotheksprojekt, und definieren Sie eine benutzerdefinierte Klasse, die von WebControl abgeleitet wird, wie im folgenden Beispiel gezeigt.

Hinweis:
Der vollständige Quellcode wird im Beispielabschnitt aufgelistet.

<Assembly: TagPrefix("Samples.AspNet", "Sample")> 
Namespace Samples.AspNet
   < _
    ToolboxData("<{0}:MailLink ID='MailLinkID' Text='WebMaster' runat=""server""> </{0}:MailLink>")> _
    Public Class MailLink
        Inherits WebControl
     ' Custom code goes here.
End Class

End Namespace

[assembly:TagPrefix("Samples.AspNet", "Sample")]
namespace Samples.AspNet
{

    [
        ToolboxData("<{0}:MailLink ID='MailLinkID' Text='WebMaster' runat=\"server\"> </{0}:MailLink>")
    ]
    public class MailLink : WebControl
    {
        // Custom code goes here.
    }

}

Fügen Sie Entwurfszeitattribute hinzu, um benutzerdefinierte Metadaten bereitzustellen, die verwendet werden, um das Steuerelement zur Entwurfszeit im visuellen Designer anzuzeigen. Um das MailLink-Steuerelement in der Visual Studio-Toolbox verfügbar zu machen, werden lediglich die beiden folgenden Entwurfszeitattribute benötigt.

Das TagPrefix-Attribut gibt das Präfix vor dem Steuerelementnamen MailLink an. Zusammen definieren das Präfix und der Steuerelementname den Tagnamen für das benutzerdefinierte Steuerelement (in diesem Fall <Sample:MailLink> </Sample:MailLink>).
```
<Assembly: TagPrefix("Samples.AspNet", "Sample")> 
```
```
[assembly:TagPrefix("Samples.AspNet", "Sample")]
```
Das ToolboxData-Attribut gibt das Standardtag an, das für das MailLink-Steuerelement generiert wird, wenn es zur Entwurfszeit aus der Toolbox in eine Seite gezogen wird.
```
<ToolboxData("<{0}:MailLink ID='MailLinkID' Text='Mail Webmaster' runat='server'"> </{0}:MailLink>")> 
```
```
[ToolboxData("<{0}:MailLink ID='MailLinkID' Text='Mail Webmaster' runat=\"server\"> </{0}:MailLink>")]
```
Kompilieren Sie das MailLink-Steuerelement in einer Bibliothek, und nennen Sie es MaiLink.Dll.

So fügen Sie das benutzerdefinierte Steuerelement der Toolbox hinzu

Klicken Sie im Menü Ansicht auf Toolbox.
Klicken Sie in der Toolbox mit der rechten Maustaste, und wählen Sie Elemente auswählen aus.
Wählen Sie im Dialogfeld Toolboxelemente auswählen die Registerkarte .NET Framework-Komponenten aus, und klicken Sie auf die Schaltfläche Durchsuchen, um das zuvor erstellte MailLink.Dll-Steuerelement zu suchen.
Aktivieren Sie das Kontrollkästchen für das MailLink-Steuerelement, und klicken Sie auf OK.

Das benutzerdefinierte MailLink-Steuerelement wird in der Toolbox angezeigt.

So verweisen Sie auf das MailLink-Steuerelement auf einer Seite

Erstellen Sie ein neues Webprojekt. Erstellen Sie anschließend eine Seite mit dem Namen MailLink.aspx. Diese Seite enthält je nach Programmiersprache, die Sie für das Projekt ausgewählt haben, eine der folgenden Direktiven.
```
<%@ page language="VB" %>
```
```
<%@ page language="C#" %>
```

Fügen Sie die folgende einfache Seitenstruktur hinzu, um das MailLink-Steuerelement zu hosten.

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Using the MailLink control</title>
</head>
<body>
<h1>Using the MailLink Custom Server Control</h1>
    <form id="form1" runat="server">
    <div>

   </div>

    </form>
</body>
</html>

Wechseln Sie zur Entwurfsansicht, und ziehen Sie das MailLink-Steuerelement auf die Seite.

Visual Studio fügt der Seite zwei Elemente hinzu: eine Registrierungsdirektive für das MailLink-Steuerelement und den auf der Seite zu verwendenden Tagnamen des MailLink-Steuerelements.
Führen Sie die Seite in einem Browser aus, und klicken Sie auf den Link Mail Webmaster.

Es wird eine E-Mail-Nachricht mit der Adresse geöffnet, die von der Email-Eigenschaft des Steuerelements angegeben wird.

Beispiel

Das MailLink-Steuerelement überschreibt die TagKey-Eigenschaft, um ein <a>-Element anstelle eines standardmäßigen <span>-Elements zu rendern, das von der WebControl-Klasse gerendert wurde.

Imports System
Imports System.ComponentModel
Imports System.Security
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls

<Assembly: TagPrefix("Samples.AspNet", "Sample")> 
Namespace Samples.AspNet

    <AspNetHostingPermission( _
    SecurityAction.Demand, _
    Level:=AspNetHostingPermissionLevel.Minimal), _
    AspNetHostingPermission( _
    SecurityAction.InheritanceDemand, _
    Level:=AspNetHostingPermissionLevel.Minimal), _
    ParseChildren(True, "Text"), _
    DefaultProperty("Email"), _
    ToolboxData("<{0}:MailLink ID='MailLinkID' Text='Mail Web Master' runat=""server""> </{0}:MailLink>")> _
    Public Class MailLink
        Inherits WebControl

        <Browsable(True), Category("Appearance"), _
        DefaultValue("webmaster@contoso.com"), _
        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 = "webmaster@contoso.com"
                Return s
            End Get
            Set(ByVal value As String)
                ViewState("Email") = value
            End Set
        End Property


        <Browsable(True), Category("Appearance"), _
        DefaultValue("Web Master"), _
        Description("The name to display."), _
        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 'AddAttributesToRender


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

        End Sub 'RenderContents
    End Class 'MailLink
End Namespace

using System;
using System.ComponentModel;
using System.Security;
using System.Security.Permissions;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

[assembly:TagPrefix("Samples.AspNet", "Sample")]
namespace Samples.AspNet
{


    [
        AspNetHostingPermission(SecurityAction.Demand,
        Level = AspNetHostingPermissionLevel.Minimal),
        AspNetHostingPermission(SecurityAction.InheritanceDemand,
        Level = AspNetHostingPermissionLevel.Minimal),
        ParseChildren(true, "Text"),
        DefaultProperty("Email"),
        ToolboxData("<{0}:MailLink ID='MailLinkID' Text='Mail Web Master' runat=\"server\"> </{0}:MailLink>")
    ]
    public class MailLink : WebControl
    {
        [
            Browsable(true),
            Category("Appearance"),
            DefaultValue("webmaster@contoso.com"),
            Description("The e-mail address.")
        ]
        public virtual string Email
        {
            get
            {
                string s = (string)ViewState["Email"];
                return (s == null) ? "webmaster@contoso.com" : s;
            }
            set
            {
                ViewState["Email"] = value;
            }
        }

        [
            Browsable(true),
            Category("Appearance"),
            DefaultValue("Web Master"),
            Description("The name to display."),
            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);
        }
    }
}

Das MailLink-Steuerelement veranschaulicht auch die innere Textdauerhaftigkeit. Mit dem MailLink-Steuerelement kann ein Seitenentwickler die Text-Eigenschaft innerhalb der Steuerelementtags angeben, wie im folgenden Beispiel gezeigt:

<Sample:MailLink id="MaillinkID" Email="Webmaster@contoso.com" 
    runat="server">
 Mail Support Team
</Sample:MailLink>

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

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

Der voranstehende Code gibt das Standardtag an, das für das Steuerelement generiert wird, wenn es aus der Toolbox in eine Seite gezogen wird.

Kompilieren des Codes

Erstellen Sie in Visual Studio ein Bibliotheksprojekt, und definieren Sie eine benutzerdefinierte Klasse, die vonWebControl abgeleitet wird, wie oben gezeigt. Der vollständige Quellcode wird im vorhergehenden Codeabschnitt aufgelistet.

Sicherheit

Benutzerdefinierte Serversteuerelemente erweitern die Funktionalität von ASP.NET und müssen bestimmten Sicherheitsrichtlinien folgen. Insbesondere muss Folgendes beachtet werden:

Laufzeit- und Entwurfszeitsicherheit.
Benutzerdefinierte Steuerelemente in Assemblys mit starkem Namen.
Betriebssystemsicherheit und Zugriffssteuerungslisten (ACLs) auf dem Server, der das benutzerdefinierte Serversteuerelement hostet.
Codezugriffssicherheit, um die Ressourcen einzuschränken, auf die das Steuerelement zugreifen kann.
Verwaltete Assemblys im globalen Assemblycache.