DPS907 notes – Thu Nov 26

Introduction to SOAP XML web services.


Web service design styles

There are two web service design styles in wide use today:

  1. web API

Their characteristics are summarized below, but feel free to learn more about each by starting with their Wikipedia articles (linked at the end of this document), and then moving on to other authoritative learning resources.


The web API style is also known as:

  • Web 2.0
  • Hypermedia-driven web services
  • Resource-oriented (or resource-driven) web services
  • REST (Representational State Transfer)

The SOAP XML style is also known as:

  • Web services
  • Big web services
  • RPC Services for the web
  • Legacy web services



In this course, we have been using the web API style.

A web API style faithfully follows the design intent of the web.

From a programmer’s perspective, the ‘root’, or starting location for a web API is located at a single endpoint, known as a resource URI. After accessing (reading) the data at the root endpoint, the returned data will guide the user/requestor to additional resource URIs, and state changes when appropriate.

All requests made to a web API use a wide range of the HTTP-defined request methods, including GET, POST, PUT, DELETE, OPTIONS, and HEAD.

The data format that passes between the caller/client and the server is negotiated (using the Accept and Content-Type request headers), but modern web APIs typically use JSON or a variant.



SOAP XML web services use XML messages that conform to the Simple Object Access Protocol (SOAP).

While there are many “moving parts” to this style, Visual Studio tooling and the .NET Framework make it fairly easy to implement a simple SOAP XML web service.

From a programmer’s perspective, a SOAP XML web service is located at a single endpoint in a web app. All of its functionality is accessed through this single URI.

A remote caller/client creates a SOAP message, and posts it to the web service endpoint, using HTTP POST. The SOAP message includes the name of the method to be called, and argument data, if required. The web service returns a SOAP message that includes the status/success result of the call, and typically some data.

This style of web services are considered to be a legacy technology by this article’s author. However, many employers of all kinds still use this style, so this topic treatment provides enough of an introduction to enable you to participate in this kind of work.

What does a SOAP message look like?

Here is a request:



Here is a response (truncated):



How can you create a SOAP XML web service, using the Microsoft Web Platform?

By creating a “WCF Service”.


What is WCF in Visual Studio and the .NET Framework? 

Microsoft’s Windows Communication Foundation (WCF) is a unified and general-purpose API for building service-oriented applications. Its foundational elements were introduced in 2005. Since then, it was significantly upgraded in 2008 and 2010.

WCF can also be considered an identity or marketing name for the namespaces and classes in the .NET Framework that fulfill this role.

For us as programmers, the WCF prefix for a project or item simply means that we’re creating a SOAP XML web service.

Historical note:

The predecessor of ASP.NET Web API was conceived as a WCF project type. However, it became apparent that too much coding ceremony was required to implement the web API style as a WCF project type, leading Glenn Block, Henrik Nielsen, and the team to develop the modern Web API framework.


How to create a SOAP XML web service

There are two paths you can follow when you need a SOAP XML web service:

  • Pure SOAP XML web service
  • Add a SOAP XML web service to an existing web app or (modern web API) web service


Pure SOAP XML web service as a new project 

In Visual Studio 2013, choose File > New > Project.

Then, choose “WCF Service Application”.


Add a SOAP XML web service to an existing project

It’s more interesting to add a “WCF Service” to an existing project, so this is the preferred learning approach.

The new web service is able to use your project’s data model infrastructure (design model classes, persistence through Entity Framework and SQL Server), resource model classes, and application and business logic classes (e.g. manager, repositories).

As a result, one project can serve both needs – modern web API, and legacy SOAP XML.

In Solution Explorer, right-click your project file, and add new item.

Choose “WCF Service”.

Visual Studio creates two source code files:

  • C# interface code module, and
  • class that inherits from the interface.

Write code as you have learned. Use your repository, and your resource models.

Test your work by using the “WCF Test Client” app.

There are two ways to start and use the WCF Test Client app:

1. Select the ~.svc file, then right-click, set as the “Start Page”, then press F5 (to begin debugging)

2. Or, in a command window, navigate to the current version of Visual Studio, then to the Common7\IDE folder, and then run the command ‘wcftestclient.exe’.

And obviously, we can also create a separate ‘client’ app that uses the web service.


Study a code example

Remember the AssociationsOther code example from Week 3? We will add a SOAP XML web service to the app, as described below. We will create an ’employee service’ class, to provide employee-related functionality.

wcf-service-filesThe new code example is named AssociationsSOAP.

Open the project, in Visual Studio. In Solution Explorer, select the Associations project. Right-click, and add a new item, a “WCF Service”, named “EmployeeService.svc”.

Notice that two source code files are created:

  • IEmployeeService.cs
  • EmployeeService.cs

IEmployeeService is an interface. Notice the ‘using System.ServiceModel‘ statement. That namespace contains the types necessary to build this style of web service.

Notice that the interface is preceded with a [ServiceContract] attribute. Notice that (many, most) methods are preceded with an [OperationContract] attribute. For example:

IEnumerable<Controllers.EmployeeBase> AllEmployees();

From the ServiceContractAttribute documentation (linked above):

Use the ServiceContractAttribute attribute on an interface (or class) to define a service contract.

Then use the OperationContractAttribute attribute on one or more of the class (or interface) methods to define the contract’s service operations.

When the service contract is implemented and combined with a Windows Communication Foundation Bindings and an EndpointAddress object, the service contract is exposed for use by clients.


EmployeeService is a class that inherits from IEmployeeService.

In this class, write members (methods and properties) for public operations, and members for private internal-to-the-class tasks.

If a method requires incoming data, the data must be packaged in a suitable SOAP message that conforms to a data contract. By default, the request-handling infrastructure uses a full-featured and good-enough SOAP XML serializer to map resource model types.

Responses (return types) from a method will use data contract defaults to deliver a SOAP message. For example:

public IEnumerable<Controllers.EmployeeBase> AllEmployees()
    return m.GetAllEmployees();


Compare to a modern web service: similarities, differences

After studying the code example, you will notice some similarities, and some differences.

Repository (or manager) classes still work with resource model objects and collections.

Resource model classes can be shared, or reused, between the two web service styles. The class names are visible in SOAP XML responses. If that is problematic, you could create more resource model classes, with names that meet your needs, and use them.

Responses are packaged as SOAP XML messages, and not as JSON results.


Testing the code example

In Solution Explorer, select (highlight) the EmployeeService.svc item, and run-without-debugging (Ctrl+F5). The WCF Test Client loads/runs.

Look at the left-side service navigator. It shows the methods that can be called.



Choose (double-click) the AddEmployee() method. Add some data. To do so, you must select the EmployeeAdd data type (which is the data contract for the method).



After invoking the method, study the returned result. As you can see, it was successfully added.



Select and invoke the AllEmployees() method. The just-added item is the second one in the collection, because the repository method orders the results by last name (then first name).



Learn more about this topic theme

Wikipedia article on SOAP

Wikipedia article on web service

Wikipedia article on web services protocol stack (authored from a SOAP XML perspective)

MSDN – What Is WCF


A service contract is a message exchange pattern. The “WCF Service” class defines the service contract and its supported operations.

A data contract is a class that describes a data entity (that will be exchanged). Conceptually, a data contract is similar to our view/resource model class.



A SOAP XML web service is considered to be legacy technology.

It is based on a remote procedure call architecture, and defines its own transport-agnostic protocol. It doesn’t really need the web (HTTP).

Many organizations (who may want to employ you) still use SOAP XML web services. As a result, you must know how to create, use, and integrate this technology with other web work.





















%d bloggers like this: