Exemplarische Vorgehensweise: Entwickeln und Verwenden eines benutzerdefinierten Serversteuerelements

Artikel
08/20/2008

Aktualisiert: November 2007

Diese exemplarische Vorgehensweise erläutert, wie Sie ein benutzerdefiniertes ASP.NET-Serversteuerelement erstellen, kompilieren und in einer Seite verwenden.

Im Rahmen dieser exemplarischen Vorgehensweise erhalten Sie Informationen zu folgenden Vorgängen:

Erstellen eines ASP.NET-Serversteuerelements.
Hinzufügen von Metadaten zum Steuerelement und zu seinen Membern, um die Sicherheit und das Entwurfszeitverhalten zu kontrollieren.
Verwenden des Verzeichnisses App_Code in einer ASP.NET-Website, um das Steuerelement ohne manuelle Kompilierungsschritte zu testen.
Angeben eines Tagpräfixes in einer Konfigurationsdatei und in der Assembly des Steuerelements.
Kompilieren des Steuerelements in eine Assembly und Hinzufügen des Steuerelements zum Verzeichnis Bin.
Einbetten einer Bitmap in die Assembly des Steuerelements als Toolboxsymbol für einen visuellen Designer.
Verwenden des kompilierten Steuerelement in einer Seite.

Ein visuelles Entwurfstool wie Microsoft Visual Studio 2005 vereinfacht die Steuerelemententwicklung, ist aber nicht Voraussetzung für das Schreiben und Erstellen von benutzerdefinierten Steuerelementen. Sie können Steuerelemente mit einem beliebigen Text-Editor schreiben und über die Befehlszeile mit den Compilern erstellen, die mit dem Windows Software Development Kit (SDK) bereitgestellt werden. Die Darstellung zur Entwurfszeit und das Verhalten in einem visuellen Designer sind unabhängig davon, wie Sie das Steuerelement erstellt haben. Der Entwickler einer Seite kann Ihr Steuerelement der Toolbox des visuellen Designers hinzufügen, es auf die Entwurfsoberfläche ziehen und im Eigenschaftenbrowser auf die Eigenschaften und Ereignisse des Steuerelements zugreifen. In einigen visuellen Designern, z. B. Visual Studio 2005, verfügt ein benutzerdefiniertes Steuerelement automatisch auch über IntelliSense-Unterstützung.

Erstellen des Serversteuerelements

Das Steuerelement, das Sie im Folgenden erstellen, WelcomeLabel, ist ein einfaches Steuerelement, das dem Label-Standardsteuerelement ähnelt. Die WelcomeLabel-Klasse ist von WebControl abgeleitet und definiert eine Text-Eigenschaft, mit der ein Seitenentwickler eine Textzeichenfolge bereitstellen kann, um den Benutzer auf der Site willkommen zu heißen. Falls der Benutzername im Header vorhanden ist, der vom Browser des Benutzers gesendet wird, hängt WelcomeLabel den Namen des Benutzers an die Textzeichenfolge an. Weitere Informationen über das Abrufen des Benutzernamens finden Sie unter User. Wenn der Entwickler der Seite z. B. "Hello" als Wert der Text-Eigenschaft festlegt, rendert WelcomeLabel die Textzeichenfolge "Hello, Benutzername!" oder "Hello!", je nachdem, ob der Benutzername im Header vorhanden ist oder nicht.

So erstellen Sie den Code für das benutzerdefinierte Serversteuerelement

Erstellen Sie eine Datei mit dem Namen WelcomeLabel.cs bzw. WelcomeLabel.vb.

Fügen Sie der Quelldatei des Steuerelements folgenden Code hinzu:

' WelcomeLabel.vb
Option Strict On
Imports System
Imports System.ComponentModel
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("Text"), _
    ToolboxData( _
        "<{0}:WelcomeLabel runat=""server""> </{0}:WelcomeLabel>") _
    > _
    Public Class WelcomeLabel
        Inherits WebControl
        < _
        Bindable(True), _
        Category("Appearance"), _
        DefaultValue(""), _
        Description("The welcome message text."), _
        Localizable(True) _
        > _
        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 Sub RenderContents( _
            ByVal writer As HtmlTextWriter)
            writer.WriteEncodedText(Text)
            If Context IsNot Nothing Then
                Dim s As String = Context.User.Identity.Name
                If (s IsNot Nothing) AndAlso (s <> String.Empty) Then
                    Dim split() As String = s.Split("\".ToCharArray)
                    Dim n As Integer = split.Length - 1
                    If (split(n) <> String.Empty) Then
                        writer.Write(", ")
                        writer.Write(split(n))
                    End If
                End If
            End If
            writer.Write("!")
        End Sub
    End Class
End Namespace

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

        protected override void RenderContents(HtmlTextWriter writer)
        {
            writer.WriteEncodedText(Text);
            if (Context != null)
            {
                string s = Context.User.Identity.Name;
                if (s != null && s != String.Empty)
                {
                    string[] split = s.Split('\\');
                    int n = split.Length - 1;
                    if (split[n] != String.Empty)
                    {
                        writer.Write(", ");
                        writer.Write(split[n]);
                    }
                }
            }
            writer.Write("!");
        }
    }
}

Codeerläuterung

