Beispiel für eine Auflistungseigenschaft eines Webserversteuerelements

Aktualisiert: November 2007

In diesem Beispiel wird veranschaulicht, wie ein Steuerelement mit dem Namen QuickContacts erstellt wird, das für eine Auflistungseigenschaft Dauerhaftigkeit in einer Seite implementiert. Das Beispielsteuerelement ist ein Steuerelement, mit dem ein Entwickler Adressbuchkontakte in einer Liste speichern kann. Das QuickContacts-Steuerelement macht eine Contacts-Auflistungseigenschaft verfügbar, die Contact-Objekte enthält. Die Contact-Klasse weist eine Name-Eigenschaft, eine Email-Eigenschaft und eine Phone-Eigenschaft auf.

Die Contact-Elemente der Contacts -Auflistungseigenschaften werden innerhalb der Steuerelementtags beibehalten, wie im folgenden Beispiel gezeigt wird:

<aspSample:QuickContacts ID="QuickContacts1" Runat="server">
  <aspSample:Contact Name="someone" Email="someone@example.com"     Phone="(555) 555-5555"/><aspSample:Contact Name="jae" Email="jae@fourthcoffee.com"     Phone="(555) 555-5555"/>
</aspSample:QuickContacts>

Aus Gründen der Übersichtlichkeit implementiert das QuickContacts-Steuerelement keine Zustandsverwaltung für die Auflistungseigenschaft. Es wird angenommen, dass die Auflistungselemente deklarativ der Seite hinzugefügt werden. Wenn sie im Code erstellt wurden, müssen sie während des Postbacks erneut erstellt werden. Bei einem auf Produktionsqualität ausgerichteten Steuerelement würden Sie die Zustandsverwaltung implementieren. Ausführliche Informationen finden Sie unter Benutzerdefinierte Zustandsverwaltung für Serversteuerelemente.

Codeauflistung für das QuickContacts-Steuerelement

' QuickContacts.vb
Option Strict On
Imports System
Imports System.ComponentModel
Imports System.Collections
Imports System.Drawing.Design
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("Contacts"), _
    ParseChildren(True, "Contacts"), _
    ToolboxData( _
        "<{0}:QuickContacts runat=""server""> </{0}:QuickContacts>") _
    > _
    Public Class QuickContacts
        Inherits WebControl

        Private contactsList As ArrayList

        < _
        Category("Behavior"), _
        Description("The contacts collection"), _
        DesignerSerializationVisibility( _
            DesignerSerializationVisibility.Content), _
        Editor(GetType(ContactCollectionEditor), _
            GetType(UITypeEditor)), _
        PersistenceMode(PersistenceMode.InnerDefaultProperty) _
        > _
        Public ReadOnly Property Contacts() As ArrayList
            Get
                If contactsList Is Nothing Then
                    contactsList = New ArrayList
                End If
                Return contactsList
            End Get
        End Property

        ' The contacts are rendered in an HTML table.
        Protected Overrides Sub RenderContents( _
        ByVal writer As HtmlTextWriter)
            Dim t As Table = CreateContactsTable()
            If t IsNot Nothing Then
                t.RenderControl(writer)
            End If
        End Sub

        Private Function CreateContactsTable() As Table
            Dim t As Table = Nothing
            If (contactsList IsNot Nothing) AndAlso _
                (contactsList.Count > 0) Then
                t = New Table
                For Each item As Contact In contactsList
                    Dim aContact As Contact = TryCast(item, Contact)
                    If aContact IsNot Nothing Then
                        Dim r As New TableRow
                        Dim c1 As New TableCell
                        c1.Text = aContact.Name
                        r.Controls.Add(c1)

                        Dim c2 As New TableCell
                        c2.Text = aContact.Email
                        r.Controls.Add(c2)

                        Dim c3 As New TableCell
                        c2.Text = aContact.Phone
                        r.Controls.Add(c3)

                        t.Controls.Add(r)
                    End If
                Next
            End If
            Return t
        End Function
    End Class
