Inheriting from WebService

In this syntax example, an Imports statement imports the System.Web.Services namespace. This namespace contains the classes and attributes that provide ASP.NET’s built-in support for XML-based Web services. In this case, the class we care about is WebService, which is inherited in this example using the Inherits keyword.

Inheriting from the WebService class is not required for a class to function as a Web service, but the WebService class provides useful plumbing for Web services. This includes access to Application, Session, and other ASP.NET objects, including the Context object, which provides access to information about the HTTP request that invokes the Web service. Any Web service you create using Visual Studio .NET will use the WebService class as the base class.

Using the <WebService()> Attribute to Specify XML Namespace

XML-based Web services use XML namespaces to uniquely identify the endpoint or listener to which a client sends requests. By default, ASP.NET sets the XML namespace for a Web service to http://tempuri.org/projectname/classname. If you plan to make your Web service available publicly over the Internet, you might want to change the default namespace to avoid potential conflicts with other XML-based Web services using the same names as your Web service, and which also might use the default namespace. Using a domain name that you control can help ensure uniqueness.

You can modify the default namespace for a Web service class by adding the WebService metadata attribute to the class definition and setting its Namespace property to the desired value for the new namespace. This value can be any unique URI that you control, such as your organization’s domain name. The namespace is used only for identification—the URI specified is not used in any other way, and need not be a valid, accessible Web site.

In Microsoft Visual C# .NET, metadata attributes use the syntax [AttributeName(PropertyName=value)] and are placed on the same line as the entity (class, method, and so on) that they modify:

[WebService(Namespace="http://www.aspnetsbs.com/webservices/") public class ClassName

Metadata Attributes

Prior to this chapter, the term attributes referred to the key/value pairs added to HTML or ASP.NET server control tags to define specific properties of those entities or controls. This chapter introduces the concept of metadata attributes.

ASP.NET and the Microsoft .NET Framework make extensive use of attributes to provide programmatic plumbing for classes, as well as to add descriptive information to managed assemblies. You can also use your own attributes (by creating classes derived from System.Attribute) to add your own descriptive information to your classes.

Attributes in ASP.NET Web services, in addition to providing access to the XML namespace used for the Web service, are used to tell ASP.NET that a given method is to be exposed as a WebMethod. ASP.NET then provides all of the runtime functionality necessary for clients of the Web service to access the WebMethod without requiring the programmer to write additional code.

You can set multiple properties in an attribute declaration and separate them by commas. Placing each property definition on a separate line can substantially improve code readability, particularly if you are using many properties in an attribute declaration.

Using the <WebMethod()> Attribute to Expose Methods

Once you’ve declared the class that implements the Web service, you will need to add one or more methods that provide functionality for the Web service. Each method will use the WebMethod metadata attribute to declare the method as one for which ASP.NET should provide the necessary plumbing to expose it to clients.

To add the WebMethod attribute to a Visual C# .NET method, use the following syntax:

[WebMethod() public <ReturnType> MethodName(  // method cod }

MethodName is the name of the method to be exposed by the Web service; ReturnType is the type of the value (if any) to be returned by the method. Even if your method does not return a value that is a result of a calculation or other action, it is usually a good idea to at least return a value that indicates the success or failure of the method.

<WebMethod()> Attribute Properties

Like the WebService attribute, the WebMethod attribute has properties that you can use to alter the behavior of the Web method. Table 11-1 describes these properties.

Create a HelloWorld Web service

1. Create a new project in Visual Studio .NET. Unlike previous projects, this project should be an ASP.NET Web Service rather than an ASP.NET Web Application. Type the name of the project as Chapter_11, and click OK. The resulting screen should show the default Web Service, Service1.asmx.cs, in design view, as shown in the following illustration.

   

2. Switch to code view. You can click on the link provided in design view to switch to code view, or use the standard Visual Studio .NET key, F7. However you switch to code view, the screen should look similar to the following illustration:

   

   Unlike Web Applications, in which a great deal of the work of building the page is done in design view, Web services are generally modified using code directly.

3. Toward the bottom of the file, locate a comment titled WEB SERVICE EXAMPLE. The code will look similar to the following:

   // WEB SERVICE EXAMPL // The HelloWorld() example service returns the string Hello Worl // To build, uncomment the following lines then save and build th // projec // To test this web service, press F //  [WebMethod //  public string HelloWorld( //   //   return "Hello World" //  }

4. Remove the comments from the beginning of each line from [WebMethod()] to the closing curly brace for the function. Rather than leave this example exactly as it is created by Visual Studio .NET, add a parameter to HelloWorld, and append the parameter to the value returned. The finished method should look like the following code:

   [WebMethod public string HelloWorld(string name  return "Hello World, from " + name }

5. Save the file, and then build the project.

6. Right-click on Service1.asmx in Solution Explorer. Select Browse With from the drop-down menu. Select Microsoft Internet Explorer from the browser list, and then click Browse. The resulting screen should look similar to the following illustration.

   

   One thing that stands out on the illustration is the warning that the Web service is using the http://tempuri.org/namespace. There is a recommendation to change the namespace before the Web service is made public. Although it is unlikely this Web service will ever be made public, let's fix this now. Close the browser and return to the source code.

7. Add a line directly below the closing summary tag just above the top of the class declaration. Note that if you press Enter at the end of the line with the closing summary tag, you should see that Visual Studio .NET will insert three slashes (as a convenience, presuming you are adding more comments). Delete the three slashes if they appear. On the line just below the closing summary tag, add the following (you can substitute a different namespace value, if you like, as long as it is unique):

   [WebService(Namespace="http://www.aspnetsbs.com/webservices/")]
   

8. Save the open files, and build the project again.

9. Browse the web service again using Internet Explorer, as described in step 6. The result should look similar to the following illustration:

   

   There are two links on this page. The first is Service Description. Click this link, and a screen similar to the following illustration will appear:

   

10. You can scroll through the entire document and see the complete Web Services Description Language (WSDL) contract for the Web service method. Click the Back button on the browser and select the other link on the page, HelloWorld. The screen should look similar to the following illustration.

    

11. Enter your name in the text box provided for the name, and then click the Invoke button. The resulting screen should look similar to the following illustration, which shows the XML output returned by the Web service.

    

    The complete source for the .asmx file and the code-behind file can be found in the practice files for the book.

Using Primitive Data Types

The HelloWorld example takes a single string as an input parameter, and returns a value of type String. But XML-based Web services are not limited to strings and can accept input parameters and return values of most types.

XML-based Web services in ASP.NET use the XML Schema Definition (XSD) draft specification to specify the datatypes that are supported by ASP.NET Web services. This includes primitive data types such as string, int, boolean, long, and so on, as well as more complex types such as classes or structs.

The definition for a Web service method that adds two numbers and returns the result would look like the following:

[WebMethod()] public int Add(int Num1, int Num2)  return (Num1 + Num2) }

Accessing Data in a Web Service

In addition to primitive types, classes, and structs, ASP.NET Web services can also return or accept ADO.NET datasets as input parameters. This is possible because the DataSet class has built-in support for being serialized as XML, which can be easily sent over an HTTP connection.

Return data from a Web service

1. In Visual Studio .NET, open the Chapter_11 project if it is not already open.

2. Create a new Web service. Right-click on the root of the project, then select Add from the drop-down menu, and then select Add Web Service. In the resulting dialog box, type the name of the file as AuthorsService.asmx, and click Open. When the design view of the new Web service appears, click on the link provided on the design surface to switch to code view.

3. At the top of AuthorsService.asmx.cs, add the following line:

   using System.Data.SqlClient;
   

4. Just above the class declaration for the AuthorsService class, add the following line. If you press Enter at the end of the line with the closing Summary tag, Visual Studio .NET will add a new line with three slashes. Delete these before adding the line.

   [WebService(Namespace="http://www.aspnetsbs.com/webservices/")]

5. Scroll to the bottom of the code file, and uncomment the commented HelloWorld method. Change the name of the method to GetAuthors, and the return type of the method from string to DataSet. Modify the WebMethod attribute just before the GetAuthors method, adding the description so that it looks like the following line:

   [WebMethod(Description="Returns the Pubs Authors table.")]

6. Modify the GetAuthors method so that it looks like the following code:

   [WebMethod(Description="Returns the Pubs Authors table.") public DataSet GetAuthors(  DataSet dsAuthors = new DataSet() SqlConnection cn = new SqlConnection() SqlDataAdapter da string strCn strCn=@"server=(local)\vsDotNet;database=pubs;"  "Trusted_Connection=yes" cn.ConnectionString=strCn da=new SqlDataAdapter "SELECT * FROM Authors ORDER BY au_LName,au_FName",cn) da.Fill(dsAuthors,"Authors") return dsAuthors }

   Much of the database access code should look very familiar from previous examples. Note that the connection is neither opened nor closed in this example. This is because the SqlDataAdapter class takes care of opening, and closing the connection automatically, using the connection object passed to its constructor.

7. Save the file and build the application.

8. Browse the Web service with Internet Explorer. The screen should look similar to the illustration on the next page. (Note that the description specified is the same as the Description property of the WebMethod attribute.)

   

9. Click GetAuthors. The resulting page will look similar to the last example page that allowed you to invoke the Web service, except in this case, there will be an Invoke button, but no text box (because there are no parameters). Click Invoke, and a window similar to the following illustration will appear.

   

10. The schema for the resulting data is at the top of the result from invoking the Web service. Scroll down in the browser window, and you will see the actual data, as shown in the following illustration.

    

Advertising Web Services Through a Discovery Document

A discovery document is an XML-based document containing references to Web services and/or other discovery documents. Through the use of discovery documents, you can easily catalog all of the available Web services on a Web server at a single location.

By publishing a discovery document to a publicly available URL, you can make it possible for clients to easily locate and consume Web services that you have made available. Clients can access the discovery document using tools such as the wsdl.exe command-line utility supplied with the .NET Framework, or with Visual Studio .NET’s Add Web Reference dialog box, in order to create clients for the Web service. We’ll discuss this process in greater detail in “Using a Web Service” on page 429.

A discovery file uses the extension .disco and contains two types of nodes: contractRef nodes and discoveryRef nodes. The contractRef nodes refer to WSDL files that you can use to create clients for a Web service, while discoveryRef nodes refer to additional discovery documents. The discovery document for the two example Web services created in this chapter is shown in the following listing, Chapter11.disco. The ref attribute of the contractRef node contains the URL to the WSDL contract for the Web service, in this case generated by ASP.NET by appending the ?WSDL argument to the URL for the .asmx file that implements the Web service. The docRef attribute contains the URL to the documentation for the Web service, in this case simply the URL to the .asmx file, since ASP.NET automatically generates documentation for Web services implemented in an .asmx file. The xmlns attributes in the discoveryRef and contractRef nodes establish the XML namespaces in which these nodes reside.

Advertising Web Services Through UDDI

Another option for advertising Web services to potential clients is UDDI. This is a multivendor initiative, spearheaded by Ariba, IBM, and Microsoft, and designed to provide an Internet-based business registry (or registries) in which creators of Web services can register their publicly available Web services. The UDDI specification describes how Web services can be registered in such a way as to allow clients to easily search for the type of Web service desired, or to discover all of the Web services offered by a particular partner or company.

The model for UDDI is for multiple identical versions of the UDDI business registry to be hosted by multiple participants, providing redundancy and load balancing for the registry. Web service providers can register their Web services at any node and the information will be replicated to all registries daily, allowing potential clients to find these services from any registry.

Currently, both Microsoft and IBM provide online UDDI registries, and both can be reached from http://www.uddi.org/, where you can also find a number of helpful white papers on UDDI.