DataAdapter 参数

项目
07/15/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 示例中，CompanyName 字段使用 CustomerID 等于 @CustomerID 参数值的行中的 @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 行值。

备注

对于 Fill 的 DataAdapter 操作和 Get 的 DataReader 方法，都将从 .NET Framework 数据提供程序数据提供程序中返回的类型来推断 .NET Framework 类型。 ADO.NET 数据类型映射中介绍了 Microsoft SQL Server、OLE DB 和 ODBC 数据类型的推断 .NET Framework 类型。

Parameter.SourceColumn，Parameter.SourceVersion

SourceColumn 和 SourceVersion 可以作为自变量传递给 Parameter 构造函数，也可以设置为现有 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 的 CustomerID SourceColumn。 @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");

注意

如果未为参数提供参数名称，则该参数将使用从“Parameter1”开始递增的默认名称 ParameterN。建议在提供参数名称时避免使用 ParameterN 命名约定，因为所提供的名称可能会与 ParameterCollection 中现有的默认参数名称发生冲突。如果提供的名称已经存在，将引发异常。

通过