14.4. WebMethod Properties

Each web method is preceded by the WebMethod attribute. You are free to add properties to this attribute. The following sections describe the valid WebMethod properties.

14.4.1. The BufferResponse Property

By default, ASP.NET buffers the entire response to a request before sending it from the server to the client. Under most circumstances, this is the optimal behavior. However, if the response is very lengthy, you might want to disable this buffering by setting the WebMethod attribute's BufferResponse property to False. If set to False, the response will be returned to the client in 16 KB chunks.

     <WebMethod(BufferResponse:=False)> 

14.4.2. The CacheDuration Property

Web services, like web pages, can cache the results returned to clients. If a client makes a request that is identical to a request made recently by another client, then the server will return the response stored in the cache. This can result in a huge performance gain, especially if servicing the request is an expensive operation (such as querying a database or performing a lengthy computation).

For the cached results to be used, the new request must be identical to the previous request. If the web method has parameters, the parameter values must also be identical. For example, if the GetPrice web method of the StockTicker web service is called with a value of msft passed in as the stock symbol, that result will be cached separately from a request for dell.

The CacheDuration property defines how long the response is cached, in seconds. Once the CacheDuration period has expired, a new page is sent. To set the CacheDuration for 30 seconds, you'd write,

     <WebMethod(CacheDuration:=30)> 

The default value for CacheDuration is 0, which disables caching of results.

14.4.3. The Description Property

The WebMethod attribute's Description property allows you to attach a descriptive string to a web method. This description will appear on the web service help page when you test the web service in a browser.

When a representation of the web service is encoded into the SOAP message that is sent out to potential consumers, the WebMethod Description property is included:

     <WebMethod(Description:="Returns the stock price for the input stock symbol.")> 

14.4.4. The EnableSession Property

The WebMethod attribute's EnableSession property defaults to False.

If set to TRue and if your web service inherits from WebService, the session-state collection can be accessed with the WebService.Session property. If the web service does not inherit from the WebService class, then the session-state collection can be accessed directly from HttpContext.Current.Session.

To see this at work, you'll add a method that tells you how many times it has been called in the current session:

     <WebMethod(Description:="Number of hits per session.", EnableSession:=True)> _     Public Function HitCounter( ) As Integer         If Session("HitCounter") Is Nothing Then             Session("HitCounter") = 1         Else             Session("HitCounter") = CInt(Session("HitCounter")) + 1         End If         Return CInt(Session("HitCounter"))     End Function 

Enabling session state adds additional performance overhead to the application.

Session state is implemented via HTTP cookies in ASP.NET web services, so if the transport mechanism is something other than HTTP (say, SMTP), then the session-state functionality will not be available.

14.4.5. The TransactionOption Property

ASP.NET web methods can use transactions, but only if the transaction originates in that web method. In other words, the web method can only participate as the root object in a transaction. This means that a consuming application cannot call a web method as part of a transaction and have that web method participate in the transaction.

The WebMethod attribute's TRansactionOption property specifies whether or not a web method should start a transaction. There are five legal values of the property, all contained in the TRansactionOption enumeration. However, because a web method transaction must be the root object, there are only two different behaviors: either a new transaction is started (Required or RequiresNew) or it is not (Disabled, NotSupported, or Supported).

To use transactions in a web service, you must take several additional steps.

Add a reference to System.EnterpriseServices.dll. In Visual Studio .NET, this is done through the Solution explorer or the Project Add Reference menu item. Add the System.EnterpriseServices namespace:

     Imports System.EnterpriseServices 

You must also add a transactionOption property with a value of RequiresNew or Required to the WebMethod attribute:

     <WebMethod(TransactionOption:=TransactionOption.RequiresNew)> 

If there are no exceptions thrown by the web method, then the transaction will automatically commit unless the SetAbort( ) method is explicitly called. If an unhandled exception is thrown, the transaction will automatically abort.

14.4.6. The MessageName Property

As with aux class, it is possible to have more than one method or function defined in your web service class with the same name (method overloading ). They are differentiated by their signature (the number, data type, and order of their parameters).

Unfortunately, method overloading is not supported by the standard industry protocols, so if you do overload a web method, you must provide each overloaded version with its own unique MessageName property. When the overloaded method is referred to in SOAP messages, the MessageName will be used, and not the method name.

To see the MessageName property at work, you'll add an overloaded method named GetValue. The first overload accepts the stock name as a parameter (presumably it looks up the user's account in the database, and returns the value of that stock). The second overload passes in not only the stock name, but also the number of shares owned. The overloaded methods are shown in Example 14-4.

Example 14-4. Overloaded versions of the GetValue WebMethod

 <WebMethod(Description:="Returns the value of the users holdings " & _                "in a specified stock symbol.", _             MessageName:="GetValueStockInPortfolio")> _ Public Function GetValue(ByVal StockSymbol As String) As Double     '  Code stubbed out     Return 0 End Function <WebMethod(Description:="Returns the value of a specified number " & _                "of shares in a specified stock symbol.", _             MessageName:="GetValueThisManyShares")> _ Public Function GetValue( _ ByVal StockSymbol As String, _ ByVal NumShares As Integer) As Double     '  Code stubbed out     Return 0 End Function 

Because you overloaded GetValues in the web service class, what you see displayed is the MessageName property, as shown in Figure 14-2).