Parameter 類別

參考

定義

命名空間:: System.Web.UI.WebControls

組件:: System.Web.dll

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

提供一種機制，資料來源控制項可使用該機制繫結程序至應用程式變數、使用者識別和選項，以及其他資料。作為所有 ASP.NET 參數類型的基底類別。

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

繼承: Object
Parameter

衍生: System.Web.DynamicData.DynamicControlParameter

System.Web.DynamicData.DynamicQueryStringParameter

System.Web.UI.WebControls.ControlParameter

System.Web.UI.WebControls.CookieParameter

System.Web.UI.WebControls.FormParameter

更多…

實作: ICloneable IStateManager

範例

下列範例示範如何在 SQL 查詢的 Where 子句中使用控件的選取值DropDownList。此範例會 ControlParameter 使用衍生自類別的 ControlParameter 類別。

元素 SelectCommand 會使用名為「@Title」的參數來定義查詢，其中應該會傳回值 DropDownList1 。元素 ControlParameter 會指定控件的 SelectedValue 屬性值 DropDownList1 將取代「@Title」佔位元。專案 ControlParameter 會新增至 SelectParameters 控件的 SqlDataSource 集合。

<!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>

下列範例與上一個範例類似，但會使用程式代碼而非標記。第一次載入頁面時， DropDownList 控件沒有選取的值，而且 DefaultValue 會使用對象的屬性 Parameter 。

<%@ 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>

下列程式代碼顯示上一個範例中頁面的程式代碼後置類別。

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
End Class

下列程式代碼範例示範如何擴充 Parameter 類別，以建立新的參數類型，供數據源控件和其他控件在數據系結案例中使用。數據源控件可以使用 StaticParameter 參數係結至任何物件的值，通常是在Web Forms 頁面上宣告的字串。

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

End Namespace ' Samples.AspNet

備註

類別 Parameter 代表參數化 SQL 查詢、篩選表示式或商務物件方法呼叫中的參數，ASP.NET 數據源控件用來選取、篩選或修改數據。 Parameter 物件包含在 ParameterCollection 物件中。 Parameter 物件會在運行時間進行評估，以將它們所代表之變數的值系結至數據源控件用來與數據互動的任何方法。

使用衍生自 Parameter 的類別搭配數據源和數據系結控件來建置 Web 型數據應用程式。數據源控件會使用這些參數類別，將 Web 應用程式中找到的特定值種類系結至 SQL 查詢字串中的佔位元、商業物件方法參數等等。下表列出包含在 ASP.NET 中的參數類型。


ControlParameter	系結 Web 伺服器控制件的任何公用屬性。
FormParameter	系結表單域。
SessionParameter	系結會話狀態欄位。
RouteParameter	系結路由 URL 參數。
CookieParameter	系結 Cookie 欄位。
QueryStringParameter	系結查詢字串參數。
ProfileParameter	系結配置檔欄位。

當您想要實作自己的自定義參數類型時，請擴充基 Parameter 類。

Parameter 物件非常簡單：它們具有 Name 和 Type 屬性、可以宣告方式表示，而且可以追蹤多個 HTTP 要求的狀態。如果參數係結至值，但值在null運行時間評估為時，所有參數都支持 DefaultValue 屬性。

搭配數據源控件使用物件的集合 Parameter 時，集合中的順序可能很重要。如需如何使用參數的詳細資訊，請參閱搭配 SqlDataSource 控件使用參數和搭配 ObjectDataSource 控制項使用參數。

建構函式

Parameter()	初始化 Parameter 類別預設的新執行個體。
Parameter(Parameter)	使用原始、指定之執行個體的值，初始化 Parameter 類別的新執行個體。
Parameter(String)	使用指定的名稱來初始化 Parameter 類別的新執行個體。
Parameter(String, DbType)	使用指定的名稱和資料庫型別，初始化 Parameter 類別的新執行個體。
Parameter(String, DbType, String)	使用指定的名稱、指定的資料庫型別，以及其 Parameter 屬性的指定值，初始化 DefaultValue 類別的新執行個體。
Parameter(String, TypeCode)	使用指定的名稱和型別來初始化 Parameter 類別的新執行個體。
Parameter(String, TypeCode, String)	使用指定的名稱、指定的型別和為其 Parameter 屬性指定的字串來初始化 DefaultValue 類別的新執行個體。

屬性

ConvertEmptyStringToNull	取得或設定值，該值指示是否應將 Parameter 物件繫結至的值轉換成 `null` (如果其為 Empty)。
DbType	取得或設定參數的資料庫型別。
DefaultValue	指定參數的預設值，當呼叫 Evaluate(HttpContext, Control) 方法時，要繫結的值應是此參數未初始化的值。
Direction	表示此 Parameter 物件是否用來將值繫結至控制項，或是這個控制項是否可用來變更該值。
IsTrackingViewState	取得值，指出 Parameter 物件是否正在將變更儲存到它的檢視狀態。
Name	取得或設定參數的名稱。
Size	取得或設定參數的大小。
Type	取得或設定參數的類型。
ViewState	取得狀態資訊的字典，允許您在相同頁面的多個要求之間，儲存和還原 Parameter 物件的檢視狀態。

方法

Clone()	傳回目前 Parameter 執行個體的複製。
ConvertDbTypeToTypeCode(DbType)	將 DbType 值轉換成對等的 TypeCode 值。
ConvertTypeCodeToDbType(TypeCode)	將 TypeCode 值轉換成對等的 DbType 值。
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
Evaluate(HttpContext, Control)	更新並傳回 Parameter 物件的值。
GetDatabaseType()	取得 DbType 值，該值等於目前 Parameter 執行個體的 CLR 型別。
GetHashCode()	做為預設雜湊函式。 (繼承來源 Object)
GetType()	取得目前執行個體的 Type。 (繼承來源 Object)
LoadViewState(Object)	將資料來源檢視還原成之前所儲存的檢視狀態。
MemberwiseClone()	建立目前 Object 的淺層複製。 (繼承來源 Object)
OnParameterChanged()	呼叫 OnParametersChanged(EventArgs) 集合的 ParameterCollection 方法，該集合包含給定的 Parameter 物件。
SaveViewState()	儲存自頁面回傳至伺服器以來 Parameter 物件檢視狀態的變更。
SetDirty()	標記 Parameter 物件，以便將其狀態記錄在檢視狀態中。
ToString()	將這個執行個體的值轉換為它的相等字串表示。
TrackViewState()	會造成 Parameter 物件追蹤其檢視狀態變更，以將這些變更儲存在控制項的 ViewState 物件中，並持續存取相同頁面的其他要求。

明確介面實作

ICloneable.Clone()	傳回目前 Parameter 執行個體的複製。
IStateManager.IsTrackingViewState	取得值，指出 Parameter 物件是否正在將變更儲存到它的檢視狀態。
IStateManager.LoadViewState(Object)	將資料來源檢視還原成之前所儲存的檢視狀態。
IStateManager.SaveViewState()	儲存自頁面回傳至伺服器以來 Parameter 物件檢視狀態的變更。
IStateManager.TrackViewState()	會造成 Parameter 物件追蹤其檢視狀態變更，以將這些變更儲存在控制項的 ViewState 物件中，並持續存取相同頁面的其他要求。

適用於

共用方式為

Parameter 類別

定義

範例

備註

建構函式

屬性

方法

明確介面實作

適用於

另請參閱

其他資源