Die folgende Codeerläuterung ist für die Ausführung der Schritte in dieser exemplarischen Vorgehensweise nicht erforderlich und kann anfangs übersprungen werden. Wenn Sie mit dem Erstellen von Steuerelementen noch wenig Erfahrung haben, sollten Sie die Erläuterung jedoch zumindest lesen, nachdem Sie die exemplarische Vorgehensweise abgeschlossen haben.

Wenn das Steuerelement ein Element der Benutzeroberfläche (UI) oder ein anderes auf dem Client sichtbares Element rendert, sollten Sie das Steuerelement von System.Web.UI.WebControls.WebControl (oder einer davon abgeleiteten Klasse) ableiten. Falls das Steuerelement ein Element rendert, das im Clientbrowser nicht sichtbar ist, z. B. ein ausgeblendetes Element oder ein meta-Element, leiten Sie das Steuerelement von System.Web.UI.Control ab. Die WebControl-Klasse ist von Control abgeleitet und fügt formatbezogene Eigenschaften hinzu, z. B. Font, ForeColor und BackColor. Zusätzlich kann ein von WebControl abgeleitetes Steuerelement die Designfeatures von ASP.NET nutzen, ohne dass für Sie zusätzliche Arbeit entsteht.

Wenn das Steuerelement die Funktionalität eines bestehenden Steuerelements (z. B. des Button-Steuerelements, des Label-Steuerelements oder des Image-Steuerelements) erweitert, können Sie es von diesem Steuerelement ableiten. Da WelcomeLabel die Funktionalität des Label-Steuerelements erweitert, liegt es nahe, es von Label abzuleiten. In dieser exemplarische Vorgehensweise wird WelcomeLabel jedoch von WebControl abgeleitet, um die Definition einer Eigenschaft und die Definition von Metadateneigenschaften zu veranschaulichen.

WelcomeLabel definiert genau eine Eigenschaft, Text, und verwendet den Ansichtszustand, um den Eigenschaftenwert zu speichern. Durch das Verwenden des Ansichtszustands wird der Wert von Text über Postbacks hinweg beibehalten. Bei jedem Postback wird die Seite neu erstellt, und die Werte werden aus dem Ansichtszustand wiederhergestellt. Wenn der Text-Wert nicht im Ansichtszustand gespeichert wird, wird er bei jedem Postback auf seinen Standardwert, Empty, festgelegt. Die von WebControl geerbte ViewState-Eigenschaft ist ein Wörterbuch, das Datenwerte speichert. Die Werte werden unter Verwendung eines String-Schlüssels eingegeben und abgerufen. In diesem Fall wird "Text" als Schlüssel verwendet. Die Elemente im Wörterbuch werden als Object eingegeben und müssen dann in den Eigenschaftentyp umgewandelt werden. Weitere Informationen finden Sie unter Übersicht über die ASP.NET-Zustandsverwaltung.

Das WelcomeLabel-Steuerelement rendert seine Text-Eigenschaft, indem es die geerbte RenderContents-Methode überschreibt. Der Parameter, der an die RenderContents-Methode übergeben wird, ist ein Objekt vom Typ HtmlTextWriter. Dieser Typ ist eine Dienstprogrammklasse, die über Methoden zum Rendern von Tags und anderem HTML-Markup (und Markup von HTML-Varianten) verfügt.

Beachten Sie, dass WelcomeLabel aufeinander folgende Aufrufe an die Write-Methode des HtmlTextWriter-Objekts macht, anstatt eine Zeichenfolgenverkettung durchzuführen und dann die Write-Methode aufzurufen. Dies verbessert die Leistung, da das HtmlTextWriter-Objekt direkt in den Ausgabestream schreibt. Eine Zeichenfolgenverkettung benötigt Zeit und Arbeitsspeicher, um die Zeichenfolge zu erstellen, und schreibt erst dann in den Stream. Wenn Sie in den Steuerelementen Rendering implementieren, sollten Sie dem in dieser exemplarischen Vorgehensweise dargestellten Muster folgen.

Hinweis:
Wenn das Steuerelement von WebControl abgeleitet ist und ein einzelnes Element rendert, sollten Sie im Allgemeinen die RenderContents-Methode (und nicht die Render-Methode) überschreiben, um den Inhalt zwischen den Steuerelementtags zu rendern. Die Render-Methode von WebControl ruft RenderContents auf, nachdem sie das Starttag für das Steuerelement und seine Formatattribute gerendert hat. Wenn Sie die Render-Methode überschreiben, um den Inhalt zu schreiben, verliert das Steuerelement die Logik für das Formatrendering, die in der Render-Methode von WebControl enthalten ist. Weitere Informationen über das Rendern eines Steuerelements, das von WebControl abgeleitet ist, finden Sie unter Beispiel für das Rendering eines Webserversteuerelements.

Wenn das Steuerelement von WebControl abgeleitet ist und ein einzelnes Element rendert, sollten Sie im Allgemeinen die RenderContents-Methode (und nicht die Render-Methode) überschreiben, um den Inhalt zwischen den Steuerelementtags zu rendern. Die Render-Methode von WebControl ruft RenderContents auf, nachdem sie das Starttag für das Steuerelement und seine Formatattribute gerendert hat. Wenn Sie die Render-Methode überschreiben, um den Inhalt zu schreiben, verliert das Steuerelement die Logik für das Formatrendering, die in der Render-Methode von WebControl enthalten ist. Weitere Informationen über das Rendern eines Steuerelements, das von WebControl abgeleitet ist, finden Sie unter Beispiel für das Rendering eines Webserversteuerelements.

