Parameter in Datenadapterbefehlen

Artikel
09/02/2008

Aktualisiert: November 2007

Die Befehle eines Datenadapters, die in der CommandText-Eigenschaft der Objekte SelectCommand,InsertCommand, UpdateCommand und DeleteCommand definiert sind, erfordern häufig Parameter. Zur Laufzeit werden Parameter verwendet, um Werte an die SQL-Anweisungen oder die gespeicherten Prozeduren zu übergeben, die von den Befehlen dargestellt werden.

Hinweis:
In der vorherigen Version von Visual Studio wurden Datenadapter für die Kommunikation zwischen einer Anwendung und einer Datenbank verwendet. Während Datenadapter eine zentrale Komponente von .NET Framework-Datenanbieter (ADO.NET) darstellen, sind TableAdapters vom Designer generierte Komponenten, die das Verschieben von Daten zwischen der Anwendung und einer Datenbank vereinfachen. Weitere Informationen zum Verwenden von TableAdapters finden Sie unter Übersicht über TableAdapters.

In der vorherigen Version von Visual Studio wurden Datenadapter für die Kommunikation zwischen einer Anwendung und einer Datenbank verwendet. Während Datenadapter eine zentrale Komponente von .NET Framework-Datenanbieter (ADO.NET) darstellen, sind TableAdapters vom Designer generierte Komponenten, die das Verschieben von Daten zwischen der Anwendung und einer Datenbank vereinfachen. Weitere Informationen zum Verwenden von TableAdapters finden Sie unter Übersicht über TableAdapters.

Parameter werden in zwei Fällen verwendet:

Auswahlparameter: In Produktionsanwendungen wird häufig nur ein Teil der Daten in einer Datenbank abgerufen. Dazu verwenden Sie eine SQL-Anweisung oder eine gespeicherte Prozedur, die eine WHERE-Klausel mit einem Parameter für Auswahlkriterien enthält, die Sie zur Laufzeit abrufen. Beim Aktualisieren oder Löschen von Datensätzen wird außerdem eine WHERE-Klausel verwendet, die den zu löschenden Datensatz bzw. die zu löschenden Datensätze festlegt. Die in der WHERE-Klausel verwendeten Werte werden im Allgemeinen zur Laufzeit abgeleitet.

Aktualisierungsparameter: Wenn Sie einen bestehenden Datensatz aktualisieren oder einen neuen einfügen, werden die Werte für die Spalte im geänderten oder neuen Datensatz zur Laufzeit erstellt. Darüber hinaus werden Werte, die bei der Prüfung auf vollständige Parallelität verwendet werden, mithilfe von Parametern erstellt.

Hinweis:
Wenn Sie für Oracle in einer SQL-Anweisung oder gespeicherten Prozedur benannte Parameter verwenden, müssen Sie vor dem Parameternamen einen Doppelpunkt (:) einfügen. Wenn Sie allerdings auf einen benannten Parameter an einer anderen Stelle im Code verweisen (z. B. beim Aufrufen von Add), fügen Sie vor dem benannten Parameter keinen Doppelpunkt (:) ein. Der Datenprovider stellt den Doppelpunkt automatisch bereit. Weitere Informationen finden Sie unter OracleParameter-Klasse.

Wenn Sie für Oracle in einer SQL-Anweisung oder gespeicherten Prozedur benannte Parameter verwenden, müssen Sie vor dem Parameternamen einen Doppelpunkt (:) einfügen. Wenn Sie allerdings auf einen benannten Parameter an einer anderen Stelle im Code verweisen (z. B. beim Aufrufen von Add), fügen Sie vor dem benannten Parameter keinen Doppelpunkt (:) ein. Der Datenprovider stellt den Doppelpunkt automatisch bereit. Weitere Informationen finden Sie unter OracleParameter-Klasse.

Auswahlparameter

Bei der Auswahl von Datensätzen für ein Dataset schließen Sie häufig einen oder mehrere Parameter in die WHERE-Klausel ein, sodass Sie zur Laufzeit angeben können, welche Datensätze abgerufen werden sollen. Benutzer könnten z. B. eine Buchdatenbank nach einem bestimmten Themenschlüsselwort durchsuchen, das sie auf einer Webseite eingeben. Um dies zu ermöglichen können Sie als CommandText-Eigenschaft eines SelectCommand eine SQL-Anweisung wie die folgende angeben. Parameter werden entweder mit einem Platzhalter (einem Fragezeichen) oder mit einer benannten Parametervariable bezeichnet. Parameter für Abfragen in Zusammenhang mit OleDbCommand-Objekten und OdbcCommand-Objekten verwenden Fragezeichen. Abfragen, die SqlCommand-Objekte verwenden, verwenden benannte Parameter, die mit dem Symbol @ anfangen, während OracleCommand-Objekte benannte Parameter verwenden, die mit einem Doppelpunkt (:) anfangen.

Eine Abfrage, in der Platzhalter verwendet werden, könnte wie folgt aussehen:

SELECT BookId, Title, Author, Price from BOOKS
WHERE (Title LIKE ?)

Eine Abfrage, in der benannte SqlCommand-Parameter verwendet werden, könnte wie folgt aussehen:

SELECT BookId, Title, Author, Price from BOOKS
WHERE (Title LIKE @title)

Eine Abfrage, in der benannte OracleCommand-Parameter verwendet werden, könnte wie folgt aussehen:

SELECT BookId, Title, Author, Price from BOOKS
WHERE (Title LIKE :title)

In Ihrer Anwendung fordern Sie den Benutzer zur Eingabe eines Titelschlüsselworts auf. Anschließend setzen Sie den Parameterwert und führen den Befehl aus.

Hinweis:
Gelegentlich müssen Sie wahrscheinlich den gesamten Inhalt einer Datenbanktabelle abrufen, z. B. wenn Sie eine Suchtabelle einrichten. In der Regel müssen Sie jedoch nur die Daten abrufen, die für die effiziente Ausführung der Anwendung benötigt werden.

In Visual Studio können Sie mithilfe des Abfrage-Generators SQL-Anweisungen mit Parametern erstellen. Wenn Sie Elemente vom Server-Explorer ziehen, kann Visual Studio nur in einigen Fällen Parameter konfigurieren, sodass Sie die Konfiguration manuell abschließen müssen.

Aktualisierungsparameter

Unabhängig davon, ob das SelectCommand-Objekt eines Adapters einen parametrisierten Befehl enthält, ist dies bei Befehlen für die Eigenschaften UpdateCommand, InsertCommand und DeleteCommand immer der Fall.

Die Befehle für die UpdateCommand-Eigenschaft und die InsertCommand-Eigenschaft erfordern Parameter für jede Spalte in der Datenbank, die aktualisiert werden soll. Ähnlich einer gängigen Konfiguration des SelectCommand-Objekts erfordern die UpdateCommand-Anweisung und die DeleteCommand-Anweisung zudem eine parametrisierte WHERE-Klausel, die den zu aktualisierenden Datensatz identifiziert.

Stellen Sie sich eine Anwendung vor, über die Benutzer Bücher kaufen können. Beim Einkaufen verwalten die Benutzer einen Einkaufswagen, der als Datentabelle implementiert ist. In der ShoppingCart-Tabelle besitzen die Benutzer für jedes Buch, das sie kaufen möchten, einen Datensatz mit der Buch-ID und der Kunden-ID, die zusammen als Schlüssel zum Datensatz für den Einkaufswagen fungieren.

Wenn ein Benutzer ein Buch in seinen Einkaufswagen "legt", könnte die Anwendung eine SQL-Anweisung aufrufen. Im Adapter könnte die Syntax der Anweisung wie folgt aussehen:

INSERT INTO ShoppingCart
   (BookId, CustId, Quantity)
Values (?, ?, ?)

Die drei Fragezeichen sind Platzhalter für Parameter, die zur Laufzeit mit den Werten für Kunden-ID, Buch-ID und Menge ersetzt werden. Wenn Sie mit benannten Parametern arbeiten, könnte dieselbe Abfrage wie folgt aussehen:

INSERT INTO ShoppingCart
   (BookId, CustId, Quantity)
Values (@bookid, @custid, @quantity)

Wenn der Benutzer sich dazu entschließt, etwas (z. B. die Menge) an einem Posten in seinem Einkaufswagen zu ändern, könnte die Anwendung eine SQL UPDATE-Anweisung aufrufen. Die Syntax der Anweisung könnte wie folgt aussehen:

