System.Web 2.0.0.0 System.Web.UI.HierarchicalDataSourceControl System.ComponentModel.IListSource System.Web.UI.IDataSource System.Web.UI.PersistChildren(false) System.Web.UI.ParseChildren(true) System.ComponentModel.DefaultEvent("Transforming") System.ComponentModel.DefaultProperty("DataFile") System.ComponentModel.Designer("System.Web.UI.Design.WebControls.XmlDataSourceDesigner, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.ComponentModel.Design.IDesigner") In this topic: Introduction Sources of XML Data Updating XML Data Specifying an XSL Transformation Filtering using an XPath Expression Caching Additional Features Data View Object Declarative Syntax

Introduction

The control is a data source control that presents XML data to data-bound controls. The control can be used by data-bound controls to display both hierarchical and tabular data. The control is typically used to display hierarchical XML data in read-only scenarios. Because the control extends the class, it works with hierarchical data. The control also implements the interface and works with tabular, or list-style, data. For security purposes, none of the control properties are stored in view state. Since it is technically possible to decode the contents of view state on the client, storing sensitive information about the data structure or its contents could expose you to an information disclosure threat. Note that if you need to store information such as property in view state, you can enable encryption to protect the contents by setting on the @ Page directive. Page developers use the control to display XML data using data-bound controls.

Sources of XML Data

The typically loads XML data from an XML file, which is specified by the property. XML data can also be stored directly by the data source control in string form using the property. If you want to transform the XML data before it is displayed by a data-bound control, you can provide an Extensible Stylesheet Language (XSL) style sheet for the transformation. As with the XML data, you typically load the style sheet from a file, indicated by the property, but you can also store it in string form directly using the property.

Updating XML Data

The control is commonly used in read-only data scenarios where a data-bound control displays XML data. However, you can also use the control to edit XML data. To edit the XML data, call the method to retrieve an object that is an in-memory representation of the XML data. You can use the object model exposed by the and objects it contains or use an XPath filtering expression to manipulate data in the document. When you have made changes to the in-memory representation of the XML data, you can save it to disk by calling the method. There are some restrictions to the editing capabilities of the control: The XML data must be loaded from an XML file that is indicated by the property, not from inline XML specified in the property. No XSLT transformation can be specified in the or properties. The method does not handle concurrent save operations by different requests. If more than one user is editing an XML file through the , there is no guarantee that all users are operating with the same data. It is also possible for a operation to fail due to these same concurrency issues.

Specifying an XSL Transformation

A common operation performed with XML data is transforming it from one XML data set into another. The control supports XML transformations with the and properties, which specify an XSL style sheet to apply to XML data before it is passed to a data-bound control, and the property, which enables you to supply dynamic XSLT style sheet arguments to be used by an XSL style sheet during the transformation. If you specify an XPath filtering expression using the property, it is applied after the transformation takes place. The class uses the deprecated class to perform XSL transformations. If you want to use style sheet features that were introduced after the class was deprecated, apply the transforms manually by using the class.

Filtering using an XPath Expression

By default, the control loads all the XML data in the XML file identified by the property or found inline in the property, but you can filter the data using an XPath expression. The property supports an XPath-syntax filter that is applied after XML data is loaded and transformed.

Caching

For performance purposes, caching is enabled for the control by default. Opening and reading an XML file on the server every time a page requested can reduce the performance of your application. Caching lets you reduce the processing load on your server at the expense of memory on the Web server; in most cases this is a good trade-off. The automatically caches data when the property is set to true, and the property is set to the number of seconds that the cache stores data before the cache is invalidated. You can use the to further fine-tune the caching behavior of the data source control.

Additional Features

The following table lists additional features that are supported by the control. Capability Description Sorting Not supported by the control. Filtering The property can be used to filter the XML data using an appropriate XPath expression. Paging Not supported by the control. Updating Supported by manipulating the directly and then calling the method. Deleting Supported by manipulating the directly and then calling the method. Inserting Supported by manipulating the directly and then calling the method. Caching Enabled by default, with the property set to 0 (infinite) and the property set to .

Data View Object

Because the control supports data-bound controls that display hierarchical data as well as controls that display tabular data, the data source control supports multiple types of data source view objects on its underlying XML data. The control retrieves a single named object when used with a data-bound control that displays tabular data. The method identifies this single named view. When used with a data-bound control that displays hierarchical data, the control retrieves an for any unique hierarchical path passed to the method.

Declarative Syntax

<asp:XmlDataSource     CacheDuration="string|Infinite"     CacheExpirationPolicy="Absolute|Sliding"     CacheKeyDependency="string"     DataFile="string"     EnableCaching="True|False"     EnableTheming="True|False"     EnableViewState="True|False"     ID="string"     OnDataBinding="DataBinding event handler"     OnDisposed="Disposed event handler"     OnInit="Init event handler"     OnLoad="Load event handler"     OnPreRender="PreRender event handler"     OnTransforming="Transforming event handler"     OnUnload="Unload event handler"     runat="server"     SkinID="string"     TransformArgumentList="string"     TransformFile="string"     Visible="True|False"     XPath="string" > <Data>string</Data> <Transform>string</Transform> </asp:XmlDataSource>

