DPS907 notes – Tue Nov 29

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

 

Test today

The weekly test will be done at the beginning of the class timeslot at 11:40am.

 

Code examples for today

Today, you will be introduced 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 feel free to learn more about each by starting with their Wikipedia articles (linked at the end of this section), 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.

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?

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.

 

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

 

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

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<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<EmployeeBase> AllEmployees()
{
    return m.EmployeeGetAll();
}

 

Compare to a modern web service: similarities, differences

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

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.

wcf-test-client-2

 

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.

 

Summary of the web service “server” content above

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.

Next, we will look at the client/requestor end.

 

Client app that interacts with a SOAP XML web service

Now, you will learn how to design and code a client app that will work with a SOAP XML web service.

Please note that today’s code examples do not use security technologies. That topic, for SOAP XML web services, is beyond the scope of this DPS907 / WSA500 course.

If or when you are interested…

Here’s some content that will help you get started with security topics for SOAP XML web services:

Open Web Application Security Project (OWASP) – Web Services development guide

Wikipedia – Start page for WS-Security, which defines the security components and process

Wikipedia – Start page for WS-Trust, which defines token issuing, token validation, and trust relationships

 

Getting started with client apps for SOAP XML web services

When working with modern web services – the style we have been learning during this course – you have used some client apps to interact with the web service.

Most of your experience is with Fiddler. It is a general-purpose HTTP inspector, but it is ideal for our needs.

More recently, you saw JavaScript interact with a web service, using an XMLHttpRequest object.

And, in an ASP.NET MVC web app, you used an HttpClient object to interact with the web service.

What about client apps for SOAP XML web services?

We used the WCF Test Client, during development.

We can also use a browser, but only for GET requests. (Many interactions with SOAP XML web services are done with POST requests.)

 

Kinds of client apps for SOAP XML web services

In general, the same kinds of client apps can be created for SOAP XML web services:

  1. Mobile devices
  2. Browsers, using JavaScript
  3. Server-based apps

Today, we will look at #3. The other two are beyond the scope of this course.

 

Server-based app, based on an ASP.NET project type

First, create a new project, maybe named SOAPClient. It can be a normal ASP.NET MVC web app, with NO user accounts or authentication.

Add a Manager class to the project. Like other client apps, this will hold methods that will call the web service.

Next, when creating an app that can call into a web service, our design uses something called a “service reference”.

In Visual Studio, adding a service reference generates some code that enable us to interact with the SOAP XML web service. In effect, it performs a task similar to the HttpClient object, but it does much more.

Please note that today’s code examples do not use security technologies.

That topic – security in SOAP XML web services – is beyond the scope of this course.

 

Configuring an app to interact with a web service

Before configuring an app, as a client, to interact with a web service, you must learn about an important standard or design approach in the SOAP XML web services world.

WSDL – web services description language – is a standard that is used to describe the functionality of a web service. The description is stored in a WSDL document, and is publicly available.

If you use Visual Studio to create a “WCF Service” – a SOAP XML web service – Visual Studio will also generate a WSDL document, available at the service endpoint URI, with a query string value of “?wsdl”.

Why is a WSDL document important?

Programmers can use it to help them create a client app that interacts with the web service.

Visual Studio has tooling that makes it really easy to add web service interaction to a client app. The tooling reads a WSDL document, and generates some code.

What code does it generate?

  • Classes that model or mimic the web service behaviour
  • Classes that model the objects that are sent to, or received from, the web service

Today’s code example uses this week’s SOAP XML web service, SOAPServer. Load/run that web service, and inspect its WSDL document in a browser, by appending “?wsdl” to the URL (e.g. /EmployeeService.svc?wsdl).

Is there a publicly-available SOAP XML web service that has a WSDL document that we could study?

Yes. The College course outline system:

http://www.senecacollege.ca/ssos/services/SubjectOutlineService?wsdl

 

Service reference, and proxy classes

The key concept at work here is the creation of a proxy, which will “model” the web service behaviour and its interaction data objects.