UPDATE ShoppingCart
   SET (BookId = ?, CustId = ?, Quantity = ?)
WHERE (BookId = ? AND CustId = ?)

Wenn Sie mit benannten Parametern arbeiten, könnte sie wie folgt aussehen:

UPDATE ShoppingCart
   SET (BookId = @bookid, CustId = @custid, Quantity = @quantity)
WHERE (BookId = @bookid AND CustId = @custid)

In dieser Anwendung werden die Parameter in der SET-Klausel durch aktualisierte Werte für den geänderten Datensatz ersetzt. Die Parameter in der WHERE-Klausel identifizieren den zu aktualisierenden Datensatz und werden durch die ursprünglichen Werte aus dem Datensatz ersetzt.

Es könnte auch sein, dass ein Benutzer einen Posten aus seinem Einkaufswagen entfernt. In diesem Fall würde die Anwendung eine SQL DELETE-Anweisung mit einer Syntax ähnlich der Folgenden aufrufen, sofern Sie Parameterplatzhalter verwenden:

DELETE FROM ShoppingCart
WHERE (BookId = ? AND CustId = ?)

Oder mit folgender Syntax, wenn Sie mit benannten Parametern arbeiten:

DELETE FROM ShoppingCart
WHERE (BookId = @bookid AND CustId = @custid)

Parameterauflistung und Parameterobjekte

Damit Sie Parameterwerte zur Laufzeit übergeben können, unterstützen alle vier Befehlsobjekte für Datenadapter eine Parameters-Eigenschaft. Die Eigenschaft enthält eine Auflistung einzelner Parameterobjekte, die eine Eins-zu-Eins-Entsprechung zu den Platzhaltern in einer Anweisung darstellen.

Die folgende Tabelle zeigt die entsprechende Parameterauflistung für jeden Datenadapter an:

Datenadapter	Parameterauflistung
SqlDataAdapter	SqlParameterCollection
OleDbDataAdapter	OleDbParameterCollection
OdbcDataAdapter	OdbcParameterCollection
OracleDataAdapter	OracleParameterCollection

Hinweis:
Wenn Sie für Oracle in einer SQL-Anweisung oder gespeicherten Prozedur benannte Parameter verwenden, müssen Sie vor dem Parameternamen einen Doppelpunkt (:) einfügen. Wenn Sie allerdings auf einen benannten Parameter an einer anderen Stelle im Code verweisen (z. B. beim Aufrufen von Add), fügen Sie vor dem benannten Parameter keinen Doppelpunkt (:) ein. Der .NET Framework-Datenprovider für Oracle stellt den Doppelpunkt automatisch bereit.

Wenn Sie für Oracle in einer SQL-Anweisung oder gespeicherten Prozedur benannte Parameter verwenden, müssen Sie vor dem Parameternamen einen Doppelpunkt (:) einfügen. Wenn Sie allerdings auf einen benannten Parameter an einer anderen Stelle im Code verweisen (z. B. beim Aufrufen von Add), fügen Sie vor dem benannten Parameter keinen Doppelpunkt (:) ein. Der .NET Framework-Datenprovider für Oracle stellt den Doppelpunkt automatisch bereit.

Wenn Sie die Parameterauflistung verwenden, müssen Sie einen SQL-Befehl als Zeichenfolge mit Laufzeitwerten nicht manuell erstellen. Außerdem können Sie die Typüberprüfung in Ihren Parametern nutzen.

Wenn Sie den Datenadapter-Konfigurations-Assistenten zum Konfigurieren des Adapters verwenden, wird die Parameterauflistung automatisch für alle vier Adapterbefehle eingerichtet und konfiguriert. Wenn Sie Elemente vom Server-Explorer auf das Formular oder die Komponente ziehen, kann Visual Studio folgende Konfigurationen ausführen:

Wenn Sie eine Tabelle oder einige Spalten auf den Designer ziehen, generiert Visual Studio ein SelectCommand-Objekt (genau genommen eine SQL SELECT-Anweisung) ohne Parameter sowie die parametrisierten Objekte UpdateCommand, InsertCommand und DeleteCommand. Wenn die SelectCommand-Objektanweisung Parameter aufweisen soll, müssen Sie die Parameter manuell konfigurieren.
Wenn Sie eine gespeicherte Prozedur auf den Designer ziehen, generiert Visual Studio ein SelectCommand-Objekt mit den für die gespeicherte Prozedur erforderlichen Parametern. Wenn Sie die Objekte UpdateCommand, InsertCommand und DeleteCommand benötigen, müssen Sie diese allerdings zusammen mit ihren Parametern selbst konfigurieren.

Wenn Sie parametrisierte Abfragen für den Adapter erstellen möchten, sollten Sie den Datenadapter-Konfigurations-Assistenten verwenden. Wenn Sie jedoch Parameter benötigen, können Sie diese über das Eigenschaftenfenster manuell konfigurieren.

Struktur der Parameterauflistung

Die Elemente in der Parameterauflistung eines Befehls bilden eine Eins-zu-Eins-Entsprechung zu Parametern, die für das entsprechende Befehlsobjekt erforderlich sind. Wenn es sich bei einem Befehlsobjekt um eine SQL-Anweisung handelt, entsprechen die in der Auflistung enthaltenen Elemente den Platzhaltern (Fragezeichen) in der Anweisung. Die folgende UPDATE-Anweisung erfordert eine Auflistung mit fünf Parameterelementen:

UPDATE ShoppingCart
   SET (BookId = ?, CustId = ?, Quantity = ?)
WHERE (BookId = ? AND CustId = ?)

Hier ist dieselbe Anweisung mit benannten Parametern.

UPDATE ShoppingCart
   SET (BookId = @bookid, CustId = @custid, Quantity = @quantity)
WHERE (BookId = @bookid AND CustId = @custid)

Wenn das Befehlsobjekt auf eine gespeicherte Prozedur verweist, wird die Anzahl der Parameterelemente in der Auflösung durch die Prozedur selbst bestimmt. Die Parameter entsprechen möglicherweise nicht genau den Platzhaltern in einer SQL-Anweisung.

In gespeicherten Prozeduren können Parameter auch Namen besitzen. In diesem Fall ist die Position eines Parameters in der Auflistung nicht wichtig. Stattdessen besitzt jedes Parameterelement in der Auflistung eine ParameterName-Eigenschaft, über die es dem entsprechenden Parameter in der gespeicherten Prozedur zugeordnet wird.

Wenn Sie die Parameterauflistung manuell konfigurieren, müssen Sie genau wissen, welche Parameter von der gespeicherten Prozedur benötigt werden. Viele gespeicherte Prozeduren geben einen Wert zurück. Wenn dies der Fall ist, wird der Wert an Ihre Anwendung in der Parameterauflistung zurückgegeben. Das bedeutet, dass Sie dies zulassen müssen. Außerdem enthalten manche gespeicherten Prozeduren mehrere SQL-Anweisungen. Sie müssen daher sicherstellen, dass die Parameterauflistung alle Werte widerspiegelt, die an alle Anweisungen in der Prozedur übergeben werden.

Wenn Parameter keinen Namen besitzen (wie in gespeicherten Prozeduren), werden die Elemente in der Auflistung den vom Befehl benötigten Parametern nach der Position zugeordnet. Wenn der Befehl eine gespeicherte Prozedur ist und einen Wert zurückgibt, wird das erste Element in der Auflistung (Element 0) für diesen Rückgabewert reserviert.

Sie können daher über die Indexposition in der Auflistung auf einzelne Parameterobjekte verweisen. Allerdings unterstützen Parameterobjekte auch eine ParameterName-Eigenschaft, die die Möglichkeit bietet, auf die verschiedenen Parameter unabhängig von deren Reihenfolge zu verweisen. Die beiden folgenden Anweisungen könnten z. B. äquivalent sein (vorausgesetzt, der zweite Parameter in der Auflistung hat den Namen Title_Keyword):

' Encloses the keyword in SQL wildcard characters.
titleKeyword = "%" & txtTitleKeyword.Text & "%"
OleDbDataAdapter1.SelectCommand.Parameters(1).Value = titleKeyword
OleDbDataAdapter1.SelectCommand.Parameters("Title_Keyword").Value = titleKeyword

// Encloses the keyword in SQL wildcard characters.
string titleKeyword = "%" + txtTitleKeyword.Text + "%";
this.OleDbDataAdapter1.SelectCommand.Parameters[1].Value = titleKeyword;
this.OleDbDataAdapter1.SelectCommand.Parameters["Title_Keyword"].Value = titleKeyword;

Die Verwendung eines Parameternamens ist im Allgemeinen viel besser als der Verweis auf Parameter über einen Indexwert, weil sich der Verwaltungsaufwand reduziert, wenn die Anzahl der Parameter geändert wird. Sie müssen sich dann nicht merken, ob eine gespeicherte Prozedur einen Wert zurückgibt. Verweise auf Parameter nach Namen sind zwar mit etwas mehr Aufwand verbunden als Verweise über den Indexwert, der Mehraufwand wird aber durch eine komfortablere Programmierung und eine einfachere Verwaltung der Anwendung ausgeglichen.

Erstellen von Parameterwerten

Der Wert eines Parameters kann auf zwei Arten erstellt werden:

Durch explizites Festlegen der Value-Eigenschaft eines Parameters.
Durch Zuordnen der Parameter zu Spalten in einer Dataset-Tabelle, sodass die Werte bei Bedarf aus Datenzeilen extrahiert werden können.

Sie legen den Parameterwert für Auswahlparameter explizit fest, wenn Sie ein Dataset mit Daten füllen oder einen Befehl aufrufen. Die Anwendung im obigen Beispiel mit der Suche nach Büchern könnte ein Textfeld besitzen, in das Benutzer ein Titelschlüsselwort eingeben. Sie würden den Wert des Parameters in diesem Fall explizit auf den Text des Textfelds setzen, bevor Sie die Fill-Methode des Adapters aufrufen. Der dafür erforderliche Code könnte dann wie unten gezeigt aussehen. In diesem Beispiel wird der Inhalt eines Textfelds vor dem Füllen eines Datasets als Parameter erstellt.

' Encloses the keyword in SQL wildcard characters.
titleKeyword = "%" & txtTitleKeyword.Text & "%"
OleDbDataAdapter1.SelectCommand.Parameters("Title_Keyword").Value = titleKeyword
OleDbDataAdapter1.Fill(dsAuthors1)

// Encloses the keyword in SQL wildcard characters.
titleKeyword = "%" + txtTitleKeyword.Text + "%";
this.OleDbDataAdapter1.SelectCommand.Parameters["Title_Keyword"].Value = titleKeyword;
this.OleDbDataAdapter1.Fill(dsAuthors1);

Bei Aktualisierungen werden zugeordnete Parameterwerte verwendet. Wenn Sie die Update-Methode eines Adapters aufrufen, durchläuft die Methode die Datensätze in einer Dataset-Tabelle und nimmt die entsprechende Aktualisierung (Aktualisieren, Einfügen, Löschen) für jeden einzelnen Datensatz vor. In diesem Fall stehen die Parameterwerte bereits als Spalten in den Datensätzen des Datasets zur Verfügung. Wenn der Aktualisierungsprozess z. B. einen neuen Datensatz in der Dataset-Tabelle erreicht, also einen Datensatz, für den eine INSERT-Anweisung in der Datenbank aufgerufen werden muss, können die Werte für die VALUE-Klausel der INSERT-Anweisung direkt aus dem Datensatz gelesen werden.

Dies sind typische Szenarios, aber nicht die einzigen. Gespeicherte Prozeduren geben manchmal Daten über out-Parameter oder über den Rückgabewert der Prozedur zurück. In einem solchen Fall müssen die zurückgegebenen Werte den Spalten in einer Dataset-Tabelle zugeordnet werden.

Aktualisierungsparameter können auch explizit festgelegt werden. Der Adapter unterstützt ein RowUpdating-Ereignis, das bei jedem Aktualisierungsvorgang für eine Zeile aufgerufen wird. Sie können einen Handler für dieses Ereignis erstellen und die Parameterwerte dort festlegen. Damit erhalten Sie genaue Kontrolle über die Parameterwerte und können Prozesse ausführen. So können Sie z. B. Parameterwerte dynamisch erstellen, bevor diese in den Datensatz der Datenbank geschrieben werden.