Parameter Parameter Parameter Parameter Class

定義

提供一種機制,資料來源控制項可使用該機制繫結至應用程式變數、使用者識別和選項,以及其他資料。Provides a mechanism that data source controls use to bind to application variables, user identities and choices, and other data. 作為所有 ASP.NET 參數類型的基底類別。Serves as the base class for all ASP.NET parameter types.

public ref class Parameter : ICloneable, System::Web::UI::IStateManager
public class Parameter : ICloneable, System.Web.UI.IStateManager
type Parameter = class
    interface ICloneable
    interface IStateManager
Public Class Parameter
Implements ICloneable, IStateManager
繼承
ParameterParameterParameterParameter
衍生
實作

範例

下列範例顯示如何在 SQL 查詢的 W DropDownList here子句中,使用控制項的選取值。The following example shows how to use the selected value of a DropDownList control in the Where clause of a SQL query. 此範例會使用ControlParameter衍生ControlParameter自類別的類別。The example uses the ControlParameter class, which derives from the ControlParameter class.

元素會使用名為 "@Title" 的參數來定義查詢,其中的值應該是。 DropDownList1 SelectCommandThe SelectCommand element defines the query with a parameter named "@Title" where the value from DropDownList1 should go. 元素會指定 "@Title" 預留位置將SelectedValueDropDownList1控制項的屬性值取代。 ControlParameterThe ControlParameter element specifies that the "@Title" placeholder will be replaced by the value of the SelectedValue property of the DropDownList1 control. 元素會新增至SqlDataSource控制項的SelectParameters集合。 ControlParameterThe ControlParameter element is added to the SelectParameters collection of the SqlDataSource control.

<!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="<%$ 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>

下列範例與前一個範例類似,但使用程式碼而不是標記。The following example is like the previous one, but uses code instead of markup. 第一次載入頁面時, DropDownList控制項沒有選取的值, DefaultValue而且會使用Parameter物件的屬性。When the page loads the first time, 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="VB" AutoEventWireup="false" CodeFile="param1avb.aspx.vb" Inherits="param1avb_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>

下列程式碼顯示上一個範例中頁面的程式碼後置類別。The following code shows the code-behind class for the page in the previous example.

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();
    }
}
Partial Class param1avb_aspx
   Inherits System.Web.UI.Page
    Private Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs)

        Dim sqlSource As SqlDataSource

        sqlSource = New SqlDataSource(ConfigurationManager.ConnectionStrings("MyNorthwind").ConnectionString, "SELECT FirstName, LastName FROM Employees WHERE Country = @country;")
        Dim country As 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()

    End Sub 'Page_Load
End Class

下列程式碼範例示範如何擴充Parameter類別,以建立新的參數類型,讓資料來源控制項和資料系結案例中的其他控制項可以使用。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. 資料來源控制項可以使用StaticParameter參數來系結至 Web form 頁面上所宣告之任何物件的值,通常是字串。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;
    }
  }
}
Imports System.ComponentModel
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls

Namespace Samples.AspNet

<AspNetHostingPermission(SecurityAction.Demand, Level:=AspNetHostingPermissionLevel.Minimal)> _
Public Class StaticParameter
   Inherits Parameter


   Public Sub New()
   End Sub

  ' The StaticParameter(string, object) constructor
  ' initializes the DataValue property and calls the
  ' Parameter(string) constructor to initialize the Name property.
   Public Sub New(name As String, value As Object)
      MyBase.New(name)
      DataValue = value
   End Sub

   ' 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 Sub New(name As String, type As TypeCode, value As Object)
      MyBase.New(name, type)
      DataValue = value
   End Sub
   ' 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 Sub New(original As StaticParameter)
      MyBase.New(original)
      DataValue = original.DataValue
   End Sub

   ' 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 Overrides Function Clone() As Parameter
      Return New StaticParameter(Me)
   End Function

   ' The DataValue can be any arbitrary object and is stored in ViewState.
   Public Property DataValue() As Object
      Get
         Return ViewState("Value")
      End Get
      Set
         ViewState("Value") = value
      End Set
   End Property
   ' 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 Property Value() As String
      Get
         Dim o As Object = DataValue
         If o Is Nothing OrElse Not TypeOf o Is String Then
            Return String.Empty
         End If
         Return CStr(o)
      End Get
      Set
         DataValue = value
         OnParameterChanged()
      End Set
   End Property
   ' The Evaluate method is overridden to return the
   ' DataValue property instead of the DefaultValue.
   Protected Overrides Function Evaluate(context As HttpContext, control As Control) As Object
      If context Is Nothing Then
          Return Nothing
      Else
          Return DataValue
      End If
   End Function
