Creating the WSDL Document by Using .NET SDK XML

In this section, we will discuss the components of WSDL specifications. Then, you will create the WSDL document that contains these components.

The Components of the WSDL Specification

The components of the WSDL specification are discussed in the following list:

  • definitions. This is the root element in any WSDL document. It contains the name of the Web service, a description of all the service elements, and the namespace declaration statements.
  • types. This element contains the definitions of all types used in the Web service. The types that can be included in a WSDL document are a part of the W3C XML schema specification.
  • message. This element describes the messages that are exchanged between the Web service and the client application. The message element also contains various part elements that refer to the parameters and the return types of the Web service operations.
  • portType. This element is a combination of similar message elements. A portType element can be used to combine messages for operations that can be grouped as one category.
  • binding. This element defines how the service will be transported. It binds the various ports to specific wire protocols.
  • service. This element defines the location from which you can invoke a Web service.

Creating the definitions Element

You will now create the WSDL document. The first step is to create the definitions element, as shown in the following code snippet:

As discussed earlier, the definitions element defines the name of the Web service. It also contains the namespace declarations that will help you refer to multiple types defined in external specifications. In addition, the definitions element defines the targetNamespace, which is an XML schema declaration that allows a document to refer to it.

The definitions element also defines a default namespace, as shown in the following statement:

xmlns=http://schemas.xmlsoap.org/wsdl/

All elements in the WSDL document that do not have a namespace prefix are assumed to belong to this namespace. It is recommended that you include this namespace because you will be using types and elements, defined in the SOAP schema, in the WSDL document.

Note?/td>
In all preceding namespace declaration statements, it is not necessary to use the URIs that exist. The URIs that are included in a WSDL document should be unique.

Creating the types and message Elements

The data exchanged between a Web service and a client application is passed in the form of messages. Therefore, the process of creating WSDL documents includes creating the types and messages that are exchanged.

Although the WSDL specification can support any type, the specification uses the types that are declared in the XML schema as its native types. In addition, the types element in the WSDL document includes any data of a type that is not a part of the Schema declaration.

For every operation in a Web service that involves calling a method exposed by the Web service and retrieving data from the data source, you need to declare two messages. Each message will contain part elements that define the type and the name of parameters that are passed to the methods and the values that those methods return. You will create the messages for the GetRateByCurrency operation that returns exchange rate for the currency that is passed as a parameter to the method. The message element for the GetRateByCurrency operation is as follows:

As you can see, the float and string types are preceded with the prefix xsd. The xsd prefix indicates that the float and string types are part of the XMLSchema namespace, as defined by the following declaration in the definitions element:

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

Each of the messages in the GetRateByCurrency operation contains one part element. The part element for the request message stores the parameter that is passed to the message, and the part element for the response message stores the value that the method returns.

Consider a situation in which you create a Visual Basic class that contains a method from these declarations.

Note?/td>
You will learn to create a Visual Basic class and the GetRateByCurrency() function in the later section titled "Using the wsdl.exe Tool."

The method in this case will have the following signature:

Function GetRateByCurrency(ByVal strCurrency As String) as Single

The preceding statement declares a function, GetRateByCurrency(), which accepts a string parameter, strCurrency. This parameter is passed as a value parameter.

Note?/td>
The preceding method passes the parameter as a value parameter (ByVal). To pass the parameter as a reference parameter (ByRef), you 183 need to include an additional part element in the message element, as shown in the following example:

The GetRateByCurrency() function processes the value passed as a parameter and returns a Single type value.

Tip?/td>
Single is the equivalent of float in Visual Basic .NET.

Another operation that a Web service can perform is to return an exchange rate depending on the currency and denomination that the user passes. The messages for this operation are declared as shown in the following code:

In addition to the preceding operations, you can define the GetCountryData operation. This operation accepts the name of a country as a parameter and returns the currency or the denomination and exchange rate. Because the operation in this case returns two values, you cannot directly use any of the types that are available in the XML schema. Therefore, you need to create a custom type in the types element, as shown in the following code:

The preceding code uses the complexType element to define a new type Country Data. You can use this type to specify the return type of an operation, as shown in the following code:

Consider another situation in which you need to pass or return a type that is not user defined, as explained in the previous example. Further, consider that the user-defined type is an array of string or float values. Therefore, you need to declare the type in the types element as shown:

After declaring the type, you can use it in the message, as shown in the following example:

As you can see, the Get Countries List operation is simple enough. It does not accept parameters, but it returns an array of strings.

Creating the port Types Element

Next, you need to group all related operations supported by the Web service together. The Web service in this case does not have various kinds of operations. All operations that the Web service exposes can be put into a single category, and therefore, a single portType. Each portType section has at least one operation element. This element links the names of the operations that the Web service supports and the messages that are related to the operation. The portType section for the Web service is shown in the following code:

The preceding code defines a port Type element with a name Exchange Rate Soap Port and groups various operations in it. Each operation can have an input message that transfers some data from a client to the Web service and an output message that transfers the data back to the client application. Various types of operations that can be grouped into a WSDL document are explained in the following list:

  • A one-way operation that contains only an input element and an input message. In a one-way operation, the client calls the Web service by passing some data as a parameter; however, the Web service does not return a value.
  • A one-way operation in which the Web service sends a message to the client application, which does not accept a parameter. This operation contains only an output message element.
  • A request-response operation in which the client calls the Web service by passing some data as a parameter and the Web service in turn processes the data and returns the output. A request-response operation has both the input and the output messages.
  • A request-response operation in which the Web service sends a message to the client and accepts a reply from the client. This operation will have an output message followed by an input message.

Creating the binding Element

Now that you have specified the operations that the Web service will support and the messages that will be used to support the operations, and you have categorized the operations into various portTypes in the WSDL document, the next step is to add details about the protocols that will be used in the Web service. The binding section specifies this information in the WSDL document. The binding section for the Web service is as shown here:

Creating the service Element

The final section in a WSDL document is the service element. This element specifies the location from which you can access the Web service. Because the Web service that you have created is an ASP.NET Web service, the URL will point to an .asmx file.

Add the following service element to the WSDL file:

After specifying the individual elements in a WSDL document, the entire WSDL document is as follows:

Creating the Web Service from the WSDL Document

You have created the WSDL document, which defines the interface for the Web service. You can now create the Web service from the document. To create a Web service, you need to create a Visual Basic .NET file, which contains class definitions for the Web service that is created from this WSDL document.

To create a Web service form the WSDL document, create a virtual directory on your local IIS installation and copy the WSDL document to it. Name the virtual directory ExchangeService. You can create the .vb file for the WSDL document by executing the wsdl.exe tool.

The wsdl.exe Tool

wsdl.exe is a command-line utility that is a part of the .NET Framework SDK and will be installed under the <Drive>:Program FilesMicrosoft Visual Studio .NETFrameworkSDK Bin folder. The wsdl.exe tool contains various command-line options. The following list discusses some of the most commonly used command-line options:

  • /language: or /l:. This command-line option allows you to select the .NET language to be used to create the Server class or the proxy class. The value for the /language: or /l: command-line option can be VB (for Visual Basic .NET), CS (for C#), or JS (for JScript). The default value for the /language: command-line option is C#.
  • /Server:. This command-line option specifies that the class is a Server class for a Web service. However, by default, a client proxy is created.
  • /protocol:. This command-line option selects the protocol that you can use to transfer the Web service messages. These protocols include SOAP, HttpGet, and HttpPost.
  • /username: or /u:This command-line option specifies the username to use when the WSDL document is present on a Web server that requires authentication.
  • /password: or /p: This command-line option specifies the password, if any, for accessing a Web server that requires authentication.
  • /domain: or /d:This command-line option specifies the domain in which the Web server is present.
  • /proxy:This command-line option specifies the URL of a proxy server, if any. The default value of the /proxy: command-line option is to use the Internet Explorer settings.
  • /proxyusername: or /pu:This command-line option specifies the username to access the proxy server as specified by the /proxy: command-line option.
  • /proxypassword: or /pp:This command-line option specifies the password to access the proxy server as specified by the /proxy: command-line option.

Using the wsdl.exe Tool

To execute the wsdl.exe tool to generate the Web service class, use the following command:

The preceding code uses the out parameter to specify the name of the .vb file. This file contains the classes for the Web service. The language parameter specifies the .NET language in which the classes are created.

The .vb file that is created by executing the wsdl.exe tool contains a class declaration for each portType declared in the WSDL document. The .vb file also contains the method declarations for each of the operations that is defined in the WSDL document. The code for the file created by wsdl.exe is shown here:

The preceding code contains a class containing a MustInherit declaration. Also, some of the methods in the class have the MustOverride declaration. This class is an abstract class. You cannot create objects out of a class declared as Must Inherit. You need to create another class that inherits from this class and overrides all methods in the base class declared as Must Override.

Tip?/td>
You cannot create an instance of an abstract class. To implement the methods of an abstract class, you need to derive a new class from the abstract class.

While you've been working with the wsdl.exe tool, you must have noticed that the tool has problems identifying and converting user-defined types. For example, the wsdl.exe tool is unable to understand the Country Data type that you declared in the types element of the WSDL document. Therefore, the tool converts the complex type to a string type, as shown in the following example:

Now you need to explicitly add a declaration for the CountryData class and change the return type of the method declaration, as shown in the following code snippet:

CountryData

The declaration of the public class CountryData is shown here:

After you add the declaration for the CountryData class, you can use the Server class. Because the Server class is abstract, you will use it as a base class. To implement the methods of the Server class, derive a new class that a Web service can use to provide the required functionality.

Next, you need to create an .asmx file and its corresponding codebehind.asmx.vb file. The .asmx.vb file contains the class, which is derived from the ExchangeRateService class that you created in the preceding example. The derived class will contain the implementation for all methods in the base class. The directive for the .asmx.vb file is shown here:

The preceding code specifies that the code that implements the logic for the .asmx file is stored in the Webservice.asmx.vb file. In addition, the class that implements the Web service is called Webservice1. To implement the functionality in the Webservice.asmx.vb file, you need to compile the .vb file as a DLL file and copy the DLL file to the bin folder.

Tip?/td>
Remember: The bin folder should be in the folder that contains the .asmx file.

The next step in the implementation of a Web service is to create the Webservice1.asmx.vb file. To create this file, perform the following steps:

  1. Use any text editor, such as Notepad, to create a new file named Webservice1.asmx.vb.
  2. Copy the contents of the ExRate.vb file to the Webservice1.asmx.vb file.
  3. Note?/td>The ExRate.vb file was created using the wsdl.exe tool.

  4. Write the code to create a new class, Webservice1, which is derived from the ExchangeRateService class.
  5. Set the WebserviceBinding attribute for the Webservice1 class.
  6. Tip?/td>Although the WebserviceBinding attribute is set for the ExchangeRateService class, you need to explicitly set the attribute for the Webservice1 class that is derived from the ExchangeRateService class.

  7. The code for the Webservice1 class is shown in the following example:
  8. Override all methods of the ExchangeRateService class by using the MustOverride attribute. For example, to override the GetRateByCountry() method, use the following code:

Note?/td>
Overriding the methods does not implement the functionality for retrieving the data from the database and returning the data to the client application. You will learn to implement the functionality later in this chapter.

Similar to the GetRateByCountry() method, you can override the rest of the methods of the abstract class, Exchange RateService. The code for overriding the GetCountryData() method is shown in the following example:

Compiling the Webservice1.asmx.vb File

The final step in the creation of the Web service is to compile the Webservice1.asmx.vb file. To compile the file, use the Visual Basic .NET command-line compiler, vbc.exe, which is available as part of the .NET Framework SDK at a path similar to <Drive>:winntmicrosoft.net frameworkv1.0.3705.

To execute the vbc.exe compiler, use the following command-line command:

As you can see, the preceding code uses the reference attribute to add references to all assemblies that contain the methods that you use in the Web service. In addition, the /target option specifies the type of the assembly. In this case, you need to use the library type assembly. However, the default value of the /target option is a console application. Next, the libpath option specifies the path of the Framework assemblies that are specified by the reference option.

Executing the preceding command-line command creates the Webservice1.dll file in the current folder. Copy this file to the bin folder.

Now your Web service is ready for access. You can access the Web service by using the address http:// localhost /Exchange Service / Webservice1.asmx. Figure shows the list of operations that support the Web service.

The List of Operations that the Web Service Supports

The List of Operations that the Web Service Supports

To test the GetRateByCountry() Web method, click on the GetRateByCountry link. You can see the page from which you can actually invoke the Web operation in Figure.

Invoking the GetRateByCountry Link

Invoking the Get Rate By Country Link

When you invoke the GetRateByCountry() Web method, an empty page is displayed. This is because you have not completed the implementation of the Web service. To complete the implementation of the Web service, you need to connect your Web service to a database. The following section discusses how to connect the Web service to a database.


All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

XML Topics