Create and consume an XML Web service: Control characteristics of Web methods by using attributes.
You've seen how easy it is to generate a Web service using Visual Studio .NET, simply by marking published methods with the WebMethod attribute. But there are also a number of ways to customize your Web service by adding properties to that attribute. Table 4.1 shows the properties that you can use to customize the WebMethod attribute.
Table 4.1. Properties of the WebMethod Attribute
| Property | Meaning |
| BufferResponse | If set to True (the default), the entire response is buffered by the server and returned to the client as a single message. If set to False, the response is sent in 16K chunks . |
| CacheDuration | Specifies the number of seconds that ASP.NET should cache results. The default is zero, which disables caching. |
| Description | Supplies a description for the Web method. |
| EnableSession | If set to True, enables session state for the Web service. The default is False. |
| MessageName | Specifies the name by which the method will be called in SOAP messages. The default is the method name . |
| TransactionOption | If set to TransactionOption.Required or TransactionsOption.RequiredNew , allows the Web method to participate as the root object of a transaction. The default is TransactionOption.Disabled . |
In the next Step By Step, you'll see how you can use several of these properties to customize a Web method.
STEP BY STEP 4.4 Customizing a Web Method -
Open the Web Service project that you created in Step by Step 4.2. -
Add this code to the existing Strings class: <WebMethod(CacheDuration:=60, _ Description:="Method to demonstrate caching")> _ Public Function CachedString(_ ByVal inputInt As Integer) As String CachedString = "The time is " & _ DateTime.Now.ToLongTimeString() End Function <WebMethod(_ Description:="Method without caching")> _ Public Function UncachedString(_ ByVal inputInt As Integer) As String UncachedString = "The time is " & _ DateTime.Now.ToLongTimeString() End Function <WebMethod(_ Description:="Store a value in session state", _ EnableSession:=True)> _ Function SetSession(_ ByVal inputInt As Integer) As String Session("StoredInt") = inputInt SetSession = "Value " & CStr(inputInt) & _ " stored in session state" End Function <WebMethod(_ Description:="Retrieve a value from session state", _ EnableSession:=True, MessageName:="GetSession")> _ Function GetValue() As String Dim outputInt As Integer outputInt = Session("StoredInt") GetValue = "Value " & CStr(outputInt) & _ " retrieved from session state" End Function -
Run the project. This opens the test page shown in Figure 4.10. Notice that the test page displays the description property of each Web method. Figure 4.10. Test page for a Web service, with Web method descriptions.  -
Click on the UncachedString link to open a test page for the UncachedString method. -
Enter a value for the input parameter and click Invoke. A second browser window appears, displaying a return message with the current time. -
Close the second browser window. Click Invoke again. A second browser window will appear with the updated current time. -
Close the second browser window. Click the link to return to the complete list of operations. -
Click on the CachedString link to open a test page for the CachedString method. -
Enter a value for the input parameter and click Invoke. A second browser window appears, displaying a return message with the current time. -
Close the second browser window. Click Invoke again. A second browser window will appear with the same current time. That happens because the result from the CachedString method is cached for sixty seconds. ASP.NET returns the cached value during that time without calling the original method. -
Close the second browser window. Change the input parameter and click Invoke again. A second browser window appears, displaying a return message with the current time. When an input parameter changes, ASP.NET does not use the cached result. -
Close the second browser window. Click the link to return to the complete list of operations. -
Click the link for the SetSession method. -
Enter an input value and click Invoke. A second browser window will open with a confirmation message. -
Close the second browser window. Click the link to return to the complete list of operations. -
Click on the link for the GetSession method. Notice that this link uses the MessageName property of the WebMethod attribute rather than the name of the underlying method. -
Click Invoke. A second browser window will open, displaying the value retrieved from the session state. |
Step By Step 4.4 demonstrates all the WebMethod properties except for BufferResponse and TransactionOption. The only time you'll want to set BufferResponse to true is when you're returning more than 16KB of data and that data is being constructed on-the-fly for example, by retrieving and formatting records from a database.
WARNING
Be Wary of Session State You should be cautious about using session state in a Web service. Session state can tie up server resources for an extended period of time. If you use session state with a popular Web service, you will apply heavy demands to the RAM on your Web server.
If you're interested in performing transactions within a Web service, you should look at the WS-Transaction portion of the new Global XML Architecture (GXA) specification instead of using the TransactionOption property. See http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dngxa/html/gloxmlws500.asp for more information on this advanced topic, which you will not find on the exam.
