DPS907 notes – Thu Dec 3

A client app for your SOAP XML web service.

 

Last week, we introduced the SOAP XML web service style, using the “WCF Service” item template. We used the “WCF Test Client” app to test our work.

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

 

Test 10 is today

Test 10 is today. We’ll probably do that closer to the end of the class/session. Example answers will be posted within hours.

 

Lab 9 discussion

If you have questions about your work on Lab 9, be prepared to ask them now.

 

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

However, when creating a client app, our design uses 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.

 

Configuring a client app to interact with a web service

Before configuring a client app 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 last week’s SOAP XML web service, AssociationsSOAP. Load/run that web service, and inspect its WSDL document.

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.

Enter the address (URI) of the 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 or repository 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.

 

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, you’re on your own for now. However, you can contact your professor in early 2016 for guidance on how to adapt your 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 AssociationsSOAP 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: