I Want To... > Automation > Communicate with the automation service

Use Case

•	You want to be able to communicate with the automation service from within your application.

Remarks

The method you use to communicate with the automation service will depend largely on the language your application is written in. Obviously, we can't cover every possible language and IDE in this guide, so we will focus on the technologies and products used to develop ClearCanvas, namely C#, .NET and Visual Studio 2005.

Option 1: Add a Web Reference

Toggle Section

This method will essentially generate a SOAP Web Service proxy. If you are more familiar with ASP .NET and/or your application is actually a web application (e.g. you want to use the automation service from within a web page), then this may be your preferred option. Also, this option does not require your application to be dependent on WCF and .NET Framework 3.0, which may or may not be important to you. Here are the steps you will need to take:

•	Ensure the viewer process is running. Otherwise, the automation service will not be available.

•	In the Solution Explorer, right-click on your project and choose Add Web Reference...

•

Enter the default URL for the viewer automation service (http://127.0.0.1:51124/ClearCanvas/ImageViewer/Automation?wsdl) and click Go. Note: you can click on the link provided to test whether the automation service is running or not. If it is, your web browser should show you the XML metadata (wsdl) provided by the service.

If successful, the Add Web Reference window will show the methods the service provides (e.g. ActivateViewer as shown above). Enter a value for Web reference name, like ViewerAutomationServiceClient, and click Add Reference.

A proxy class named ViewerAutomationServiceClient has now been generated and will appear under Web References.

Option 2: Add a WCF Service Reference

Toggle Section

Note: in order to be able to use this functionality in Visual Studio 2005, you must have the Extensions for .NET Framework 3.0 (WCF & WPF) installed. Unfortunately, in order to encourage developers to switch to Visual Studio 2008, this package is no longer available from Microsoft. However, as of the time this section was written, it was still available from ZDNet.

The steps that must be taken are very similar to adding a Web Reference, the main difference being that the proxy class generated uses WCF, and hence .NET Framework 3.0. The main benefit to this is that you are not limited to using the HTTP (SOAP) Web Service provided by the viewer—you can use the local Named Pipes service as well. There are a few benefits to using Named Pipes over HTTP:

•	You can completely disable the HTTP service.

•	Named Pipes inherently provides better performance than HTTP.

•	Non-administrative users require permission to open ports on the local machine (for example, to host the automation service in the viewer process). These permissions are set automatically by the ClearCanvas Workstation installer for Users and Power Users.

Now, let's add the service reference:

•	Ensure the viewer process is running. Otherwise, the automation service will not be available.

•	In the Solution Explorer, right-click on your project and choose Add Service Reference...

•	For the Service URI, enter the default URL for the viewer automation service (http://127.0.0.1:51124/ClearCanvas/ImageViewer/Automation?wsdl). For Service reference name, enter something like ViewerAutomationServiceClient. Click Ok.

•	A proxy class named ViewerAutomationServiceClient has now been generated and will appear under Service References.

Option 3: Use ClearCanvas Assemblies Directly

Toggle Section

The first two options keep your code completely independent of the CC Framework, which has it's benefits in terms of minimizing dependencies if all you are doing with CC is automating the viewer. However, if you don't object to the dependencies, or your code is already dependent on some parts of the CC Framework, then this may be your best option. The CC Framework provides some extra classes that make automating the viewer even easier. More on this in the later sections. For now, do the following:

•	In the Solution Explorer, right-click References and choose Add Reference...

•	Browse to wherever your CC SDK binaries are located for your project. Follow the section on Using the pre-built binaries for an explanation of where these files can be located.

•	Add references to the following 3 assemblies: ClearCanvas.Common, ClearCanvas.Dicom, ClearCanvas.ImageViewer.Services. The automation proxy class provided is called ClearCanvas.ImageViewer.Services.Automation.ViewerAutomationClient.

By now, you should have what you need to automate the viewer. You can start the viewer process from within your application, and you have a service proxy class to communicate with it. From this point on, the samples will use the WCF proxy class from Option 3, since there is really not much difference between any of them from a coding perspective.

Examples in Code Base

•	ClearCanvas.ImageViewer.DesktopServices.Automation.TestClient.csproj (C# project) can be conditionally compiled (e.g. Debug or Debug ASP) to use either a WCF or SOAP proxy.