'DataAdapter'-Parameter (ADO.NET)

Artikel
05/20/2011

Der DbDataAdapter verfügt über vier Eigenschaften, die zum Abrufen von Daten aus einer Datenquelle und zum Aktualisieren der Daten in der Datenquelle verwendet werden: die SelectCommand-Eigenschaft gibt die Daten aus der Datenquelle zurück, und die Eigenschaften InsertCommand, UpdateCommand und DeleteCommand dienen zum Verwalten von Änderungen in der Datenquelle. Die SelectCommand-Eigenschaft muss vor dem Aufrufen der Fill-Methode des DataAdapter festgelegt werden. Die Eigenschaft InsertCommand, UpdateCommand oder DeleteCommand (abhängig von der Art der Änderungen in der DataTable) muss vor dem Aufruf der Update-Methode des DataAdapter festgelegt werden. Wenn beispielsweise Zeilen hinzugefügt wurden, muss vor dem Aufrufen von Update das InsertCommand festgelegt werden. Wenn Update eine eingefügte, aktualisierte oder gelöschte Zeile verarbeitet, verwendet der DataAdapter die entsprechende Command-Eigenschaft, um die Aktion zu verarbeiten. Aktuelle Informationen zur geänderten Zeile werden über die Parameters-Auflistung an das Command-Objekt übergeben.

Rufen Sie zum Aktualisieren einer Zeile in der Datenquelle die UPDATE-Anweisung auf, die mit einem eindeutigen Bezeichner die Zeile in der Tabelle identifiziert, die aktualisiert werden soll. Der eindeutige Bezeichner ist im Allgemeinen der Wert eines Primärschlüsselfelds. Die UPDATE-Anweisung verwendet Parameter, die sowohl den eindeutigen Bezeichner als auch die Spalten und Werte enthalten, die aktualisiert werden sollen, wie in der folgenden Transact-SQL-Anweisung dargestellt.

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

Hinweis
Die Syntax für Parameterplatzhalter hängt von der jeweiligen Datenquelle ab.Dieses Beispiel zeigt Platzhalter für eine SQL Server-Datenquelle.Verwenden Sie Fragezeichen (?) als Platzhalter für den System.Data.OleDb-Parameter und den System.Data.Odbc-Parameter.

In diesem Visual Basic-Beispiel wird das CompanyName-Feld mit dem Wert des @CompanyName-Parameters für die Zeile aktualisiert, in der CustomerID dem Wert des @CustomerID -Parameters entspricht. Die Parameter rufen mithilfe der SourceColumn-Eigenschaft des SqlParameter-Objekts Informationen aus der geänderten Zeile ab. Im Folgenden finden Sie die Parameter für das vorherige Beispiel einer UPDATE-Anweisung. Der Code geht davon aus, dass die adapter-Variable für ein gültiges SqlDataAdapter-Objekt steht.

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

Die Add-Methode der Parameters-Auflistung nimmt den Namen des Parameters, den Datentyp, die Größe (wenn für den Typ zutreffend) und den Namen der SourceColumn aus der DataTable an. Beachten Sie, dass der SourceVersion-Wert des @CustomerID-Parameters Original lautet. Dadurch wird sichergestellt, dass die vorhandene Zeile in der Datenquelle aktualisiert wird, wenn sich der Wert der ID-Spalte oder -Spalten in der geänderten DataRow geändert hat. In diesem Fall stimmt der Original-Zeilenwert mit dem aktuellen Wert in der Datenquelle überein, und der Current-Zeilenwert enthält den aktualisierten Wert. Die SourceVersion für den @CompanyName-Parameter ist nicht festgelegt, und es wird der Standardwert, nämlich der Current-Zeilenwert, verwendet.

Hinweis
Sowohl bei den Fill-Vorgängen des DataAdapter als auch bei den Get-Methoden des DataReader wird der .NET Framework-Typ von dem Typ hergeleitet, der vom .NET Framework-Datenanbieter zurückgegeben wird.Die hergeleiteten .NET Framework-Typen und Accessormethoden für Datentypen von Microsoft SQL Server, OLE DB und ODBC werden in Datentypzuordnungen in ADO.NET erläutert.

Parameter.SourceColumn, Parameter.SourceVersion

Die SourceColumn und die SourceVersion können als Argumente an den Parameter-Konstruktor übergeben oder als Eigenschaften eines vorhandenen Parameter festgelegt werden. Die SourceColumn ist der Name der DataColumn aus der DataRow, aus der der Wert des Parameter abgerufen wird. Die SourceVersion gibt die DataRow-Version an, die der DataAdapter zum Abrufen des Werts verwendet.

Die folgende Tabelle zeigt die DataRowVersion-Enumerationswerte an, die für die Verwendung mit SourceVersion zur Verfügung stehen.

DataRowVersion-Enumeration	Beschreibung
Current	Der Parameter verwendet den aktuellen Wert der Spalte. Dies ist die Standardeinstellung.
Default	Der Parameter verwendet den DefaultValue der Spalte.
Original	Der Parameter verwendet den ursprünglichen Wert der Spalte.
Proposed	Der Parameter verwendet einen vorgeschlagenen Wert.

Das SqlClient-Codebeispiel im nächsten Abschnitt definiert einen Parameter für einen UpdateCommand, bei dem die CustomerID-Spalte als SourceColumn für die folgenden beiden Parameter verwendet wird: @CustomerID (SET CustomerID = @CustomerID) und @OldCustomerID (WHERE CustomerID = @OldCustomerID). Der @CustomerID-Parameter wird zum Aktualisieren der CustomerID-Spalte auf den aktuellen Wert in der DataRow verwendet. Daraufhin wird die CustomerID-SourceColumn mit einer SourceVersion von Current verwendet. Der @OldCustomerID-Parameter wird dazu verwendet, die aktuelle Zeile in der Datenquelle anzugeben. Da sich der passende Spaltenwert in der Original-Version der Zeile befindet, wird die gleiche SourceColumn (CustomerID) mit einer SourceVersion von Original verwendet.

Verwenden von "SqlClient"-Parametern

Im folgenden Beispiel wird gezeigt, wie Sie einen SqlDataAdapter erstellen und für die MissingSchemaAction AddWithKey festlegen können, um zusätzliche Schemainformationen aus der Datenbank abzurufen. Die Eigenschaften SelectCommand, InsertCommand, UpdateCommand und DeleteCommand werden festgelegt, und die zugehörigen SqlParameter-Objekte werden der Parameters-Auflistung hinzugefügt. Die Methode gibt ein SqlDataAdapter-Objekt zurück.

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

    Dim adapter As SqlDataAdapter = 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

public static SqlDataAdapter CreateSqlDataAdapter(SqlConnection connection)
{
    SqlDataAdapter adapter = 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;
}

"OleDb"-Parameterplatzhalter

Beim OleDbDataAdapter-Objekt und beim OdbcDataAdapter-Objekt müssen Sie das Fragezeichen (?) als Platzhalter zum Identifizieren der Parameter verwenden.

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 = ?";

Die parametrisierten Abfrageanweisungen definieren, welche Eingabe- und Ausgabeparameter erstellt werden müssen. Verwenden Sie zum Erstellen eines Parameters die Parameters.Add-Methode oder den Parameter-Konstruktor, um den Spaltennamen, den Datentyp und die Größe anzugeben. Für systeminterne Datentypen, wie Integer, muss die Größe nicht angegeben werden. Sie können auch die Standardgröße angeben.

Das folgende Codebeispiel erstellt die Parameter für eine SQL-Anweisung und füllt dann ein DataSet.

OLE DB-Beispiel

' 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-Parameter

' 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");

Hinweis
Wenn für einen Parameter kein Parametername angegeben ist, erhält der Parameter einen Standardnamen der Form "ParameterN". Der erste Parameter heißt damit "Parameter1", der zweite "Parameter2" usw.Allerdings wird davon abgeraten, die Benennungskonvention "ParameterN" zu verwenden, wenn Sie einen Parameternamen bereitstellen, da der so bereitgestellte Name möglicherweise mit dem Standardparameternamen in der ParameterCollection in Konflikt geraten kann.Wenn der angegebene Name bereits vorhanden ist, wird eine Ausnahme ausgelöst.

Wenn für einen Parameter kein Parametername angegeben ist, erhält der Parameter einen Standardnamen der Form "ParameterN". Der erste Parameter heißt damit "Parameter1", der zweite "Parameter2" usw.Allerdings wird davon abgeraten, die Benennungskonvention "ParameterN" zu verwenden, wenn Sie einen Parameternamen bereitstellen, da der so bereitgestellte Name möglicherweise mit dem Standardparameternamen in der ParameterCollection in Konflikt geraten kann.Wenn der angegebene Name bereits vorhanden ist, wird eine Ausnahme ausgelöst.