End Namespace

// QuickContacts.cs
using System;
using System.ComponentModel;
using System.Collections;
using System.Drawing.Design;
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("Contacts"),
    ParseChildren(true, "Contacts"),
    ToolboxData(
        "<{0}:QuickContacts runat=\"server\"> </{0}:QuickContacts>")
    ]
    public class QuickContacts : WebControl
    {
        private ArrayList contactsList;

        [
        Category("Behavior"),
        Description("The contacts collection"),
        DesignerSerializationVisibility(
            DesignerSerializationVisibility.Content),
        Editor(typeof(ContactCollectionEditor), typeof(UITypeEditor)),
        PersistenceMode(PersistenceMode.InnerDefaultProperty)
        ]
        public ArrayList Contacts
        {
            get
            {
                if (contactsList == null)
                {
                    contactsList = new ArrayList();
                }
                return contactsList;
            }
        }


        // The contacts are rendered in an HTML table.
        protected override void RenderContents(
            HtmlTextWriter writer)
        {
            Table t = CreateContactsTable();
            if (t != null)
            {
                t.RenderControl(writer);
            }
        }

        private Table CreateContactsTable()
        {
            Table t = null;

            if (contactsList != null && contactsList.Count > 0)
            {
                t = new Table();

                foreach (Contact item in contactsList)
                {
                    Contact aContact = item as Contact;

                    if (aContact != null)
                    {
                        TableRow r = new TableRow();

                        TableCell c1 = new TableCell();
                        c1.Text = aContact.Name;
                        r.Controls.Add(c1);

                        TableCell c2 = new TableCell();
                        c2.Text = aContact.Email;
                        r.Controls.Add(c2);


                        TableCell c3 = new TableCell();
                        c3.Text = aContact.Phone;
                        r.Controls.Add(c3);

                        t.Controls.Add(r);
                    }
                }
            }
            return t;
        }
    }
}

Codeerläuterung

Um das Analysieren der Auflistungselemente innerhalb der Steuerelementtags zu ermöglichen, fügt das QuickContacts-Steuerelement dem Steuerelement das ParseChildren(true, "Contacts")-Attribut hinzu. Das erste Argument (true) von ParseChildrenAttribute gibt an, dass der Seitenparser den geschachtelten Inhalt innerhalb der Steuerelementtags als Eigenschaften und nicht als untergeordnete Steuerelemente analysieren soll. Das zweite Argument ("Contacts") gibt den Namen der inneren Standardeigenschaft an. Wenn Sie das zweite Argument festlegen, muss der Inhalt innerhalb der Steuerelementtags ausschließlich mit der inneren Standardeigenschaft (Contact-Objekte) übereinstimmen.

Das QuickContacts-Steuerelement beinhaltet außerdem die folgenden Entwurfszeitattribute, die Sie auf eine Auflistungseigenschaft zum Zwecke der Serialisierung und Dauerhaftigkeit während der Entwurfszeit anwenden müssen:

DesignerSerializationVisibilityAttribute Das Festlegen des Content-Parameters gibt an, dass ein visueller Designer den Inhalt der Eigenschaft serialisieren soll. Die Eigenschaft enthält im Beispiel Contact-Objekte.
PersistenceModeAttribute Das Weitergeben des InnerDefaultProperty-Parameters legt fest, dass ein visueller Designer die Eigenschaft beibehalten soll, für die das Attribut als innere Standardeigenschaft angewendet wird. Dies bedeutet, dass ein visueller Designer die Eigenschaft innerhalb der Steuerelementtags beibehält. Das Attribut kann nur auf eine Eigenschaft angewendet werden, da nur eine Eigenschaft innerhalb der Steuerelementtags beibehalten werden kann. Der Eigenschaftenwert wird nicht in ein besonderes Tag eingebunden.