Die auf WelcomeLabel angewendeten Attribute enthalten Metadaten, die von der Common Language Runtime und von Entwurfszeittools verwendet werden.

Auf Klassenebene wird WelcomeLabel mit den folgenden Attributen gekennzeichnet:

AspNetHostingPermissionAttribute ist ein Attribut für die Codezugriffssicherheit. Dieses Attribut bewirkt, dass der JIT-Compiler nachprüft, ob der mit WelcomeLabel verknüpfte Code die AspNetHostingPermission-Berechtigung besitzt. Alle öffentlichen ASP.NET-Klassen sind mit diesem Attribut gekennzeichnet. Sie sollten AspNetHostingPermissionAttribute auf Ihre Steuerelemente anwenden, und zwar als Sicherheitsüberprüfung gegen teilweise vertrauenswürdige Aufrufer.
DefaultPropertyAttribute ist ein Entwurfszeitattribut, das die Standardeigenschaft eines Steuerelements angibt. In den meisten visuellen Designern hebt der Eigenschaftenbrowser die Standardeigenschaft hervor, wenn Sie auf der Entwurfsoberfläche auf das Steuerelement klicken.
ToolboxDataAttribute gibt die Formatzeichenfolge für das Element an. Die Zeichenfolge wird zum Markup des Steuerelements, wenn in der Toolbox auf das Steuerelement doppelgeklickt wird oder es von der Toolbox auf die Entwurfsoberfläche gezogen wird. Die Zeichenfolge erstellt für WelcomeLabel dieses Element:
```
<aspSample:WelcomeLabel > </aspSample:WelcomeLabel>
```

Das WelcomeLabel-Steuerelement erbt auch zwei Attribute von der WebControl-Basisklasse, ParseChildrenAttribute und PersistChildrenAttribute. Sie werden als ParseChildren(true) und PersistChildren(false) angewendet. Diese zwei Attribute arbeiten untereinander und auch mit dem ToolboxDataAttribute-Attribut zusammen, sodass untergeordnete Elemente als Eigenschaften interpretiert werden und Eigenschaften als Attribute beibehalten werden.

Die folgenden Attribute, angewendet auf die Text-Eigenschaft von WelcomeLabel, sind standardmäßige Entwurfszeitattribute, die Sie in der Regel auf alle öffentlichen Eigenschaften der Steuerelemente anwenden:

BindableAttribute, auf true oder false festgelegt, gibt für visuelle Designer an, ob es sinnvoll ist, die Eigenschaft an Daten zu binden. Wenn zum Beispiel in Visual Studio 2005 eine Eigenschaft mit Bindable(true) gekennzeichnet ist, wird die Eigenschaft im Dialogfeld DataBindings angezeigt. Wenn eine Eigenschaft nicht mit diesem Attribut gekennzeichnet ist, geht der Eigenschaftenbrowser vom Wert Bindable(false) aus.
CategoryAttribute gibt an, wie die Eigenschaft im Eigenschaftenbrowser des visuellen Designers kategorisiert werden soll. Category("Appearance") teilt dem Eigenschaftenbrowser z. B. mit, dass die Eigenschaft in der Kategorie Darstellung angezeigt werden soll, wenn der Seitenentwickler die Kategorieansicht des Eigenschaftenbrowsers verwendet. Sie können ein Zeichenfolgenargument angeben, das einer vorhandenen Kategorie im Eigenschaftenbrowser entspricht, oder eine eigene Kategorie erstellen.
DescriptionAttribute enthält eine kurze Beschreibung der Eigenschaft. In Visual Studio 2005 zeigt der Eigenschaftenbrowser die Beschreibung der ausgewählten Eigenschaft am unteren Rand des Eigenschaftenfensters an.
DefaultValueAttribute legt einen Standardwert für die Eigenschaft fest. Dieser Wert sollte mit dem Standardwert identisch sein, der vom Eigenschaftenaccessor (Getter) zurückgegeben wird. In Visual Studio 2005 kann der Entwickler einer Seite mit DefaultValueAttribute einen Eigenschaftenwert auf den Standardwert zurücksetzen, indem er im Eigenschaftenfenster das entsprechende Kontextmenü aufruft und auf die Schaltfläche Zurücksetzen klickt.

LocalizableAttribute, auf true oder false festgelegt, gibt für visuelle Designer an, ob es sinnvoll ist, die Eigenschaft zu lokalisieren. Wenn eine Eigenschaft als Localizable(true) gekennzeichnet ist, schließt der visuelle Designer sie in die Serialisierung lokalisierter Ressourcen ein. Der Designer übernimmt den Eigenschaftenwert in eine kulturneutrale Ressourcendatei oder eine andere Lokalisierungsquelle, wenn das Steuerelement auf lokalisierbare Eigenschaften hin abgefragt wird.

Hinweis:
Sie können LocalizableAttribute in den ASP.NET-Versionen 1.0 und 1.1 aufgrund des anderen ASP.NET-Lokalisierungsmodells nicht auf ein benutzerdefiniertes Serversteuerelement anwenden.

Entwurfszeitattribute, die auf ein Steuerelement und dessen Member angewendet werden, wirken sich zur Laufzeit nicht auf die Funktionsweise des Steuerelements aus, verbessern aber die Programmierung, wenn das Steuerelement in einem visuellen Designer verwendet wird. Sie finden eine vollständige Auflistung der Entwurfszeitattribute, Analysezeitattribute und Laufzeitattribute für Serversteuerelemente unter Metadatenattribute für benutzerdefinierte Serversteuerelemente.

Verwenden des Verzeichnisses App_Code, um Steuerelemente ohne Kompilierung zu testen

Sie können das dynamische Kompilierungsfeature von ASP.NET verwenden, um das Steuerelement in der Seite zu testen, ohne es in eine Assembly zu kompilieren. Code im Verzeichnis App_Code unter dem Stammverzeichnis einer ASP.NET-Website wird von ASP.NET dynamisch kompiliert. Klassen in Quelldateien, die im Verzeichnis App_Code liegen, müssen also nicht erst manuell in Assemblys kompiliert werden – der Zugriff von Seiten auf diese Klassen ist auch so möglich. Wenn Sie die Quelldateien für Ihre Steuerelemente in das Verzeichnis App_Code legen, werden die am Code der Steuerelemente vorgenommenen Änderungen sofort in den Seiten wiedergegeben, die diese Steuerelemente verwenden.

Hinweis:
Das Verzeichnis App_Code ist ein neues Feature, das es in ASP.NET 1.0 und 1.1 noch nicht gab. Das Verwenden des Verzeichnisses App_Code für das erste Testen des Steuerelements ist optional. Die Hauptschritte beim Erstellen eines Serversteuerelements sind dieselben wie in früheren Versionen, wie Sie im nächsten Abschnitt, "Kompilieren des Steuerelements in eine Assembly", sehen werden.

So erstellen Sie die ASP.NET-Website und das Verzeichnis App_Code

Erstellen Sie eine Website mit dem Namen ServerControlsTest. Sie können die Site in IIS als virtuelles Verzeichnis mit dem Namen ServerControlsTest erstellen. Ausführliche Informationen zur Erstellung und Konfiguration eines virtuellen IIS-Verzeichnisses finden Sie unter Gewusst wie: Erstellen und Konfigurieren von virtuellen Verzeichnissen in IIS 5.0 und 6.0.
Erstellen Sie direkt unter dem Stammverzeichnis Ihrer Website (auch Webanwendungsstammverzeichnis genannt) das Verzeichnis App_Code.
Kopieren Sie die Quelldatei für das Steuerelement (WelcomeLabel.cs oder WelcomeLabel.vb) in das Verzeichnis App_Code.

Erstellen eines Tagpräfixes

Ein Tagpräfix ist das Präfix, z. B. "asp" in <asp:Table />, das vor dem Typnamen des Steuerelements angezeigt wird, wenn das Steuerelement in einer Seite deklarativ erstellt wird. Damit ein Steuerelement in einer Seite deklarativ verwendet werden kann, benötigt ASP.NET ein Tagpräfix, das dem Namespace des Steuerelements zugeordnet ist. Der Entwickler einer Seite kann eine Tagpräfix-Namespace-Zuordnung bereitstellen, indem er auf jeder Seite, die das benutzerdefinierte Steuerelement verwendet, eine @ Register-Direktive hinzufügt, wie in folgendem Beispiel gezeigt:

<%@ Register TagPrefix="aspSample" 
        Namespace="Samples.AspNet.CS.Controls"%>

[Visual Basic]

<%@ Register TagPrefix="aspSample" 
        Namespace="Samples.AspNet.VB.Controls"%>

Hinweis:
Die @ Register-Direktive wurde in ASP.NET 2.0 gegenüber ASP.NET 1.0 und ASP.NET 1.1 nicht geändert. Wenn Sie mit der Register-Direktive in früheren Versionen von ASP.NET vertraut sind, werden Sie möglicherweise feststellen, dass das assembly-Attribut, das den Namen der Steuerelementassembly angibt, in der vorhergehenden Register-Direktive fehlt. Wenn das assembly-Attribut fehlt, geht ASP.NET davon aus, dass die Assembly aus Quelldateien im Verzeichnis App_Code dynamisch kompiliert wird.

Die @ Register-Direktive wurde in ASP.NET 2.0 gegenüber ASP.NET 1.0 und ASP.NET 1.1 nicht geändert. Wenn Sie mit der Register-Direktive in früheren Versionen von ASP.NET vertraut sind, werden Sie möglicherweise feststellen, dass das assembly-Attribut, das den Namen der Steuerelementassembly angibt, in der vorhergehenden Register-Direktive fehlt. Wenn das assembly-Attribut fehlt, geht ASP.NET davon aus, dass die Assembly aus Quelldateien im Verzeichnis App_Code dynamisch kompiliert wird.

Als Alternative zur Verwendung der @ Register-Direktive in jeder ASPX-Seite kann der Seitenentwickler in der Datei Web.config die Tagpräfix-Namespace-Zuordnung angeben. Dies ist nützlich, wenn das benutzerdefinierte Steuerelement in mehreren Seiten einer Webanwendung verwendet wird. Die folgende Prozedur beschreibt, wie die Tagpräfixzuordnung in der Datei Web.config angegeben wird.

So fügen Sie in der Datei Web.config eine Tagpräfixzuordnung hinzu

Erstellen Sie unter dem Stammverzeichnis der Website eine Textdatei mit dem Namen Web.config, falls diese Datei nicht bereits vorhanden ist.

