In this chapter, you will learn how to:
Set up the development environment required to create XML Web services for the Microsoft .NET platform.
Create a simple XML Web service using Microsoft Visual Studio .NET.
Test the XML Web service using Microsoft Internet Explorer.
Upload files to an Internet Information Services (IIS) server.
Now that we have discussed what XML Web services are, their capabilities, and the technologies they employ, it is time to learn how to develop and use them. We believe the fastest and easiest way to develop XML Web services for the Microsoft .NET platform is to create them as ASP.NET applications using Visual Studio .NET. The ASP.NET Web application framework is flexible and efficient, and the facilities provided by Visual Studio .NET are extensive, resulting in substantial time savings.
Important
Throughout this book we will use Visual Studio .NET as our principal development tool and will present our examples using both C# and Visual Basic .NET.
Before you can start developing XML Web services, you need to be sure your development environment is properly installed and configured. This is a simple process, aided by the automated installation capabilities provided with Microsoft Windows and Visual Studio .NET. In order to develop XML Web services, you need the following:
Access to a Microsoft Internet Information Service (IIS) Web server with FrontPage Server Extensions (FPSE). The IIS server must be updated by installing some .NET Framework and Visual Studio .NET components.
Tip
We strongly recommend installing a local copy of an IIS server onto your development machine. Having a local copy will simplify and speed up the XML Web service development process. Once the XML Web service is completed and tested, you can easily deploy it on a different IIS server for live testing and production use.
Access to a development machine with Visual Studio .NET installed, including either Microsoft Visual C#, Microsoft Visual Basic .NET, or both.
We provide rudimentary instructions for setting up IIS and Visual Studio .NET in the following sections. For more detailed instructions or to troubleshoot installation problems, you should refer to the appropriate product documentation. However, if you already have access to these facilities, you’ll be eager to start programming and should skip ahead to the section "Creating XML Web Service Projects in Visual Studio .NET" later in this chapter.
To develop XML Web services using Visual Studio .NET and run them as ASP.NET applications, you need access to a correctly configured IIS server. The IIS server requirements are summarized in the following table.
Feature | Requirement |
|---|---|
Operating system | Windows XP or Windows 2000. |
Version | 5.0 or later with FPSE installed. |
User permissions | Permission to write files to the IIS server either through direct Windows file-sharing capabilities or through FPSE. |
Development and run-time components | Microsoft .NET Framework. Also the Web Development and Remote Debugging components from Visual Studio .NET. |
We will use the IIS server extensively throughout this book to run the XML Web services that we develop. Ideally, the server should be a dedicated development or testing computer. You should not use an IIS server that is used for work or business purposes. A good approach for development is to install the IIS server on your development computer; this simplifies the installation, development, and debugging processes and ensures that you do not affect anybody else if things go wrong.
Here are the steps necessary to install IIS on your Windows XP or Windows 2000 computer. IIS and FPSE are standard components in these two versions of Windows and are installed through the Windows component management screens.
Procedure 2-1. Install Internet Information Services
Ensure you are logged onto the computer using an administrator account.
From the Start menu, select Run and type control into the dialog box that appears. Click OK.
Run the Add/Remove Programs utility and click the Add/Remove Windows Components option on the left side of the Add/Remove Programs dialog box.
The list of available components on the first screen of the Windows Components Wizard contains an entry for Internet Information Services (IIS), as shown here:
Select the Internet Information Services (IIS) entry, and then click the Details button.
At a minimum, select the following components and then click OK.
Common Files
Microsoft FrontPage 2000 Server Extensions
Internet Information Services Snap-In
World Wide Web Service (In Windows 2000, this component is named World Wide Web Server)
Click Next to install the selected components. During the installation process, you might be asked to insert the original Windows CD so that the system can load the required IIS files.
If you decide to install IIS on your development computer, you must do so before installing Visual Studio .NET. The Visual Studio .NET installation makes the necessary additions to the IIS installation. Skip the following steps and jump straight to the section "Installing Visual Studio .NET" later in the chapter if you’ve installed IIS on your development computer.
However, if you plan to use IIS on a remote machine, you must perform the following steps. These steps update the IIS server configuration, enabling it to run ASP.NET applications and work properly with the Visual Studio .NET integrated development environment (IDE).
Procedure 2-2. Configure the IIS Server
Log onto the IIS server using an administrator account.
Ensure IIS and FPSE are installed. If they are not installed, review the simple IIS installation instructions provided in the preceding section; alternatively consult the product documentation.
Insert the Visual Studio .NET DVD (or the first CD in the Visual Studio .NET set) into your computer.
The setup program is normally run from a CD or DVD but could also be run from a shared location on a network server. The installer applications will start automatically, and you will see the Visual Studio .NET Setup screen, shown here.
Run Step 1, Windows Component Update.
This installs the .NET Framework, including the .NET common language runtime (CLR) and the class libraries required to run .NET applications. It also makes sure that various Windows components, such as Internet Explorer and FPSE, are the required version. You will be asked to accept a license agreement and then shown which components the installer will update.
Click Install Now to start the Windows Component Update; when complete, the setup process returns to the Visual Studio .NET Setup screen.
Start Step 2, Visual Studio .NET. After accepting the license agreement and entering your product code and user name on the Visual Studio .NET Setup Start Page, you will see the Visual Studio .NET Setup Options Page.
In the tree of components on the leftmost side of the Setup Options Page, expand the Server Components and Remote Debugger branches and select the Full Remote Debugging and Web Development components, as shown in the preceding screenshot.
Click Install Now to start the installation of the selected components. After the installation is complete, the process returns to the Visual Studio .NET Setup screen.
If you have an Internet connection or a .NET Service Pack disk, start Step 3, Service Releases. This step ensures that your IIS server has the latest version of the .NET Framework and the required Windows components.
Finally, set up all programmers who will be creating XML Web service projects as members of the Windows VS Developers group.
The installation of Visual Studio .NET is straightforward and very flexible, offering fine-grained control over exactly which components are installed. To enable you to work through the examples in this book, the default installation configuration is adequate. You can always run the setup program again to add or remove additional components. In this section, we’ll list the steps required to install Visual Studio .NET.
Procedure 2-3. Install Visual Studio .NET
If you have decided to install IIS on your development machine, be sure it is installed before installing Visual Studio .NET. Refer to the instructions provided in the section "Installing Internet Information Services" earlier in this chapter or consult the product documentation.
Insert the Visual Studio .NET DVD (or the first CD in the Visual Studio .NET set) into your computer.
The Visual Studio .NET Setup screen is displayed. (This screen is shown earlier in this chapter in the section "Configuring IIS Server for XML Web Service Development.")
Click Step 1, Windows Component Update from the Setup screen.
This step installs the .NET Framework, including the CLR and the class libraries required to run .NET applications. When complete, the setup process returns to the Visual Studio .NET Setup screen.
Click Step 2, Visual Studio .NET.
After accepting the license agreement and entering your product code and user name on the Visual Studio .NET Setup Start Page, you will see the Visual Studio .NET Setup Options Page. As mentioned earlier in this section, the default component selection will be sufficient for working through this book.
Click Install Now to start the installation of the selected components. Once the installation has finished, the process returns to the Visual Studio .NET Setup screen.
If you have an Internet connection or a .NET Service Pack disk, start Step 3, Service Releases. This step ensures that the latest release and fixes to all .NET components are installed.
The XML Web services we will develop run as ASP.NET applications on an IIS server. ASP.NET provides an extensive programming framework built on the common language runtime for developing and running Web applications, including XML Web services. Although the development of XML Web services utilizes some of the features of ASP.NET, many features are not required. We will limit our discussions to those elements used in the development of XML Web services.
In this section, we discuss only basic ASP.NET features used to create XML Web services. We will introduce additional elements of ASP.NET as required in later chapters. Most importantly, we focus on a set of features known as ASP.NET intrinsic services in Chapter 10, and Chapter 12.
The XML Web services you create in ASP.NET are contained in files with an .asmx extension; each .asmx file represents a single XML Web service. Consumers utilize the functionality of the XML Web service by accessing the .asmx file, addressed by its Uniform Resource Identifier (URI). An XML Web service’s .asmx file must contain the following:
An ASP.NET @ WebService directive
The code that implements the XML Web service or a reference to the file in which the implementation can be found.
If the implementation code is contained directly in the .asmx file, it is said to be inline. Using an attribute of the @ WebService directive, you can specify another file (known as a code-behind file) where the implementation code is located.
Note
ASP.NET automatically compiles any code contained in a page the first time a client accesses it; future page requests are serviced using the compiled code, resulting in improved performance. Although you can write XML Web services to make use of the automated compilation capabilities of ASP.NET, it places restrictions on the structure and capabilities of the service. It is more common to compile an XML Web service manually, which is the approach we use in this book.
The @ WebService directive tells the ASP.NET runtime that the .asmx file contains an XML Web service and provides information about the implementation of the service. Here is an example of an @ WebService directive.
<%@ WebService Language="c#" Codebehind="Service1.asmx.cs" Class="HelloWorld.Service1" %>
The XML Web service implementation details are specified using the four attributes of the @ WebService directive, listed in the following table.
Code-behind files are an ASP.NET feature that supports the separation of HTML user interface code from the program code that provides the underlying functionality. Although HTML is not used to define user interfaces for XML Web services as it is in other ASP.NET projects, code-behind files can still be used to contain the XML Web service implementation code. Code-behind files provide structure and leave your source code free of ASP.NET directives.
Visual Studio .NET makes developing XML Web services a very simple process. In this section, we introduce the capabilities provided by Visual Studio .NET and create a simple example. Following in the tradition of software development books, we will create the XML Web service equivalent of the HelloWorld application.
The HelloWorld XML Web service is an ASP.NET application with a single method named HelloWorld. When a client invokes the HelloWorld method via a correctly formatted SOAP (Simple Object Access Protocol), HTTP-GET, or HTTP-POST request, the service responds with a message consisting of a String containing the words "Hello World". As you will see, this application can be created in Visual Studio .NET without writing a single line of code.
We recommend that you take the time to work through this example; it provides hands-on experience and provides a clear frame of reference for the more complex development activities presented throughout the rest of the book.
The following procedures show you how to create the HelloWorld XML Web service using both C# and Visual Basic .NET. The point of this example is not to understand the code but to understand the process. We will not explain the code or edit the files beyond what is necessary to get our HelloWorld service working. However, don’t worry, we will address each aspect of XML Web service development in detail using more realistic and interesting examples in later chapters. Some of the steps described below might seem obvious to readers familiar with the Visual Studio .NET IDE. However, they are brief, so we include them for completeness and for the benefit of less-experienced readers.
Procedure 2-4. Create a New Project
Start the Visual Studio .NET IDE.
Use one of the following methods to create a new project:
In the Project Types pane on the left side of the New Project dialog box, select either Visual C# Projects or Visual Basic Projects depending on the language you want to use.
In the Templates pane on the right side of the New Project dialog box, select ASP.NET Web Service.
In the Location box, type http:// <servername> /XMLWebServices/Chapter02/HelloWorld. Replace <servername> with the name of your IIS server; most likely you will use localhost.
This URL identifies the IIS server and directory in which the XML Web service files will be stored and from which the completed service will be run.
Click OK.
Visual Studio .NET generates the files necessary for the Web service and uploads them to the IIS server at the location specified, creating and configuring the server directories as required. If a project with the same name already exists at the specified location, the Project Folder Already Exists dialog box is displayed and you are prompted for a new Project Name.
Procedure 2-5. Edit the HelloWorld code
From the View menu, select Solution Explorer.
In the Solution Explorer window, right-click the Service1.asmx file and select View Code from the shortcut menu, shown in the following.
You will notice that Visual Studio .NET does not show the code contained in Service1.asmx, but in a file named Service1.asmx.cs or Service1.asmx.vb depending on the language you are using. Ignore this for now and continue with the example. We will explain the reason for these additional files in the section "The XML Web Services Project Files" later in this chapter.
Both the C# and Visual Basic .NET versions of Service1.asmx contain only a few lines of code; look through them and find the following statements.
Example 2-1. C#
// WEB SERVICE EXAMPLE // The HelloWorld() example service returns the string Hello World. // To build, uncomment the following lines then save and build the // project. To test this web service, press F5. // [WebMethod] // public string HelloWorld() // { // return "Hello World"; // }Example 2-2. Visual Basic .NET
‘ WEB SERVICE EXAMPLE ‘ The HelloWorld() example service returns the string Hello World. ‘ To build, uncomment the following lines then save and build the ‘ project. To test this Web service, ensure that the .asmx file is ‘ the start page and press F5. ‘<WebMethod()> Public Function HelloWorld() As String ‘ HelloWorld = "Hello World" ‘End Function
As you can see, the HelloWorld functionality is already written for us and included in the code that is generated by the ASP.NET Web Service project template.
Uncomment the lines of code that define the HelloWorld method, shown in the following.
Press Ctrl+S, or select Save Service1.asmx.cs (or Save Service1.asmx.vb) from the File menu.
Press Ctrl+Shift+B, or select Build Solution from the Build menu. You should see the following Output window.
You have just built your first XML Web service using Visual Studio .NET. Now we want to test the service to be sure it works. We will cover the development of XML Web service clients in Chapter 4, and Chapter 5. However, all we want now is something simple to ensure that the HelloWorld service is performing as expected. Fortunately, the ASP.NET framework provides service help pages that make it easy to inspect and test simple XML Web services using Internet Explorer.
Procedure 2-6. Test the HelloWorld XML Web Service
Start Internet Explorer.
Type the URL of the HelloWorld service’s .asmx file into the Address bar and then press Enter. For this example, assuming you used localhost as your server name, use the URL http://localhost/XMLWebServices/Chapter02/HelloWorld/Service1.asmx.
The service help page contains general information about the XML Web service and the methods it exposes. Most of the information on this page is advising us on the proper use of namespaces in XML Web services, a topic we will discuss in Chapter 3.
Click the link for the HelloWorld method at the top of the service help page.
The Web page that’s displayed provides details for the HelloWorld Web method. It includes sections showing the correct structure of SOAP, HTTP-GET, and HTTP-POST requests to the HelloWorld service as well as the response that the service will send back. The highlighted parts identify message elements that are variable at run time. We will discuss SOAP and the HTTP protocols in more detail in Chapter 4 and Chapter 5.
Click the Invoke button located in the Test section.
This button invokes the HelloWorld Web method using the HTTP-GET protocol and displays the following response data in a new browser window. The response might be a little meaningless; XML Web services are primarily intended to be used by other programs, not for interaction with people. However, you can see the string "Hello World" in the response.
<?xml version="1.0" encoding="utf-8" ?> <string xmlns="http://tempuri.org/">Hello World</string>
In this section, we’ll examine the project files created by Visual Studio .NET when you create an XML Web Service.
Procedure 2-7. View the Project Files
Open Solution Explorer while the HelloWorld project is open. You will see the following files listed.
AssemblyInfo.cs or AssemblyInfo.vb
Global.asax
Service1.asmx
Web.config
HelloWorld.vsdisco
You will also see the References folder that contains information about all the external assemblies, libraries, and components referenced by the HelloWorld solution. You might be familiar with the System, System.Data, and System.Xml references from other programming projects. However, you will also see two references that are more generally related to Web and XML Web service development: System.Web and System.Web.Service.
Click the Show All Files button on the Solution Explorer toolbar. You’ll see some additional entries. Expanding the list fully gives you access to the following files and directories.
Global.asax.cs or Global.asax.vb
Global.asax.resx
Service1.asmx.cs or Service1.asmx.vb
Service1.asmx.resx
bin directory
This is a surprising number of files for an application that does so little. Although the number of files could be dramatically reduced for the simple HelloWorld example, the project created by the Visual Studio .NET project template puts in place a structure suitable for larger applications. This setup is based on the assumption that programmers will use the project as a base on which to build larger, more functional XML Web services. We summarize the purpose of each file in the following table.
File/Directory
Description
AssemblyInfo.cs or AssemblyInfo.vb
Contains metadata that will be applied to the assemblies contained in a project, including name, version, and culture information. For more information, see the "Assembly Manifest" section in the Visual Studio .NET documentation. Assemblies and metadata are outside the scope of this book; you do not need to know about these topics to develop XML Web services.
Global.asax
This file, also known as the "ASP.NET application file," allows the programmer to add application and session startup procedures and event handlers. By convention, the functionality is implemented in separate code-behind files. For more information about this topic, consult Chapter 12.
Global.asax.cs or Global.asax.vb
The Global.asax.* files are code-behind files containing the C# or Visual Basic .NET source code that implements the functionality referenced in the Global.asax file.
Global.asax.resx
XML resources file for the Global.asax file.
Service1.asmx
Contains the main logic of the HelloWorld XML Web service, although the code is separated into a code-behind file. All that you will see here is an ASP.NET directive indicating that this file represents an XML Web service. Normally you would change the name of this file to better reflect the application being developed.
Service1.asmx.cs or Service1.asmx.vb
The Service1.asmx.* files are code-behind files for the Service1.asmx file and contain the C# or Visual Basic .NET functionality for the XML Web service.
Service1.asmx.resx
XML resources file for the Service1.asmx file.
HelloWorld.vsdisco
This file is used by ASP.NET to automatically generate DISCO (short for discovery) files from Web services. When a client requests this file from the IIS server, the subdirectories are searched for files that contain XML Web services, and a DISCO file is generated automatically. We discuss this feature in Chapter 9.
Web.config
Web.config is an XML file that holds configuration settings for the XML Web service. We discuss Web.config file settings throughout the book in the context of the features they relate to.
in directory
When the source files are compiled, the resulting assembly files are stored in the bin directory. The bin directory is the location from which the XML Web service functionality is executed when a client makes a request. All external libraries used by the XML Web service should also be put in the bin directory.
XML Web service project files must be uploaded to an IIS server before they can be executed. This is true even if the IIS server is running on your development machine. There are two methods that Visual Studio .NET uses to communicate with the IIS server to upload your XML Web service project files.
File Share
When using an IIS server installed on the local machine or on a network server to which you have Windows-based file access, Visual Studio .NET can upload files to the server directly. File Share access is fast but is limited by the requirement of having Windows networking connectivity to the target server, something rarely possible across the Internet.
FrontPage extensions
For remote IIS servers that are not accessible as Windows file servers, Visual Studio .NET uses FPSE to upload project files to the server. FPSE do not offer the performance of File Share, but they allow much more flexible connectivity over large networks such as the Internet.
The communications mechanism used is controlled by a project’s Web access mode. Following installation, the default mechanism is File Share, but a programmer can configure this option and the setting can be changed on a per-project basis as well. If you need to change the Web access mode for a particular project, be sure that you have the ability to connect to the IIS server using the new method or it will prevent you from uploading your project files. Changing the default Web access mode affects the Web access mode of new projects but not existing projects.
Procedure 2-8. Configure the Default Web Access Mode
Select Options from the Tools menu; the Options dialog box appears.
Select the Projects folder from the pane on the left, followed by the Web Settings item.
At the top of the pane on the right, the options named File Share and FrontPage Extensions control the default Web access mode for XML Web service projects.
Select the default method you prefer, and then click OK.
Procedure 2-9. Configure the Web Access Mode for a Project
In Solution Explorer, highlight the XML Web service project that you want to configure and press Alt+Enter. (You can also right-click the project and choose Properties from the shortcut menu.) The project’s properties page is displayed.
Select the Common Properties folder from the pane on the left, followed by the Web Settings item.
Expand the Web Server Connection folder in the pane on the right.
Select the setting you want for the Web access mode from the drop-down list and then click OK.
To | Do This |
|---|---|
Install IIS and FPSE | Open the Add/Remove Programs in Control Panel. Select Add/Remove Windows Components, and then select Internet Information Service from the list of components. Use the Details button for fine-grained control over which components will be installed. |
Upgrade an IIS server installation for use with XML Web services created in ASP.NET | Run the Visual Studio .NET setup program on the IIS server. Following the instructions, install the Windows Component Updates, and then install the Web Development and Remote Debugging components from Visual Studio .NET. |
Create a new XML Web service project using Visual Studio .NET | From the Visual Studio .NET File menu, select New and then select Project. Choose C# or Visual Basic .NET as the development language, and then select the ASP.NET Web Service project template. Type the location for the new XML Web service, and then click OK. |
Test an XML Web service using Internet Explorer | Run Internet Explorer and navigate to the URL of the .asmx file for the XML Web service you want to test. |