End Class ' StaticParameter

End Namespace ' Samples.AspNet

備註

Parameter類別代表參數化 SQL 查詢、篩選運算式,或 ASP.NET 資料來源控制項用來選取、篩選或修改資料的商務物件方法呼叫。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 物件包含在 ParameterCollection 物件中。Parameter objects are contained in a ParameterCollection object. Parameter物件會在執行時間進行評估,以便將它們所代表的變數值系結至資料來源控制項用來與資料互動的任何方法。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.

使用衍生自Parameter的類別搭配資料來源和資料繫結控制項,來建立 Web 資料應用程式。Use classes that derive from Parameter with data source and data-bound controls to build Web-based data applications. 這些參數類別是由資料來源控制項用來將 Web 應用程式中的特定類型值,系結至 SQL 查詢字串中的預留位置、商務物件方法參數等等。These parameter 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. 下表列出包含在 ASP.NET 中的參數類型。The following table lists parameter types that are included in ASP.NET.

ControlParameter 系結 Web 服務器控制項的任何公用屬性。Binds any public property of a Web server control.
FormParameter 系結表單欄位。Binds a form field.
SessionParameter 系結會話狀態欄位。Binds a session-state field.
RouteParameter 系結路由 URL 參數。Binds a route URL parameter.
CookieParameter 系結 cookie 欄位。Binds a cookie field.
QueryStringParameter 系結查詢字串參數。Binds a query-string parameter.
ProfileParameter 系結設定檔欄位。Binds a profile field.

當您想Parameter要執行自己的自訂參數類型時,請擴充基類。Extend the base Parameter class when you want to implement your own custom parameter types.

Parameter物件非常簡單:具有Name Type和屬性,可以宣告方式表示,而且可以追蹤多個 HTTP 要求的狀態。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. 所有參數都支援DefaultValue屬性,適用于將參數系結至值的情況,但是值會在運行null時間評估為。All parameters support a DefaultValue property, for cases when a parameter is bound to a value, but the value evaluates to null at run time.

使用具有資料來源控制項Parameter的物件集合時,其在集合中的順序可能會很重要。When using a collection of Parameter objects with a data source control, their order in the collection might matter. 如需如何使用參數的詳細資訊,請參閱搭配使用參數與 SqlDataSource 控制項和搭配ObjectDataSource 控制項使用參數For more information on how parameters are used, see Using Parameters with the SqlDataSource Control and Using Parameters with the ObjectDataSource Control.

建構函式

Parameter() Parameter() Parameter() Parameter()

初始化 Parameter 類別預設的新執行個體。Initializes a new default instance of the Parameter class.

Parameter(Parameter) Parameter(Parameter) Parameter(Parameter) Parameter(Parameter)

使用原始、指定之執行個體的值,初始化 Parameter 類別的新執行個體。Initializes a new instance of the Parameter class with the values of the original, specified instance.

Parameter(String) Parameter(String) Parameter(String) Parameter(String)

使用指定的名稱來初始化 Parameter 類別的新執行個體。Initializes a new instance of the Parameter class, using the specified name.

Parameter(String, DbType) Parameter(String, DbType) Parameter(String, DbType) Parameter(String, DbType)

使用指定的名稱和資料庫型別,初始化 Parameter 類別的新執行個體。Initializes a new instance of the Parameter class, using the specified name and database type.

Parameter(String, DbType, String) Parameter(String, DbType, String) Parameter(String, DbType, String) Parameter(String, DbType, String)

使用指定的名稱、指定的資料庫型別,以及其 Parameter 屬性的指定值,初始化 DefaultValue 類別的新執行個體。Initializes a new instance of the Parameter class, using the specified name, the specified database type, and the specified value for its DefaultValue property.

Parameter(String, TypeCode) Parameter(String, TypeCode) Parameter(String, TypeCode) Parameter(String, TypeCode)

使用指定的名稱和型別來初始化 Parameter 類別的新執行個體。Initializes a new instance of the Parameter class, using the specified name and type.

Parameter(String, TypeCode, String) Parameter(String, TypeCode, String) Parameter(String, TypeCode, String) Parameter(String, TypeCode, String)

使用指定的名稱、指定的型別和為其 Parameter 屬性指定的字串來初始化 DefaultValue 類別的新執行個體。Initializes a new instance of the Parameter class, using the specified name, the specified type, and the specified string for its DefaultValue property.

屬性

ConvertEmptyStringToNull ConvertEmptyStringToNull ConvertEmptyStringToNull ConvertEmptyStringToNull

取得或設定值,該值指示是否應將 Parameter 物件繫結至的值轉換成 null (如果其為 Empty)。Gets or sets a value indicating whether the value that the Parameter object is bound to should be converted to null if it is Empty.

DbType DbType DbType DbType

取得或設定參數的資料庫型別。Gets or sets the database type of the parameter.

DefaultValue DefaultValue DefaultValue DefaultValue

指定參數的預設值,當呼叫 Evaluate(HttpContext, Control) 方法時,要繫結的值應是此參數未初始化的值。Specifies a default value for the parameter, should the value that the parameter is bound to be uninitialized when the Evaluate(HttpContext, Control) method is called.

Direction Direction Direction Direction

表示此 Parameter 物件是否用來將值繫結至控制項,或是這個控制項是否可用來變更該值。Indicates whether the Parameter object is used to bind a value to a control, or the control can be used to change the value.

IsTrackingViewState IsTrackingViewState IsTrackingViewState IsTrackingViewState

取得值,指出 Parameter 物件是否正在將變更儲存到它的檢視狀態。Gets a value indicating whether the Parameter object is saving changes to its view state.

Name Name Name Name

取得或設定參數的名稱。Gets or sets the name of the parameter.

Size Size Size Size

取得或設定參數的大小。Gets or sets the size of the parameter.

Type Type Type Type

取得或設定參數的型別。Gets or sets the type of the parameter.

ViewState ViewState ViewState ViewState

取得狀態資訊的字典,允許您在相同頁面的多個要求之間,儲存和還原 Parameter 物件的檢視狀態。Gets a dictionary of state information that allows you to save and restore the view state of a Parameter object across multiple requests for the same page.

方法

Clone() Clone() Clone() Clone()

傳回目前 Parameter 執行個體的複製。Returns a duplicate of the current Parameter instance.

ConvertDbTypeToTypeCode(DbType) ConvertDbTypeToTypeCode(DbType) ConvertDbTypeToTypeCode(DbType) ConvertDbTypeToTypeCode(DbType)

DbType 值轉換成對等的 TypeCode 值。Converts a DbType value to an equivalent TypeCode value.

ConvertTypeCodeToDbType(TypeCode) ConvertTypeCodeToDbType(TypeCode) ConvertTypeCodeToDbType(TypeCode) ConvertTypeCodeToDbType(TypeCode)

TypeCode 值轉換成對等的 DbType 值。Converts a TypeCode value to an equivalent DbType value.

Equals(Object) Equals(Object) Equals(Object) Equals(Object)

判斷指定的物件是否等於目前的物件。Determines whether the specified object is equal to the current object.

(Inherited from Object)
Evaluate(HttpContext, Control) Evaluate(HttpContext, Control) Evaluate(HttpContext, Control) Evaluate(HttpContext, Control)

更新並傳回 Parameter 物件的值。Updates and returns the value of the Parameter object.

GetDatabaseType() GetDatabaseType() GetDatabaseType() GetDatabaseType()

取得 DbType 值,該值等於目前 Parameter 執行個體的 CLR 型別。Gets the DbType value that is equivalent to the CLR type of the current Parameter instance.

GetHashCode() GetHashCode() GetHashCode() GetHashCode()

做為預設雜湊函式。Serves as the default hash function.

(Inherited from Object)
GetType() GetType() GetType() GetType()

取得目前執行個體的 TypeGets the Type of the current instance.

(Inherited from Object)
LoadViewState(Object) LoadViewState(Object) LoadViewState(Object) LoadViewState(Object)

將資料來源檢視還原成之前所儲存的檢視狀態。Restores the data source view's previously saved view state.

MemberwiseClone() MemberwiseClone() MemberwiseClone() MemberwiseClone()

建立目前 Object 的淺層複本 (Shallow Copy)。Creates a shallow copy of the current Object.

(Inherited from Object)
OnParameterChanged() OnParameterChanged() OnParameterChanged() OnParameterChanged()

呼叫 OnParametersChanged(EventArgs) 集合的 ParameterCollection 方法,該集合包含給定的 Parameter 物件。Calls the OnParametersChanged(EventArgs) method of the ParameterCollection collection that contains the Parameter object.

SaveViewState() SaveViewState() SaveViewState() SaveViewState()

儲存自頁面回傳至伺服器以來 Parameter 物件檢視狀態的變更。Saves the changes to the Parameter object's view state since the time the page was posted back to the server.

SetDirty() SetDirty() SetDirty() SetDirty()

標記 Parameter 物件,以便將其狀態記錄在檢視狀態中。Marks the Parameter object so its state will be recorded in view state.

ToString() ToString() ToString() ToString()

將這個執行個體的值轉換為它的相等字串表示。Converts the value of this instance to its equivalent string representation.

TrackViewState() TrackViewState() TrackViewState() TrackViewState()

會造成 Parameter 物件追蹤其檢視狀態變更,以將這些變更儲存在控制項的 ViewState 物件中,並持續存取相同頁面的其他要求。Causes the Parameter object to track changes to its view state so they can be stored in the control's ViewState object and persisted across requests for the same page.

明確介面實作

ICloneable.Clone() ICloneable.Clone() ICloneable.Clone() ICloneable.Clone()

傳回目前 Parameter 執行個體的複製。Returns a duplicate of the current Parameter instance.

IStateManager.IsTrackingViewState IStateManager.IsTrackingViewState IStateManager.IsTrackingViewState IStateManager.IsTrackingViewState

取得值,指出 Parameter 物件是否正在將變更儲存到它的檢視狀態。Gets a value indicating whether the Parameter object is saving changes to its view state.

IStateManager.LoadViewState(Object) IStateManager.LoadViewState(Object) IStateManager.LoadViewState(Object) IStateManager.LoadViewState(Object)

將資料來源檢視還原成之前所儲存的檢視狀態。Restores the data source view's previously saved view state.

IStateManager.SaveViewState() IStateManager.SaveViewState() IStateManager.SaveViewState() IStateManager.SaveViewState()

儲存自頁面回傳至伺服器以來 Parameter 物件檢視狀態的變更。Saves the changes to the Parameter object's view state since the time the page was posted back to the server.

IStateManager.TrackViewState() IStateManager.TrackViewState() IStateManager.TrackViewState() IStateManager.TrackViewState()

會造成 Parameter 物件追蹤其檢視狀態變更,以將這些變更儲存在控制項的 ViewState 物件中,並持續存取相同頁面的其他要求。Causes the Parameter object to track changes to its view state so they can be stored in the control's ViewState object and persisted across requests for the same page.

適用於

另請參閱