---
title: Use data source controls
slug: cms-11/dev-docs/using-data-source-controls
createdAt: 2026-07-22T19:45:19.953Z
---

:::hint{type="warning"}
**Important**
This topic applies to sites using Web Forms.
:::

One of the more influential groups of controls included in Optimizely Content Management System (CMS) is the data source controls. One of the major benefits of using these controls is that they minimize the need for code-behind for day-to-day operations involving reading data and populating various lists, trees, and so on. The controls support all or a few of the select, insert, update, and delete operations.

Some benefits of using the controls are:

- Minimized need for plumbing code in code-behind.
- Built-in support for selecting, inserting, updating, and deleting.
- A contract that fits many of the built-in .NET controls and third-party controls.

You can categorize the data source controls as `Hierarchical`, `Tabular`, or both, depending on how they can deliver data.

- Hierarchical data source controls expose data in a hierarchical fashion (parent-child), which you can use for tree views such as the `TreeView` and `Menu` controls in ASP.NET.
- Most controls serve data in a tabular fashion, which you can use to list controls such as the `Repeater`, `DataList`, `GridView`, and so on.

:::hint{type="info"}
**Note**
An important difference between hierarchical and tabular data sources are that hierarchical data sources are read-only whereas the tabular data sources can support inserting, updating, and deleting.
:::

The following controls implement the `IHierarchicalDataSource` interface and can generate data for tree view controls or menus:

- `PageDataSource`
- `CategoryDataSource`
- `FileSystemDataSource`

To create your own tabular data source controls, use the base class `GenericDataSource`.

## Use a CMS data source control

You should use the data source classes in markup. You should not code against or inherit from them, so you should not need to add your code-behind. If you do need additional functionality, you should inherit from the `GenericDataSource` control and create classes that suit your needs.

The data source controls work as any standard control in an `.aspx` page.

## Element attribute and query parameter

When you populate a data source, you usually use a [QueryStringParameter](http://msdn2.microsoft.com/en-us/library/system.web.ui.webcontrols.querystringparameter.aspx) to read a selection of objects from the database. You can define a value for a member of the object as an attribute in the asp element and as a parameter in the query string. In this case, the query string definition precedes the `asp` attribute. Consider the following example:

```xml
<EPiServer:CategoryDataSource
  runat="server"
  ID="CategoryData"
  IncludeRootCategory="true">
  <SelectParameters>
    <asp:QueryStringParameter
      Name="ID"
      QueryStringField="ID"
      Type="Int32" />
    <asp:QueryStringParameter
      Name="IncludeRootCategory"
      QueryStringField="IncludeRootCategory"
      Type="Boolean"
      DefaultValue="false" />
  </SelectParameters>
</EPiServer:CategoryDataSource>
```

Because `IncludeRootCategory` is defined twice (being set to **true** in the tag definition and **false** in the `QueryStringParameter`), the value set in the query string parameter is used. If no query string parameter named `IncludeRootCategory` is specified, it is the default value that is used, in this case, **false**. For information about using parameters with Data Source Controls, see Microsoft’s article [Using Parameters with Data Source Controls](http://msdn2.microsoft.com/en-us/library/xt50s8kz.aspx).

:::hint{type="info"}
**Note**
You should not use certain words to use as parameter names for http requests. For example, **ID** causes a conflict if you try to use it as a parameter name for one of your http requests, because ID is used to identify aspx pages in CMS. If the page had an ID of 200, every call to the `CategoryDataSource` would try to fetch categories with a parent ID of 200. You can solve the issue by adding text to certain words, such as changing **ID** to `CategoryID`.
:::

## Create data source controls

Designing data source controls is a matter of inheriting from the `GenericDataSource` class. The following lines of code show how the `TabDefinitionDataSource` is defined. There is little code involved in getting access to the basic functionality.

```csharp
public class TabDefinitionDataSource:
  GenericDataSource<TabDefinition, TabDefinitionCollection, int> {
    protected override TabDefinition CreateItem(List<TabDefinition> items) {
      return new TabDefinition();
    }

    protected override List< TabDefinition> ListItems() {
      return ToList(TabDefinition.List());
    }

    protected override TabDefinition LoadItem(int key) {
      return TabDefinition.Load(key);
    }

    protected override void SaveItem(TabDefinition item) {
      item.Save();
    }

    protected override void DeleteItem(TabDefinition item) {
      item.Delete();
    }
  }
```

`GenericDataSource<TObject, TCollection, TKey>` has the following type parameters:

| Name        | Explanation                                          | Example                                         |
| ----------- | ---------------------------------------------------- | ----------------------------------------------- |
| TObject     | The business object type                             | TabDefinition                                   |
| TCollection | A collection type that holds objects of type TObject | TabDefinitionCollection or List\<TabDefinition> |
| TKey        | The data type of the primary key                     | int                                             |

**Business Objects**
Before creating your data source control type, have a class, your business object, that handles the data you want to present. In the sample above, the class used for this is `TabDefinition`. This class is responsible for reading and saving data from the database.

Suppose you do not need to implement a specialized behavior in your collection of business objects. In that case, you can use the generic [List](http://msdn2.microsoft.com/en-us/library/6sh2ey19.aspx) provided by the .NET Framework as described in the following short sample:

```csharp
...
...
public class MyObjectDataSource :
GenericDataSource<MyObject, List<MyObject>, int>
{
    
...
...
```

## Map between control properties and data source parameters

A common way to limit a result set of a data source control is to provide its parameters in the `SelectParameters` collection (see [Parameter](http://msdn2.microsoft.com/en-us/library/system.web.ui.webcontrols.parameter.aspx)), which most CMS data source controls support by allowing overrides of certain control properties by a parameter value. You can specify the following properties using `Parameters` for a given CMS data source control. The parameter name must correspond to the property name.

### PageDataSource

- `AccessLevel` – `EPiServer.Security.AccessLevel`
- `PageLink` – `EPiServer.Core.PageReference`
- `PageLinkProperty` – `String`
- `IncludeRootPage` – `Bool`

### SearchDataSource

- `AccessLevel` –  `EPiServer.Security.AccessLevel`
- `PageLink `– `EPiServer.Core.PageReference`
- `PageLinkProperty` – `String`
- `IncludeRootPage` – `Bool`
- `OnlyWholeWords` – `Bool`
- `SearchQuery` – `String`
- `SearchFiles` – `Bool`
- `SearchLocations` – `String`
- `MainCatalog` – `String`
- `MainScope` – `String`
- `MaxAllowHits` – `Integer`

### CategoryDataSource

- `IncludeRootCategory` – `Bool`

### FileSystemDataSource

### LanguageDataSource

### PageDefinitionDataSource

- `Dynamic` – `Bool`
- `PageTypeID` – `Integer`

### PageDefinitionTypeDataSource

- `ID` – `Integer`

### TabDefinitionDataSource

- `ID` – `Integer`

### MembershipUserDataSource

- `UserName` – `string`

### SoftLinkDataSource

- `PageLink` – `EPiServer.Core.PageReference`
- `ListReferencing` – `Bool`