Represents an XML data source to data-bound controls.

Constructor To be added.

Creates a new instance of the class.

2.0.0.0 Property System.ComponentModel.DefaultValue(0) System.Int32 To be added. The control automatically caches data when the following applies: The property is set to true. The property is set to a value greater than 0, which indicates the number of seconds that the cache stores data before the cache is invalidated. Any change to the property or the contents of the file that contains the XML data causes the cache to be invalidated. By default, the property is set to 0, which indicates an indefinite cache, and the data source will cache data until the XML file that it depends on is changed. The behavior of the cache is governed by a combination of the duration and the setting. If is set to , the control caches data on the first data retrieval operation, holds it in memory for the amount of time specified by , and invalidates it after the time has lapsed. The cache is then refreshed upon the next operation. If is set to , the data source control caches data on the first data retrieval operation, but resets the time window that it holds the cache for upon each subsequent operation. The cache will only expire if there is no activity for a time equal to the since the last data retrieval.

Gets or sets the length of time, in seconds, that the data source control caches data it has retrieved.

2.0.0.0 Property System.ComponentModel.DefaultValue(System.Web.UI.DataSourceCacheExpiry.Absolute) System.Web.UI.DataSourceCacheExpiry To be added. The behavior of the cache is governed by a combination of the and settings. If the is set to , the caches data on the first data retrieval operation, holds it in memory for the amount of time specified by , and invalidates it after the time has lapsed. The cache is then refreshed upon the next operation. If the is set to , the data source control caches data on the first data retrieval operation, but resets the time window that it holds the cache for upon each subsequent operation. The cache will expire only if there is no activity for a time equal to the since the last data retrieval.

Gets or sets the cache expiration policy that is combined with the cache duration to describe the caching behavior of the cache that the data source control uses.

2.0.0.0 Property System.ComponentModel.DefaultValue("") System.String To be added. The control supports data caching. While data is cached, the retrieves data from the cache rather than from the underlying data file. When the cache expires, it retrieves data from the underlying file and re-caches the data. You can set the property to create a dependency between all cache entries created by the control and the key. You can programmatically invalidate all the cache entries at any time by expiring the key. Because of the properties used to create the , it is possible that multiple controls can use the same cache in scenarios where they load the same data from the same XML file and transform file and have the same and set.

Gets or sets a user-defined key dependency that is linked to all data cache objects created by the data source control. All cache objects explicitly expire when the key expires.

2.0.0.0 Property System.ComponentModel.Editor("System.ComponentModel.Design.MultilineStringEditor,System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a") System.Web.UI.PersistenceMode(System.Web.UI.PersistenceMode.InnerProperty) System.ComponentModel.DefaultValue("") System.String To be added. In declarative scenarios, the property is specified as a multiline inner property of the object. An inner property is compatible with XML data, because it enables you to format the XML data in any way and ignore character padding issues, such as padding quote characters. If both the and properties are set, the property takes precedence and the data in the XML file is used instead of the XML data specified in the property. If you change the value of the property, the event is raised. If caching is enabled and you change the value of , the cache is invalidated.

Gets or sets a block of XML data that the data source control binds to.

2.0.0.0 Property System.ComponentModel.Editor("System.Web.UI.Design.XmlDataFileEditor, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a") System.ComponentModel.DefaultValue("") System.String To be added. If both the and properties are set, the property takes precedence and the data in the XML file is used instead of the XML data specified in the property. If you change the value of the property, the event is raised. If caching is enabled and you change the value of , the cache is invalidated.

Specifies the file name of an XML file that the data source binds to.

2.0.0.0 Property System.ComponentModel.DefaultValue(true) System.Boolean To be added. The control automatically caches data when the property is set to true. By default, the property is set to 0, which indicates an indefinite cache, and the data source will cache data until the XML file that it depends on is changed. If you set the property to a value greater than 0, the cache stores data for that many seconds before retrieving a fresh set. If the property is set to true and the property is set, the cache entries are not automatically invalidated when the parameters change in the transforms argument list. In that case, you must write code to invalidate the cache by setting the property.

Gets or sets a value indicating whether the control has data caching enabled.

2.0.0.0 Method System.Web.UI.HierarchicalDataSourceView You can call the method to retrieve a object associated with the control. If you specify value, the control returns a data source view object that represents the view on the node identified by , along with all its child nodes. If you set to , the control checks the property to determine the root node from which to build the data source view. If the property is set, the control uses it to return a data source view in the same way the expression is used. If the property is not set, the control returns a view of all the data nodes in the XML data.

Gets the data source view object for the control. The parameter can be an XPath expression.

Returns an object that represents a single view of the data starting with the data node identified by . An XPath expression that identifies a node from which the current hierarchical view is built. 2.0.0.0 Method System.Xml.XmlDocument Use the method for direct access to an in-memory representation of the underlying XML data. You can manipulate the returned object and then call to persist your changes to the XML file specified by the property. Several requirements must be met before the object can be saved successfully. For more information, see the method.

Loads the XML data into memory, either directly from the underlying data storage or from the cache, and returns it in the form of an object.

An object that represents the XML specified in the property or in the file identified by the property, with any transformations and queries applied. 2.0.0.0 Method System.Void Raising an event invokes the event handler through a delegate. For more information, see Consuming Events. The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Raises the event before the control performs an XSLT transformation on its XML data.

An that contains the event data. 2.0.0.0 Method System.Void While the control is typically used in read-only data-binding scenarios, you can use the control to edit XML data in the underlying XML data file. In these scenarios, XML data is loaded from an XML file by the control. You modify the in memory using the method, and then save to the XML data file by calling the method. This editable XML scenario is possible when the following conditions are met: The XML data is loaded from an XML file indicated by the property, not from inline XML data specified in the property. No XSLT transformation is specified in the or properties. The method does not handle concurrent save operations by different requests. If more than one user is editing an XML file through the control, there is no guarantee that all users are operating with the same data. It is also possible for a operation to fail due to these same concurrency issues.

Saves the XML data currently held in memory by the control to disk if the property is set.

2.0.0.0 Property 2.0.0.0 System.Boolean To be added. This member is an explicit interface member implementation. It can be used only when the instance is cast to the interface.

For a description of this member, see .

Method 2.0.0.0 System.Collections.IList This member is an explicit interface member implementation. It can be used only when the instance is cast to the interface.

For a description of this member, see .

An object implementing that can be bound to a data source. Method 2.0.0.0 System.Web.UI.DataSourceView To be added.

Gets the named data source view associated with the data source control.

Returns the named object associated with the control. The name of the view to retrieve. If is specified, the default view for the control is retrieved. Method 2.0.0.0 System.Collections.ICollection This member is an explicit interface member implementation. It can be used only when the instance is cast to the interface.

For a description of this member, see .

An object implementing containing names representing the list of view objects associated with the object. Property System.ComponentModel.DefaultValue("") System.ComponentModel.Editor("System.ComponentModel.Design.MultilineStringEditor,System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a") System.Web.UI.PersistenceMode(System.Web.UI.PersistenceMode.InnerProperty) System.String To be added. In declarative scenarios, the property is specified as a multiline inner property of the object. An inner property is compatible with XSL style sheet data, because it enables you to format the style sheet in any way and ignore character padding issues such as padding quote characters. If both the and properties are set, the property takes precedence and the data in the XSL style sheet file (.xsl) is used instead of the style sheet elements specified in the property. If an XPath expression is set using the property, it is applied after the XML data is transformed. If you change the value of the property, the event is raised. If caching is enabled and you change the value of , the cache is invalidated. The class uses the deprecated class to perform XSL transformations. If you want to use style sheet features that were introduced after the class was deprecated, apply the transforms manually by using the class.

Gets or sets a block of Extensible Stylesheet Language (XSL) data that defines an XSLT transformation to be performed on the XML data managed by the control.

2.0.0.0 Property System.ComponentModel.Browsable(false) System.Xml.Xsl.XsltArgumentList To be added. Set the property when the event is raised to ensure the XSLT parameters are available at the time that the XSLT transformation is applied to the XML data. If the property is set to true and the property is set, the cache entries are not automatically invalidated when the parameters change in the transforms argument list. In that case, you must write code to invalidate the cache by setting the property.

Provides a list of XSLT arguments that are used with the style sheet defined by the or properties to perform a transformation on the XML data.

2.0.0.0 Property System.ComponentModel.DefaultValue("") System.ComponentModel.Editor("System.Web.UI.Design.XslTransformFileEditor, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a") System.String To be added. If both the and properties are set, the property takes precedence and the data in the XSL style sheet file (.xsl) is used instead of the style sheet elements specified in the property. If an XPath expression is set using the property, it is applied after the XML data is transformed. If you change the value of the property, the event is raised. If caching is enabled and you change the value of , the cache is invalidated. The class uses the deprecated class to perform XSL transformations. If you want to use style sheet features that were introduced after the class was deprecated, apply the transforms manually by using the class.

Specifies the file name of an Extensible Stylesheet Language (XSL) file (.xsl) that defines an XSLT transformation to be performed on the XML data managed by the control.

2.0.0.0 Event System.EventHandler Handle the event to set the property with an object before the control performs an XML transformation. For more information about handling events, see [<topic://cpconEventsOverview>].

Occurs before the style sheet that is defined by the property or identified by the property is applied to XML data.

2.0.0.0 Property System.ComponentModel.DefaultValue("") System.String To be added. For more information on XPath data-binding expressions, see Binding a Tabular Control to the XmlDataSource Control.

Specifies an XPath expression to be applied to the XML data contained by the property or by the XML file indicated by the property.

2.0.0.0