Walkthrough: Accessing a Web Service Using Visual Basic or Visual C#

Article
11/16/2012

The following walkthrough describes the process for accessing a Web service from an application created with Visual Basic or Visual C#.

During the course of this walkthrough, you will accomplish the following activities:

Create a client application using the ASP.NET Web Application project template.
Add a Web reference for a Web service.
Write code to access the Web service.
Run the Web application in debug mode.
Deploy the Web application.

To complete the walkthrough, you must provide the following:

Because this walkthrough uses a Web application to access a Web service, you must provide a machine that meets the requirements for creating a Web project. You will also need sufficient permissions to be able to create Web Service projects on the computer where your Web server is.
A Web service created from the following walkthrough:
- Walkthrough: Creating a Web Service Using Visual Basic or Visual C#

Creating a Web Service Client Project

For this walkthrough, you will create a simple Web application that accesses the TempConvert1 Web service, which was the name given to the Web service created in Walkthrough: Creating a Web Service Using Visual Basic or Visual C#.

Note

If you changed the name of the temperature conversion Web service when you created it, simply substitute the appropriate names where the TempConvert1 name appears throughout this walkthrough.

To create an ASP.NET Web application

On the File menu, choose New Web Site.
In the New Web Site dialog box, select the ASP.NET Web Site icon.
Enter the address of the Web server on which you will develop the Web application and specify TempConvertClient1 as the directory name, such as "https://MyServer/TempConvertClient1". By default, the project uses your local machine, "https://localhost".

Note

For some project types, the Name textbox is unavailable because specifying the location sets the project name instead. For example, Web applications and Web services are located on a Web server and derive their name from the virtual directory specified on that server.

Note

You develop Web applications on a development server. By default, the development server is your local machine. Typically, you develop and build the project on a development server, and then you deploy it to another server (the deployment server) that hosts the Web application using a deployment project. However, if you are developing directly on the server that hosts the Web application, the development server and deployment server are the same.
Click OK to create the project.
In Solution Explorer, right-click Default.aspx and choose View Designer to open the designer.
From the Web Forms tab of the Toolbox, drag a Text Box, a Label, and a Button to the design surface of Default.aspx and arrange them to your liking.
Right-click the button you added, Button1, and click Properties on the shortcut menu. In the Properties window, set the Text property to Convert.
Right-click the label you added, Label1, and click Properties on the shortcut menu. In the Properties window, clear the Text property to make this a blank label.

Adding a Web Reference

Web service discovery is the process by which a client locates a Web service and obtains its service description. The process of Web service discovery in Visual Studio involves interrogating a Web site following a predetermined algorithm. The goal of the process is to locate the service description, which is an XML document that uses the Web Services Description Language (WSDL). For more information, see XML Web Service Discovery.

The service description describes what services are available and how to interact with those services. Without a service description, it is impossible to programmatically interact with a Web service. For more information, see XML Web Service Description.

Your application must have a means to communicate with the Web service and to locate it at run time. Adding a Web reference to your project for the Web service does this by generating a proxy class that interfaces with the Web service and provides a local representation of the Web service. For more information, see Web References in Visual Studio and How to: Generate a Web Service Proxy.

To add a Web reference

On the Website menu, choose Add Web Reference.
In the URL box of the Add Web Reference dialog box, type the URL to obtain the service description of the Web service you want to access, such as https://localhost/TempConvert1/Service1.asmx. Then click the Go button to retrieve information about the Web service.

- or -

If the Web service exists on the local machine, click the Web services on the local machine link in the browser pane. Then click the link for the TempConvert1 Web service from the list provided to retrieve information about the Web service.
In the Web reference name box, rename the Web reference to ConvertSvc, which is the namespace you will use for this Web reference.
Click Add Reference to add a Web reference for the target Web service. For more information, see How to: Add and Remove Web References.

Visual Studio downloads the service description and generates a proxy class to interface between your application and the Web service.

Accessing the Web Service

Once you add a reference for the Web service to your project, the next step is to create an instance of the Web service's proxy class. You can then access the methods of the Web service in the same manner that you access any object's methods by calling methods in the proxy class. When your application calls these methods, the proxy class code generated by Visual Studio handles the communications between your application and the Web service.

First, you will create an instance of the Web service's proxy class. Next, you will take a value, provided in TextBox1, and make a call to the Web service's ConvertTemperature method using the proxy class. You will then display the value returned from the Web service in Label1.

To access the Web service

Double-click the Convert button on WebForm1.aspx to create an event-handling method for this button and to display the code-behind file.

Enter the following code:

' Visual Basic
Protected Sub Button1_Click(ByVal sender As Object, _
  ByVal e as EventArgs) Handles Button1.Click
    Dim ws As New ConvertSvc.Service
    Dim dFahrenheit As Double
    Dim dCelsius As Double
    Try
        dFahrenheit = Convert.ToDouble(TextBox1.Text)
        dCelsius = ws.ConvertTemperature(dFahrenheit)
        Label1.Text = dCelsius.ToString()
    Catch
        Label1.Text = "Conversion failed."
    End Try
End Sub

// C#
protected void Button1_Click (System.Object sender, System.EventArgs e)
{
   try
   {
      ConvertSvc.Service1 ws = new ConvertSvc.Service1();
      double dFahrenheit = Convert.ToDouble(TextBox1.Text);
      double dCelsius = ws.ConvertTemperature(dFahrenheit);
      Label1.Text = dCelsius.ToString();
   }
   catch
   {
      Label1.Text = "Conversion failed.";
   }
}

Note

The name of the Web service class generated when adding a Web reference may differ from the one shown above as Service1.

Select Default.aspx in Solution Explorer.
On the Website menu, click Set as Start Page.
Save the solution.

For more information, see How to: Access a Web Service in Managed Code.

Debugging the Web Service Client

Visual Studio offers several methods to build and run a Web application from the IDE, such as:

Start (with Debugging)
Start without Debugging
View in Browser

As a Visual Studio project, this Web application has separate configurations for Release and Debug versions. Since you created this project using the ASP.NET Web Application project template, Visual Studio automatically created these configurations and set the appropriate default options and other settings. For more information, see How to: Set Debug and Release Configurations.

In this walkthrough, you will place a breakpoint in the Button1_Click event and use the Start (with debugging) method. For more information, see How to: Debug Web Services in Managed Code.

Prior to debugging, verify your debug settings. For more information, see Debugging Preparation: ASP.NET Web Applications.

To use a breakpoint and start the Web application with debugging

On the Debug menu, click New Breakpoint then choose Break At Function.

Type Button1_Click in the Function box and click OK to place a breakpoint on the Button1_Click event handler. For more information, see Breakpoints Overview.
On the Debug menu, click Start, then click Ok in the Debugging Not Enabled window to start debugging.

This command instructs Visual Studio to run the Web application in the debugger. Visual Studio builds the project and deploys it to the designated development server. Upon completion, the default browser launches and navigates to the .aspx file on the deployment server.
Once the page displays in the browser, type the number 212 in the text box and then click the Convert button.

When processing reaches the Button1_Click event handler, processing stops. The Visual Studio debugger highlights the line containing the breakpoint and while halted, you can perform a variety of tasks. For more information, see Debugger Roadmap and Viewing Data in the Debugger.
On the Debug menu, click Continue to continue processing.
The Web service responds by returning the converted value and the application sets the text of Label1 to 100.

To stop running the Web application and return to the Code Editor, on the Debug menu, click Stop Debugging.
On the Debug menu, click Clear All Breakpoints.

Deploying the Client

To make your Web application available to others, you must deploy it to a Web server that is accessible to the clients you wish to support. To deploy the Web application to a server other than the development server, you can either add a Web Setup project or copy the required files to the destination server. In this walkthrough, you can choose how to deploy this Web application. For more information, see Deploying Applications and Components.

To deploy the Web application using a Web Setup project

On the File menu, point to Add, and then click New Project.
Select the Other node, then the Setup and Deployment Projects node, and then click Web Setup Project.
In the Name box, type TempConvertClient1WebSetup, and then click OK.

Note

By default, the installer uses the deployment project name when creating the virtual directory on your deployment server.
In the left pane of the File System Editor, select Web Application Folder. For more information, see File System Editor.
In Solution Explorer, right-click TempConvertClient1WebSetup, point to Add, and then click Project Output.
In the Add Project Output Group dialog box, select Content Files. For more information, see How to: Add and Remove Project Outputs in the File System Editor.
- The Content Files group consists of the remaining files for the Web application, such as WebForm1.aspx and Web.config.
Click OK.
In Solution Explorer, right-click the TempConvertClient1WebSetup project, and then on the shortcut menu, click Build.

This creates a Windows Installer file in the local project directory. Executing this file installs the Web application.

To deploy the Web application by copying the project

In Solution Explorer, select the TempConvertClient1 project.
On the Project menu, click Copy Web Site.
Click the icon next to the Connect To dropdown box to open the Open Web Site dialog box. Browse to the location to which you want to copy the project.
In the Source Web Site pane, select the files to copy and move them to the Remote Web Site pane by clicking the right-arrow icon.
Click Copy Web Site to copy the Web site.