Having defined a WCF service in code, and built that code into an assembly, a runtime instance of the service must be “hosted” somewhere in order for other application to be able to connect to and interact with the service. There are several ways to host WCF services. In an earlier post I described how to Host a WCF Service in an ASP.NET Web Application, which is a commonly used approach. But in some situations, for example if the only requirement for an IIS web server is to host a WCF service, it is preferable to host a service in a different way. In this post I will describe how to do just that, by leveraging capabilities of the .NET Framework which allow WCF services to be “self hosted”.

This is the fifth in a series of posts relating to the various ways in which Synergy developers can use of Windows Communication Foundation (WCF) when building their applications. The posts in the series are:

1. Building Distributed Apps with Synergy/DE and WCF
2. Exposing WCF Services using xfNetLink .NET
3. Hosting WCF Services in an ASP.NET Web Application
4. Exposing WCF services using Synergy .NET Interop
5. Self-Hosting WCF Services (this post)
6. Exposing WCF services using Synergy .NET

What is Self Hosting?

As its name suggests, self hosting a WCF service refers to the ability to host a WCF service within another application that you write, rather than hosting the service in a container such as that provided by Internet Information Services (IIS), or Windows Process Activation Services (WAS).

The .NET Framework provides various classes that can be used to host WCF Services within the context of a .NET application. This could be any type of .NET application, including console applications and desktop applications. However, in most cases WCF services need to be continually available, and it is often not convenient to host a service in a console or desktop application, because those applications typically execute in the context of a logged in user session.

A Windows Service application on the other hand can provide an excellent mechanism for hosting a WCF service. Windows Services are generally designed to automatically start when a system boots, stopped when the system is closed down, be continually available while the system is running, and are not associated with the desktop of any logged in user.

Since 9.5.1a Synergy .NET has included a project template which makes creating a Windows Service very easy, and as you are about to see, adding the code necessary to instantiate and host a WCF service is relatively straight forward.

Creating a WCF Service

In this post I’m assuming that you have already created a WCF service that you wish to host. If you have read the earlier posts in this series you will already know of two ways to create a WCF service, and in a later post I’ll show you another way.

• Exposing WCF Services using xfNetLink .NET
• Exposing WCF services using Synergy .NET Interop
• Exposing WCF Services using Synergy .NET

Creating a Windows Service

Using Synergy .NET it is very easy to create a Windows Service. We provide a project template called “Windows Service”, and when you create a new project from the template you essentially have all of the code that you need to implement the service. Of course, apart from starting and stopping a service the default code that you get from the template doesn’t actually do anything … that’s where you come in!

You’ll need a Windows development system with the following products installed

• Visual Studio 2010 Professional (or higher / later)
• Synergy/DE 9.5.1a (or later)
• Synergy Language Integration for Visual Studio 9.5.1a (or later)

Follow these steps to create a new Windows Service:

• Start Visual Studio
• From the menu, select File > New > Project.
• From the installed templates list, select Synergy/DE.
• From the project templates list select Windows Service.
• Provide a name for the project and set its location.
• Click the OK button to create the new project.

As you can see, in my example I have named my service MyWcfHostService and have created the project below my c:temp folder.

Once the Windows Service project has been created, if you look in Solution Explorer you should see something like this:

You will notice that three source files were added to the project. In my example the file MyWcfHostService.dbl contains the code for the service itself, MyWcfHostServiceInstaller.dbl contains code used when the service is registered (installed), and Program.dbl is simply the main-line program that actually launches the service when the process starts.

Take a look at the main service source file (the one that ends …Service.dbl) and you will see that the code is relatively self explanatory. The class defined in the source file extends a parent class called ServiceBase. This means that our class has inherited a lot of functionality which essentially makes it a Windows Service.

You’ll also see that the class has a constructor method with the same name as the class itself, and the constructor calls a method called InitializeComponent, which sets various properties in order to configure various capabilities of the service.

private method InitializeComponent, void
    endparams
proc
    this.ServiceName = "MyWcfHostService"
    this.AutoLog = true
    this.CanPauseAndContinue = false
    this.CanHandlePowerEvent = false
    this.CanShutdown = false
    this.CanStop = true
endmethod

All Windows services have the ability to be started, and as you can likely derive from the code, by default a new service has the ability to be stopped, but not to be paused and continued, or to respond to changes in the systems power state (mains vs. battery).

So, our new service can start, and it can be stopped. All we need to do is define what code should be executed when the service starts, and when the service stops. And if you scroll down a little you will notice that the code already contains place-holder event handlers where we can add whatever code we need:

protected override method OnStart, void
    byval args, [#]String
    endparams
proc
    ;;TODO: Add code to execute when the service is instructed to start
endmethod
		
protected override method OnStop, void
    endparams
proc
    ;;TODO: Add code to execute when the service is instructed to stop
endmethod

Our task is relatively straight forward. All we need to do is add whatever code is necessary to create and expose an instance of a WCF service in the OnStart method, and to stop the service in the OnStop method.

Referencing a WCF Service

The WCF service that we will be hosting has already been created in a separate assembly, so to get access to it we need to add a reference to that assembly in our Windows Service project.

• In Solution Explorer, right-click on the References folder and from the context menu select Add Reference.
• Wait for the Add Reference dialog to be displayed and load it’s data, which usually takes a few seconds.
• Click on the Browse tab, then browse to the location of the assembly that contains your WCF service.
  • If your WCF service is defined in an xfNetLink .NET assembly then this is whatever folder you created the assembly in.
  • If your WCF service is defined in a Synergy .NET Interop project, or some other Visual Studio project, then you will generally find the assembly below that projects “bin” folder.
• Select the assembly and click the OK button to add the reference to the assembly containing the WCF service.

Additional Steps for xfNetLink .NET WCF Services Only

If your WCF service is defined in an xfNetLink .NET assembly then there are two additional steps that you will need to complete.

Add a reference to xfNetLink .NET

Because your WCF service is defined in an xfNetLink .NET assembly, that assembly will require that your project also has a reference to the xfNetLink .NET assembly.

• In Solution Explorer, right-click on the References folder and from the context menu select Add Reference.
• Wait for the Add Reference dialog to be displayed and load it’s data, which usually takes a few seconds.
• Click on the Browse tab, then browse to the location of the xfNetLink .NET assembly (xfnlnet.dll).
  • The assembly will normally be found under your Program FilesSynergexxfNLNet folder.
• Select the assembly and click the OK button to add the reference.

Supply xfNetLink .NET Connection Information

Because your WCF service uses xfNetLink (to connect to xfServerPlus in order to execute your Synergy methods), you must tell xfNetLink where the instance of xfServerPlus is listening (host name or IP address, and port number). The best way to do this is via an application configuration (app.config) file.

• In Solution Explorer, right click on your Windows Service project and from the context menu, select Add > New Item.
• Select Application Configuration File and click the Add button.

Having added the configuration file to the project you need to specify the required configuration information, something like this:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <sectionGroup name="xfnlnet">
      <section name="default" type="System.Configuration.NameValueSectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
    </sectionGroup>
  </configSections>
  <xfnlnet>
    <default>
      <add key="host" value="192.168.1.10" />
      <add key="port" value="2356" />
    </default>
  </xfnlnet>
</configuration>

Note: You can also use the Synergy .NET Configuration Utility to add this information to the file. Clearly you should replace the IP address and port number with the correct values for your own instance of xfServerPlus.

Hosting an Instance of the WCF Service

In the most basic form, self-hosting a WCF service in another application essentially turns that application into a web server. The web server capabilities are provided by a class in the .NET Framework called ServiceHost. This class is found in a namespace called System.ServiceModel, and is provided the System.ServiceModel.dll assembly.

The code that we’ll be adding will use these web server capabilities to expose a “WCF Endpoint” at a specified HTTP address.

In addition to exposing an endpoint which is an instance of your WCF service, you will usually also want to expose a second “metadata endpoint”. This allows other applications that may need to interact with your WCF service to download the metadata for your service. The metadata fully describes the service and its capabilities, and is made available automatically by WCF. Clients applications can use a standard protocol called Metadata Exchange (often referred to as MEX) in order to download a WCF services metadata from a metadata endpoint. In code, we use a second class called ServiceMetaDataBehavior to expose our services metadata. This class is in the System.ServiceModel.Description namespace, and is also in the System.ServiceModel.dll assembly.

If all of this is starting to sound really complicated, well it is! Luckily the .NET Framework hides most of these requirements from us, and does most of the work. Despite sounding really complicated, the code that we need to write is remarkably simple.

To self host a WCF service there are generally three main things you will need:

• The URI for the endpoint for the service.
• An instance of the ServiceHost class to expose your service at that URI
• An instance of the ServiceMetaDataBehavior class to expose a metadata (MEX) endpoint.

So, lets write this thing:

• Use the Add Reference dialog that you used earlier to add a reference to the Frameworks System.ServiceModel assembly.
• At the top of the code in your …Service.dbl file, add the following two import statements:

import System.ServiceModel
import System.ServiceModel.Description

• Somewhere inside the class, but NOT inside any method, add the following data declarations:

private baseAddress ,String
private host        ,@ServiceHost
private smb         ,@ServiceMetadataBehavior

In the procedure division of the OnStart method, add code like this:

protected override method OnStart, void
    byval args, [#]String
    endparams
proc
    ;;Define the URI for the service endpoint
    baseAddress = "http://" + Environment.MachineName + ":8080"

    ;;Create a ServiceHost instance for the WCF service
    host = new ServiceHost(
    &       ^typeof(spc2011.SynergyServer),
    &       new Uri(baseAddress))

    ;;Add a BasicHttp endpoint
    host.AddServiceEndpoint(
    &       ^typeof(spc2011.ISynergyServer),
    &       new BasicHttpBinding(),
    &       "SynergyServer")

    ;;Create a ServiceMetaDataBehavior instance
    smb = new ServiceMetadataBehavior()
    smb.HttpGetEnabled = true
    smb.MetadataExporter.PolicyVersion = PolicyVersion.Policy15

    ;;Add a MEX endpoint
    host.Description.Behaviors.Add(smb)

    ;;Start the listener
    host.Open()

endmethod

In my example, the namespace in which my WCF service is defined is “spc2011” and the name of the WCF service class is “SynergyServer”. You would need to:

• Replace the reference to spc2011.SynergyServer with the namespace and class of your WCF service.
• Replace the reference to spc2011.ISynergyServer with the namespace and interface of your WCF service.

IMPORTANT: When GENCS –W is used to create a WCF service, it applies the ServiceContract attribute to the CLASS that is created, rather than to the INTERFACE. So for xfNetLink .NET WCF services both of the above references should point to the CLASS.

Other than that, the code should work for any WCF service.

Now all that remains it to add the code to stop the WCF service when the Windows service stops. In the procedure division of the OnStop method, add this code:

protected override method OnStop, void
    endparams
proc
    host.Close()
    host.Finalize()
endmethod

Build the Windows Service

It’s time to build the application and see how good your typing is!

• In Solution Explorer, right-click on your Windows Service project and select Build.
• Check the output window to make sure your application built correctly. You’re looking for something like this:

------ Build started: Project: MyWcfHostService, Configuration: Debug Any CPU ------
========== Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ==========

If your application does not build correctly then you’ll need to review the instructions above and make sure that you completed the required steps.

Registering and Starting the Windows Service

Now that you have a Windows service there are only two more steps that you’ll need to complete before the service can be tested. Those steps are:

• Register the service with Windows.
• Start the service.

To register the service you’ll need to open a Visual Studio command prompt window and then go the the folder that contains your applications executable. This will generally be the binDebug or binRelease folder below your project. Once you’re there you should be able to register your service like this:

..binDebug> INSTALLUTIL MyWcfHostService.exe

Look for messages that indicate that the service was successfully installed, then start your service like this:

..binDebug> NET START MyWcfHostService

Look for messages indicating that the service was started correctly.

Testing the WCF Service

If your Windows service started correctly then your WCF service should now be running. To verify that it is, open a browser and navigate to the URI that was specified in the code.

http://localhost:8080

You should see a WCF service home page similar to this:

If you see a service page like this then you should be able to start using the service. Of course we haven’t talked about how to do that yet … that’s for another day!

Remember to Stop The Service

You probably want to stop and unregister your Windows Service before you forget that it’s running. To do do, return to the Visual Studio command prompt and use commands like these:

..binDebug> NET STOP MyWcfHostService
..binDebug> INSTALLUTIL /u MyWcfHostService.exe