Share via


SPDataSource.SelectParameters Property

Gets the parameters collection that contains parameters for selecting data.

Namespace:  Microsoft.SharePoint.WebControls
Assembly:  Microsoft.SharePoint (in Microsoft.SharePoint.dll)
Available in Sandboxed Solutions: No

Syntax

'Declaration
<PersistenceModeAttribute(PersistenceMode.InnerProperty)> _
Public ReadOnly Property SelectParameters As ParameterCollection
    Get
'Usage
Dim instance As SPDataSource
Dim value As ParameterCollection

value = instance.SelectParameters
[PersistenceModeAttribute(PersistenceMode.InnerProperty)]
public ParameterCollection SelectParameters { get; }

Property Value

Type: System.Web.UI.WebControls.ParameterCollection
A System.Web.UI.WebControls.ParameterCollection object that contains any parameters that will be used to select data.

Remarks

The parameters in the SelectParameters collection depend on the data in the data-bound control, the parameters that are specified declaratively, and the parameters that are added programmatically. The entire collection is used by the associated SPDataSourceView object to select data.

Note

The SelectParameters property is read-only. However, this does not mean that you cannot add or remove parameters from the ParameterCollection object that is returned by the property. To add a parameter to the colllection, call the Add method. To remove a parameter, call the Remove method.

Among other uses, select parameters can help the control identify and locate the data source that it will query. In general, the control understands certain well-known parameter names and values as data context identifiers. The following table lists the names of these parameters and describes what you can assign as default values. The parameter names are not case-sensitive.

Name

Description

WebID

”RootWeb” for the root Web site or “SubWeb” for the child Web site in which the page resides. (The attribute is case insensitive, so “rootweb” and “subweb” also work.) Otherwise, a string representation of a GUID such as the value of the SPWeb.ID property.

WebURL

An empty string for the root Web site. Otherwise, a string containing a server-relative URL.

ListID

A string representation of a GUID such as the value of the SPList.ID property. You can also specify the list by setting the List property.

ListName

The value of the SPList.Title property. You can also specify the list by setting the List property

ListItemGUID

A string representation of a GUID such as the value of the SPListItem.UniqueId property.

ListItemID

A string representation of an integer such as the value of the SPListItem.ID property.

RootFolder

The value of the SPFolder.Name property.

FolderID

A string representation of a GUID such as the value of the SPFolder.UniqueId property.

The type of data that the control will query determines which of these select parameters are required. For example, if you want the SPDataSource control to retrieve data from the Tasks list in the root Web site of a site collection, you must first set the DataSourceMode property to specify List mode, and then you must set parameters that identify the list and the Web site where it can be found. All of this work can be accomplished declaratively in page markup, as illustrated by following example.

<SharePoint:SPDataSource 
    ID="SPDataSource1" 
    runat="server" 
    DataSourceMode="List"
    UseInternalName="true"
    SelectCommand="<View></View>">
    <SelectParameters>
        <asp:Parameter Name="ListName" DefaultValue="Tasks" />
        <asp:Parameter Name="WebID" DefaultValue="RootWeb" />
    </SelectParameters>
</SharePoint:SPDataSource>

Examples

The following example shows page markup that links a data-bound grid control to an SPDataSource control that is configured to query the Contacts list in the root Web site of a site collection.

Notice that the SelectCommand has a Where clause that defines a filter based on the value of the Company field, and the value is specified by a substitution parameter. The SPDataSource control uses curly braces around substitution parameter names: {parametername}. In this case, the substitution parameter {CompanyName} corresponds to a QueryStringParameter that is named "CompanyName." When the page is rendered, the value of the CompanyName parameter is taken from a QueryString field on the URL and then passed to the substitution parameter in the Where clause.

<SharePoint:SPDataSource ID="SPDataSource1" runat="server" 
    DataSourceMode="List" UseInternalName="true"
    SelectCommand="<View><Query><Where><Eq><FieldRef Name='Company'/><Value Type='Text'>{CompanyName} </Value></Eq></Where></Query></View>" >
    <SelectParameters>
        <asp:Parameter Name="WebID" DefaultValue="RootWeb" />
        <asp:Parameter Name="ListName" DefaultValue="Contacts" />
        <asp:QueryStringParameter Name="CompanyName" QueryStringField="Company" DefaultValue="Contoso" />
    </SelectParameters>
</SharePoint:SPDataSource>

<asp:GridView ID="GridView1" runat="server" 
    DataSourceID="SPDataSource1" 
    AutoGenerateColumns="false">
    <Columns>
        <asp:BoundField HeaderText="First Name" DataField="FirstName" />
        <asp:BoundField HeaderText="Last Name" DataField="Title" />
        <asp:BoundField HeaderText="Job Title" DataField="JobTitle" />
   </Columns>
</asp:GridView>

The next example is almost identical, except that rather than using a QueryStringParameter, it uses an instance of the ControlParameter class. As in the previous example, the query string contains a Where clause with a substitution parameter, {CompanyName}. The difference here is that the value for substitution is provided by a DropDownList control. Notice that the AutoPostBack property of the drop-down list control is set to true so that postback to the server occurs whenever the user changes the list selection. Similarly, the EnableViewState property of the GridView control is set to false so that the control is forced to get fresh data from the SPDataSource control when the page is rendered on postback.

<SharePoint:SPDataSource ID="SPDataSource1" runat="server"
    DataSourceMode="List"
    UseInternalName="true" 
    SelectCommand="<View><Query><Where><Eq><FieldRef Name='Company'/><Value Type='Text'>{CompanyName} </Value></Eq></Where></Query></View>">
    <SelectParameters>
        <asp:Parameter Name="WebID" DefaultValue="RootWeb" />
        <asp:Parameter Name="ListName" DefaultValue="Contacts"  />
        <asp:ControlParameter Name="CompanyName" ControlID="DropDownList1" PropertyName="SelectedValue" />
    </SelectParameters>
</SharePoint:SPDataSource>

<asp:DropDownList ID="DropDownList1" runat="server" AutoPostBack="true">
    <asp:ListItem Selected="True">Adventure Works</asp:ListItem>
    <asp:ListItem>Contoso</asp:ListItem>
 </asp:DropDownList>
 <br />
 <br />
     
<asp:GridView ID="GridView1" runat="server" EnableViewState="false"
    DataSourceID="SPDataSource1" 
    AutoGenerateColumns="false">
    <Columns>
        <asp:BoundField HeaderText="First Name" DataField="FirstName" />
        <asp:BoundField HeaderText="Last Name" DataField="Title" />
        <asp:BoundField HeaderText="Job Title" DataField="JobTitle" />
    </Columns>
</asp:GridView>

See Also

Reference

SPDataSource Class

SPDataSource Members

Microsoft.SharePoint.WebControls Namespace

SelectParameters