This chapter is from the book
This chapter is from the book
This chapter is from the book
Passing Arguments
Often, it is necessary to do more than simply have your methods return data to a user request. Oftentimes, you will require some information from them in order to perform your tasks. This is where parameters come in. Parameters define the types of information that you are requesting from a client.
XML Web services accept all primitive data types as parameters. The syntax for declaring your parameters is exactly the same as it is in function calls in non XML Web service programming. That is to say, it takes the following form:
<Webmethod()> Public Function FuntionName (ByVal/byRef paramName as Type) as type
Or in C#
Public type FunctionName(type paramName)
byVal and byRef denote the way in which incoming variables are treated. For now, we will be using only byVal, which accepts a copy of the data and leaves the original unchanged. In later examples, we will want to change the original variables, and byRef will be used.
If you need to use multiple parameters, they must be separated by a comma.
Listing 10.13 shows an XML Web service method that accepts two strings as its parameters, concatenates them with the word "and" in between them, and returns the resulting string.
Listing 10.13 Primitive Data Type Parameters in VB
1: <WebMethod()> Public Function ParamStringReturn( _ 2: ByVal sWord1 As String, ByVal sWord2 As String) As String 3: 4: Return sWord1 & " and " & sWord2 5: 6: End Function
The C# declaration for that same example is as follows:
public string ParamStringReturn(string sWord1, string sWord2)
To call the above function, a client application could now use the following syntax:
SVar = Service.ParamStringReturn("HITHER", "THITHER")
In the above, sVar is a string variable for the return value and Service is the object reference to your XML Web service.
You can also accept more complicated types, such as enumerations, as parameters in your code. Listing 10.14 shows a new enumeration in Visual Basic.
Listing 10.14 Enumeration Called Champion in VB
1: Public Enum Champion 2: Corum = 1 3: Renark = 2 4: Urlich = 3 5: Hawkmoon = 4 6: End Enum
Now we can accept this enumeration in code in exactly the same way as we did the previous primitive types. Listing 10.15 shows a method that will accept a variable of type Champion.
Listing 10.15 Passing Enumerations into VB
1: <WebMethod()> Public Function ParamEnumReturn( _ 2: ByVal enumName As Champion) As champion 3: 4: Return enumName 5: 6: End Function
The C# code for declaring the function would be
public Champion ParamEnumReturn(Champion enumName )
XML Web services allow us to accept variable sized arrays as parameters in our code. To do so, you would simply declare parameters as such:
ByVal/byRef paramName() as Type
Listing 10.16 demonstrates the Visual Basic method of accepting an array of integers, iName, as a parameter. This method then returns an integer—in this case the number of elements in the array.
Listing 10.16 Accepting Arrays as Parameters in VB
1: <WebMethod()> Public Function ParamArrayReturn( _ 2: ByVal iName() As Integer) As Integer 3: 4: Return UBound(iName) 5: 6: End Function
Listing 10.17 shows the C# method for accepting an array as a parameter. It also returns the number of elements in the array by using the GetUpperBound method. The ability to retrieve the number of elements in an array is crucial to working with them.
Listing 10.17 Accepting Arrays as Parameters in C#
1: [WebMethod]
2: public int ParamArrayReturn( int[] iName )
3: {
4: return iName.GetUpperBound(0);
5: }
Passing Arguments by Reference
Up until now, all the examples that you have seen have passed values in byVal. Using byVal, a copy of the variable is sent to the method and the original data is left unchanged. In this section, we will look at byRef. Using byRef, or ref in C#, a reference to the original variable is used and any alterations that the method does to its parameters are also done to the original variable in the calling program.
If you have been adding the previous methods into your DataTypes XML Web service, continue doing so with the following examples. If you haven't, you may wish to start, as you will soon be building a small client application to demonstrate how the following methods change the value of variables on the client.
Add Listing 10.18 to your service. This method accepts an integer as its parameter and then decrements it by one. It also saves a copy of the original value to pass back as its return value.
Listing 10.18 Passing a Primitive Data Type byRef Parameters in VB
1: <WebMethod()> Public Function RefReturn ( _ 2: ByRef iVal As Integer) As Integer 3: 4: Dim iOld As Integer 5: 6: iOld = iVal 7: iVal = iVal - 1 8: 9: Return iOld 10: End Function
If you are using C#, you will have to build your method using the following declaration:
public int RefReturn(ref int iVal)
After you have added the refReturn method, go back and make sure that you have the declaration for the Person class, Listing 10.7 (Listing 10.8 for C#), in your code. You will be using this class shortly.
Now, add listing 10.19 to your service. This new method will accept a Person object as a parameter and change its values.
Listing 10.19 Accepting an Object as a Parameter in VB
1: <WebMethod()> Public Sub refClassReturn(ByRef oPers As Person) 2: 3: oPers.ID = oPers.ID - 1 4: oPers.Name = "Hi " & oPers.Name 5: 6: End Sub
For those following along in C#, declare your refClassReturn with the following line:
public void refClassReturn(ref Person oPers)
Now, save and build the project. At this point, you will begin work on a simple client application that will call your XML Web service and display the return values.
Create a new Windows application and add a Web reference to your DataType XML Web service. See Hour 8 if you need a reminder on how this is done.
Next, create a form that looks like the one shown in Figure 10.5. For simplicity's sake, leave the default names for all of the controls.
){kind=link}
Figure 10.5 The form for your byRef client application.
Now, add the following line to your general declarations:
Dim oData As New localhost.Service1()
This will create the object reference to your DataType XML Web service.
Now, add listing 10.20 to the button click event of Button1. This code will take the integer value typed into TextBox1 and store it to a variable called iVal. iVal is then passed to the RefReturn method and the return value is displayed in TextBox2. The new value of iVal is displayed in TextBox3.
Listing 10.20 Passing a Primitive Data Type by Reference
1: Protected Sub Button1_Click(ByVal sender As System.Object,_ 2: ByVal e As System.EventArgs) Handles Button1.Click 3: 4: Dim iVal As Integer 5: 6: iVal = CInt(TextBox1.Text) 7: 8: textbox3.text = CStr(oData.RefReturn (iVal)) 9: 10: Textbox2.Text = CStr(iVal) 11: 12: End Sub
Figure 10.6 shows the end result of clicking Button1. Notice that the value of iVal, labeled "Old Value," is now decremented by one.
){kind=link}
Figure 10.6 Returning values from your refReturn method.
Listing 10.21 shows the code that you should now add to the Click event of Button2. This code will take the values in TextBox4 and TextBox5 and store them into the Name and Id properties of our oPerson object. oPerson is then passed, byRef, to the refClassReturn method and the value refreshed to its respective textboxes.
Listing 10.21 Passing an Object as a Parameter
1: Public Sub Button2_Click(ByVal sender As Object,_ 2: ByVal e As System.EventArgs) Handles Button2.Click 3: 4: Dim oPerson As New localhost.Person() 5: 6: oPerson.Name = textbox4.Text 7: oPerson.ID = Cint(Textbox5.Text) 8: 9: odata.refClassReturn(oPerson) 10: 11: Textbox4.Text = oPerson.Name 12: Textbox5.Text = CStr(operson.ID) 13: End Sub
Figure 10.7 shows the results of passing the Name "Danielle" and ID "6" to the refClassReturn method.
){kind=link}
Figure 10.7 Returning an array of objects of type Person.