Building Simple Output Web Services

only for RuBoard

Now that you are familiar with what a Web service is, and the standards and protocols that are usable by Web services, it is time to get your hands dirty by building some Web services. In the following section, I will show you how to build a simple Web service (the classic "Hello World" example you didn't think you could get through a programming book without writing Hello World, did you?). You will build on the concepts learned while building a simple Web service, and build bigger, more complex Web services.

WebMethod

Building a basic Web service is really no different than creating a custom class and exposing public methods . Listing 14.1 shows the code to create a HelloWorld class (not a Web service, yet).

Listing 14.1 Building a Custom HelloWorld Class

 [VB] 01: Public Class HelloWorld 02: 03:  Public Function SayHello() As String 04:   Return "Hello World!" 05:  End Function 06: End Class [C#] 01: public class HelloWorld{ 02: 03:  public string SayHello(){ 04:   return "Hello World!"; 05:  } 06: } 

In Listing 14.1, you create a class named HelloWorld . The class has one public instance method, on lines 3 through 5, named SayHello() .

To turn the SayHello() method into a Web-callable method (a Web service), you only need to change a few things.

1. Web services are saved as files with the .asmx extension. This identifies them as Web services.

2. Similar to how a Web Form uses the @ Page directive, a Web service uses the @ WebService directive. The directive specifies the class name for the Web service.

3. The methods you are exposing in the service need to be declared as WebMethod s.

Listing 14.2 shows how to make the HelloWorld class into a Web service.

Listing 14.2 Making the HelloWorld Web Service

 [VB] 01: <%@ WebService Language="VB" Class="HelloWorld" %> 02: 03: Imports System.Web.Services 04: 05: <WebService(Namespace:="http://www.dotnetjunkies.com")> _ 06: Public Class HelloWorld 07: 08:  <WebMethod(Description:="Say Hello to the world!")> _ 09:  Public Function SayHello() As String 10:   Return "Hello World!" 11:  End Function 12: End Class [C#] 01: <%@ WebService Language="C#" Class="HelloWorld" %> 02: 03: using System.Web.Services; 04: 05: [WebService(Namespace="http://www.dotnetjunkies.com")] 06: public class HelloWorld{ 07: 08:  [WebMethod(Description="Say Hello to the world!")] 09:  public string SayHello(){ 10:   return "Hello World!"; 11:  } 12: } 

When you create a Web service, you use the @ WebService directive (line 1) to tell the .NET Framework that this class is exposed as a Web service. The @ WebService directive specifies the language with which the class is written and the name of the class being exposed.

On line 5 you use the optional WebService attribute to provide an XML namespace for the Web service. If you do not provide a namespace for the Web service it will default to <http://tempuri.org> . By providing an XML namespace you are distinguishing the Web service from other Web services that may be using the <http://tempuri.org> namespace.

Note

The WebService attribute is optional. If you do not specify a namespace value using the WebService attribute, the Web service will use the default namespace <http://tempuri.org> . For further information regarding using namespaces with your Web services, see the Microsoft information provided at http://tempuri.org.

In a Web service, you indicate the methods you want to expose as part of the service using the WebMethod attribute. The class and any methods declared with the WebMethod attribute must be declared publicly . Looking at Listing 14.2, you can see there are some slight differences in the syntax for WebMethods in Visual Basic and C#. In Visual Basic, the WebMethod attribute is part of the method declaration. On line 8 of the Visual Basic code, the WebMethod is exposed by prefixing the function declaration with the <WebMethod()> attribute. Notice the use of the code continuation character ( _ ) to wrap the function declaration across two lines. On line 8 of the C# code, the WebMethod is exposed by adding the [WebMethod()] attribute on the line before the function declaration.

When you navigate to HelloWorld.asmx in a browser, you see a page that is automatically rendered by the .NET Framework. The page displays the name of the Web service (the class name) and a list of any methods declared as WebMethod s. Figure 14.2 shows this page.

Figure 14.2. Web service files ( .asmx ) automatically render a page displaying the name of the Web service and any Web-callable methods ( WebMethods ) available in the service.

If you click on the name of a WebMethod, a page is rendered explaining the WebMethod. The page includes a description of the WebMethod (if one was provided), a button to invoke the WebMethod (for testing), sample SOAP request and response messages, and sample Http-Get and Http-Post request and response headers. This is seen in Figure 14.3.

Figure 14.3. Clicking on a WebMethod renders a page that describes the WebMethod and the SOAP or Http-Get/Http-Post interactions.

From the WebMethod page, you can invoke the Web service to test the execution and see the results that are returned. These pages are provided for the developer and the consumer to test with and are not intended for normal user viewing. Figure 14.4 shows the page that is rendered when the SayHello() WebMethod is invoked.

Figure 14.4. Invoking the SayHello() WebMethod renders an XML document with the return value as an XML node.

From the HelloWorld.asmx file, you also can also click a link to the Service Description, which will display the WSDL document. Figure 14.5 shows the WSDL document for the HelloWorld Web service.

Figure 14.5. The WSDL for the HelloWorld Web service is automatically created by the .NET Framework.

The WSDL defines the Web service and how the client should interact with it. You will notice if you look through the WSDL that there are sections that describe how to interact using SOAP, Http-Get, and Http-Post.

only for RuBoard