Chapter 10 Adding Standards to Queries After completing this chapter, you will be able to: ■■ Understand why parameters are important in queries ■■ Add parameters to standard selection and data update queries ■■ Call stored procedures that include both in and out parameters In ADO.NET, queries pass to external data sources as strings These strings include not only essential command keywords and syntactical elements but also the data values used to limit and fulfill each query Building command strings is an art long practiced by developers in many programming languages, but it’s quite different from NET’s promise of strongly typed data management Why store values as distinct data types at all if you are eventually going to convert everything to ASCII text? To push aside these and other deficiencies that stem from inserting all types of data values into SQL statements, ADO.NET includes the parameter, an object that bridges the gap between the text-based needs of the external data source’s command processing system and the intelligent data type system that epitomizes NET development This chapter demonstrates query parameters and their uses in SQL Server database queries Note  This chapter focuses on parameters as implemented in the SQL Server provider Although the OLE DB and ODBC providers also implement parameters, there are some minor differences that will be pointed out within the chapter The exercises in this chapter all use the same sample project, a tool that uses parameters to retrieve and update database values Although you can run the application after each exercise, the expected results for the full application might not appear until you complete all exercises in the chapter Developing Parameterized Queries In the SQL Server provider, parameters appear as the System.Data.SqlClient.SqlParameter class By creating relevant parameters and attaching them to SqlCommand instances, ordinary text queries become parameterized queries Dwonloaded from: iDATA.ws 153 154 Microsoft ADO.NET Step by Step Note  In the OLE DB provider, the parameter class appears as System.Data.OleDb OleDbParameter The ODBC equivalent is System.Data.Odbc.OdbcParameter Both of these classes and the SqlParameter class in the SQL Server provider derive from System.Data.Common DbParameter Understanding the Need for Parameters As mentioned in the “Connection String Builders” section on page 124 of Chapter 8, “Establishing External Connections,” there are certain risks involved in building SQL statements and related string elements A key risk is the SQL injection attack, in which a user can inadvertently or deliberately alter the intent of a SQL statement by supplying corrupted content Consider the following statement, which modifies the Employee.Salary value for a specific employee record: UPDATE Employee SET Salary = XXX WHERE ID = 5; It works well if the user provides 50000 or a similar number as the value of XXX But what if resourceful employee John Doe replaces XXX with the following SQL fragments? 150000 WHERE FirstName = 'John' AND LastName = 'Doe'; UPDATE Employee SET Salary = 50000 The user-supplied content includes a semicolon, effectively turning one statement into a batch of two statements Most programmers design their code to avoid such scenarios, but this type of situation still manages to show up from time to time Parameters help reduce such issues by using typed substitution placeholders instead of unchecked plain-text gaps in SQL strings Parameters understand how to properly format their replacement values so that SQL injection attacks and other mishaps don’t occur Parameters solve these problems by making changes to both the SQL statement and the data destined for that statement Instead of piecing together workable SQL statements from a combination of programmer and user-supplied parts, parameterized query statements exist in a standardized form, free of unknown and unsafe user data Portions of the statement that require user input exist as named placeholders, @name elements that get replaced with the final type-specific data values after they have been transmitted to the database Dwonloaded from: iDATA.ws Chapter 10  Adding Standards to Queries 155 This process provides for a more generic command text, and a logical separation between the command and its data Removing ever-changing data values from SQL statements also increases performance within SQL Server Like many advanced relational database systems, SQL Server compiles each statement into an internal format, one that doesn’t require it to constantly parse a text string to determine its actions If SQL Server encounters the same SQL statement twice, it doesn’t need to go through the time-consuming compilation process again For example, the following three SQL statements are different in the compiler’s view: UPDATE Employee SET Salary = 50000 WHERE ID = 5; UPDATE Employee SET Salary = 56000 WHERE ID = 12; UPDATE Employee SET Salary = 52000 WHERE ID = 8; Parameterized queries replace these three instance-specific versions with a generic version of the statement, free of the varying data portions Removing dynamic data values from what would otherwise be standard SQL command structures allows applications to send a much more limited number of queries to SQL Server, queries that show up again and again, and that don’t need to be recompiled every time Implementing Standard Queries The UPDATE statement shown previously modifies the salary for an employee record based on that record’s primary key UPDATE Employee SET Salary = 50000 WHERE ID = 25; To prepare the statement for parameters, all elements destined for substitution by the parameter values get replaced with “@” identifiers UPDATE Employee SET Salary = @NewSalary WHERE ID = @EmployeeID; In standard SQL statements (all statements other than stored procedures), the names you provide are up to you, so being descriptive is best Each placeholder must begin with the @ sign followed by a unique name Parameter names are not case-sensitive Dwonloaded from: iDATA.ws 156 Microsoft ADO.NET Step by Step As with nonparameterized queries, this enhanced statement gets wrapped up in a SqlCommand object: C# string sqlText = @"UPDATE Employee SET Salary = @NewSalary WHERE ID = @EmployeeID"; SqlCommand salaryUpdate = new SqlCommand(sqlText, linkToDB); Visual Basic Dim sqlText As String = "UPDATE Employee SET Salary = @NewSalary WHERE ID = @EmployeeID" Dim salaryUpdate = New SqlCommand(sqlText, linkToDB) The SqlCommand class includes a Parameters collection to which you add the specific replacement values for each placeholder You wrap up each parameter in an instance of SqlParameter, setting its properties as needed, and adding it to the SqlCommand.Parameters collection When you execute the command, ADO.NET passes both the placeholder-laden SQL text and the parameter collection to the database for evaluation Each parameter includes the elements you would expect: the parameter name (which must match a placeholder name in the SQL statement), the data type along with any data typespecific settings (such as the length of string parameters), the actual data content to be included in the processed command, and a few other generic settings To add a parameter to a command, create a SqlParameter instance and add it to the SqlCommand object C# SqlParameter paramValue = new SqlParameter("@NewSalary", SqlDbType.Money); paramValue.Value = 50000m; salaryUpdate.Parameters.Add(paramValue); paramValue = new SqlParameter("@EmployeeID", SqlDbType.BigInt); paramValue.Value = 25L; salaryUpdate.Parameters.Add(paramValue); Visual Basic Dim paramValue As New SqlParameter("@NewSalary", SqlDbType.Money) paramValue.Value = 50000@ salaryUpdate.Parameters.Add(paramValue) paramValue = New SqlParameter("@EmployeeID", SqlDbType.BigInt) paramValue.Value = 25& salaryUpdate.Parameters.Add(paramValue) Dwonloaded from: iDATA.ws Chapter 10  Adding Standards to Queries 157 SqlParameter includes lots of constructor options for setting the data type of the passed data, plus other settings Or you can go the traditional route and update the object’s individual properties directly, including the following: ■■ ParameterName  The name of the parameter; that is, the placeholder Don’t forget to include the @ sign at the start of the name ■■ DbType or SqlDbType  One of the System.Data.SqlDbType enumeration values, which all parallel the available data types in SQL Server For example, SqlDbType.VarChar maps to SQL Server’s varchar column type Both DbType and SqlDbType refer to the same property; update either one as needed ■■ IsNullable  Indicates whether the parameter accepts NULL values ■■ Precision and Scale  Some of SQL Server’s numeric data types require specific precision and scale values Use these properties to configure the data from ADO.NET’s point of view ■■ Size  Similar to Precision and Scale, Size is commonly used for text and binary data types It affects only the amount of data sent to SQL Server with a query If your query sends data back through a parameter (described below), it ignores this Size setting ■■ Value and SqlValue  The actual value that will replace the placeholder in the SQL statement Use Value to work with data defined using the standard NET data types Use the SqlValue property instead to work with data in a format that more closely resembles SQL Server’s data types, and as expressed through the classes in the System Data.SqlTypes namespace If your data needs are simple, you can let the SqlCommand.Parameters collection define the data type of your parameters for you The collection’s AddWithValue method accepts the parameter name and the intended value and adds a new SqlParameter instance to the command using the specified settings C# salaryUpdate.Parameters.AddWithValue("@NewSalary", 50000m); salaryUpdate.Parameters.AddWithValue("@EmployeeID", 25L); Visual Basic salaryUpdate.Parameters.AddWithValue("@NewSalary", 50000@) salaryUpdate.Parameters.AddWithValue("@EmployeeID", 25&) Once the parameters are all in place, calling one of the command’s Execute methods processes the command on the database, and returns any results as with nonparameterized queries Dwonloaded from: iDATA.ws 158 Microsoft ADO.NET Step by Step C# salaryUpdate.ExecuteNonQuery(); Visual Basic salaryUpdate.ExecuteNonQuery() Updating Data with Parameters: C# Open the “Chapter 10 CSharp” project from the installed samples folder The project includes multiple Windows.Forms classes and a sealed class named General Open the code for the General class This class centralizes much of the database functionality for the sample application Locate the GetConnectionString function, a routine that uses a SqlConnectionStringBuilder to create a valid connection string to the sample database It currently includes the following statements: builder.DataSource = @"(local)\SQLExpress"; builder.InitialCatalog = "StepSample"; builder.IntegratedSecurity = true; Adjust these statements as needed to provide access to your own test database Open the code for the RenameCustomer form This form lets the user modify the FullName value for a single record in the Customer database table Locate the ActOK_ Click event handler This routine does the actual update of the record Just after the “Save the new name” comment, add the following code: sqlText = "UPDATE Customer SET FullName = @NewName WHERE ID = @CustID"; commandWrapper = new SqlCommand(sqlText); commandWrapper.Parameters.AddWithValue("@NewName", NewName.Text.Trim()); commandWrapper.Parameters.AddWithValue("@CustID", ActiveCustomerID); try { General.ExecuteSQL(commandWrapper); } catch (Exception ex) { MessageBox.Show("Error occurred updating customer name: " + ex.Message); return; } These statements create a SqlCommand object with a SQL statement that includes two placeholders: @NewName and @CustID The code then adds two matching parameters to the command and sends it to the database for processing Run the program On the Customer Management form, select a customer from the list of customers and then click Rename Customer When the Rename Customer form appears, enter a new value in the New Name field and then click OK This process updates the database using the newly added code Dwonloaded from: iDATA.ws Chapter 10  Adding Standards to Queries 159 Updating Data with Parameters: Visual Basic Open the “Chapter 10 VB” project from the installed samples folder The project includes multiple Windows.Forms classes and a module named General Open the code for the General module This file centralizes much of the database functionality for the sample application Locate the GetConnectionString function, a routine that uses a SqlConnectionStringBuilder to create a valid connection string to the sample database It currently includes the following statements: builder.DataSource = "(local)\SQLExpress" builder.InitialCatalog = "StepSample" builder.IntegratedSecurity = True Adjust these statements as needed to provide access to your own test database Open the code for the RenameCustomer form This form lets the user modify the FullName value for a single record in the Customer database table Locate the ActOK_ Click event handler This routine does the actual update of the record Just after the “Save the new name” comment, add the following code: sqlText = "UPDATE Customer SET FullName = @NewName WHERE ID = @CustID" commandWrapper = New SqlCommand(sqlText) commandWrapper.Parameters.AddWithValue("@NewName", NewName.Text.Trim) commandWrapper.Parameters.AddWithValue("@CustID", ActiveCustomerID) Try ExecuteSQL(commandWrapper) Catch ex As Exception MessageBox.Show("Error occurred updating customer name: " & ex.Message) Return End Try These statements create a SqlCommand object with a SQL statement that includes two placeholders: @NewName and @CustID The code then adds two matching parameters to the command and sends it to the database for processing Dwonloaded from: iDATA.ws 160 Microsoft ADO.NET Step by Step Run the program On the Customer Management form, select a customer from the list of customers and then click Rename Customer When the Rename Customer form appears, enter a new value in the New Name field and then click OK This process updates the database using the newly added code Using Parameters with Other Providers The OLE DB and ODBC providers also include support for parameterized queries However, the definitions of both the command text and the associated parameters vary somewhat from the SQL Server implementation Instead of including placeholder names prefixed with @ signs, each replaceable element appears as a nameless question mark (?) in the command text Parameters added to the associated OleDbCommand or OdbcCommand instance must be added in the order indicated by the placeholders Although the command text does not include parameter names, each added OleDbParameter or OdbcParameter instance should still include @-prefixed names C# string sqlText = @"UPDATE Employee SET Salary = ? WHERE ID = ?"; SqlCommand salaryUpdate = new SqlCommand(sqlText, linkToDB); salaryUpdate.Parameters.AddWithValue("@NewSalary", 50000m); salaryUpdate.Parameters.AddWithValue("@EmployeeID", 25L); Visual Basic Dim sqlText As String = "UPDATE Employee SET Salary = ? WHERE ID = ?" Dim salaryUpdate = New SqlCommand(sqlText, linkToDB) salaryUpdate.Parameters.AddWithValue("@NewSalary", 50000@) salaryUpdate.Parameters.AddWithValue("@EmployeeID", 25&) Dwonloaded from: iDATA.ws Chapter 10  Adding Standards to Queries 161 Using Parameters in Stored Procedures Calls to stored procedures with parameterized queries vary only slightly from those to standard statements There are four main differences you need to consider when accessing stored procedures The first is simple: Make sure you set the SqlCommand object’s CommandType property to CommandType.StoredProcedure The second difference is equally simple: The command object’s CommandText property should include only the name of the stored procedure Exclude any arguments or query elements The third difference is in how you name the parameters As with standard queries, each parameter includes an @-prefixed name and a data type, plus other optional settings you might want to configure Unlike standard queries, you have no flexibility in how you define the parameter names They must match precisely the parameter names used when the stored procedure was defined within SQL Server The last difference has to with the direction of a parameter The SqlParameter class includes a Direction property that tells ADO.NET which way data flows from your query’s data value to the stored procedure There are four available System.Data.ParameterDirection options: ■■ ParameterDirection.Input  The parameter value is considered input, flowing from the application to the stored procedure This is the default for all parameters ■■ ParameterDirection.Output  The parameter is used to retrieve data back from the stored procedure, much like a ByRef (Visual Basic) or out (C#) function argument ■■ ParameterDirection.InputOutput  A combination of the input and output directions Your application provides an input value that can be modified and returned by the stored procedure ■■ ParameterDirection.ReturnValue  For stored procedures or other database features that sport a return value, this parameter type lets you collect that value Parameters added to standard query commands also support the Direction property, but in most cases the default of ParameterDirection.Input is the right choice The following SQL Server stored procedure includes an input value (@locationName), an output value (@newID), and a return value (@@ROWCOUNT): CREATE PROCEDURE AddLocation (@locationName varchar(50), @newID bigint OUT) AS BEGIN INSERT INTO BuildingLocation (Name) VALUES (@locationName); SET @newID = SCOPE_IDENTITY(); RETURN @@ROWCOUNT; END Dwonloaded from: iDATA.ws 162 Microsoft ADO.NET Step by Step The following code calls the AddLocation stored procedure, passing it the name of a new location and returning the new ID value: C# // - Use a stored procedure to add a new building location string sqlText = "dbo.AddLocation"; SqlCommand locationCommand = new SqlCommand(sqlText, linkToDB); locationCommand.CommandType = CommandType.StoredProcedure; // - Add the input parameter: locationName SqlParameter workParameter = locationCommand.Parameters.AddWithValue( "@locationName", LocationNameField.Text.Trim()); workParameter.Size = 50; // - Add the output parameter: newID workParameter = locationCommand.Parameters.Add("@newID", SqlDbType.BigInt); workParameter.Direction = ParameterDirection.Output; // - Add the return value parameter The name is not important workParameter = locationCommand.Parameters.Add("@returnValue", SqlDbType.Int); workParameter.Direction = ParameterDirection.ReturnValue; // - Add the location locationCommand.ExecuteNonQuery(); // - Access returned values as: // locationCommand.Parameters["@newID"].Value // locationCommand.Parameters["@returnValue"].Value Visual Basic ' - Use a stored procedure to add a new building location Dim sqlText As String = "dbo.AddLocation" Dim locationCommand As New SqlCommand(sqlText, linkToDB) locationCommand.CommandType = CommandType.StoredProcedure ' - Add the input parameter: locationName Dim workParameter As SqlParameter = locationCommand.Parameters.AddWithValue( "@locationName", LocationNameField.Text.Trim) workParameter.Size = 50 Dwonloaded from: iDATA.ws Chapter 10  Adding Standards to Queries 163 ' - Add the output parameter: newID workParameter = locationCommand.Parameters.Add("@newID", SqlDbType.BigInt) workParameter.Direction = ParameterDirection.Output ' - Add the return value parameter The name is not important workParameter = locationCommand.Parameters.Add("@returnValue", SqlDbType.Int) workParameter.Direction = ParameterDirection.ReturnValue ' - Add the location locationCommand.ExecuteNonQuery() ' - Access returned values as: ' locationCommand.Parameters("@newID").Value ' locationCommand.Parameters("@returnValue").Value The return value will be if the code was successful, or if the insert failed (along with a thrown error) Calling a Stored Procedure with Parameters: C# Note  This exercise uses the “Chapter 10 CSharp” sample project and continues from where the previous exercise in this chapter left off Open the code for the ViewOrders form This form processes data from a stored procedure that returns two distinct sets of records The stored procedure GetCustomerOrders has the following definition: CREATE PROCEDURE dbo.GetCustomerOrders(@customerID bigint) AS BEGIN SELECT * FROM Customer WHERE ID = @customerID; SELECT * FROM OrderEntry WHERE Customer = @customerID ORDER BY OrderDate; END; Locate the ViewOrders_Load event handler This routine calls the stored procedure and processes the returned records In the try block, just after the “Process the query ” comment, add the following statements: sqlText = "dbo.GetCustomerOrders"; commandWrapper = new SqlCommand(sqlText, linkToDB); commandWrapper.CommandType = CommandType.StoredProcedure; commandWrapper.Parameters.AddWithValue("@customerID", ActiveCustomerID); customerReader = commandWrapper.ExecuteReader(); Dwonloaded from: iDATA.ws 164 Microsoft ADO.NET Step by Step These lines add the @customerID parameter to the stored procedure command The @customerID parameter name must match the @customerID parameter as defined in the original stored procedure Just after the “First read the customer record” comment, add the following code: customerReader.Read(); CustomerName.Text = (string)customerReader["FullName"]; AnnualFee.Text = string.Format("{0:c}", (decimal)customerReader["AnnualFee"]); These statements process the first set of results from the stored procedure, the SELECT statement for the Customer table Just after the “Read the next set, which contains the orders” comment, add the following code: customerReader.NextResult(); while (customerReader.Read()) { oneOrder = new OrderInfo(); oneOrder.ID = (long)customerReader["ID"]; oneOrder.OrderDate = (DateTime)customerReader["OrderDate"]; oneOrder.OrderTotal = (decimal)customerReader["Total"]; AllOrders.Items.Add(oneOrder); } This code accesses the records in the second set of results, the SELECT statement for the OrderEntry table, via the NextResult method call Run the program On the Customer Management form, select a customer from the list of customers and then click View Orders When the View Orders form appears, it includes content from both SELECT statements as returned by the stored procedure Dwonloaded from: iDATA.ws Chapter 10  Adding Standards to Queries 165 Calling a Stored Procedure with Parameters: Visual Basic Note  This exercise uses the “Chapter 10 VB” sample project and continues from where the previous exercise in this chapter left off Open the code for the ViewOrders form This form processes data from a stored procedure that returns two distinct sets of records The stored procedure GetCustomerOrders has the following definition: CREATE PROCEDURE dbo.GetCustomerOrders(@customerID bigint) AS BEGIN SELECT * FROM Customer WHERE ID = @customerID; SELECT * FROM OrderEntry WHERE Customer = @customerID ORDER BY OrderDate; END; Locate the ViewOrders_Load event handler This routine calls the stored procedure and processes the returned records In the Try block, just after the “Process the query ” comment, add the following statements: sqlText = "dbo.GetCustomerOrders" commandWrapper = New SqlCommand(sqlText, linkToDB) commandWrapper.CommandType = CommandType.StoredProcedure commandWrapper.Parameters.AddWithValue("@customerID", ActiveCustomerID) customerReader = commandWrapper.ExecuteReader() These lines add the @customerID parameter to the stored procedure command The @customerID parameter name must match the @customerID parameter as defined in the original stored procedure Just after the “First read the customer record” comment, add the following code: customerReader.Read() CustomerName.Text = CStr(customerReader!FullName) AnnualFee.Text = Format(CDec(customerReader!AnnualFee), "Currency") These statements process the first set of results from the stored procedure, the SELECT statement for the Customer table Dwonloaded from: iDATA.ws 166 Microsoft ADO.NET Step by Step Just after the “Read the next set, which contains the orders” comment, add the following code: customerReader.NextResult() Do While (customerReader.Read = True) oneOrder = New OrderInfo oneOrder.ID = CLng(customerReader!ID) oneOrder.OrderDate = CDate(customerReader!OrderDate) oneOrder.OrderTotal = CDec(customerReader!Total) AllOrders.Items.Add(oneOrder) Loop This code accesses the records in the second set of results, the SELECT statement for the OrderEntry table, via the NextResult method call Run the program On the Customer Management form, select a customer from the list of customers and then click View Orders When the View Orders form appears, it includes content from both SELECT statements returned by the stored procedure Summary This chapter discussed parameters, which are data value objects that help ensure the accuracy and safety of the data being sent to and returned from external data sources Parameterized queries use special SQL statements that include placeholders for each parameter Each SqlParameter instance defines the name of the parameter, its data type, and its value Parameters work with either standard SQL commands or with stored procedures When using them with stored procedures, you can create both input and output stored procedures, supporting two-way communications with these custom database functions Dwonloaded from: iDATA.ws Chapter 10  Adding Standards to Queries 167 Chapter 10 Quick Reference To Do This Create a parameterized query for SQL Server Create a SQL query string that includes @-prefixed placeholders Create a SqlCommand instance Assign the SQL query to the SqlCommand object’s CommandText property Create SqlParameter objects, one for each placeholder in the query, and add them to the command object’s Parameters collection Set the SqlCommand.Connection property Call one of the command object’s Execute methods Create a parameterized query for an OLE DB data source Create a SQL query string that includes question marks (?) for placeholders Create an OleDbCommand instance Assign the SQL query to the OleDbCommand object’s CommandText property Create OleDbParameter objects, one for each placeholder in the query, and add them to the command object’s Parameters collection Set the OleDbCommand.Connection property Call one of the command object’s Execute methods Create an “out” parameter for a stored procedure Create a SqlParameter instance, setting its fields as needed Set the SqlParameter.Direction property to ParameterDirection.Output Dwonloaded from: iDATA.ws Dwonloaded from: iDATA.ws ... applications to send a much more limited number of queries to SQL Server, queries that show up again and again, and that don’t need to be recompiled every time Implementing Standard Queries The... parameters to the command and sends it to the database for processing Run the program On the Customer Management form, select a customer from the list of customers and then click Rename Customer When... Parameters in Stored Procedures Calls to stored procedures with parameterized queries vary only slightly from those to standard statements There are four main differences you need to consider when