Skip to content

Going from Schema to Code Using C# (SOAP Web Service)

Jump to bottom
Daniel Lowe edited this page Nov 17, 2021 · 1 revision

Overview

The software artifacts in the ES-CIM repository are meant for use in either SOAP or RESTful web services. Although the majority of web services utilize REST, SOAP is still a major part of the CIM world, and can be challenging for new developers unfamiliar with the technology to use. Therefore this page will serve mainly to give an overview on SOAP and creating a SOAP web service with the supplied artifacts, with a short explanation of how to do the same for REST.

What is a SOAP Web Service?

SOAP (Simple Object Access Protocol) is a messaging protocol specification for exchanging messages from machine to machine by means of a web service. Data is transmitted as XML (extensible markup language) with a unique SOAP envelope header over HTTP (HyperText Transfer Protocol). Due to the nature of the message, SOAP web services are language agnostic; a web service written in Java could communicate easily with a client written in another language such as C# or Python. Even though most developers are moving more toward REST (Representational State Transfer) architectures for the backend to accommodate other payloadds such as JSON, SOAP is still widely used, particularly in the utility industry with data models such as the Common Information Model (CIM) or MultiSpeak. There are two key components to making a SOAP web service: the WSDL (Web Services Definition Language) and XSD (XML Schema Definition). A WSDL describes a web service, where it’s located, and the methods that it invokes, while the XSD describes the structure of the XML document being sent. Both of these are used together when creating a contract-first web service.

How are WSDL/XSD Represented as Code?

Multiple libraries exist for converting WSDLs into Java or C# code. One of the more popular ones for Java is called wsdl2java while C# provides wsdl.exe and svcutil.exe with Visual Studio. If a client is being made for a hosted WSDL, most programming languages have a library that can convert that into suitable code, such as Zeep for Python or Savon for Ruby on Rails.

Generating Code from WSDL Using Visual Studio

For the creation of this web service, svcutil was used to generate code from the WSDL/XSDs. See https://docs.microsoft.com/en-us/dotnet/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe for documentation on svcutil. A template to use to generate code from MultiSpeak WSDL might look something like: svcutil *.wsdl *.xsd ..\..\xsd\*.xsd /language:C# /syncOnly For this to work, the sandbox XSDs would likely need to be temporarily removed from the xsd directory. The command /syncOnly removes extra operations being added to the generated interface file. Also note that this command would only work if run directly from the directory containing the MultiSpeak WSDL file, and also only while using the VS Command Prompt. Once the file is generated, remove all instances of ReplyAction=”*” as directed in the documentation at https://docs.microsoft.com/en-us/dotnet/framework/wcf/feature-details/how-to-retrieve-metadata-and-implement-a-compliant-service.

Creating the SOAP Web Service in Visual Studio

This guide assumes the use of Visual Studio 2019, and also the installation of WCF (Windows Communicatoin Foundation) templates. If these have not been installed, open the Visual Studio Installer, select “Visual Studio 2019”, and select “Modify” from the dropdown box. From there, make sure to check the box for Windows Communication Foundation (see screenshot below).

  1. Create a New Project To create a new project from scratch, select New Project when first opening Visual Studio. To create a SOAP web service, there are two main options: ASMX Web Site (legacy) and WCF Application. Two different options should come up. Select the option for C#. Proceed to click “Next” and name the project.

  1. Import the WSDL/XSD Interface Code If you haven’t already, run the svcutil command to generate code from the WSDLs/XSDs. This will generate both a .cs file and a .config file. For now, only the .cs file will be used. These files are generated in the same directory that the command was run unless specified otherwise, so if the command was run from the same directory as the WSDL, then the .cs and .config files will be in the same directory that the command was issued from. Copy and paste that .cs file into Visual Studio. This will replace the Iservice1.cs file that the WCF Service Application template automatically inserts.

  1. The .cs file generated from the WSDL/XSD will not work completely out-of-the-box on its own and will require some minor changes. As pointed out in Step 3 of Microsoft’s tutorial at https://docs.microsoft.com/en-us/dotnet/framework/wcf/feature-details/how-to-retrieve-metadata-and-implement-a-compliant-service, the ReplyAction=”*” property will need to be removed from the entire file. Another change that will need to be made is to add the namespace of the project to the file, shown in the picture below.

  1. By default, Visual Studio creates a .svc file with the name Service1.svc. Change this to a name more fitting to the project, such as MySOAPService.svc. Double click MySOAPService.svc and change the implementation from the Iservice interface that the template provides and put in the name of the interface generated by the WSDL. Upon doing so, Visual Studio should underline the name of that interface in red, telling you that a number of methods have not been implemented for that interface.

Click the error icon that should appear on the left side of the screen and select “implement interface.” This will add every method defined by the WSDL, and by default has all of them throw a NotImplementedException. Find the operations for the WSDL that need to be defined for this web service, and add custom code to implement those methods. After that, right-click the .svc file and select “View Markup”.

Change the name from Service1 to that of the class defined in the .svc.cs file.

  1. The default settings for the Web.config do the bare minimum and do not allow for error logging. Under System.ServiceModel, add something similar to the below picture:

Error logging could be set up using something like the following figure. For more details on error logging, Microsoft’s WCF tutorials go into deeper detail.

  1. Right click the Project and select Build. Fix any errors that may come up. Once the project is built, the project needs to be placed in IIS (Internet Information Services).

  2. Open up Internet Information Services (IIS) Manager and expand the column on the left until Default Web Site appears. This is where the web service will appear.

Copy the folder containing the source code of the web service. Do not copy the entire project folder that includes the solution (.sln) file though. Note the file path in the following image.

Next, copy this file to the wwwroot folder. By default, this should be at C:\inetpub\wwwroot. Once it’s copied, it should appear in IIS Manager. In IIS Manager, select that folder and select “Convert to Application.” This may require you to refresh the Default Web Site to get the folder to appear.

With that completed, select content view on the bottom of the window, right click the .svc file, and select “Browse” to view the Web Service in-browser.

This will open up in the default web browser.

If accessing this service from a remote machine, the computer name will need to be changed to its IP Address instead. Make sure that port 808 is allowed in Firewall settings for IIS WCF web services.

Clone this wiki locally