DPS907 notes – Tue Dec 19 2017

An introduction to SOAP XML web services, server and client.

 

Code examples for this week

This week, we will introduce you to SOAP XML web services. We have two code examples. Both are in the code repository:

Server: SOAP Server – implements a standard SOAP XML web service listener

Client: SOAP Client – a standard web app, which calls into the server above

 

Web service design styles

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

  1. Web API
  2. SOAP XML

Their characteristics are summarized below, but please attempt to learn more about each by starting with their Wikipedia articles (linked later in this week’s notes), 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.

The 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

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.

These are the most notable “big differences”:
1. The service is located at a single endpoint URI
2. Almost all requests use HTTP POST

 

This style of web services are considered to be a legacy technology by this document’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?

The request method is usually “POST”, and the content type is typically “application/soap+xml”. Most requests include an entity body.

Here is an example of a requests’s data (entity body):

soap-request-v1

 

Here is an example of the response data (partial):

soap-response-v1

 

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

 

Getting started with a SOAP XML web service

Your professor will guide you through the process of creating a legacy SOAP XML web service.

Make sure you have the Assignment 3 example solution, from the course’s GitHub repository.

Be prepared to follow along in Visual Studio.

 

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

Why? Several advantages:

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). And, it can use your accumulated knowledge and experience in building modern web services.

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.

In the interface, add definitions for the methods that are needed.

In the inheriting class, implement the methods that were added in the interface.

Then, write code as you have learned, in the inheriting class. Use your manager, 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.

 

Get started on the assignment

Assignment 9 – the final assignment in the course – is now available.

Its due date is after the Christmas – New Year’s Day break, on Thursday, January 4, 2018, at 11:00pm ET.

Before leaving the classroom at the end of the timeslot, hand in your work report.

 

 

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Advertisements
%d bloggers like this: