DataAdapter 的參數

  • 發行項

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 中目前的值。 因此會使用 SourceVersion 為 Current 的 CustomerIDSourceColumn。 @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 中現有的預設參數名稱衝突。 如果提供的名稱已經存在，便會發生例外狀況。

另請參閱