To create the proxy, we add a Service Reference to our client app project. In Solution Explorer, right-click the References branch, and choose “Add Service Reference…”.

Enter the address (URI) of the existing web service, and click the Go button.

client-add-service-reference-1

 

Before continuing, do one more configuration task. Click the Advanced button, and clear (un-check) the “Reuse types in referenced assemblies” checkbox.

client-add-service-reference-2

 

Save your work.

This action will create a local proxy of the SOAP XML web service. What’s interesting is that the proxy in the client app will have a complete and usable definition for the web service class, and all of its operations, and it will have definitions for the data objects sent to or received from the web service.

In Solution Explorer, if you show all files, and expand the web service item, you will see the generated code

client-add-service-reference-3

 

Then, elsewhere in your ASP.NET MVC app (i.e. a manager class), you simply 1) create an instance of the proxy class, and 2) call its methods.

To emphasize:

As a result of the Service Reference creation, the client will have definitions for the entity types. This will enable the client app to work with instances (and collections) of entity types. Put another way, the client will be able to (for example) fetch a specific “Product” or “Employee”, enable the browser user to edit it, and return/save the changes, all while knowing the object’s properties and structure.

 

Summary / wrap-up:
Web service project design (structure) that includes
a SOAP XML web service or client app

During the semester, you learned and implemented a series of best practices for building a web service.

For example, a project has a design model that was separated from the code modules that handle user interaction. And, it has separate modules (repositories) for data service operations, as well as resource model classes that exactly match use cases.

Can we continue to use this design (structure) for a project that includes a SOAP XML web service or client app?

Yes.

Please do.

 

SOAP XML web service (“WCF Service”)

Here are some design considerations for SOAP XML web services.

SOAP XML web services have fewer publicly-accessible endpoints, when compared to a modern “web API”, which can have many, many resource URIs.

Each endpoint is implemented by a “WCF Service” project item. Its publicly-accessible URI ends with the name of the item’s source code file (e.g. OrderService.svc). The service has one or more methods, and it usually has many, many methods.

From a code module perspective, a WCF Service class is similar to an ApiController class, because it contains the request-handling and response-delivery logic. As covered earlier, a WCF Service interacts using SOAP XML messages, while an ApiController interacts using (typically) JSON messages.

Continue to use your repositories, the unit-of-work class, the resource models, and so on. None of that has to change.

 

Client app for a SOAP XML web service

Here are some design considerations for a client app for a SOAP XML web service.

As noted earlier, we are not using security features in our course’s treatment of this topic.

If you get into a position where you need to use security in this style of web service, you’re on your own for now. Use the resources cited above. Have confidence – you will be able to adapt your existing security knowledge to cover and include SOAP XML web services.

As noted above, create a Service Reference to the SOAP XML web service. This action creates the programmed components needed for efficient and useful interaction.

As you have learned, continue to use manager or repository classes to hold the logic for interacting with a web service. And, continue to use whatever client-side technology that you have used before. For example, ASP.NET MVC controller and view, and/or JavaScript Ajax call.

What about resource model classes? We suggest an initial strategy for learning, and a best practice strategy for a production-ready client app.

Initial strategy: Use the generated proxy classes to work with the entities. As you noticed in the SOAPServer web service, its methods accept and deliver resource model objects and collections – from the perspective of that web service. Will these classes meet the needs of your client app? Maybe for easy getting-started learning scenarios. However, they are designed to work with the web service client proxy class, and therefore have features that may not meet our needs. (Go ahead and study them. Notice the different attributes, and additional class members.)

Best practice strategy: Create resource model classes in the client app, when they are needed. Use the typical AutoMapper pattern. Add data annotations to the resource model classes to match the client app’s use cases.

 

Summary

A client app that uses a SOAP XML web service typically uses tooling to create a local proxy for the remote web service.

To interact with the web service, the client app 1) creates an instance of the proxy class, and then 2) calls a method, and handles the results.

 

 

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

%d bloggers like this: