Syntax für benutzerdefinierte Serversteuerelemente

Artikel
05/27/2012

[Dieses Dokument dient lediglich Vorschauzwecken und kann in späteren Versionen geändert werden. Leere Themen sind als Platzhalter enthalten.]

Mit der Syntax für benutzerdefinierte Serversteuerelemente können Sie Benutzersteuerelemente und benutzerdefinierte Serversteuerelemente als Markupelemente in ASP.NET-Anwendungsdateien deklarieren, z. B. in Webseiten, Benutzersteuerelementen und Masterseiten. Die Syntax unterscheidet sich kaum von der allgemeinen Syntax zum Deklarieren von ASP.NET-Serversteuerelementen, außer dass für benutzerdefinierte Steuerelemente und Benutzersteuerelemente in der Regel ein eindeutiges Tagpräfix und ein Tagname deklariert werden müssen, die dem Steuerelement entsprechen.

<tagprefix:tagname id="OptionalID"
   attributename="value"
   eventname="eventhandlermethod"
   runat="server" />
OR
<tagprefix:tagname id="OptionalID"
   runat="server" />

Attribute

tagprefix
Ein Alias für den vollqualifizierten Namespace der auf der Seite verwendeten Markupelemente. Der Wert des Alias ist beliebig, bietet jedoch eine schnelle Möglichkeit, um das Markup eines benutzerdefinierten Steuerelements oder eines Benutzersteuerelements dem Namespace der anderen in einer ASP.NET-Datei deklarierten Markupelemente zuzuordnen.
tagname
Bei einem benutzerdefinierten Steuerelement verweist tagname auf den Namen eines Typs, für den von ASP.NET eine Laufzeitinstanz erstellt wird. Bei einem Benutzersteuerelement verweist tagname auf die zugeordnete Quelldatei, die das Benutzersteuerelement definiert. Diese Datei definiert wiederum den Typ, für den von ASP.NET eine Instanz erstellt wird.
id
Ein eindeutiger Bezeichner, der programmgesteuerte Verweise auf das Steuerelement ermöglicht.
attributename
Der Name eines Attributs, das einer Eigenschaft des Steuerelements entspricht.
value
Der dem Attribut (der Eigenschaft) zugewiesene Wert.
eventname
Der Name eines Ereignisses im Steuerelement.
eventhandlermethod
Der Name eines Ereignishandlers, der definiert wird, um das angegebene Ereignis für das Steuerelement zu behandeln.

Hinweise

Verwenden Sie die Syntax für benutzerdefinierte Serversteuerelemente, um Benutzersteuerelemente und benutzerdefinierte Serversteuerelemente innerhalb des Textteils einer ASP.NET-Webseite zu deklarieren. Damit die Syntax funktioniert, muss das Steuerelement auf der Seite oder in einer Konfigurationsdatei registriert werden (Sie können ein Steuerelement auf allen Seiten einer Anwendung registrieren, indem Sie es den <controls> der Datei Web.config hinzufügen). Sie können ein Steuerelement auf einer einzelnen Seite registrieren, indem Sie die @ Register-Direktive verwenden.

Das Starttag eines Elements für ein Benutzersteuerelement oder ein benutzerdefiniertes Steuerelement muss ein runat="server"-Attribut-Wert-Paar enthalten. Um programmgesteuertes Verweisen auf das Steuerelement zu aktivieren, können Sie optional einen eindeutigen Wert für das id-Attribut angeben.

Alle in einem Benutzersteuerelement oder benutzerdefinierten Serversteuerelement erstellten Eigenschaften können deklarativ im Starttag des Serversteuerelements verfügbar gemacht werden. Deklarieren Sie die Eigenschaft dafür einfach als Attribut, und weisen Sie diesem einen Wert zu. Wenn Sie z. B. ein benutzerdefiniertes Textfeld-Steuerelement mit einer width-Eigenschaft erstellen, können Sie durch Deklarieren von width="50" im Starttag des Steuerelements die Anzeigebreite des Serversteuerelements auf 50 Pixel festlegen.

In einigen Fällen können Attribute Objekte mit eigenen Eigenschaften sein. Fügen Sie in diesem Fall den Eigenschaftennamen in die Deklaration ein. Wenn Sie z. B. ein benutzerdefiniertes Textfeld-Steuerelement mit einem font-Attribut erstellen, kann dieses eine name-Eigenschaft enthalten. Anschließend können Sie die Eigenschaft im öffnenden Tag des Serversteuerelements als font-name="Arial" deklarieren. Weitere Informationen über das Entwickeln von benutzerdefinierten Serversteuerelementen mit Eigenschaften finden Sie unter Server Control Simple Properties and SubProperties.

Sie können Ereignisse in benutzerdefinierten Serversteuerelementen und Benutzersteuerelementen wie in ASP.NET-Serversteuerelementen deklarieren. Geben Sie die Ereignisbindung im Starttag des Serversteuerelements mit einem Attribut und einem Wert an. Weitere Informationen über das Erstellen von benutzerdefinierten Serversteuerelementen, die Ereignisse unterstützen, finden Sie unter Server Event Handling in ASP.NET Web Pages.

Sie können benutzerdefinierte Serversteuerelemente verwenden und entwickeln, die Inlinevorlagen unterstützen. Ausführliche Informationen zum Deklarieren von Vorlagen in einem benutzerdefinierten Serversteuerelement finden Sie unter Syntax für Inlinevorlagen für Serversteuerelemente. Informationen über das Erstellen benutzerdefinierter Serversteuerelemente, die Inlinevorlagen unterstützen, finden Sie unter How to: Create Templated ASP.NET User Controls.

Beispiel

Das folgende Codebeispiel veranschaulicht, wie Sie ein benutzerdefiniertes Serversteuerelement auf einer ASP.NET Web-Webseite registrieren und deklarieren. Im ersten Codeabschnitt wird eine öffentliche Klasse erstellt, die sich von der Button-Klasse ableitet. Bei dem zweiten Teil des Codes handelt es sich um eine Webseite, die die benutzerdefinierte Schaltfläche hostet. Beachten Sie, dass die Webseite die @ Register-Direktive verwendet, um den Namespace für das Steuerelement zu registrieren und das tagprefix-Attribut festzulegen. Mit dem tagprefix-Wert und dem Klassennamen des Steuerelements, getrennt durch einen Doppelpunkt (:), wird dann auf der Seite auf das Steuerelement verwiesen.

Wenn Sie das Codebeispiel ausführen möchten, müssen Sie dieses benutzerdefinierte Steuerelement kompilieren. Sie können den Code explizit kompilieren und die sich ergebende Assembly im Ordner Bin der Website oder im globalen Assemblycache ablegen. Alternativ können Sie den Quellcode im Ordner App_Code der Site ablegen, wo er zur Laufzeit dynamisch kompiliert wird. Dieses Codebeispiel verwendet die dynamische Kompilierung, weshalb die @ Register-Direktive in der Seite kein Assembly-Attribut deklarieren muss (da die Quelle zur Laufzeit dynamisch kompiliert wird). Eine exemplarische Vorgehensweise, in der die Kompilierung veranschaulicht wird, finden Sie unter Walkthrough: Developing and Using a Custom Server Control.

Sicherheitshinweis
In diesem Beispiel ist ein Textfeld für eine Benutzereingabe enthalten. Dies stellt ein potenzielles Sicherheitsrisiko dar.Standardmäßig stellt die ASP.NET-Seite sicher, dass die Benutzereingabe keine Skript- oder HTML-Elemente enthält.Weitere Informationen finden Sie unter Script Exploits Overview.

// A custom Button control to reference in the page.
using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Security.Permissions
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;

namespace Samples.AspNet.CS.Controls
{
  [AspNetHostingPermission(SecurityAction.Demand,
  Level = AspNetHostingPermissionLevel.Minimal)]
  [AspNetHostingPermission(SecurityAction.InheritanceDemand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  public class CustomButton : Button
  {
    public CustomButton()
    {
      this.Text = "Click Here";
    }
  }
}

<!-- A page that references the custom control. -->
<%@Page language="C#" %>
<!-- This directive does not require the assembly attribute 
     because the source file is in the App_Code directory, 
     so it gets dynamically compiled with the page. -->
<%@ Register TagPrefix="custom"  
    namespace="Samples.AspNet.CS.Controls" %>
    
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html>   
 <script runat="server">
     private void custButton_Click(Object sender, EventArgs e)
     {
       TextBox.BackColor = System.Drawing.Color.Green;
       TextBox.Text = "You clicked the button";
     }       
 </script>
 <body>      
    <form id="Form1" runat=server>
       Here is the custom button.<br>
       <custom:CustomButton runat="server" id="custButton" 
         onclick="custButton_Click" /> 
       <br>
       <br>
       <asp:TextBox id = "TextBox" Text="Click the button"
        Width = "200" BackColor="Cyan" runat="server" /> 
       <br>      
    </form>         
  </body>          
</html>

' A custom Button control to reference in the page.
Imports System
Imports System.Collections
Imports System.ComponentModel
Imports System.Drawing
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.Configuration
Imports System.Data.Sql
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Web.UI.WebControls.WebParts

Namespace Samples.AspNet.VB.Controls

  <AspNetHostingPermission(SecurityAction.Demand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  <AspNetHostingPermission(SecurityAction.InheritanceDemand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  Public Class CustomButton
    Inherits Button

    Public Sub New()
      Me.Text = "Click Here"
    End Sub

  End Class

End Namespace
<!-- A page that references the custom control. -->
<%@ Page Language="VB" %>
<!-- This directive does not require the assembly attribute 
     because the source file is in the App_Code directory, 
     so it gets dynamically compiled with the page. -->
<%@ Register TagPrefix="custom"
    namespace="Samples.AspNet.VB.Controls" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html>   
 <script runat="server">
   Sub custButton_Click(ByVal sender As Object, _
    ByVal e As EventArgs)
     TextBox.BackColor = Drawing.Color.Green
     TextBox.Text = "You clicked the button."
   End Sub
 </script>
 <body>      
    <form id="Form1" runat=server>
       Here is the custom button.<br>
       <custom:CustomButton runat="server" id="custButton" 
         onclick="custButton_Click" /> 
       <br>
       <br>
       <asp:TextBox id = "TextBox" Text="Click the button"
        Width = "200" BackColor="Cyan" runat="server" /> 
       <br>      
    </form>         
  </body>          
</html>

Siehe auch

Konzepte

ASP.NET Web Page Syntax Overview

Share via