DPS907 notes – Tue Nov 18

Introduction to SOAP XML web services.

.

Plans for the last three weeks of the course

The following is the plan for the last three weeks of the course.

Tuesday Thursday
Nov 18
RPC Services (aka SOAP XML web services) introduction
Nov 20
Security topic – claims
Nov 25
Security topic – claims
Other TBA
Nov 27
Test 2 (security-related programming task)
Dec 2
TBA
Dec 4
Work on Assignment 2
(due on Friday December 5)

A reminder: This course does not have a final exam.

.

Web service design styles

There are two web service design styles in wide use today: web API, and SOAP XML. Their characteristics are summarized below, but feel free to learn more about each by starting with their Wikipedia articles, and then moving on to other authoritative learning resources.

Terminology:

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

.

Web API

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.

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

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 an introduction.

What does a SOAP message look like?

Here is a request:

soap-request-v1

.

Here is a response (truncated):

soap-response-v1

.

How can you create a SOAP XML web service, using the Microsoft Web Platform? Create 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 ceremony was required to implement the web API style as a WCF project type, leading Glenn, Henrik, 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).

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 Associations code example from a few weeks ago? We will add a SOAP XML web service to this app, as described below. We will create an ’employee service’ class, to provide employee-related functionality.

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

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:

[OperationContract]
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.Employees.GetAll();
}

.

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.

 

soap-service-navigator

.

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

soap-add-item

.

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

soap-add-item-result

.

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

soap-all-items-including-new-item

.

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.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

  1. No comments yet.
  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: