HowTo: Accessing a SOAP/XML Web Service Using Visual C# 

 

 

Table Of Contents

1. About this Document

2. Creating a Web Service Client Project

3. Adding a Web Reference

4. Accessing the Web Service

5. Debugging the Web Service Client

1. Aboutthis Document

  The following document describes the process for creating a C# client and connecting it to SOAP/XML Web service. The actions you will preform closely resemble what an EHR would do to talk to your web service. You will build a simple proof of concept client application submits a web service request consisting of a user id, password, facility id and hl7 message and receives a response.

You will create a simple Web application that accesses the refrence implementation IIS web service provided by the Transport Layer Expert Panel (TLEP) available at: http://openimmunizationsoftware.us:6394/ImmMessagingServer/client_Service. This web service happens to be implemented in Java, but this doesn't matter because the client application that we are creating will be able to connect to a Web service implented in any programming language. During the course of this walkthrough, you will accomplish the following activities:

  • Create a C# client application.

  • Add a Web reference for a SOAP/XML Web service.

  • Write code to access the SOAP/XML Web service.

  • Run the Web application in debug mode.

To complete the walkthrough, you must provide the following:

  • Because this walkthrough uses a Web application to access an SOAP/XML Web service, you must provide a machine that meets the requirements for creating a Web project.

  • Access to a SOAP/XML Web service. We will be accessing a refrence implementation of an IIS web service provided by the Transport Layer Expert Panel (TLEP) available at:  http://openimmunizationsoftware.us:6394/ImmMessagingServer/client_Service

 

 

To create an ASP.NET Web application

  1. On the File menu, choose New Web Site.

  2. In the New Web Site dialog box, select the ASP.NET Web Site icon.

  3. Click OK to create the project.

  4. In Solution Explorer, right-click Default.aspx and choose View Designer to open the designer.

  5. From the Web Forms tab of the Toolbox, drag 5 Text Boxes, 5 Labels, and a Button to the design surface of Default.aspx and arrange them to your liking (see image below for example).

  6. Right-click the button you added and click Properties on the shortcut menu. In the Properties window, set the Text property and Id property to Submit.

  7. Right-click the labels you added and click Properties on the shortcut menu. Rename the labels them by modifying the Text property in the Properties window.

  8. Right-click the textboxes you added and click Properties on the shortcut menu. In the Properties window, rename the Id property of all the textboxes according to type of input the textbox captures. For instance, the textbox that captures the username should have it's Id set to Username.

  9. Increase the size of the HL7 Message and Response text boxes to make easier to read the Hl7 Messages.

Once you've completed the steps above you should have a page the resembles the following:

 

XML Web service discovery is the process by which a client locates an XML Web service and obtains its service description. The process of XML 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).

Your application must have a means to communicate with the XML Web service and to locate it at run time. Adding a Web reference to your project for the XML Web service does this by generating a proxy class that interfaces with the XML Web service and provides a local representation of the XML Web service.

To add a Web reference

  1. On the Website menu, choose Add Web Reference.

  2. 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 http://openimmunizationsoftware.us:6394/ImmMessagingServer/client_Service?wsdl. Then click the Go button to retrieve information about the Web service.

  3. In the Web reference name box, rename the Web reference to ImmunizationService which is the namespace you will use for this Web reference.

  4. Click Add Reference to add a Web reference for the target Web service.

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

Once you've completed the steps above your Add Web Reference screen should resemble the image below:

 

AddWebReference

 

 

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 values, provided in Username, Password, FacilityId and Hl7Message textboxes, and make a call to the Web service's submitSingleMessage method using the ImmunizationService proxy class. You will then display the value returned from the Web service in the Response textbox.

To access the Web service

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

  2. Modify the Submit_Click() method so that it contains the code below:

    using System; 
    using System.Collections.Generic; 
    using System.Linq; using System.Web; 
    using System.Web.UI; 
    using System.Web.UI.WebControls; 
    
    namespace WebApplication3 
    { 
      public partial class _Default : System.Web.UI.Page 
      { 
        protected void Page_Load(object sender, EventArgs e) 
        { 
        
        }
        
         // Executes when the Submit button is pressed
        protected void Submit_Click(System.Object sender, System.EventArgs e) 
        { 
          try 
          { 
             // Instantiate the web service reference 
            ImmunizationService.client_Service service = new ImmunizationService.client_Service();  
             // Execute the web service method
            String result = service.submitSingleMessage(Username.Text, Password.Text, FacilityID.Text, HL7Message.Text); 
             // Display the response from the web service
            Response.Text = result.ToString(); 
          } 
          catch 
          { 
            Response.Text = "Request failed."; 
          } 
        } 
      } 
    }
    
                                                
    NoteNote

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

  3. Select Default.aspx in Solution Explorer.

  4. On the Website menu, click Set as Start Page.

  5. Save the solution.

To use a breakpoint and start the Web application with debugging

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

    Type Submit_Click in the Function box and click OK to place a breakpoint on the Submit_Click event handler.

  2. 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.

  3. Once the page displays in the browser, fill in the text boxes and then click the Submit button.

    When processing reaches the Submit_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.

  4. On the Debug menu, click Continue to continue processing.

  5. The XML Web service responds by returning the response and the application sets the text of Response.

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

  6. On the Debug menu, click Clear All Breakpoints.