DataAdapter 的參數

發行項
03/09/2024

DbDataAdapter 具有四個屬性，可用來擷取資料來源的資料，以及將資料更新至資料來源：SelectCommand 屬性可傳回資料來源的資料，而 InsertCommand、UpdateCommand 和 DeleteCommand 屬性可用來管理在資料來源的變更。在您呼叫 SelectCommand 的 Fill 方法前，必須先設定 DataAdapter 屬性。您必須先設定 InsertCommand、UpdateCommand 或 DeleteCommand 屬性，然後再呼叫 Update 的 DataAdapter 方法，端視針對 DataTable 中的資料進行哪些變更而定。例如，如果已經加入資料列，則必須先設定 InsertCommand，才能呼叫 Update。 Update 正在處理已插入、已更新或已刪除的資料列時，DataAdapter 會使用個別的 Command 屬性來處理這項動作。已修改資料列的目前資訊會透過 Command 集合傳遞給 Parameters 物件。

當您更新資料來源的資料列時，您會呼叫 UPDATE 陳述式，此陳述式會使用唯一識別碼，來識別待更新資料表中的資料列。唯一的識別項一般是主索引鍵欄位的值。 UPDATE 陳述式所使用的參數包含唯一的識別項，以及要更新的資料行和值，如下列 Transact-SQL 陳述式所示。

UPDATE Customers SET CompanyName = @CompanyName
  WHERE CustomerID = @CustomerID

注意

參數預留位置的語法會隨資料來源而有所不同。此範例將說明 SQL Server 資料來源的保留字元。若為 System.Data.OleDb 和 System.Data.Odbc 參數，請使用問號 (?) 保留字元。

在此 Visual Basic 範例中，會針對 CustomerID 等於 @CustomerID 參數值的資料列，以 @CompanyName 參數的值來更新 CompanyName 欄位。這些參數會使用 SqlParameter 物件的 SourceColumn 屬性，從已修改的資料列擷取資訊。下列是前述範例 UPDATE 陳述式的參數。程式碼會假設變數 adapter 表示有效的 SqlDataAdapter 物件。

adapter.Parameters.Add( _  
  "@CompanyName", SqlDbType.NChar, 15, "CompanyName")  
Dim parameter As SqlParameter = _  
  adapter.UpdateCommand.Parameters.Add("@CustomerID", _  
  SqlDbType.NChar, 5, "CustomerID")  
parameter.SourceVersion = DataRowVersion.Original

Add 集合的 Parameters 方法會擷取參數的名稱、資料型別、大小 (如果此型別有大小)，以及來自 SourceColumn 的 DataTable 名稱。請注意，SourceVersion 參數的 @CustomerID 會設定為 Original。如此一來，如果已修改的 DataRow 內識別欄位的值有所變更，便可確保資料來源內的現有資料列也已經更新。在這種情況下，Original 資料列值會與資料來源中的目前值相符，而 Current 資料列值會包含已更新的值。 SourceVersion 參數的 @CompanyName 並未設定，因此會使用預設的 Current 資料列值。

注意

DataAdapter 的 Fill 作業與 DataReader 的 Get 方法都是以 .NET Framework 資料提供者傳回的型別來推斷 .NET Framework 型別。 Microsoft SQL Server、OLE DB 和 ODBC 資料型別的推斷 .NET Framework 型別和存取子方法詳述於 ADO.NET 中的資料類型對應。

Parameter.SourceColumn、Parameter.SourceVersion

SourceColumn 和 SourceVersion 可當做引數傳遞給 Parameter 建構函式 (Constructor)，或設定為現有 Parameter 的屬性。 SourceColumn 是將在其中擷取 DataColumn 值之 DataRow 的 Parameter 名稱。 SourceVersion 會指定 DataRow 用來擷取值的 DataAdapter 版本。

下表顯示可與 DataRowVersion 搭配使用的 SourceVersion 列舉值。

DataRowVersion 列舉型別	描述
`Current`	這個參數會使用資料行目前的值。此為預設值。
`Default`	此參數會使用資料行的 `DefaultValue`。
`Original`	這個參數會使用資料行的原始值。
`Proposed`	這個會參數使用建議值。

下一區段中的 SqlClient 程式碼範例會定義 UpdateCommand 的參數，其中 CustomerID 資料行將做為兩個參數的 SourceColumn 使用：@CustomerID (SET CustomerID = @CustomerID) 和 @OldCustomerID (WHERE CustomerID = @OldCustomerID)。 @CustomerID 參數是用來將 CustomerID 資料行更新為 DataRow 中目前的值。因此，會使用 CustomerID 為 SourceColumn 的 SourceVersionCurrent。 @OldCustomerID 參數是用來識別資料來源中的目前資料列。因為在資料列的 Original 版本中找到相符的資料行值，所以會使用 SourceColumn 為 CustomerID 的同一個 SourceVersion (Original)。

使用 SqlClient 參數

下列範例將示範如何建立 SqlDataAdapter 並將 MissingSchemaAction 設定為 AddWithKey，以便從資料庫中擷取其他結構描述資訊。 SelectCommand、InsertCommand、UpdateCommand 和 DeleteCommand 屬性已設定而且其對應的 SqlParameter 物件已加入至 Parameters 集合。此方法會傳回 SqlDataAdapter 物件。

public static SqlDataAdapter CreateSqlDataAdapter(SqlConnection connection)
{
    SqlDataAdapter adapter = new()
    {
        MissingSchemaAction = MissingSchemaAction.AddWithKey,

        // Create the commands.
        SelectCommand = new SqlCommand(
        "SELECT CustomerID, CompanyName FROM CUSTOMERS", connection),
        InsertCommand = new SqlCommand(
        "INSERT INTO Customers (CustomerID, CompanyName) " +
        "VALUES (@CustomerID, @CompanyName)", connection),
        UpdateCommand = new SqlCommand(
        "UPDATE Customers SET CustomerID = @CustomerID, CompanyName = @CompanyName " +
        "WHERE CustomerID = @oldCustomerID", connection),
        DeleteCommand = new SqlCommand(
        "DELETE FROM Customers WHERE CustomerID = @CustomerID", connection)
    };

    // Create the parameters.
    adapter.InsertCommand.Parameters.Add("@CustomerID",
        SqlDbType.Char, 5, "CustomerID");
    adapter.InsertCommand.Parameters.Add("@CompanyName",
        SqlDbType.VarChar, 40, "CompanyName");

    adapter.UpdateCommand.Parameters.Add("@CustomerID",
        SqlDbType.Char, 5, "CustomerID");
    adapter.UpdateCommand.Parameters.Add("@CompanyName",
        SqlDbType.VarChar, 40, "CompanyName");
    adapter.UpdateCommand.Parameters.Add("@oldCustomerID",
        SqlDbType.Char, 5, "CustomerID").SourceVersion =
        DataRowVersion.Original;

    adapter.DeleteCommand.Parameters.Add("@CustomerID",
        SqlDbType.Char, 5, "CustomerID").SourceVersion =
        DataRowVersion.Original;

    return adapter;
}

Public Function CreateSqlDataAdapter( _
    ByVal connection As SqlConnection) As SqlDataAdapter

    Dim adapter As New SqlDataAdapter()
    adapter.MissingSchemaAction = MissingSchemaAction.AddWithKey

    ' Create the commands.
    adapter.SelectCommand = New SqlCommand( _
        "SELECT CustomerID, CompanyName FROM CUSTOMERS", connection)
    adapter.InsertCommand = New SqlCommand( _
        "INSERT INTO Customers (CustomerID, CompanyName) " & _
         "VALUES (@CustomerID, @CompanyName)", connection)
    adapter.UpdateCommand = New SqlCommand( _
        "UPDATE Customers SET CustomerID = @CustomerID, CompanyName = " & _
        "@CompanyName WHERE CustomerID = @oldCustomerID", connection)
    adapter.DeleteCommand = New SqlCommand( _
        "DELETE FROM Customers WHERE CustomerID = @CustomerID", connection)

    ' Create the parameters.
    adapter.InsertCommand.Parameters.Add("@CustomerID", _
        SqlDbType.Char, 5, "CustomerID")
    adapter.InsertCommand.Parameters.Add("@CompanyName", _
        SqlDbType.VarChar, 40, "CompanyName")

    adapter.UpdateCommand.Parameters.Add("@CustomerID", _
        SqlDbType.Char, 5, "CustomerID")
    adapter.UpdateCommand.Parameters.Add("@CompanyName", _
        SqlDbType.VarChar, 40, "CompanyName")
    adapter.UpdateCommand.Parameters.Add("@oldCustomerID", _
        SqlDbType.Char, 5, "CustomerID").SourceVersion = _
        DataRowVersion.Original

    adapter.DeleteCommand.Parameters.Add("@CustomerID", _
        SqlDbType.Char, 5, "CustomerID").SourceVersion = _
        DataRowVersion.Original

    Return adapter
End Function

OleDb 參數預留位置

若為 OleDbDataAdapter 和 OdbcDataAdapter 物件，則必須使用問號 (?) 保留字元來識別參數。

Dim selectSQL As String = _  
  "SELECT CustomerID, CompanyName FROM Customers " & _  
  "WHERE CountryRegion = ? AND City = ?"  
Dim insertSQL AS String = _  
  "INSERT INTO Customers (CustomerID, CompanyName) VALUES (?, ?)"  
Dim updateSQL AS String = _  
  "UPDATE Customers SET CustomerID = ?, CompanyName = ? " & _  
  WHERE CustomerID = ?"  
Dim deleteSQL As String = "DELETE FROM Customers WHERE CustomerID = ?"

string selectSQL =
  "SELECT CustomerID, CompanyName FROM Customers " +  
  "WHERE CountryRegion = ? AND City = ?";  
string insertSQL =
  "INSERT INTO Customers (CustomerID, CompanyName) " +  
  "VALUES (?, ?)";  
string updateSQL =
  "UPDATE Customers SET CustomerID = ?, CompanyName = ? " +  
  "WHERE CustomerID = ? ";  
string deleteSQL = "DELETE FROM Customers WHERE CustomerID = ?";

參數化的查詢陳述式可定義必須建立的輸入和輸出參數。若要建立參數，請使用 Parameters.Add 方法或 Parameter 建構函式來指定資料行名稱、資料型別和大小。如果資料型別為內建 (如 Integer)，則沒有必要包含大小，或者您也可以指定預設大小。

下列程式碼範例會建立 SQL 陳述式的參數，然後填入 DataSet。

OleDb 範例

' Assumes that connection is a valid OleDbConnection object.  
Dim adapter As OleDbDataAdapter = New OleDbDataAdapter
  
Dim selectCMD AS OleDbCommand = New OleDbCommand(selectSQL, connection)  
adapter.SelectCommand = selectCMD  
  
' Add parameters and set values.  
selectCMD.Parameters.Add( _  
  "@CountryRegion", OleDbType.VarChar, 15).Value = "UK"  
selectCMD.Parameters.Add( _  
  "@City", OleDbType.VarChar, 15).Value = "London"  
  
Dim customers As DataSet = New DataSet  
adapter.Fill(customers, "Customers")

// Assumes that connection is a valid OleDbConnection object.  
OleDbDataAdapter adapter = new OleDbDataAdapter();  
  
OleDbCommand selectCMD = new OleDbCommand(selectSQL, connection);  
adapter.SelectCommand = selectCMD;  
  
// Add parameters and set values.  
selectCMD.Parameters.Add(  
  "@CountryRegion", OleDbType.VarChar, 15).Value = "UK";  
selectCMD.Parameters.Add(  
  "@City", OleDbType.VarChar, 15).Value = "London";  
  
DataSet customers = new DataSet();  
adapter.Fill(customers, "Customers");

Odbc 參數

' Assumes that connection is a valid OdbcConnection object.  
Dim adapter As OdbcDataAdapter = New OdbcDataAdapter  
  
Dim selectCMD AS OdbcCommand = New OdbcCommand(selectSQL, connection)  
adapter.SelectCommand = selectCMD  
  
' Add Parameters and set values.  
selectCMD.Parameters.Add("@CountryRegion", OdbcType.VarChar, 15).Value = "UK"  
selectCMD.Parameters.Add("@City", OdbcType.VarChar, 15).Value = "London"  
  
Dim customers As DataSet = New DataSet  
adapter.Fill(customers, "Customers")

// Assumes that connection is a valid OdbcConnection object.  
OdbcDataAdapter adapter = new OdbcDataAdapter();  
  
OdbcCommand selectCMD = new OdbcCommand(selectSQL, connection);  
adapter.SelectCommand = selectCMD;  
  
//Add Parameters and set values.  
selectCMD.Parameters.Add("@CountryRegion", OdbcType.VarChar, 15).Value = "UK";  
selectCMD.Parameters.Add("@City", OdbcType.VarChar, 15).Value = "London";  
  
DataSet customers = new DataSet();  
adapter.Fill(customers, "Customers");

注意

若未提供參數名稱給參數，則系統會為參數指定 ParameterN 的累加預設名稱，並且是從 "Parameter1" 開始。當您提供參數名稱時，建議您避免使用 ParameterN 命名慣例，因為您所提供的名稱可能會與 ParameterCollection 中現有的預設參數名稱衝突。如果提供的名稱已經存在，便會發生例外狀況。

共用方式為