Das QuickContacts-Steuerelement verknüpft einen Auflistungs-Editor mit der Contacts-Auflistungseigenschaft. Dazu wird, wie folgendes Beispiel zeigt, EditorAttribute verwendet:

Editor(typeof(ContactCollectionEditor), typeof(UITypeEditor))

Editor(GetType(ContactCollectionEditor), GetType(UITypeEditor))

Durch das Verknüpfen eines Auflistungs-Editors mit der Eigenschaft kann der Eigenschaftenbrowser in einem visuellen Designer einen Auflistungs-Editor öffnen, um Contact-Elemente hinzuzufügen. Dies ähnelt der Benutzeroberfläche zum Bearbeiten der Items-Eigenschaft des DropDownList-Steuerelements oder des ListBox-Steuerelements. Der von QuickContacts verwendete benutzerdefinierte Auflistungs-Editor ContactCollectionEditor wird in Beispiel für einen Auflistungs-Editor beschrieben.

Aus Gründen der Übersichtlichkeit legt das QuickContacts-Steuerelement keine Auflistung mit strikter Typbindung fest, sondern verwendet stattdessen eine ArrayList als Auflistungstyp. Im Allgemeinen soll eine stark typisierte Auflistung als Typ für die Auflistungseigenschaft verwendet werden, damit ein Anwendungsprogrammierer der Auflistung keine beliebigen Typen hinzufügen kann.

Codeauflistung für die Kontaktklasse

Die Entwurfszeitattribute im Code der Contact-Klasse werden für Eigenschaftenbearbeitung und Entwurfszeitserialisierung benötigt. Der ExpandableObjectConverter-Typkonverter, der mit der Contact-Klasse verknüpft ist (unter Verwendung von TypeConverterAttribute), ermöglicht dem Auflistungs-Editor, eine Benutzeroberfläche zum Erweitern/Reduzieren für das Bearbeiten von untergeordneten Eigenschaften bereitzustellen (Name, Email, Phone). Diese ist der Benutzeroberfläche ähnlich, mit der Sie die Font-Eigenschaft eines Websteuerelements im Eigenschaftenbrowser eines visuellen Designers bearbeiten. Die Anwendung von NotifyParentPropertyAttribute (mit dem Konstruktorargument gleich true) auf die Name-Eigenschaft, die Email-Eigenschaft und die Phone -Eigenschaft führt dazu, dass der Editor die Änderungen in diesen Eigenschaften in den übergeordneten Eigenschaften serialisiert, die eine Instanz der Contact-Klasse sind.

' Contact.vb
' The type of the items in the Contacts collection property 
' in QuickContacts.
Option Strict On
Imports System
Imports System.Collections
Imports System.ComponentModel
Imports System.Web.UI

Namespace Samples.AspNet.VB.Controls
    < _
    TypeConverter(GetType(ExpandableObjectConverter)) _
    > _
    Public Class Contact
        Private _name As String
        Private _email As String
        Private _phone As String

        Public Sub New()
            Me.New(String.Empty, String.Empty, String.Empty)
        End Sub

        Public Sub New(ByVal name As String, _
        ByVal email As String, ByVal phone As String)
            _name = name
            _email = email
            _phone = phone
        End Sub

        < _
        Category("Behavior"), _
        DefaultValue(""), _
        Description("Name of contact"), _
        NotifyParentProperty(True) _
        > _
        Public Property Name() As String
            Get
                Return _name
            End Get
            Set(ByVal value As String)
                _name = value
            End Set
        End Property

        < _
        Category("Behavior"), _
        DefaultValue(""), _
        Description("Email address of contact"), _
        NotifyParentProperty(True) _
        > _
        Public Property Email() As String
            Get
                Return _email
            End Get
            Set(ByVal value As String)
                _email = value
            End Set
        End Property


        < _
        Category("Behavior"), _
        DefaultValue(""), _
        Description("Phone number of contact"), _
        NotifyParentProperty(True) _
        > _
        Public Property Phone() As String
            Get
                Return _phone
            End Get
            Set(ByVal value As String)
                _phone = value
            End Set
        End Property
    End Class
End Namespace

// Contact.cs
// The type of the items in the Contacts collection property 
//in QuickContacts.

using System;
using System.Collections;
using System.ComponentModel;
using System.Web.UI;

namespace Samples.AspNet.CS.Controls
{
    [
    TypeConverter(typeof(ExpandableObjectConverter))
    ]
    public class Contact
    {
        private string nameValue;
        private string emailValue;
        private string phoneValue;


        public Contact()
            : this(String.Empty, String.Empty, String.Empty)
        {
        }

        public Contact(string name, string email, string phone)
        {
            nameValue = name;
            emailValue = email;
            phoneValue = phone;
        }

        [
        Category("Behavior"),
        DefaultValue(""),
        Description("Name of contact"),
        NotifyParentProperty(true),
        ]
        public String Name
        {
            get
            {
                return nameValue;
            }
            set
            {
                nameValue = value;
            }
        }

        [
        Category("Behavior"),
        DefaultValue(""),
        Description("Email address of contact"),
        NotifyParentProperty(true)
        ]
        public String Email
        {
            get
            {
                return emailValue;
            }
            set
            {
                emailValue = value;
            }
        }

        [
        Category("Behavior"),
        DefaultValue(""),
        Description("Phone number of contact"),
        NotifyParentProperty(true)
        ]
        public String Phone
        {
            get
            {
                return phoneValue;
            }
            set
            {
                phoneValue = value;
            }
        }
    }
}

Testseite für das QuickContacts-Steuerelement

Das folgende Beispiel zeigt eine ASPX-Seite, die das QuickContacts-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" >
    <title>
      QuickContacts test page
    </title>
  </head>
  <body>
    <form id="Form1" >
      <aspSample:QuickContacts ID="QuickContacts1" Runat="server" 
        BorderStyle="Solid" BorderWidth="1px">
        <aspSample:Contact Name="someone" Email="someone@example.com" 
          Phone="(555) 555-0100"/>
        <aspSample:Contact Name="jae" Email="jae@fourthcoffee.com" 
          Phone="(555) 555-0101"/>
        <aspSample:Contact Name="lene" Email="lene@contoso.com" 
          Phone="(555) 555-0102"/>        
      </aspSample:QuickContacts>
    </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>
      QuickContacts test page
    </title>
  </head>
  <body>
    <form id="Form1" >
      <aspSample:QuickContacts ID="QuickContacts1" Runat="server" 
        BorderStyle="Solid" BorderWidth="1px">
        <aspSample:Contact Name="someone" Email="someone@example.com" 
          Phone="(555) 555-0100"/>
        <aspSample:Contact Name="jae" Email="jae@fourthcoffee.com" 
          Phone="(555) 555-0101"/>
        <aspSample:Contact Name="lene" Email="lene@contoso.com" 
          Phone="(555) 555-0102"/>        
      </aspSample:QuickContacts>
    </form>
  </body>
</html>

Erstellen und Verwenden des Beispiels

Kompilieren Sie das QuickContacts-Steuerelement und die Contacts-Klasse mit dem ContactCollectionEditor-Editor, der in Beispiel für einen Auflistungs-Editor aufgelistet ist. Für die Kompilierung müssen Sie einen Verweis auf die System.Design-Assembly hinzufügen.

Weitere Informationen über das Kompilieren und Verwenden der benutzerdefinierten Beispielsteuerelemente finden Sie unter Erstellen der Beispiele für benutzerdefinierte Serversteuerelemente.

Siehe auch

Konzepte

Beispiel für einen Auflistungs-Editor

Erstellen der Beispiele für benutzerdefinierte Serversteuerelemente

Weitere Ressourcen

Entwickeln von benutzerdefinierten ASP.NET-Serversteuerelementen

Last updated on 2014-10-22