Archive

Archive for August, 2009

How the new Host feature works in nServiceBus

3 August, 2009 5 comments

The latest Alpha version of nServiceBus uses the TopShelf project as part of its new hosting feature. This new Host feature makes it super easy to setup a console/windows service for your clients/servers. So here’s how *I think* it works and what you can do with it…

Get nServiceBus

First you’ll need to get the latest build which includes the new Host feature either:

Either way take a look at the FullDuplex/RequestResponse sample project which consists of a Client, Server and Messages project:

image

Run the sample

Note: To get the Server to run successfully in my demo solution I had to change the app.config slightly by replacing the UnicastBusConfig setting with:

<UnicastBusConfig DistributorControlAddress="" DistributorDataAddress="">
  <MessageEndpointMappings>
  </MessageEndpointMappings>
</UnicastBusConfig>

Ok simply hit F5 to run the sample and two console windows should appear one for the Client and one for the Server:

image

So everything is running ok our Client can send messages to the Server and receive a response. But what’s just happened?

Multiple startup projects

First the solution is set to start both the Client and the Server projects. This is set in the solution property pages you can view this setting by right clicking on the solution and selecting Set StartUp Projects…

image

As you can see the solution is set to start multiple projects namely the Client and the Server.

Now the Server and Client projects are both Class Library’s so how come they are running as console apps when we F5 (debug) the solution?

Debug settings

If we take a look at the Debug settings for the Client (Right click the Client project and select Properties, then Debug from the tab):

image

Notice the Start Action is set to Start external program NServiceBus.Host.exe from the Client projects debug\bin directory. When we hit F5 to debug the application visual studio runs this exe and that’s how we get the console windows.

Reference NServiceBus.Host.exe

NServiceBus.Host.exe ends up in the debug\bin because its referenced by the project for example in the Client:

image

But how does it know where to get its configuration?

Configuration

NServiceBus.Host.exe scans its current directory for any dlls. For each dll it finds it searches for a class which implements the interface IConfigureThisEndpoint. If the search is successful the Host knows to use the app.config for this dll so in the case of the Client – Client.dll.config is used to configure nServiceBus.

Client

If we take a look at the Client project we’ll find the class EndpointConfig which implements the IConfigureThisEndpoint. This is simply a marker interface which has no actual implementation. Notice there are other interfaces used to configure the client which do require implementations:

public class EndpointConfig:IConfigureThisEndpoint,
                            As.aClient,                               
                            ISpecify.ToUseXmlSerialization,
                            ISpecify.XmlSerializationNamespace,
                            IWantCustomInitialization,
                            ISpecify.ToRun<ClientEndpoint>
{
    public string Namespace
    {
        get { return "http://www.UdiDahan.com"; }
    }

    public void Init(Configure configure)
    {
        configure.RijndaelEncryptionService();
    }
}

Of particular interest, the interface used to configure the dll as a client (As.aClient) and another to specify which code to actually run (ISpecify.ToRun<ClientEndpoint>). The ClientEndPoint class contains the code which is runs when the Host starts and stops.

Note there are lots more interfaces which can be used to specify configuration options:

image

Server

The Server project works in pretty much the same way as the Client it has an EndpointConfig class:

public class EndpointConfig:IConfigureThisEndpoint,
                            As.aServer,
                            ISpecify.ToUseXmlSerialization,
     

                       ISpecify.XmlSerializationNamespace,
                            IWantCustomInitialization
{
    public string Namespace
    {
        get { return "http://www.UdiDahan.com"; }
    }

    public void Init(Configure configure)
    {
        configure.RijndaelEncryptionService();
    }
}

Here the interfaces are used to configure the dll as a server (As.aServer) and IWantCustomInitialization which allows you to specify additional configuration via the Init method. The Server project also contains the RequestDataMessageHandler class which the bus knows to use when a RequestDataMessage arrives.

All this makes it very easy to create Client and Server applications for nServiceBus which are a doddle to debug in visual studio.

But wait there’s more…

Run from console

You can run the Client or Server from outside Visual Studio from the command line. Open a command prompt, cd to the relevant bin folder and type:

NServiceBus.Host.exe

image

Install as a Windows Service

We can install the Server as a Windows Service no extra code or configuration required! Open a command prompt, cd to the relevant bin folder and type:

NServiceBus.Host.exe /install

image

You’ll then be prompted to supply some authentication details for the service:

image

Enter some relevant user details and hit ok and your service will be installed and ready to start:

image

Uninstall service

Finally you can also uninstall the service:

NServiceBus.Host.exe /uninstall

image

Note: The service will not disappear from this Services management console until you reboot your machine, this is standard for a windows service.

That’s as much as I have puzzled out for now, if I’ve made and glaring errors please let me know.

kick it on DotNetKicks.com

Categories: nServiceBus Tags: