Using Services

Glossary Item Box

Using Services

Services are separately compiled programs, usually written in C#, that can be used in a similar way to activities in a VPL diagram. You can add services to your diagram from the Services toolbox.

When you drag a service from the Services toolbox to your diagram the first time the service is set to automatically be created when you run your diagram. You might need to configure the service for it to work properly.

Once you have added a service to your diagram, you will see it listed in the Edit menu under Insert => Activities.

Consider the following activity block for a service that implements the Timer service:

Operations

The input (also called action or request) pin on the left-hand side (arrow pointing into the block) can be used to send requests to the Timer service, such as GetCurrentTime, SetTimer and Wait. These message types are also often referred to as operations in DSS terminology.

In the DSS Protocol, there are several standard operations that services can choose to implement. The documentation for services in the Reference section does not include the following operations because they are common to all services:

Responses

In response to a request, the Timer service outputs a message on the result (or response) pin at the right-hand side (arrow pointing out of the block). For GetCurrentTime, the response is the current date and time when the request was received. For SetTimer and Wait the response is just a Success message. However there is a difference. A Wait request does not receive a response until the specified time interval has elapsed, causing the dataflow to pause at that point. A SetTimer request is a little more complex. In addition to sending back a response immediately to say that the request was accepted, the Timer service sends a notification some time later (after the specified amount of time).

Notifications

The round pin on the right-hand side is the notification pin. Notifications occur when some event happens that causes the service to update its internal state. The message types for notifications are often the same as for update-type operations.

For the Timer service, notifications are sent when a timer "fires" due to a previous SetTimer request. Note that in this case two messages are received from the Timer service: an immediate Success response when the request is made and a TimerComplete notification some time later.

In VPL, when you hook an activity block up to the notification pin of a service it receives all notifications from that service for the entire time that the program is running. This is called subscribing to the service. If the service has multiple different types of notifications, you can add more connections by just dragging another one from the notification pin. An additional pin will be created as shown below.

Notice that when you connect to the notification pin on a service, the input pin disappears. Therefore you have to add another service activity block to your diagram if you also want to send requests.

If you drag the a service to your diagram that you have added previously, a dialog box will appear asking if you want to create a new activity or use the existing one. This dialog is shown below.

In VPL you can use existing services over and over again by just creating new activity blocks for them. This is handy if you want to use a service from several places in your diagram because it makes the layout cleaner and easier to read. Be careful not to create new activities if you only want one. Otherwise VPL will start multiple instances of the service and it will get very confusing. It is easy to see if you have created multiple instances because VPL activity names must be unique and it will automatically append a number to the name, so you would end up with Timer, Timer0, Time1, Timer2, etc.

Faults

If everything in your program is working as expected, then you will always get the responses you are looking for from a service. However, sometimes things go wrong. If a service cannot complete your request or rejects it as unacceptable then it will send back a Fault. (Faults are also sometimes referred to as Exceptions. Technically they are different, but they both mean that an unexpected error occurred.)

There are many different types of Faults and they are specific to particular services so it is not possible to provide a list of all possible Faults. A Fault message contains the following information: Code, Reason, Node, Role and Detail. Some or all of these fields might be empty. In general, the types of Faults that might occur are OperationFailed, InsufficientResources, ActionNotSupported, MessageNotSupported, UnknownContract, UnknownEntry, DuplicateEntry, or DuplicateSubscriber.

It is good practise to always check for a Fault when you send a request to a service. VPL allows you to connect to the output pin of a service multiple times. The expected response can be forwarded to several different activities. Similarly the Fault response can be sent elsewhere. The following diagram shows how to set a time delay of 1 second (1000 milliseconds). If it is successful, two other activities are activated. However, if there is a Fault then a Simple Dialog is displayed on the screen with an error message. 

Note that either a valid response will be received or a Fault. You will never get both as a result of the same request. So even though there are three output connections in the diagram above, all three will never be active at the same time. Also in this particular case, the response comes back immediately from SetTimer. As explained above, you need to use a notification to receive a message when the timer has expired. At first glance this diagram might look like it waits for one second before running Test and Activity, but if everything is working they run almost straight away and the Simple Dialog never appears.

© 2012 Microsoft Corporation. All Rights Reserved.