Export (0) Print
Expand All

Parameter Class

Provides a mechanism that data source controls use to bind to application variables, user identities and choices, and other data. Serves as the base class for all ASP.NET parameter types.

Namespace: System.Web.UI.WebControls
Assembly: System.Web (in system.web.dll)

public class Parameter : ICloneable, IStateManager
public class Parameter implements ICloneable, IStateManager
public class Parameter implements ICloneable, IStateManager
Not applicable.

The Parameter class represents a parameter in a parameterized SQL query, a filtering expression, or a business object method call that an ASP.NET data source control uses to select, filter, or modify data. Parameter objects are contained in a ParameterCollection object. Parameter objects are evaluated at run time, to bind the values of the variables they represent to whatever method is used by a data source control to interact with data.

Use the parameter classes that are provided with ASP.NET, including ControlParameter, CookieParameter, SessionParameter, ProfileParameter, and QueryStringParameter, with data source and data-bound controls to build Web-based data applications. These classes are used by data source controls to bind specific kinds of values found in Web applications to placeholders in SQL query strings, business object method parameters, and more. For example, the ControlParameter class is used to bind any public property of a Web server control; the SessionParameter class is used to bind user session values; and the QueryStringParameter and CookieParameter classes are used to bind to values in the HttpRequest class. Extend the base Parameter class when you want to implement your own custom parameter types.

Parameter objects are very simple: they have a Name and a Type property, can be represented declaratively, and can track state across multiple HTTP requests. All parameters support a DefaultValue property, for cases when a parameter is bound to a value, but the value evaluates to a null reference (Nothing in Visual Basic) at run time.

When using a collection of Parameter objects with a data source control, their order in the collection might matter. For more information on how parameters are used, see Parameters with the SqlDataSource and AccessDataSource Controls and Parameters with the ObjectDataSource Control.

The following code example demonstrates how to use a Parameter object to bind data displayed in a ListBox control to the selected value of a DropDownList control in a declarative scenario. The ControlParameter object is added to the SelectParameters collection of the SqlDataSource control on the form, and corresponds to the "@Title" placeholder text in the SelectCommand property.

<!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 runat="server">
    <title>ASP.NET Example</title>
</head>
<body>
    <form id="form1" runat="server">

      <p><asp:dropdownlist
          id="DropDownList1"
          runat="server"
          autopostback="True">
          <asp:listitem selected="True">Sales Representative</asp:listitem>
          <asp:listitem>Sales Manager</asp:listitem>
          <asp:listitem>Vice President, Sales</asp:listitem>
      </asp:dropdownlist></p>

      <asp:sqldatasource
          id="SqlDataSource1"
          runat="server"
          connectionstring="<%$ ConnectionStrings:MyNorthwind%>"
          selectcommand="SELECT LastName FROM Employees WHERE Title = @Title">
          <selectparameters>
              <asp:controlparameter name="Title" controlid="DropDownList1" propertyname="SelectedValue"/>
          </selectparameters>
      </asp:sqldatasource>

      <p><asp:listbox
          id="ListBox1"
          runat="server"
          datasourceid="SqlDataSource1"
          datatextfield="LastName">
      </asp:listbox></p>

    </form>
  </body>
</html>

<!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 runat="server">
    <title>ASP.NET Example</title>
</head>
<body>
    <form id="form1" runat="server">

      <p><asp:DropDownList
          id="DropDownList1"
          runat="server"
          AutoPostBack="True">
          <asp:ListItem Selected="True">Sales Representative</asp:ListItem>
          <asp:ListItem>Sales Manager</asp:ListItem>
          <asp:ListItem>Vice President, Sales</asp:ListItem>
      </asp:DropDownList></p>

      <asp:SqlDataSource
          id="SqlDataSource1"
          runat="server"
          ConnectionString="Data Source=localhost;Integrated Security=SSPI;Initial Catalog=Northwind;"
          SelectCommand="SELECT LastName FROM Employees WHERE Title = @Title">
          <SelectParameters>
              <asp:ControlParameter Name="Title" ControlId="DropDownList1" PropertyName="SelectedValue"/>
          </SelectParameters>
      </asp:SqlDataSource>

      <p><asp:ListBox
          id="ListBox1"
          runat="server"
          DataSourceID="SqlDataSource1"
          DataTextField="LastName">
      </asp:ListBox></p>

    </form>
  </body>
</html>

The following code example demonstrates how to use a Parameter object to bind data displayed in a DataGrid control to the selected value of a DropDownList control in a programmatic scenario. When the page initially loads, the DropDownList control has no selected value, and the DefaultValue property of the Parameter object is used.

<%@ Page Language="C#" CodeFile="param1acs.aspx.cs" Inherits="param1acs_aspx" %>
<!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 runat="server">
    <title>ASP.NET Example</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
        <asp:DropDownList
          runat="server"
          AutoPostBack="True"
          id="DropDownList1">
            <asp:ListItem Value="USA">USA</asp:ListItem>
            <asp:ListItem Value="UK">UK</asp:ListItem>
         </asp:DropDownList>

        <asp:DataGrid
          runat="server"
          id="DataGrid1" />    
    </div>
    </form>
</body>
</html>

<%@ Page Language="VJ#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<script runat="server">
private void Page_Load(Object sender, System.EventArgs e)
{
    SqlDataSource sqlSource = new SqlDataSource("Data Source=localhost;" 
        + "Integrated Security=SSPI;Initial Catalog=Northwind;",
        "SELECT FirstName, LastName FROM Employees WHERE Country = @country;");

    ControlParameter country = new ControlParameter();
    country.set_Name("country");
    country.set_Type(System.TypeCode.String);
    country.set_ControlID("DropDownList1");
    country.set_PropertyName("SelectedValue");

    // If the DefaultValue is not set, the DataGrid does not
    // display anything on the first page load. This is because
    // on the first page load, the DropDownList has no
    // selected item, and the ControlParameter evaluates to
    // String.Empty.
    country.set_DefaultValue("USA");

    sqlSource.get_SelectParameters().Add(country);

    // Add the SqlDataSource to the page controls collection.
    get_Page().get_Controls().Add(sqlSource);

    DataGrid1.set_DataSource(sqlSource);
    DataGrid1.DataBind();
} //Page_Load
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
    <head runat="server">
    <title>ASP.NET Example</title>
</head>
<body>
        <form id="form1" runat="server">

        <asp:DropDownList
          runat="server"
          AutoPostBack="True"
          id="DropDownList1">
            <asp:ListItem Value="USA">USA</asp:ListItem>
            <asp:ListItem Value="UK">UK</asp:ListItem>
         </asp:DropDownList>

        <asp:DataGrid
          runat="server"
          id="DataGrid1" />

        </form>
    </body>
</html>

The following code-behind module is used with the previous Web Forms page.

public partial class param1acs_aspx : System.Web.UI.Page 
{
    private void Page_Load(object sender, System.EventArgs e)
    {
        SqlDataSource sqlSource = new SqlDataSource(
          ConfigurationManager.ConnectionStrings["MyNorthwind"].ConnectionString,
          "SELECT FirstName, LastName FROM Employees WHERE Country = @country;");

        ControlParameter country = new ControlParameter();
        country.Name = "country";
        country.Type = TypeCode.String;
        country.ControlID = "DropDownList1";
        country.PropertyName = "SelectedValue";

        // If the DefaultValue is not set, the DataGrid does not
        // display anything on the first page load. This is because
        // on the first page load, the DropDownList has no
        // selected item, and the ControlParameter evaluates to
        // String.Empty.
        country.DefaultValue = "USA";

        sqlSource.SelectParameters.Add(country);

        // Add the SqlDataSource to the page controls collection.
        Page.Controls.Add(sqlSource);

        DataGrid1.DataSource = sqlSource;
        DataGrid1.DataBind();
    }
}

The following code example demonstrates how to extend the Parameter class to create a new parameter type that can be used by data source controls and other controls in data-binding scenarios. A data source control can use a StaticParameter parameter to bind to the value of any object, typically a string, declared on a Web Forms page.

namespace Samples.AspNet {

  using System;
  using System.ComponentModel;
  using System.Security.Permissions;
  using System.Web;
  using System.Web.UI;
  using System.Web.UI.WebControls;

  [AspNetHostingPermission(SecurityAction.Demand, Level=AspNetHostingPermissionLevel.Minimal)]
  public class StaticParameter : Parameter {

    public StaticParameter() {
    }
    // The StaticParameter(string, object) constructor
    // initializes the DataValue property and calls the
    // Parameter(string) constructor to initialize the Name property.
    public StaticParameter(string name, object value) : base(name) {
      DataValue = value;
    }
    // The StaticParameter(string, TypeCode, object) constructor
    // initializes the DataValue property and calls the
    // Parameter(string, TypeCode) constructor to initialize the Name and
    // Type properties.
    public StaticParameter(string name, TypeCode type, object value) : base(name, type) {
      DataValue = value;
    }
    // The StaticParameter copy constructor is provided to ensure that
    // the state contained in the DataValue property is copied to new
    // instances of the class.
    protected StaticParameter(StaticParameter original) : base(original) {
      DataValue = original.DataValue;
    }

    // The Clone method is overridden to call the
    // StaticParameter copy constructor, so that the data in
    // the DataValue property is correctly transferred to the
    // new instance of the StaticParameter.
    protected override Parameter Clone() {
      return new StaticParameter(this);
    }
    // The DataValue can be any arbitrary object and is stored in ViewState.
    public object DataValue {
      get {
        return ViewState["Value"];
      }
      set {
        ViewState["Value"] = value;
      }
    }
    // The Value property is a type safe convenience property
    // used when the StaticParameter represents string data.
    // It gets the string value of the DataValue property, and
    // sets the DataValue property directly.
    public string Value {
      get {
        object o = DataValue;
        if (o == null || !(o is string))
          return String.Empty;
        return (string)o;
      }
      set {
        DataValue = value;
        OnParameterChanged();
      }
    }

    // The Evaluate method is overridden to return the
    // DataValue property instead of the DefaultValue.
    protected override object Evaluate(HttpContext context, Control control) {

      if (context.Request == null)
          return null;

      return DataValue;
    }
  }
}

package Samples.AspNet ;
import System.* ;
import System.ComponentModel.* ;
import System.Web.UI.* ;
import System.Web.UI.WebControls.* ;

public class StaticParameter extends Parameter
{
    public StaticParameter()
    {
    } //StaticParameter


    // The StaticParameter(string, object) constructor
    // initializes the DataValue property and calls the 
    // Parameter(string) constructor to initialize the Name property.
    public StaticParameter(String name, Object value)
    {
        super(name);
        set_DataValue(value);
    } //StaticParameter

    
    // The StaticParameter(string, TypeCode, object) constructor
    // initializes the DataValue property and calls the 
    // Parameter(string, TypeCode) constructor to initialize the Name and 
    // Type properties.
    public StaticParameter(String name, TypeCode type, Object value)
    {
        super(name, type);
        set_DataValue(value);
    } //StaticParameter

    
    // The StaticParameter copy constructor is provided to ensure that 
    // the state contained in the DataValue property is copied to new
    // instances of the class. 
    protected StaticParameter(StaticParameter original)
    {
        super(original);
        set_DataValue(original.get_DataValue());
    } //StaticParameter


    // The Clone method is overridden to call the 
    // StaticParameter copy constructor, so that the data in 
    // the DataValue property is correctly transferred to the 
    // new instance of the StaticParameter.
    protected Parameter Clone()
    {
        return new StaticParameter(this);
    } //Clone

    
    // The DataValue can be any arbitrary object and is stored in ViewState.
    /** @property 
     */
    public Object get_DataValue()
    {
        return get_ViewState().get_Item("Value");
    } //get_DataValue


    /** @property 
     */
    public void set_DataValue(Object value)
    {
        get_ViewState().set_Item("Value", value);
    } //set_DataValue

    
    // The Value property is a type safe convenience property 
    // used when the StaticParameter represents string data.
    // It gets the string value of the DataValue property, and
    // sets the DataValue property directly.
    /** @property 
     */
    public String get_Value()
    {
        Object o = get_DataValue();

        if (o == null || !(o instanceof String)) {
            return String.Empty;
        }

        return (String)(o);
    } //get_Value


    /** @property 
     */
    public void set_Value(String value)
    {
        set_DataValue(value);
        OnParameterChanged();
    } //set_Value

    
    // The Evaluate method is overridden to return the 
    // DataValue property instead of the DefaultValue.
    protected Object Evaluate(Control control)
    {
        return get_DataValue();
    } //Evaluate
} //StaticParameter

System.Object
  System.Web.UI.WebControls.Parameter
     Derived Classes

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 98, Windows Server 2000 SP4, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0

Community Additions

ADD
Show:
© 2014 Microsoft