This documentation is archived and is not being maintained.

HierarchicalDataSourceControl Class

Provides a base class for data source controls that represent hierarchical data.

Namespace:  System.Web.UI
Assembly:  System.Web (in System.Web.dll)

<BindableAttribute(False)> _
<AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level := AspNetHostingPermissionLevel.Minimal)> _
<AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level := AspNetHostingPermissionLevel.Minimal)> _
Public MustInherit Class HierarchicalDataSourceControl _
	Inherits Control _
	Implements IHierarchicalDataSource
Dim instance As HierarchicalDataSourceControl
<asp:HierarchicalDataSourceControl />

ASP.NET supports a controls data-binding architecture that enables Web server controls to bind to data and present it in a consistent fashion. Web server controls that bind to data are called data-bound controls, and the classes that facilitate binding are called data source controls. Data source controls can represent any data source: a file, a stream, a relational database, a business object, and so on. Data source controls present data in a consistent way to data-bound controls, regardless of the source or format of the underlying data.

Data source controls that represent hierarchical data derive from the HierarchicalDataSourceControl class, while data source controls that represent lists or tables of data derive from the DataSourceControl class. The HierarchicalDataSourceControl class is the base implementation of the IHierarchicalDataSource interface, which defines a single method to retrieve hierarchical data source view objects associated with the data source control, GetHierarchicalView.

You can think of a data source control as the combination of the HierarchicalDataSourceControl object and its associated views on the underlying data, called data source view objects. While data source controls that represent tabular data are typically associated with only one named view, the HierarchicalDataSourceControl class supports a data source view for each level of hierarchical data that the data source control represents. The level of hierarchical data is identified by a unique hierarchical path, passed to the GetHierarchicalView method in the viewPath parameter. Each HierarchicalDataSourceView object defines the capabilities of a data source control for the hierarchical level represented, and performs operations such as insert, update, delete, and sort.

Web server controls that derive from the HierarchicalDataBoundControl class, such as TreeView, use hierarchical data source controls to bind to hierarchical data.

Data source controls are implemented as controls to enable declarative persistence and to optionally permit participation in state management. Data source controls have no visual rendering, and therefore do not support themes.

The following code example demonstrates how to extend the abstract HierarchicalDataSourceControl class and the HierarchicalDataSourceView class, and implement the IHierarchicalEnumerable and IHierarchyData interfaces to create a hierarchical data source control that retrieves file system information. The FileSystemDataSource control enables Web server controls to bind to FileSystemInfo objects and display basic file system information. The FileSystemDataSource class in the example provides the implementation of the GetHierarchicalView method, which retrieves a FileSystemDataSourceView object. The FileSystemDataSourceView object retrieves the data from the underlying data storage, in this case the file system information on the Web server. For security purposes, file system information is displayed only if the data source control is being used in a localhost, authenticated scenario, and only starts with the virtual directory that the Web Forms page using the data source control resides in. Finally, two classes that implement IHierarchicalEnumerable and IHierarchyData are provided to wrap the FileSystemInfo objects that FileSystemDataSource uses.

Imports System
Imports System.Collections
Imports System.IO
Imports System.Runtime.InteropServices
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls

Namespace Samples.AspNet

    Public Class FileSystemDataSource
        Inherits HierarchicalDataSourceControl

        Public Sub New()
        End Sub 

        Private view As FileSystemDataSourceView = Nothing 

        Protected Overrides Function GetHierarchicalView( _
            ByVal viewPath As String) As HierarchicalDataSourceView

            view = New FileSystemDataSourceView(viewPath)
            Return view
        End Function 

    End Class 
    Public Class FileSystemDataSourceView
        Inherits HierarchicalDataSourceView

        Private _viewPath As String 

        Public Sub New(ByVal viewPath As String)
            Dim currentRequest As HttpRequest = HttpContext.Current.Request
            If viewPath = "" Then
                _viewPath = currentRequest.MapPath(currentRequest.ApplicationPath)
                _viewPath = Path.Combine(currentRequest.MapPath(currentRequest.ApplicationPath), viewPath)
            End If 
        End Sub 'New 

        ' Starting with the rootNode, recursively build a list of 
        ' FileSystemInfo nodes, create FileSystemHierarchyData 
        ' objects, add them all to the FileSystemHierarchicalEnumerable, 
        ' and return the list. 
        Public Overrides Function [Select]() As IHierarchicalEnumerable
            Dim currentRequest As HttpRequest = HttpContext.Current.Request

            ' SECURITY: There are many security issues that can be raised 
            ' SECURITY: by exposing the file system structure of a Web server 
            ' SECURITY: to an anonymous user in a limited trust scenario such as 
            ' SECURITY: a Web page served on an intranet or the Internet. 
            ' SECURITY: For this reason, the FileSystemDataSource only 
            ' SECURITY: shows data when the HttpRequest is received 
            ' SECURITY: from a local Web server. In addition, the data source 
            ' SECURITY: does not display data to anonymous users. 
            If currentRequest.IsAuthenticated AndAlso _
                (currentRequest.UserHostAddress = "" OrElse _
                 currentRequest.UserHostAddress = "::1") Then 

                Dim rootDirectory As New DirectoryInfo(_viewPath)

                Dim fshe As New FileSystemHierarchicalEnumerable()

                Dim fsi As FileSystemInfo
                For Each fsi In rootDirectory.GetFileSystemInfos()
                    fshe.Add(New FileSystemHierarchyData(fsi))
                Next fsi
                Return fshe
                Throw New NotSupportedException( _
                    "The FileSystemDataSource only " + _
                    "presents data in an authenticated, localhost context.")
            End If 
        End Function 'Select 
    End Class 'FileSystemDataSourceView

    Public Class FileSystemHierarchicalEnumerable
        Inherits ArrayList
        Implements IHierarchicalEnumerable

        Public Sub New()
        End Sub 

        Public Overridable Function GetHierarchyData( _
            ByVal enumeratedItem As Object) As IHierarchyData _
            Implements IHierarchicalEnumerable.GetHierarchyData

            Return CType(enumeratedItem, IHierarchyData)
        End Function 

    End Class 

    Public Class FileSystemHierarchyData
        Implements IHierarchyData

        Public Sub New(ByVal obj As FileSystemInfo)
            fileSystemObject = obj
        End Sub 

        Private fileSystemObject As FileSystemInfo = Nothing 

        Public Overrides Function ToString() As String 
            Return fileSystemObject.Name
        End Function 

        ' IHierarchyData implementation. 
        Public Overridable ReadOnly Property HasChildren() As Boolean _
         Implements IHierarchyData.HasChildren
                If GetType(DirectoryInfo) Is fileSystemObject.GetType() Then 
                    Dim temp As DirectoryInfo = _
                        CType(fileSystemObject, DirectoryInfo)
                    Return temp.GetFileSystemInfos().Length > 0
                    Return False 
                End If 
            End Get 
        End Property 
        ' DirectoryInfo returns the OriginalPath, while FileInfo returns 
        ' a fully qualified path. 

        Public Overridable ReadOnly Property Path() As String _
         Implements IHierarchyData.Path
                Return fileSystemObject.ToString()
            End Get 
        End Property 

        Public Overridable ReadOnly Property Item() As Object _
         Implements IHierarchyData.Item
                Return fileSystemObject
            End Get 
        End Property 

        Public Overridable ReadOnly Property Type() As String _
         Implements IHierarchyData.Type
                Return "FileSystemData" 
            End Get 
        End Property 

        Public Overridable Function GetChildren() _
            As IHierarchicalEnumerable _
            Implements IHierarchyData.GetChildren

            Dim children As New FileSystemHierarchicalEnumerable()

            If GetType(DirectoryInfo) Is fileSystemObject.GetType() Then 
                Dim temp As DirectoryInfo = _
                    CType(fileSystemObject, DirectoryInfo)
                Dim fsi As FileSystemInfo
                For Each fsi In temp.GetFileSystemInfos()
                    children.Add(New FileSystemHierarchyData(fsi))
                Next fsi
            End If 
            Return children
        End Function 'GetChildren

        Public Overridable Function GetParent() As IHierarchyData _
         Implements IHierarchyData.GetParent
            Dim parentContainer As New FileSystemHierarchicalEnumerable()

            If GetType(DirectoryInfo) Is fileSystemObject.GetType() Then 
                Dim temp As DirectoryInfo = _
                    CType(fileSystemObject, DirectoryInfo)
                Return New FileSystemHierarchyData(temp.Parent)
            ElseIf GetType(FileInfo) Is fileSystemObject.GetType() Then 
                Dim temp As FileInfo = CType(fileSystemObject, FileInfo)
                Return New FileSystemHierarchyData(temp.Directory)
            End If 
            ' If FileSystemObj is any other kind of FileSystemInfo, ignore it. 
            Return Nothing 
        End Function 'GetParent
    End Class 'FileSystemHierarchyData
End Namespace

The following code example demonstrates how to declaratively bind a TreeView control to file system data using the FileSystemDataSource example.

<%@ Page Language="VB" %>
<%@ Register Tagprefix="aspSample" Namespace="Samples.AspNet" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">

<html xmlns="" >
    <head runat="server">
    <title>ASP.NET Example</title>
        <form id="form1" runat="server">

                datasourceid="FileSystemDataSource1" />            

                id = "FileSystemDataSource1"
                runat = "server" />            


Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0