Falls Sie eine neue (leere) Datei Web.config erstellt haben, kopieren Sie den folgenden Code in die Datei. Speichern Sie die Datei anschließend.

<?xml version="1.0"?>
<configuration>
  <system.web>    
   <pages>
     <controls>
       <add tagPrefix="aspSample"            namespace="Samples.AspNet.CS.Controls">       </add>
     </controls>
   </pages>
  </system.web>
</configuration>

<?xml version="1.0"?>
<configuration>
  <system.web>    
   <pages>
     <controls>
       <add tagPrefix="aspSample"            namespace="Samples.AspNet.VB.Controls">       </add>
     </controls>
   </pages>
  </system.web>
</configuration>

Der hervorgehobene Abschnitt zeigt einen Tagpräfixeintrag, der das Tagpräfix "aspSample" dem Namespace Samples.AspNet.CS.Controls oder Samples.AspNet.VB.Controls zuordnet.

Fügen Sie der Konfigurationsdatei den hervorgehobenen Text aus dem vorigen Schritt als untergeordnetes Element des controls-Elements hinzu, falls die Datei Web.config bereits vorhanden ist. Wenn in der Datei Web.config das controls-Element und das pages-Element noch nicht existieren, erstellen Sie diese Elemente, wie im vorigen Schritt gezeigt.

Hinweis:

Der Tagpräfixeintrag muss dem controls-Abschnitt untergeordnet sein, der sich unter dem pages-Abschnitt befindet, welcher wiederum system.web untergeordnet sein muss.

Hinweis:
Der Tagpräfixeintrag muss dem controls-Abschnitt untergeordnet sein, der sich unter dem pages-Abschnitt befindet, welcher wiederum system.web untergeordnet sein muss.

Nachdem Sie in der Konfigurationsdatei eine Tagpräfixzuordnung angegeben haben, können Sie das WelcomeLabel-Steuerelement deklarativ (als <aspSample:WelcomeLabel />) in jeder Seite Ihrer Website verwenden.

Hinweis:
Ein Konfigurationseintrag für das Tagpräfix ist ein neues Feature in ASP.NET 2.0. In ASP.NET 1.0 und 1.1 musste die Tagpräfixzuordnung in der @ Register-Direktive jeder einzelnen Seite angegeben werden, in der das benutzerdefinierte Steuerelement verwendet wurde.

Erstellen einer Seite, die das Steuerelement verwendet

So erstellen Sie eine Seite, die das benutzerdefinierte Steuerelement verwendet

Erstellen Sie in der Website eine Textdatei mit dem Namen WelcomeLabelTest.aspx.

Kopieren Sie das folgende Markup in die Datei WelcomeLabelTest.aspx, und speichern Sie die Datei.

<%@ 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>WelcomeLabel Test</title>
  </head>
  <body>
    <form id="form1" >
      <div>
        <aspSample:WelcomeLabel Text="Hello" ID="WelcomeLabel1" 
           BackColor="Wheat" ForeColor="SaddleBrown" />
      </div>
    </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>WelcomeLabel Test</title>
  </head>
  <body>
    <form id="form1" >
      <div>
        <aspSample:WelcomeLabel Text="Hello" ID="WelcomeLabel1" 
           BackColor="Wheat" ForeColor="SaddleBrown" />
      </div>
    </form>
  </body>
</html>

Zeigen Sie WelcomeLabelTest.aspx im Browser an, indem Sie die folgende URL in die Adressleiste eingeben:
```
https://localhost/ServerControlsTest/WelcomeLabelTest.aspx
```
Nehmen Sie einige Änderungen am Quellcode des Steuerelements vor. Schreiben Sie zum Beispiel eine zusätzliche Zeichenfolge, indem Sie am Ende der RenderContents-Methode diese Codezeile hinzufügen:
```
writer.Write("Testing how the App_Code directory works.");
```
```
writer.Write("Testing how the App_Code directory works.")
```
Aktualisieren Sie die Seite WelcomeLabelTest.aspx im Browser.

Sie werden sehen, dass die am Steuerelement vorgenommenen Änderungen in der Seite widergespiegelt werden, obwohl Sie das Steuerelement nicht kompiliert haben.

Zusätzlich zur von Ihnen explizit definierten Text-Eigenschaft besitzt die in der Seite angezeigte Instanz des WelcomeLabel-Steuerelements die BackColor-Eigenschaft und die ForeColor-Eigenschaft, die Sie nicht definiert haben. Das WelcomeLabel-Steuerelement erhält diese und andere formatbezogene Eigenschaften durch Vererbung von der WebControl-Basisklasse. Außerdem kann WelcomeLabel ein Design (skin) zugewiesen werden, und es kann Teil eines Designs (theme) sein, ohne dass Sie dies speziell ermöglichen müssen.

Kompilieren des Steuerelements in eine Assembly

Obwohl Sie das Steuerelement mithilfe des Verzeichnisses App_Code ohne Kompilieren testen können, müssen Sie das Steuerelement kompilieren, wenn Sie es als Objektcode an andere Entwickler verteilen möchten. Außerdem können Sie ein Steuerelement erst dann der Toolbox eines visuellen Designers hinzufügen, wenn es in eine Assembly kompiliert wurde.

So kompilieren Sie das Steuerelement in eine Assembly

Legen Sie die Windows-Umgebungsvariable PATH auf Ihrem Computers so fest, dass Sie den Pfad zur .NET Framework-Installation beinhaltet. Führen Sie dazu folgende Schritte aus:
1. Klicken Sie in Windows mit der rechten Maustaste auf Arbeitsplatz. Klicken Sie im Kontextmenü auf Eigenschaften, dann auf die Registerkarte Erweitert und anschließend auf die Schaltfläche Umgebungsvariablen.
2. Doppelklicken Sie in der Liste Systemvariablen auf die Path-Variable.
3. Fügen Sie in dem Textfeld Wert der Variablen am Ende der in dem Textfeld vorhandenen Werte ein Semikolon (;) ein, und geben Sie dann den Pfad Ihrer .NET Framework-Installation ein. .NET Framework wird normalerweise im Windows-Installationsverzeichnis unter \Microsoft.NET\Framework\Versionsnummer installiert.
4. Klicken Sie jeweils auf OK, um die Dialogfelder zu schließen.
Führen Sie den folgenden Befehl aus dem Verzeichnis heraus aus, das Sie in der ersten Prozedur dieser exemplarischen Vorgehensweise für Quelldateien erstellt haben.

Hinweis:

Dabei handelt es sich nicht um das Verzeichnis App_Code, in das Sie die Quelldatei des Steuerelements zum Testen kopiert haben.
```
csc /t:library /out:Samples.AspNet.CS.Controls.dll /r:System.dll /r:System.Web.dll *.cs
```
```
vbc /t:library /out:Samples.AspNet.VB.Controls.dll /r:System.dll /r:System.Web.dll *.vb
```
Aufgrund der /t:library-Compileroption erstellt der Compiler eine Bibliothek anstelle einer ausführbaren Assembly. Die /out-Option stellt einen Namen für die Assembly bereit, und die /r-Option listet die Assemblys auf, die mit Ihrer Assembly verknüpft werden.

Hinweis:
Dabei handelt es sich nicht um das Verzeichnis App_Code, in das Sie die Quelldatei des Steuerelements zum Testen kopiert haben.

Um das Beispiel in sich abgeschlossen zu halten, wird in dieser exemplarischen Vorgehensweise eine Assembly mit nur einem Steuerelement erstellt. Im Allgemeinen empfehlen die .NET Framework-Entwurfsrichtlinien, keine Assemblys zu erstellen, die nur wenige Klassen enthalten. Um die Bereitstellung zu erleichtern, sollten Sie so wenige Assemblys wie möglich erstellen.

Einbetten eines Symbols in die Steuerelementassembly

Ein visueller Designer, z. B. Visual Studio 2005, verfügt in der Regel über ein Standardsymbol (z. B. das Bild eines Zahnrads), um ein Steuerelement in der Toolbox anzuzeigen. Sie können die Darstellung des Steuerelements in der Toolbox anpassen, indem Sie eine Bitmap mit 16 × 16 Pixeln in die Assembly des Steuerelements einbetten. Visuelle Designer verwenden konventionsgemäß das linke untere Pixel der Bitmap als transparente Farbe.

So betten Sie ein Symbol in die Assembly des Steuerelements ein

Erstellen Sie eine Bitmap mit 16 × 16 Pixeln, die Sie als Toolboxsymbol für das Steuerelement verwenden möchten.
Nennen Sie die Bitmap WelcomeLabel.bmp.
Fügen Sie die Bitmapdatei dem Verzeichnis hinzu, in dem sich die Quelldateien für das WelcomeLabel-Steuerelement befinden (CustomControlsCS oder CustomControlsVB).
Führen Sie den folgenden Befehl aus dem Verzeichnis heraus aus, das die Quelldateien enthält:
```
csc /res:WelcomeLabel.bmp,Samples.AspNet.CS.Controls.WelcomeLabel.bmp 
/t:library /out:Samples.AspNet.CS.Controls.dll /r:System.dll 
/r:System.Web.dll *.cs
```
```
vbc /res:WelcomeLabel.bmp,Samples.AspNet.VB.Controls.WelcomeLabel.bmp 
/t:library /out:Samples.AspNet.VB.Controls.dll /r:System.dll 
/r:System.Web.dll *.vb
```
Dieser Befehl kompiliert das Steuerelement und bettet die Bitmap als Ressource in die Assembly ein. Der Name der eingebetteten Bitmapressource muss exakt dem namespacequalifizierten Namen des Steuerelements entsprechen, mit dem sie verknüpft ist. Wenn der Name des Steuerelements z. B. Samples.AspNet.CS.Controls.WelcomeLabel ist, muss der Name der eingebetteten Bitmap Samples.AspNet.CS.Controls.WelcomeLabel.bmp sein. Diese Namenskonvention bewirkt, dass ein visueller Designer die Bitmap automatisch als Toolboxsymbol des Steuerelements verwendet. Wenn Sie die Namenskonvention nicht verwenden, müssen Sie ToolboxBitmapAttribute auf das Steuerelement anwenden, um den Namen der eingebetteten Bitmapressource anzugeben.

Verwenden von TagPrefixAttribute, um eine Tagpräfix-Namespace-Zuordnung bereitzustellen

In dieser exemplarischen Vorgehensweise wurde im Zusammenhang mit der Verwendung des Verzeichnisses App_Code bereits erläutert, wie ein Seitenentwickler ein Tagpräfix in der Seite oder in der Datei Web.config angeben kann. Sie können optional ein Standardpräfixtag vorschlagen, das ein visueller Designer für das Steuerelement verwenden soll, indem Sie das assemblyweit gültige System.Web.UI.TagPrefixAttribute-Attribut hinzufügen. Das TagPrefixAttribute-Attribut ist nützlich, da es einem visuellen Designer ein Tagpräfix für den Fall bereitstellt, dass in der Datei Web.config oder in einer Register-Direktive in der Seite keine Tagpräfixzuordnung vorhanden ist. Das Tagpräfix wird mit der Seite registriert, wenn in der Toolbox erstmals auf das Steuerelement doppelgeklickt wird oder das Steuerelement erstmals von der Toolbox auf die Seite gezogen wird.

Wenn Sie sich entscheiden, das TagPrefixAttribute-Attribut zu verwenden, können Sie es in einer getrennten Datei angeben, die mit dem Steuerelement kompiliert wird. Die Datei hat konventionsgemäß den Namen AssemblyInfo.Spracherweiterung, z. B. AssemblyInfo.cs oder AssemblyInfo.vb. Im folgenden Verfahren wird beschrieben, wie Sie die TagPrefixAttribute-Metadaten angeben.

Hinweis:
Wenn Sie in der Assembly des Steuerelements das TagPrefixAttribute nicht angeben und der Seitenentwickler weder in der Seite noch in der Datei Web.config die Tagpräfix-Namespace-Zuordnung angibt, erstellt der visuelle Designer möglicherweise ein Standardtagpräfix. So erstellt Visual Studio 2005 beispielsweise ein eigenes Tag (wie cc1) für das Steuerelement, sobald das Steuerelement aus der Toolbox gezogen wird.

Wenn Sie in der Assembly des Steuerelements das TagPrefixAttribute nicht angeben und der Seitenentwickler weder in der Seite noch in der Datei Web.config die Tagpräfix-Namespace-Zuordnung angibt, erstellt der visuelle Designer möglicherweise ein Standardtagpräfix. So erstellt Visual Studio 2005 beispielsweise ein eigenes Tag (wie cc1) für das Steuerelement, sobald das Steuerelement aus der Toolbox gezogen wird.

So fügen Sie mit TagPrefixAttribute eine Namespace-Tagpräfix-Zuordnung hinzu

Erstellen Sie im Quellcodeverzeichnis eine Datei mit dem Namen AssemblyInfo.cs bzw. AssemblyInfo.vb, und fügen Sie der Datei den folgenden Code hinzu:
```
using System;
using System.Web.UI;
[assembly: TagPrefix("Samples.AspNet.CS.Controls", "aspSample")]
```
```
Imports System
Imports System.Web.UI
<Assembly: TagPrefix("Samples.AspNet.VB.Controls", "aspSample")> 
```
Das Tagpräfixattribut erstellt eine Zuordnung zwischen dem Namespace Samples.AspNet.CS.Controls bzw. Samples.AspNet.VB.Controls und dem Präfix aspSample.
Kompilieren Sie erneut alle Quelldateien mit dem Kompilierungsbefehl, den Sie bereits zuvor (mit oder ohne der eingebetteten Ressource) verwendet haben.

Verwenden des kompilierten benutzerdefinierten Steuerelements in einer ASP.NET-Seite

Um die kompilierte Version Ihres benutzerdefinierten Steuerelements zu testen, müssen Sie den Seiten in der Website den Zugriff auf die Steuerelementassembly ermöglichen.

So machen Sie der Website die Steuerelementassembly zugänglich

Erstellen Sie unter dem Stammverzeichnis der Website das Verzeichnis Bin.
Kopieren Sie die Steuerelementassembly (Samples.AspNet.CS.Controls.dll bzw. Samples.AspNet.VB.Controls.dll) in das Verzeichnis Bin.
Löschen Sie die Quelldatei des Steuerelements aus dem Verzeichnis App_Code.

Wenn Sie die Quelldateien nicht löschen, besteht der Steuerelementtyp sowohl aus der kompilierten Assembly als auch aus der von ASP.NET dynamisch generierten Assembly. Dadurch entsteht beim Laden des Steuerelements ein mehrdeutiger Verweis, und alle Seiten, in denen das Steuerelement verwendet wird, generieren einen Compilerfehler.

Die von Ihnen in dieser exemplarischen Vorgehensweise erstellte Assembly wird als private Assembly bezeichnet, weil sie in das Verzeichnis Bin einer ASP.NET Website platziert werden muss, damit die Seiten in der Website das Steuerelement verwenden können. Von anderen Anwendungen aus kann nicht auf die Assembly zugegriffen werden, außer Sie fügen diesen Anwendungen eine Kopie der Assembly hinzu. Wenn Sie Steuerelemente für freigegebene Webhostinganwendungen erstellen, packen Sie die Steuerelemente i. d. R. in einer privaten Assembly zusammen. Wenn Sie jedoch Steuerelemente für die Verwendung in einer dedizierten Hostingumgebung erstellen oder wenn Sie eine Gruppe von Steuerelementen erstellen, die ein Internetanbieter allen seinen Kunden bereitstellt, müssen Sie die Steuerelemente i. d. R. in einer freigegebenen Assembly (mit starkem Namen) zusammenpacken, die im globalen Assemblycache installiert wird. Weitere Informationen finden Sie unter Arbeiten mit Assemblys und dem globalen Assemblychache.

Danach müssen Sie die Tagpräfixzuordnung ändern, die Sie in der Datei Web.config erstellt haben, um den Namen der Steuerelementassembly anzugeben.

So ändern Sie in der Datei Web.config die Tagpräfixzuordnung

Fügen Sie in der Datei Web.config dem addtagPrefix-Element ein assembly-Attribut hinzu:

<controls>
  <add tagPrefix="aspSample"   
    namespace="Samples.AspNet.CS.Controls" 
    assembly="Samples.AspNet.CS.Controls">
  </add>
</controls>

<controls>
  <add tagPrefix="aspSample"   
    namespace="Samples.AspNet.VB.Controls" 
    assembly="Samples.AspNet.VB.Controls">
  </add>
</controls>

Das assembly-Attribut gibt den Namen der Assembly an, in der sich das Steuerelement befindet. Mit dem addtagPrefix-Element wird ein Tagpräfix einer Kombination aus Namespace und Assembly zugeordnet. Wenn ASP.NET die Assembly aus den Quelldateien im Verzeichnis App_Code dynamisch generiert, wird kein Assemblyattribut benötigt. Wenn das Assemblyattribut nicht verwendet wird, lädt ASP.NET den Steuerelementtyp aus den Assemblys, die aus dem Verzeichnis App_Code dynamisch generiert werden.

So zeigen Sie die Seite an, die das benutzerdefinierte Steuerelement verwendet

Zeigen Sie die Seite WelcomeLabelTest.aspx im Browser an, indem Sie folgende URL in die Adressleiste eingeben:
```
https://localhost/ServerControlsTest/WelcomeLabelTest.aspx
```

Wenn Sie das Steuerelement in einem visuellen Designer verwenden, z. B. Visual Studio 2005, können Sie das Steuerelement der Toolbox hinzufügen, es von der Toolbox auf die Entwurfsoberfläche ziehen und im Eigenschaftenbrowser auf die Eigenschaften und Ereignisse des Steuerelements zugreifen. In Visual Studio 2005 verfügt das Steuerelement in der Quellansicht des Seitendesigners und im Code-Editor außerdem über vollständige IntelliSense-Unterstützung. Dazu gehören sowohl die Anweisungsvervollständigung in einem script-Block als auch die Unterstützung für den Eigenschaftenbrowser, wenn ein Seitenentwickler auf das Tag des Steuerelements klickt.

Hinweis:
In vielen visuellen Designern können Sie der Toolbox des Designers benutzerdefinierte Steuerelemente hinzufügen. Ausführliche Informationen finden Sie in der Dokumentation zu Ihrem Designer.

Nächste Schritte

In dieser exemplarischen Vorgehensweise wurde gezeigt, wie Sie ein einfaches benutzerdefiniertes ASP.NET-Serversteuerelement entwickeln und in einer Seite verwenden können. Sie haben gesehen, wie eine Eigenschaft definiert wird und wie das Steuerelement in eine Assembly kompiliert wird. Weitere Informationen, einschließlich Informationen über Rendering, Definieren von Eigenschaften, Beibehalten des Zustands und Implementieren von zusammengesetzten Steuerelementen, finden Sie unter Entwickeln von benutzerdefinierten ASP.NET-Serversteuerelementen.

In dieser exemplarischen Vorgehensweise haben Sie gelernt, wie Sie ein benutzerdefiniertes Toolboxsymbol für das Steuerelement bereitstellen können. Sie haben außerdem erfahren, wie Sie Entwurfszeitmetadaten hinzufügen können, um die Eigenschaftenbrowserunterstützung für das Steuerelement anzupassen. Komplexe Steuerelemente, z. B. das GridView-Steuerelement, vereinfachen das Arbeiten zur Entwurfszeit, indem sie visuelle Designerklassen verwenden, die zur Entwurfszeit und zur Laufzeit unterschiedliche Benutzeroberflächen bereitstellen. Das Objektmodell von ASP.NET 2.0 für Serversteuerelemente unterscheidet sich deutlich von dem Modell, das in ASP.NET 1.0 und 1.1 bereitgestellt wurde. Weitere Informationen über das Implementieren von benutzerdefinierten Designerklassen für Steuerelemente in ASP.NET 2.0 finden Sie unter Übersicht über ASP.NET-Steuerelement-Designer.

Mit den Adapterklassen von ASP.NET 2.0 können Sie ein unterschiedliches Verhalten des Serversteuerelements für verschiedene Clientbrowser bzw. Clientgeräte definieren. Weitere Informationen finden Sie unter Entwickeln von Adaptern für ASP.NET-Serversteuerelemente.

Unterschiedliche Browser und die verschiedenen Versionen der Browser unterstützen jeweils unterschiedliche Features. ASP.NET-Serversteuerelemente bestimmen automatisch den Browser, von dem die ASPX-Seite angefordert wurde, und passen das generierte HTML-Markup automatisch an das für diesen Browser geeignete Format an. Einige Steuerelementfeatures können jedoch von älteren Browsern nicht gerendert werden. Daher empfiehlt es sich, die Ausgabe der Seiten für möglichst viele Browsertypen zu überprüfen, um sicherzustellen, dass die Seiten von allen Browsern wie gewünscht dargestellt werden. Weitere Informationen finden Sie unter ASP.NET-Webserversteuerelemente und Browserfunktionen.

Siehe auch

Weitere Ressourcen

Entwickeln von benutzerdefinierten ASP.NET-Serversteuerelementen