1.4.4. Параметры команд объекта DataAdapter
Команды адаптера данных DataAdapter определены в свойстве CommandText объектов SelectCommand, InsertCommand, UpdateCommand и DeleteCommand. Обычно в этих командах содержится такие элементы, как параметры. Ведь заранее неизвестно, например, какие записи будет удалять или обновлять пользователь, это станет ясно только в процессе работы приложения. Причем в каждом сеансе набор этих записей будет различным.
Можно выделить два типа параметров.
□ Параметры выборки. В реальных приложениях обычно требуется выбрать только некоторое подмножество записей из базы данных. Чтобы осуществить это, используется SQL-запрос или хранимая процедура, которые включают предложение where с параметрами — критериями выборки. Кроме того, когда пользователь модифицирует или удаляет запись, используется предложение where, в котором параметры определяют, какие записи необходимо модифицировать или удалить. Значения параметров становятся известными только во время выполнения приложения, поэтому разработчик не может их заранее однозначно задать в программе.
□ Параметры обновления. Когда в приложении модифицируются существующие записи или добавляются новые, то колонки (поля) в модифицируемых или добавляемых записях, должны получить новые значения. Чаще величина этих значений также становится известной только во время выполнения приложения.
Параметры выборки
Когда требуется выбрать ограниченное подмножество записей, чтобы заполнить таблицу в объекте DataSet, в предложение where SQL-запроса включается один или более параметров, значения которых определяются только во время выполнения приложения. Например, пользователь хочет найти в базе данных книгу, название которой он ввел в текстовом поле Web-формы. Для этого вы должны в свойстве CommandText объекта SelectCommand написать SQL-запрос. Параметры запроса можно определить следующими способами: вопросительным знаком (?) или переменной с именем параметра (перед именем параметра должен стоять знак @). Для обозначения параметров в запросах на основе объектов OleDbCommand используются вопросительные знаки; в запросах на основе объектов SqlCommand использует переменные с именем параметра.
Текст запроса для объекта OleDbCommand может выглядеть следующим образом:
SELECT BookId, Title, Author, Price FROM BOOKS WHERE (Title LIKE ?)
Соответственно текст запроса для объекта SqlCommand:
SELECT BookId, Title, Author, Price FROM BOOKS WHERE (Title LIKE @title)
В приложении вы даете возможность пользователю ввести значение параметра запроса (наименование книги — title), например, в текстовом поле, затем присваиваете полученное значение параметру:
OleDbDataAdapterl.Selectcommand.Parameters("title").Value=txtTitle.Text
После этого запускаете команду на выполнение.
В Visual Studio можно формировать SQL-запросы с параметрами, используя встроенное средство Query Builder (построитель запросов).
Параметры обновления
Если объект SelectCommand адаптера данных может иметь или не иметь параметры, то объекты UpdateCommand, InsertCommand и DeleteCommand всегда имеют параметры.
Такие команды как UpdateCommand и InsertCommand всегда требуют наличия параметра для каждого столбца, который будет модифицирован. Кроме того, UpdateCommand И DeleteCommand требуют наличия параметра и в предложения where, который будет идентифицировать те записи, в которые будут вноситься изменения.
Представим приложение, с помощью которого пользователи могут заказывать и покупать книги. Как и обычные покупатели в магазине, они имеют тележку для выбранных книг, которая в приложении реализована в виде таблицы данных — ShoppingCart. В таблице ShoppingCart пользователи заводят новые записи под каждую книгу, которую они хотят купить, с атрибутами: идентификатором книги (BookId) и идентификатором клиента (CustId), которые совместно выступают в роли ключа, однозначно идентифицирующего Каждую запись в таблице ShoppingCart.
Когда пользователь кладет новую книгу в тележку для покупок, он фактически добавляет запись в таблицу ShoppingCart. В приложении эту процедуру можно реализовать с помощью SQL-запроса с инструкцией insert. В этом случае SQL-запрос выглядит следующим образом:
INSERT INTO ShoppingCart (BookId, CustId, Quantity) Values (?, ?, ?)
Три вопросительных знака в тексте запроса представляют собой параметры, значения которым будут присвоены во время выполнения приложения, соответственно после отработки запроса значения параметров будут переданы в колонки Bookid, Custid, Quantity новой записи таблицы ShoppingCart. Если использовать переменные с именами параметров, тот же самый запрос будет иметь вид:
INSERT INTO ShoppingCart (BookId, CustId, Quantity) Values (@BookId, @CustId, @Quantity)
Если пользователь решает что-нибудь изменить в уже сделанной покупке, например, количество книг, то эту процедуру можно реализовать в приложении с помощью SQL-запроса на обновление, содержащего инструкцию update. Такой запрос может иметь следующий вид:
UPDATE ShoppingCart
SET (BookId=?, CustId=?, Quantity=?)
WHERE (Bookld=? AND Custld=?)
Или, при использовании переменных с именем параметра:
UPDATE ShoppingCart
SET{BookId=@BookId, CustId=@CustId, Quantity=@Quantity)
WHERE (BookId=@BookId AND CustId=@CustId)
В этом SQL-запросе параметры в предложении set используются для заполнения новыми данными соответствующих колонок в таблице ShoppingCart. Параметры в предложении where выделяют тот набор записей, в которых произойдет обновление данных.
Пользователь может также удалить книгу из тележки для покупок. В том случае приложение могло бы вызвать SQL-запрос на удаление с предложением delete следующего типа:
DELETE FROM ShoppingCart WHERE (BookId=? AND CustId=?)
Или для переменных с именем параметра:
DELETE FROM ShoppingCart WHERE (BookId=@BookId AND CustId =@CustId)
Коллекция параметров
Для обеспечения возможности передачи значений параметров из приложения в запрос во время выполнения программы, каждый из четырех объектов (SelectCommand, InsertCommand, UpdateCommand и DeleteCommand) объекта DataAdapter поддерживает свойство Parameters, которое содержит коллекцию параметров, соответствующих параметрам SQL-запроса. В командах для объекта OleDbDataAdapter индивидуальные параметры обозначаются, как OleDbParameter в коллекции параметров OleDbParameterCollection.
По аналогии команды в объекте SQLDataAdapter имеют обозначение параметров SqlParameter в коллекции SqlParameterCollection.
Если вы используете мастера конфигурации адаптера данных (Data Adapter Configuration Wizard), чтобы сконфигурировать объект DataAdapter, то коллекция параметров создается автоматически для всех четырех команд (SelectCommand, InsertCommand, UpdateCommand и DeleteCommand). Если вы перетаскиваете элементы из Server Explorer на форму или компонент, то Visual Studio может выполнить следующие действия:
□ Если вы перетаскиваете таблицу или некоторые колонки таблицы в окно дизайнера формы, то Visual Studio генерирует объект SelectCommand(SQL-запрос с инструкцией select) без параметров и параметризованные объекты UpdateCommand, InsertCommand и DeleteCommand. если вы хотите, чтобы SQL-запрос объекта SelectCommand имел параметры, вы должны конфигурировать их вручную.
□ Если вы перемещаете хранимую процедуру в окно дизайнера формы, тоVisual Studio генерирует объект SelectCommand с параметрами, как и требуется для хранимой процедуры. Однако если вы нуждаетесь в других объектах (UpdateCommand, InsertCommand И DeleteCommand) , вы должны сконфигурировать их самостоятельно, вручную задав их параметры.
Наиболее рациональный путь создания параметризированных запросов для объекта DataAdapter — использование мастера Data Adapter Configuration Wizard. После работы мастера, если необходимо, можно изменить конфигурацию параметров вручную в окне Properties.
Структура коллекции Parameters
Каждый элемент коллекции параметров в объектах Command (SelectCommand, UpdateCommand, InsertCommand и DeleteCommand) соответствуют параметру SQL-запроса, записанного в свойство CommandText. Если объект Command представляет собой SQL-запрос с параметрами в виде знаков вопроса, то каждый элемент в коллекции параметров будет соответствовать одному вопросительному знаку в SQL-запросе. Например, следующая инструкция запроса на обновление update требует коллекции из пяти параметров:
UPDATE ShoppingCart
SET (BookId=?, CustId=?, Quantity=?)
WHERE (BookId=? AND CustId=?)
Аналогично для именованных параметров:
UPDATE ShoppingCart
SET (BookId=@BookId, CustId=@CustId, Quantity=@Quantity)
WHERE (BookId=@BookId AND CustId=@CustId)
Если объект Command ссылается на хранимую процедуру, то номер элемента параметра в коллекции определяется процедурой. В хранимых процедурах параметры могут также иметь имена. В этом случае позиция параметра в коллекции не имеет значения. Каждый элемент параметра в коллекции имеет свойство ParameterName, которое используется для согласования с соответствующим параметром в хранимой процедуре.
Если вы формируете коллекцию параметров вручную, то необходимо точно знать, какие параметры требуются для корректной работы хранимой процедуры. Многие хранимые процедуры возвращают значение. В таком случае возвращаемое значение передается назад вашему приложению через коллекцию параметров, и вы должны учесть это. Кроме того, часто хранимые процедуры состоят из множества SQL-запросов, и вы должны убедиться, что коллекция параметров содержит все значения, которые необходимы всем запросам в процедуре.
Если параметры не имеют имен (в хранимых процедурах), то элементы коллекции имеют такую же нумерацию и расположение, как и параметры в хранимой процедуре. Если хранимая процедура возвращает значение, то первый элемент в коллекции параметров (нулевой элемент) зарезервирован для этого возвращаемого значения.
Поэтому для доступа к индивидуальному параметру коллекции можно сослаться на его индекс (номер) в коллекции. Однако если в объекте поддерживается свойство имя параметра (ParameterName), то возможен доступ к параметру по его имени. В листинге 1.1 приведен пример SQL-запроса на Visual Basic и С#. Вторая и третья строка запроса эквивалентны при условии, что второй параметр в коллекции имеет имя Title_Keyword.
Листинг 1.1
' Visual Basic
titleKeyword="%" & txtTitleKeyword.Text & "%"
OleDbDataAdapterl.SelectCommand.Parameters(1).Value=titleKeyword
OleDbDataAdapterl.SelectCommand.Parameters("Title_Keyword").Value =titleKeyword
// C#
string titleKeyword="%"+txtTitleKeyword.Text+"%";
this.OleDbDataAdapterl.SelectCommand.Parameters[1].Value=titleKeyword;
this.OleDbDataAdapterl.SelectCommand.Parameters["Title_Keyword"].Value=titleKeyword;
Здесь в первом случае программа присваивает значение параметру, ссылаясь на его номер в коллекции — 1, во втором случае — на его имя. Использование имени параметра в практике программирования более предпочтительно, чем индекса. При использовании имени уменьшается потребность в переписывании кода, если в ходе работы над проектом вдруг меняется количество параметров, а также отпадает необходимость помнить, возвращает ли хранимая процедура значение.
Если щелкнуть кнопку на поле (Collection) в строке Parameters, то откроется диалоговое окно редактирования свойств коллекции параметров (рис. 1.11). В этом окне разработчик приложения имеет возможность изменить перечень параметров и их атрибуты. В левой части окна представлена созданная по умолчанию коллекция параметров с указанием их имен и индексов, в правой части окна – свойства каждого параметра.
Установление значений параметров
Есть два способа, с помощью которых можно задать значения параметров:
□ явным заданием значений параметрам через свойство Value;
□ располагая (добавляя) параметры в колонки таблицы объекта DataSet.
Вы устанавливаете значения параметров явно, когда заполняете набор данных или вызываете команду (для параметров выбора). Например, в примере поиска книг, приведенного выше, в приложении есть текстовое поле, в которое пользователь вводит ключевое слово (название книги). В этом случае можно явно установить значение параметра, привязав его к свойству Text тетового поля перед вызовом метода Fill объекта DataAdapter. Пример программного кода такого способа приведен в листинге 1.2.
Листинг 1.2
' Visual Basic
titleKeyword="%" & txtTitleKeyword.Text & "%"
OleDbDataAdapterl.SelectCommand.Parameters("Title_Keyword").Value =titleKeyword
OleDbDataAdapterl.Fill(dsAuthorsl)
// C#
titleKeyword="%"+txtTitleKeyword.Text+"%";
this.OleDbDataAdapterl.SelectCommand.Parameters["Title_Keyword"].Value=titleKeyword;
this.OleDbDataAdapterl.Fill(dsAuthorsl);
Параметры должны получить значения и в случаях обновления данных. Когда вызывается метода Update объекта DataAdapter, то осуществляется просмотр всех записей таблицы набора данных DataSet, и модификация записей базовой таблицы (Update, Insert, Delete) происходит на основе значений, полученных из соответствующих колонок каждой записи. То есть параметры получают свои значения из колонок записи набора данных DataSet. Например, если в таблице объекта DataSet была добавлена новая запись и активизирована команда InsertCommand на вставку строки в основную таблицу базы данных, то значения параметров для предложения INSERT этой команды будут считаны из колонок той записи, которая была добавлена в таблицу объекта DataSet. Таков типичный сценарий работы команд обновления данных, но не единственный. Хранимые процедуры тоже могут возвращать данные через коллекцию параметров или через возвращаемое значение. В этом случае возвращенные значения должны быть "привязаны" к соответствующим колонкам таблицы набора данных DataSet.
Параметры обновления также возможно задать явно. Объект DataAdapter поддерживает событие RowUpdating, которое вызывается каждый раз, когда происходит обновление записи. Вы можете создать обработчик данного события и в нем явно присвоить параметрам нужные значения. Это обеспечивает жесткий контроль над значениями параметров и позволяет переназначать их динамически в ходе работы программы непосредственно перед обновлением записи в таблице исходной базы данных.