Introduction

This is a simple mechanism to authenticate users to a Web Service, using a Time Token and MD5 Hashing to encrypt password.

Background

In CodeProject, you can find at least two others' mechanism to authenticate users to a Web Service. Dan_P wrote Authentication for Web Services as a Simple authentication for web services using SOAP headers. But the username and password are send in clear text and there is no encryption for the data. HENDRIK R. is the author of An introduction to Web Service Security using WSE, that is really a complete solution, but too much complicated for my purposes. The username is send in clear text, but it is possible to use Password Digest to encrypt the password. The data are encrypted using XML Encryption specification to encrypt portions of the SOAP messages.

My solution is something in the middle of the above two. The username is send in clear text, but I use MD5 to encrypt the password. I do not need to send sensitive data, so the data returned by the Web Service is not encrypted.

Using the code

The basic idea is to send UserName and Password from the client to the Web Service using MD5 Hash Code as encryption system. In this way, the password never travels in clear over the network. The Web Service retrieves the user password from a DB or anything else and uses the same MD5 algorithm to test if the password is correct. To be sure that if someone intercepts the Hash, this can be used to authenticate in a later time, I added a timestamp before hashing the Key string. Last, as we are not always on the same server and/or the client clock may be in a different Time Zone or simply not synchronized, I added the possibility to request a Token containing the time mark to the server.

I provided a sample in ASP.NET C# for the client side, but it is possible to use any language: ASP classical JScript or VBScript, PHP, Python, etc. Anyway, on the client side we need to build up the Key using UserName, Password and the hashed timestamp Token previously got from the same Web Service. We can then call the Service and we will get the answer (or an authentication failure warning) that is displayed on the web page.

private void ButtonUseToken_Click(object sender, System.EventArgs e)
{
string ret;
string UserName, Password, ServiceName, Token;
string Key, ToHash;
UserName=this.TextBoxUserName.Text;
Password=this.TextBoxPwd.Text;
ServiceName=this.TextBoxService.Text;
Token=this.TextBoxToken.Text;
ToHash=UserName.ToUpper()+"|"+Password+"|"+Token;
Key=Hash(ToHash)+"|"+UserName;
ServicePointReference.ServicePoint Authenticate =
new ServicePointReference.ServicePoint();
ret=Authenticate.UseService(Key, ServiceName);
this.ServResponse.Text=ret;
}

The MD5 Hash procedure is very simple in C#; this one was written by Vasudevan Deepak Kumar in Securing Web Accounts.

private string Hash(string ToHash)
{
// First we need to convert the string into bytes,
// which means using a text encoder.
Encoder enc = System.Text.Encoding.ASCII.GetEncoder();
// Create a buffer large enough to hold the string
byte[] data = new byte[ToHash.Length];
enc.GetBytes(ToHash.ToCharArray(), 0, ToHash.Length, data, 0, true);
// This is one implementation of the abstract class MD5.
MD5 md5 = new MD5CryptoServiceProvider();
byte[] result = md5.ComputeHash(data);
return BitConverter.ToString(result).Replace("-", "").ToLower();
}

On Web Service server side I implemented just three Web Methods:

GetToken is used to get the Time-marked token. The token you get this way, is intended to be used in the basic Authenticate method, or in the UseService that can also verify the access rights for the users authenticated to the requested service. The core of the system is implemented by TestHash. Here the password is hard-coded, but in the sample provided you have also the code to get it from a database:

Collapse

private bool TestHash (string HashStr,
string UserName, int minutes, string ServiceName)
{
string Pwd, ToHash;
string sResult, sResultT, sResultToken;
try
{
// JUST FOR TEST: the password is hard-coded:
Pwd="SeCrEt";
DateTime dt = DateTime.Now;
System.TimeSpan minute = new System.TimeSpan(0,0,minutes,0,0);
dt = dt-minute;
//before hashing we have:
//USERNAME|PassWord|YYYYMMDD|HHMM
ToHash=UserName.ToUpper()+"|"+Pwd+"|"+dt.ToString("yyyyMMdd")+
"|"+dt.ToString("HHmm");
sResult = Hash(ToHash);
//TokenWeGotBefore
ToHash=dt.ToString("yyyyMMdd")+"|"+dt.ToString("HHmm");
sResultToken = Hash(ToHash);
//USERNAME|PassWord|TokenWeGotBefore
ToHash=UserName.ToUpper()+"|"+Pwd+"|"+sResultToken;
sResultT = Hash(ToHash);
if ((sResult==HashStr) || (sResultT==HashStr))
return true;
else
if (minutes==0) // allowed max 2 minutes - 1
// second to call web service
return TestHash (HashStr, UserName, 1, ServiceName);
else
return false;
}
catch
{
return false;
}
}

To request a hashed time-stamped Token to the Web Service the method is:

[WebMethod]
public string GetToken ()
{
string ToHash, sResult;
DateTime dt = DateTime.Now;
ToHash=dt.ToString("yyyyMMdd")+"|"+dt.ToString("HHmm");
sResult = Hash(ToHash);
return sResult;
}

The method that checks the user authentication is also kept very simple; in a real application you normally need to access a database to check the authentication level and may need to return some data to the caller:

Collapse

[WebMethod]
public string UseService (string Key, string ServiceName)
{
string [] HashArray;
string UserName, level;
// Key string: HASH|User|OptionalData
HashArray=Key.Split('|');
level = "-1";    //defaul level
if (TestHash(HashArray[0], HashArray[1], 0, ServiceName))
{
try
{
UserName=HashArray[1];
// JUST FOR TEST: the User authentication level is hard-coded
// but may/shuold be retrieved from a DataBase
switch (UserName)
{
case "MyUserName":
level="1";
break;
case "OtherUser":
level="2";
break;
default:
level="-1";
break;
}
if (level=="1") return "YOU ARE AUTHORIZED";
}
catch (Exception exc)
{
return "Authentication failure: " + exc.ToString();
}
}
return "Authentication failure";
}

Points of Interest

TestHash checks to see if the Hash contains a timestamp or an already-hashed token, and calls itself once again in case of failure: if someone is calling the service, let's say, at 11:34:58 the Key is valid from 11:34:00 until 11:35:00, that is during two minutes.

The client side may be implemented in any language: ASP classical, JScript or VBScript, PHP, Python, etc. I have intention to post this code too next time...

History

Introduction

The Windows service code that ships with the .NET framework and Visual Studio works just fine usually. However, sometimes it's just annoying to have to create an installer project just for a simple service you're writing. Furthermore, Microsoft tends to hide away the Win32 service infrastructure from us. I'm not saying that's a bad thing, but sometimes you just need something a little better. There're some advanced issues with services that make working with the API difficult and so wouldn't it be nice to have something that encapsulates all the functionality, but exposes it to those who need it? The code provides a base class and an attribute for you to use to define your own service.

Background

A thorough discussion of the intricacies of Win32 services is another subject. This code focuses on bringing it all together and then exposing it via an easy to use class and custom attribute.

Using the code

Using the code is as simple as deriving from the base class:

				using System;
using HoytSoft.ServiceProcess.Attributes;

namespace MyServices {
    publicclass TestService : HoytSoft.ServiceProcess.ServiceBase {

        protectedoverridebool Initialize(string[] Arguments) {
            this.Log("Test service initialized correctly, starting up...");
            returntrue;
        }
    }
}

And then defining an attribute:

Collapse

				using System;
using HoytSoft.ServiceProcess.Attributes;

namespace MyServices {
    [Service(
    "HoytSoft_TestService", 
    DisplayName         = "HoytSoft Test Service", 
    Description         = "Isn't this just absolutely amazing?",
    ServiceType         = ServiceType.Default,
    ServiceAccessType   = ServiceAccessType.AllAccess,
    ServiceStartType    = ServiceStartType.AutoStart,
    ServiceErrorControl = ServiceErrorControl.Normal,
    ServiceControls     = ServiceControls.Default
    )]publicclass TestService : HoytSoft.ServiceProcess.ServiceBase {

        protectedoverridebool Initialize(string[] Arguments) {
            this.Log("Test service initialized correctly, starting up...");
            returntrue;
        }
    }
}

All the attributes correspond to their equivalent Win32 service descriptions. A lot of the code has been commented, so a glance at the intellisense should give you an idea of what each option is and how it modifies your Windows service.

It is important that you give a name to your service. It is a required parameter for the Service attribute. The attribute values specified here are used in the ServiceBase's Main() method. I suppose I should also note that your service should not define its own Main() method since ServiceBase uses its own that reads in Service attributes and then creates objects automatically for you. If the service has not been installed, it will auto-install it for you. To uninstall a service, simply pass in "u" or "uninstall" to the program. To manually do this, go to a DOS prompt and type in: sc delete "MyServiceName".

An interesting feature that hasn't been tested at all is the ability to use multiple services in a single application. To do this, be sure to set the ServiceType to ServiceType.ShareProcess or ServiceType.InteractiveProcessShare.

Now of most importance to you is probably developing, testing, and debugging your service. There is a property on the Service attribute named "Debug". Set this to true and the base class will automatically treat your program like a normal console program so you can develop the rest of the program. When you're ready to test it out as an actual service running on the machine, just switch this to false or take it out and it will work like a service. The program will install the service whether or not you're in debug mode when it's first run. If you try to run the program when it was compiled in Debug mode, you will get an error saying the process couldn't be started. This is by design since to gain all of the debug mode capabilities in Visual Studio, you can't have it start up as a real service. Simply switch the Debug mode, recompile, and it will run as normal.

You can write to the system event log by making a call to this.Log("My message here."):

The main meat of your code should be the overridden methods:

• bool Initialize(string[] Arguments)

  "Arguments" are those passed in when called.

• Start()
• Stop()
• Pause()
• Continue()
• Shutdown()
• Interrogate()
• Install()
• Uninstall()

All of these should be fairly straightforward. Any questions?

Updates

• 10/4/05: After the default timeout of 30 seconds (this is a Windows-imposed standard), if the service is not being run by the service control manager (SCM), the program runs like a normal console/Windows program. This is done in the ServiceBase's main method which will detect when it's not being run as a service and executes the proper methods on the service.

  You just continue to use the service like you normally would through the Initialize() and Start() methods. If you want to test other methods, you can optionally use the following methods from inside Start():

  • TestPause()
  • TestContinue()
  • TestStop()
  • TestShutdown()
  • TestInterrogate()
  • TestInstall()
  • TestUninstall()

  ServiceBase will take care of calling your methods while attempting to simulate a real situation or user by calling your overridden methods asynchronously.

• 10/12/05: A message was added to the CodeProject article informing me of missing copyright notices in the source code, so I've added them here along with some more updates. This version has a major fix involving running it from a referenced, external DLL. If you put the code inside another DLL and then try to use it, you may notice you can start, but can't pause or stop your service. The fix, actually, was just adding a strong name key (HoytSoft.snk) to the external assembly. After I did this, I was able to run the service normally.

  As a result, I have divided the solution into two projects - one containing the service code and the other is just a simple example console service app.

  Important! The namespace has changed! It was HoytSoft.Service, but it is now HoytSoft.ServiceProcess to more accurately reflect its replacement of the System.ServiceProcess namespace. Please keep in mind that to install/run the service you must have the proper permissions!

• 10/21/05: There were some more problems with referencing the ServiceBase class from a class library. I think the main problem was a delegate that was going out of scope that rendered a callback useless. Lots of people got errors when trying to pause, stop, or do anything on the service when using it as a class library. I was able to reproduce the problem and after making the aforementioned fixes, it worked just fine.

  Also of note is the ability to explicitly and only install the service without having to run the rest of the service. To do this, just start the service and pass in "i" or "install" and it will quickly install and exit. If you start the app normally and it hasn't been installed yet, the app will work like before and install it before proceeding. You should still be able to run it as a console or service app.

Points of Interest

• The service installs itself and can uninstall itself through a command line argument ("u" or "uninstall").
• You can run, test, and debug your service from within Visual Studio without having to create a separate installer project or use the ServiceController classes.

History

• Took out "Debug" property from the ServiceAttribute attribute since the code now auto-detects this. (See "Points of Interest" above).

About DavidHoyt

Introduction

This is an ASP.NET web service for sending e-mail messages. When programming with .NET, sending e-mail doesn't seem to be a complicated task at all, you need only to know two simple framework classes, MailMessage and SmtpMail, in the System.Web.Mail namespace. If you want to attach a file to your e-mail message, then you also need to know the MailAttachment class.

Suppose the SMTP service is enabled on your machine, here is a C# example of sending an e-mail message with attachment.

MailMessage oMsg = new MailMessage();
oMsg.From = "me@MyServer.Net";
oMsg.To = "you@YourServer.Net";
oMsg.Cc = "him@HisServer.Net";
oMsg.Subject = "Test";
oMsg.Body = "This is only a test";
oMsg.Attachments.Add(new MailAttachment("c:\temp\Test.txt"));
SmtpMail.Send(oMsg);

If you copy/paste/modify the above code, all your programs can have e-mail capability and there is no need for any web service as far as e-mail is concerned.

However, there are some advantages in providing e-mail capability in a web service, such as:

• A web service can be accessed by all servers on the network. You need only to enable SMTP service on a single machine. In other words, you can have better control over e-mail.
• All of your non .NET programs can use the web service to send e-mail as well. So you don't have to write e-mail related code for your C/C++/VB/Java programs (but you do need to know how to call a web service from these programs).
• You are not limited to the Windows platform, programs running on other platforms can use the e-mail service.
• Programs can access the e-mail service across firewalls without additional firewall configuration (assuming HTTP traffic is allowed). Of course, you need to have authentication in this case so that the service won't be abused.

My simple e-mail web service has only one method, SendMail, which can be used to send multiple e-mails with a single call. Please note that you cannot use this web service to retrieve e-mail messages.

The web service for e-mail

To send an e-mail, you need to specify the destination address, the sender address, the list of addresses to copy the e-mail message, the subject line, the message body, and the list of attachment files, etc. Some of the information is not required. Things can get more complicated if you want to send multiple e-mails at once.

Instead of having multiple web methods that take various numbers of parameters, I decided to implement a single method SendMail that takes only one string parameter and returns a boolean value to indicate success or failure. The string parameter represents an XML document, here is the format:

<EMailMessageList>
    <EMailMessage>
        <From></From>
        <To></To>
        <Cc></Cc>
        <Bcc></Bcc>
        <ReplyTo></ReplyTo>
        <Subject></Subject>
        <Body></Body>
        <Format></Format>
        <AttachmentList>
            <Attachment></Attachment>
        </AttachmentList>
    </EMailMessage>
</EMailMessageList>

The From element is the sender's e-mail address. The To element is the destination address, it could be multiple e-mail addresses separated by semi-colons. The same goes with the Cc and the Bcc elements. The ReplyTo element is the e-mail address to be used when replying to this message, it can be different from the sender's e-mail address. The Subject and Body elements are obvious.

The Format element specifies the format of the message body, which can be either HTML or TEXT with TEXT as the default. The Attachment element holds the full path of a file on the local system. Please note that you cannot attach a file that is not on the server where the web service resides.

As you can see, it is possible to pack multiple e-mail messages in the input string parameter and each message can have multiple attachment files. Here is the C# code that uses the web service to send e-mail (for simplicity, the above XML string is saved in the file EMailTemplate.txt and used as a template for XML document in the code).

				// prepare the xml document
XmlDocument oDoc = new XmlDocument();
oDoc.Load("EMailTemplate.txt");
oDoc.SelectSingleNode("//From").InnerText = "me@MyServer.net";
oDoc.SelectSingleNode("//To").InnerText = "you@MyServer.net";
oDoc.SelectSingleNode("//Subject").InnerText = "Test";
oDoc.SelectSingleNode("//Body").InnerText = "This is a test";
// send the e-mail message
EMailService oWebSvcProxy = new EMailService();
oWebSvcProxy.Url = "http://MyServer.Net/TheEMailService/EMailService.asmx";
oWebSvcProxy.SendMail(oDoc.OuterXML);

Please note that EMailService in the above code is the proxy class generated when you add a web reference for the e-mail service to your project.

Comparing to sending e-mails from individual programs, we may have to write a few more lines of code to use the e-mail web service. However, there are some additional advantages besides the ones listed above. For example, the web service writes all errors and debug information into a trace file. In case of failure, you can see exactly what is happening (what input the user is sending to the web service and what is causing the problem, etc.).

The tracing capability in this web service is similar to my other components posted on Code Project, basically there will be one trace file for each day and the amount of information written to the trace file can be controlled by setting trace level from the web.config file. Also, old trace files will be deleted automatically to save disk space.

To call the web service from C/C++/VB programs, you can use the Microsoft Toolkit 3.0. I also wrote a COM DLL XYSoapClient that uses the SOAP client object from the SOAP toolkit to simplify the code.

Security and installation

Now we have this web service ready, there is always a danger that the service will be exploited and misused. Any program on the same network can call this web service unless you restrict the access to it explicitly.

Access to the web service can be restricted by configuring it from the Windows Internet Service Manager. It is possible to allow only access from the local machine and deny all other requests. You can grant or deny access for a group of IP addresses. You may also use Windows authentication or require a password. I will not go into details here.

The included VB script file InstallEMailService.vbs can ease the pain of installation and configuration. First, you need to unzip the downloaded file into a folder on your machine. Then you run the VB script file, which will popup message boxes to ask you the following questions.

1. What directory you want to install the web service?
2. What is the website you want to install the web service? This is because some servers may have multiple websites and each of them is bound to a different IP address (or port number). You can use the "app friendly name" to distinguish websites. Just click OK if this does not apply to you.
3. What is the port number of the website? Click OK if it is 80 (the default).
4. Do you want to allow access from all IP addresses? If you choose "yes", then anyone can call the web service. Otherwise, only IP addresses from the same subgroup can access the web service. For example, if your website is bound to IP address 205.188.200.159, then only IP addresses of the form 205.188.200.* can call the web service you installed.

The installation script will automatically create virtual directory for the web service on the website you specified, copy files, and set access permissions.

Thank you for reading my articles and using my tools.

Recent Updates

02/09/2004: Updated the install script file. The previous version does not set permissions properly.

Xiangyang Liu

Introduction

This article describes step-by-step, with screen snapshots, how to create a polling service using VB.NET and Visual Studio 2005. It solves the problem of using timers in a service in a quick and simple manner.

Background

Over the years I have leaned on Code Project to help me get started on many projects that involved programming technologies I was not familiar with at the time. This last project required me to create a service for a set of code I had already written. So I headed over to Code Project to figure out if my friends at Code Project had a good article to do that. I was not disappointed. Mahmoud Nasr had written a highly rated and popular article Simple Windows Service Sample.

Everything went fine until I needed to add the timer part. There are a great many opinions about which timers to use in a service. And a Google search will yield many requests and complaints about all of them. I never did find a satisfactory article that explained how to do this seemingly simple thing. In addition, there were issues with multithreading and reentrancy when the timer fires before your task is ready to start over again.

So I think I have solved this with a simple and quick solution. So if you want to run a task repeatedly in the background, without worrying about reentrancy, or multiple threading. If you just want to wrap your code in a Windows Service. Here is a very simple straight forward way to do it.

Using the code

The code I present, basically follows the same steps to create a service that MSDN recommends. And is very similar to Mahmoud's article. The main difference being that it includes code to do polling and shows you where you can drop your code in.

Executing the demo will install a service called "Polling Service". It will write an event log entry to the Application Log on your computer every 30 seconds. The source code is everything you need to build the demo. It is also the final result of following the steps in this article.

1. Create New Service Project

Start by creating a new Visual Studio Project. Startup Visual Studio 2005.

Select the "Windows Service" template and name the project.

Drag and drop the "Event Log" component from the toolbox onto your new service designer window.

Set the "ServiceName" and "(Name)" property to the name of your new service.

Set the "Log" property to "Application". Set the "Source" property to the name of your new service.

Enter the wrapper code for your service.

You can cut and paste the following code into the code window for your service. Change variable names and message text as appropriate for your service.

Collapse

Imports System.Threading

Public Class PollingService
    ' Keep track of worker thread.
    Private m_oPollingThread As New Thread( _
        New System.Threading.ThreadStart(AddressOf PollProcess))

    Protected Overrides Sub OnStart(ByVal args() As String)
        ' Add code here to start your service. This method should set things
        ' in motion so your service can do its work.
        EventLog1.WriteEntry("PollingService is starting.")

        ' Start the thread.
        m_oPollingThread.Start()
    End Sub

    Protected Overrides Sub OnStop()
        ' Add code here to perform any tear-down necessary to stop your service.
        EventLog1.WriteEntry("PollingService is stopping.")

        ' Stop the thread.
        m_oPollingThread.Abort()
    End Sub

    Private Sub PollProcess()
        ' Loops, until killed by OnStop.
        EventLog1.WriteEntry("PollingService service polling thread started.")
        Do
            ' Wait...
            System.Threading.Thread.Sleep(30000) ' 30000 = 30 seconds

            PollingPass()
        Loop
    End Sub

    Private Sub PollingPass()
        Try
            ' Do Stuff Here...
            EventLog1.WriteEntry("PollingService service polling pass executed.")
        Catch ex As System.Exception
            EventLog1.WriteEntry("PollingService encountered an error '" & _
                ex.Message & "'", EventLogEntryType.Error)
            EventLog1.WriteEntry("PollingService service Stack Trace: " & _
                ex.StackTrace, EventLogEntryType.Error)
        End Try
    End Sub

End Class

Notes About the Code

When the service is started, in the "OnStart" method, a new thread is started. You must start a new thread because the service manager controls this process. If you simply called the polling process from the OnStart method, the service mananger would complain that the service does not respond. In other words, the OnStart method did not return control to the service manager.

That new thread loops indefinitely and the only way to stop it is to issue the Abort command on the thread, which we do when we stop the service in the "OnStop" method.

The thread process continually executes two commands. The command to wait for a specified period of time. And then the command to run your code.

In my example, I have added exception checking to write any problems to the event log. The event log is the only way to debug a service during the startup time, as you can only interactively debug a service by attaching to the process "AFTER" it has already started.

That's it for your service. Pretty simple, eh? Replace the comment "Do Stuff Here..." with the code you want to run on a periodic basis.

You can change the period that the service waits between executing your code by changing the sleep time. It is specified in milliseconds, there's 1000 milliseconds in one second.

2. Add Project Installer

The service is done. However, to run it we can't just press the F5 button. We have to install the service. The following describes how to include in the project all the "stuff" needed to install the service on a computer.

Right click on the designer pane for your service and select the option "Add Installer".

Everything is setup for you. You can choose how your service starts by setting the "StartType" property. The default is "Manual". I've set it to "Automatic" in my example.

You can also specify which account the service runs under when it is started. Select the "ServiceProcessInstaller" component and set the "Account" property. The default is "User Account" and you will need to specify the username and password at installation time. I have set the example to use "LocalSystem" which does not require a username or password. Most Windows services run this way.

Ok, now when your application is run using the /install option, it will install itself as a service on your computer. And when /uninstall is specified it will remove the service from your computer.

Now all we have to do is build the thing and resolve any build errors. To do that, select the properties of "My Project" in the Solution Explorer.

Change the "Startup Object" to the name of your service.

Now build your solution.

3. Add Setup Project

OK, you have a service, let's add a setup procedure to this project to make it easy for others to install and use your funky new service.

Choose the "Setup Wizard" and choose a name. You can use the same name as your setup project.

Follow the setup wizard prompts.

Now you need to add a custom action so that after all the files are copied over the program is setup as a service.

We are done setting up the setup project. Now build it.

4. Run It

Your service has been installed. Now go to the Service Manager and start it. The Service Manager can be found in "Administrative Tools".

Start the service. Even though we set it to start automatically. It does not start automatically after we install the service. It will start automatically when the computer starts up.

Now examine the event log to verify our service started and is running successfully. The Event Viewer can be found in "Administrative Tools".

5. Notes on uninstall

This example will continue to write event log messages to your application log every 30 seconds. Once you are convinced it works you will want to uninstall it.

To do that simply run the same .msi file that you ran to install it in the first place. It will prompt to repair or remove. Choose the remove option.

Another way to remove your service is through the Add/Remove Software Control panel option. If you have lost or overwritten your .msi file with a new version, this is the only way to remove your service.

BEFORE UNINSTALLING A SERVICE: be sure to close the Services Viewer. If you do not and you have your service highlighted in the Service Viewer the uninstall will not be able to remove your service. This is because the Service Viewer "locks" the service that is highlighted. The uninstaller will instead "mark" the service for deletion. When this happens you cannot reinstall the service until the marked service is removed. There is no way to remove the marked service except by restarting the computer.

Mark James Newman

Contents

Introduction

Features

Concept

Usage

Implementation

Test

Version

Conclusion

Introduction

The distributed object has to be properly hosted by the application domain process such as Web Server, Console, Windows Form or Windows Service before using it. The host process requires configuration of a remoting infrastructure to enable consuming the published objects. The remoting configuration can be done programmatically or administratively. Using the config file to administrate an application deployment is a preferable and recommended way to easy mapped the logical application model to its physical implementation.

The Remoting Management Console (RMC) is an administrative tool to create and configure a remoting host process built as a windows service. The console has a mechanism to create a windows service on the fly including its configuration file. Using the properly snap-in nodes the config file can be administratively finalized based on the application requirements before the host process starts. On the other hand, the RMC is also very useful tool for administrating (tuning phase) already deployed the distributed application modifying the contents of the host process config files. This article describes a usage and implementation of the Remoting Management Console tool.

Features

Basically the RMC snap-in control is divided into the following activities:

Host Process

• Scanning an installed host processes
• Creating and installing a new host process
• Creating a host process configuration file
• Controlling the host process such as start, stop and restart
• Receiving the host process Event Logs

Config File

• Creating or modifying the remoting section
• Creating or modifying appSettings
• Creating or modifying configSections
• Declaration of the configSections
• Declaration of the Channels
• Declaration of the ChannelSinkProviders

Inside of the remoting section the following sections are managed:

• Lifetime
• Service
• Channels
• ClientProviders
• ServerProviders

Drag&Drop Feature

There are few places where the drag&drop can be used to enter an existing assembly:

• HostProcesses result view panel to drop the host process
• RemoteObjects result view panel to drop the assembly of the remote object

Additionally, the drag&drop can be used within the configSection to move or copy nodes in the root.

Concept

The concept of the RMC is based on the following:

• Remoting host process is a windows service
• Remoting configuration is driven by the config file
• Microsoft Management Console (MMC) to host the RMC snap-in

Using the windows service to host remoting objects is straightforward. The standard boilerplate generated by .Net wizard has been extended for a remoting registration and un-registration parts like it's shown in the following code snippet:

				protected
				override
				void OnStart(string[] args)
{
   if(args.Length == 1) Thread.Sleep(Convert.ToInt32(args[0]));
   RemotingConfiguration.Configure(
                 AppDomain.CurrentDomain.SetupInformation.ConfigurationFile);
}
protectedoverridevoid OnStop()
{
   foreach(IChannel objChannel in ChannelServices.RegisteredChannels)
      ChannelServices.UnregisterChannel(objChannel);
}

When the windows service receives a Start command, the OnStart action is invoked to perform a remoting configuration from the config file. On the other side, the OnStop action will clean-up all listeners hosted by this service included their worker threads.

The host process (windows service) must have a unique name registered on the local machine. The RMC has a mechanism to create a unique host process on the fly based on the application requirements. Practically, the host process template source is modified in the variable places before its compiling (see Implementation)

Once the host process has been created, the RMC will control its state such as start, stop and restart using the MMC environment.

In the case of the existing non-installed host process, the RMC has a drag&drop capability making its entry to the catalog. The other hand, the already installed host processes are scanned and added into the snap-in. Notice that the host process need to have an implementation of the derived Installer class attributed with RunInstaller(true) to make its installation rsp. un-installation service automatically.

The initiate config file image is generated from the template HostProcessTemplate.exe.config file located in the %windir%/system32 folder. It's very easy to replace it for another one with custom pre-built common configuration. The RMC has many features for administrating this config file using the snip-in layout.

The RMC is a stateless snap-in in the MMC environment. Each node is updated on the runtime based on the host process status and contents of the config file. Thanks for MMCLib library developed by http://www.ironringsoftware.com to make my life easy to handle a unmanaged MMC code. I made some slightly modification of the MMCLib for my needs, that's why I included its source in my solution. Basically, the MMCLib handles a snap-in such as creating nodes and processing their events. The following picture show that:

Based on the menu selection, for instance: New -> Remote Object, the snap-in delegates call to the properly event handler (OnNewTask) to perform the specific action. In this case, the windows form is popup to enter necessary attributes requested by the remoting service section in the config file. After pressing the Apply button on the form, the config file is updated and snap-in is notified via its handler - OnUser. This scenario is repeated mostly for all node's activities.

Usage

The RMC requires to be installed by the RemotingManagementConsole.msi file. The windows installer will perform all necessary tasks such as RMC snap-in, MMCLib.dll and MMCFormsShim.dll registration included creating its desktop folder. Opening this folder and clicking on the RemotingManagementConsole.msc icon, the Remoting Management Console will show up with the snap-in of all the installed host processes on your machine. The screen snippet has been shown in the previously chapter.

Let me suppose that we have a remote object and its consumer ready to deploy them. Before the actually work, the remoting object is necessary be hosted and published by windows service host process.

What we need to do?

• create a windows host process
• publish a remoting object in the remoting service tag
• create a channel to listen an incoming remoting messages (IMessages)

Additionally, based on the application requirements:

• adding server Sinks (formatter, provider)
• creating an appSettings for configuration purposes (key/value pairs)
• creating specific config sections

When the configuration process is done, the host process is ready to start. Using the Event Log we can see a process of the remoting configuration. Based on the detail event log message is easy to figure out which attribute in the config file caused the problem.

Now, if we know what the remoting configuration needs, let handle this task do it by RMC. Here are its steps:

Step A. Create a new host process

1. Select the Remoting Host Processes node in the snap-in area
2. Right-click on the node
3. Select New and click Process
4. The following Form dialog will show-up

   

5. Change the Name properties, for instance: HostProcess_Sample
6. Press button CREATE

Now we have a host process installed as a windows service and initiate image of the host process config file. The RMC snap-in created automatically static nodes for this host process:

• lifetime
• RemoteObjects
• Channels
• appSettings
• configSections

The above nodes represent xml sections in the host process remoting config file. For the next step we are going to administrate them based on the application requirements.

Step B. Publishing Remote Object

1. Select the RemoteObjects node in the HostProcess_Sample root
2. Right-click on the node
3. Select New and click Remote Object
4. The following Form dialog will show-up

   

5. Populate all attributes on the Form
6. Press button APPLY

The other, shortcut way (skipping the steps 1-3) is to use a Drag&Drop feature when the remote object exist. The following steps explain that:

1. Drag the assembly of the Remote Object, which you what to publish it from its folder
2. Drop the assembly on the RemoteObjects result view (right panel)
3. follow the above instruction steps 4 - 6 to finalize the entry process.

Step C. Configuring Channel

1. Select the Channels node in the HostProcess_Sample root
2. Right-click on the node
3. Select New and click Remoting channel
4. The following Form dialog will show-up

   

5. Populate necessary attributes on the Form (see below notes)
6. Press button APPLY

Notes:

• When your application using a standard channel, for instance: tcp, enter the port number (must be unique on the machine) and leave empty the other attributes.
• The channel can be configured using the already registered channels (machine.config and host process config) or typing its type in this element. See the checkBox and comboBox features.
• On the bottom of the Form is displayed the finally element for config file.
• The textBox More can be used to add any specific attributes using the name/value pair, for instance: priority="1" myProperty="myValue"

Now, we have a basic configuration of the host process for our remote object. Of course, we can continue to make more advance configuration. I assume you have a knowledge of the remoting configuration and MMC to allow you easy figure out usage of the others nodes in the RMC snap-in.

Let's continue with our basic configuration. As the next step is to start the host process.

Step D. Start Host Process

1. Select the HostProcess_Sample node in the snap-in area
2. Right-click on the node
3. Select All Task and click Start
4. The Form dialog will show the progress of the starting process
5. Check the Host Process result view (right panel) for the Event Log Messages

To Stop or Restart the host process follow the same steps as for Start one.

Refreshing snap-in

Each static node in the snap-in has a Refresh menu item to perform a updating result view and snap-in at the selected level. There is one special Refresh at the snap-in root. In this case the RMC is invoking the scanner of the installed host processes (windows services) on the local machine and refreshing a completely snap-in. You can use also the key F5 to invoke the refresh task.

Implementation

The RMC Solution is divided into the following projects:

• MMCLib this is a modified 3rd party software to handle unmanaged MMC code, http://www.ironringsoftware.com
• ConfigFileLib to handle contents of the configuration file
• HostProcessLib to handle host process such as start, stop, create, install, etc.
• InstallClassRegAsm is a helper install class for custom action
• InstallClassRegsrv32 is a helper install class for custom action
• RemotingManagementConsole is a msi installation project
• RemotingManagement this is a snap-in implementation. There are 17 forms and user controls to handle the snap-in activities.

Note that all projects except the RemotingManagement are re-usable, for instance: HostProcessLib can be used for programmatically creating a host process on the fly in your application, etc.

The following code snippet show an implementation of the creating a host process on the fly:

Collapse

				public
				string Create(string strServiceName, string strServiceDesc, 
                     bool bStartAutomatic, bool bTrayIcon, 
                     string strAssemblyName) 
{
   string strAssemblyFile = null;

   //--- create service ---
   ServiceSrcCode ssc = new ServiceSrcCode();
   string strServiceSrcCode = ssc.GetSrcCodeForService(strServiceName, 
                                                       strServiceDesc, 
                                                       bStartAutomatic, 
                                                       bTrayIcon);

   string strOutputAssembly = string.Format(@"{0}.exe", strAssemblyName);

   // assembly compilation.string[] strArrayReferences = {
      "System.dll", 
      "System.Data.dll", 
      "System.ServiceProcess.dll", 
      "System.Configuration.Install.dll" }; 
   CompilerParameters cp = new CompilerParameters();
   cp.ReferencedAssemblies.AddRange(strArrayReferences);
   cp.GenerateExecutable = true;
   cp.GenerateInMemory = false; 
   cp.OutputAssembly = strOutputAssembly; 
   cp.WarningLevel = 4;
   cp.IncludeDebugInformation = false; 
   ICodeCompiler icc = new CSharpCodeProvider().CreateCompiler();
   CompilerResults cr = icc.CompileAssemblyFromSource(cp, strServiceSrcCode);

   if(cr.Errors.Count > 0)
   {
      foreach(string s in cr.Output) 
      {
         Trace.WriteLine(s);
      }
      thrownew Exception(string.Format("Build failed: {0} errors", 
                                         cr.Errors.Count)); 
   }
   //cr.TempFiles.KeepFiles = true;
   strAssemblyFile = cp.OutputAssembly;

   return strAssemblyFile;
}

The above function is using the ServiceSrcCode class to generate a properly source code of the requested host process from its template:

Collapse

				#region windows service template text
				const string strSrcTmplService = "namespace RemotingHostService" + 
"{ " +
   "using System;" + 
   "using System.Collections;" +
   "using System.ComponentModel;" +
   "using System.Data;" +
   "using System.Diagnostics;" +
   "using System.ServiceProcess;" +
   "using System.Runtime.Remoting;" +
   "using System.Runtime.Remoting.Channels;" +
   "using System.Threading;" +
   "public class Service : ServiceBase" + 
   "{" +
      "private Container components = null;" +
      "public Service()" +
      "{"+
         "components = new Container();" +
         "this.ServiceName = \"SERVICE_NAME\";" +
      "}" +
      "static void Main()" +
      "{" + 
         "ServiceBase[] ServicesToRun;" +
         "ServicesToRun = new ServiceBase[] { new Service() };" +
         "Run(ServicesToRun);" +
      "}" +
      "protected override void Dispose(bool disposing)" +
      "{" +
         "if(disposing) { if(components != null) components.Dispose(); }" +
         "base.Dispose(disposing);"+
       "}" +
       "protected override void OnStart(string[] args)" +
       "{" +
           "if(args.Length == 1) Thread.Sleep(Convert.ToInt32(args[0]));" + 
           "RemotingConfiguration.Configure(AppDomain.CurrentDomain." + 
                                     "SetupInformation.ConfigurationFile);" +
       "}" +
       "protected override void OnStop()" +
       "{" +
          "foreach(IChannel objChannel in ChannelServices.RegisteredChannels)" + 
             "ChannelServices.UnregisterChannel(objChannel);" +
       "}" +
   "}\r\n" +
   "[RunInstaller(true)]" +
   "public class ProjectInstaller : System.Configuration.Install.Installer" +
   "{" +
      "private ServiceProcessInstaller serviceProcessInstaller1;" +
      "private ServiceInstaller serviceInstaller1;" +
      "public ProjectInstaller() {InitializeComponent();}" +
      "private void InitializeComponent()" +
      "{" +
        "this.serviceProcessInstaller1 = new ServiceProcessInstaller();" +
        "this.serviceInstaller1 = new ServiceInstaller();"+
        "this.serviceProcessInstaller1.Account = ServiceAccount.LocalSystem;" +
        "this.serviceInstaller1.ServiceName = \"SERVICE_NAME\"; " +
        "this.serviceInstaller1.StartType = SERVICE_START;" +
        "this.Installers.AddRange(new System.Configuration.Install.Installer[]" +
        "{this.serviceProcessInstaller1, this.serviceInstaller1});" +
      "}" + 
      "public override void Install(IDictionary stateServer)" +
      "{" +
        "Microsoft.Win32.RegistryKey system, currentControlSet, services, " +
               "service; " + 
        "base.Install(stateServer);" +
        "system = Microsoft.Win32.Registry.LocalMachine.OpenSubKey(\"System\");" +
        "currentControlSet = system.OpenSubKey(\"CurrentControlSet\");" +
        "services = currentControlSet.OpenSubKey(\"Services\");" +
        "service = services.OpenSubKey(this.serviceInstaller1.ServiceName, " + 
                "true);" +
        "service.SetValue(\"Description\", \"SERVICE_DESCRIPTION\");" +
        "SERVICE_TRAYICON" +
      "}" +
   "}" +
"}";
#endregion

The template requires to customize its entries such as SERVICE_NAME, SERVICE_START, SERVICE_DESCRIPTION and SERVICE_TRAYICON to finalize the host process code. This task is performed using the string.replace function.

As I mentioned early, the RemotingManagement contains many forms and user controls to handle a particular snap-in node. Basically, their implementations has the same design pattern based on the event driven mechanism. You can see it in the following code snippet how the lifetime node handle it:

Collapse

				#region Lifetime
				protected BaseNode CreateLifetimeNodeTree(BaseNode parentNode, 
                                           string nodeName, bool bRefresh)
{
   FormNode node = new FormNode(this);
   node.ControlType
                = Type.GetType("RKiss.RemotingManagement.PropertiesControl");
   node.DisplayName = nodeName; 
   node.Tag = parentNode.Tag;
   node.OpenImageIndex = intLifetimeImage;
   node.ClosedImageIndex = intLifetimeImage;

   //---add/insert this nodeif(bRefresh)
      node.Insert(parentNode);
   else
     parentNode.AddChild(node);

   node.OnSelectScopeEvent
                       += new NodeNotificationHandler(OnSelectEvent_Lifetime);
   node.OnQueryPropertiesEvent
                   += new NodeNotificationHandler(OnQueryProperties_Lifetime);

   //---this is a post-process notification from the user form
   node.OnUserEvent += new NodeNotificationHandler(OnUserEvent_Lifetime);

   return node;
}

privatevoid OnSelectEvent_Lifetime(object sender, NodeEventArgs args)
{
   BaseNode selNode = sender as BaseNode;

   //---checkpoint
   Trace.WriteLine(string.Format("OnSelectEvent: sender={0}", 
                   selNode.DisplayName));

   //---ask snap-in for the following buttons 
   IConsoleVerb icv; 
   selNode.Snapin.ResultViewConsole.QueryConsoleVerb(out icv);
   icv.SetVerbState(MMC_VERB.PROPERTIES, MMC_BUTTON_STATE.ENABLED, 1);

   //---status text
   selNode.Snapin.ResultViewConsole.SetStatusText("The lifetime properties" + 
       "of the remote singleton and activated objects in the application.");
}

protectedvoid OnQueryProperties_Lifetime(object sender, NodeEventArgs e)
{
   BaseNode selNode = sender as BaseNode;

   //---checkpoint
   Trace.WriteLine(string.Format("OnQueryProperties: sender={0}", 
                                 selNode.DisplayName));

   //---action
   string strConfigFilePath = Convert.ToString(selNode.Tag) + ".config";
   LifetimeForm formLT = new LifetimeForm(selNode, selNode.DisplayName, 
                                           strConfigFilePath);
   formLT.Show();
}

privatevoid OnUserEvent_Lifetime(object sender, NodeEventArgs args)
{
   try 
   {
      //---inputs
      BaseNode node = sender as BaseNode;
      NameValueArgs nva = args as NameValueArgs;
      string strCheckpoint = nva.Key;
      string strLifetimeName = Convert.ToString(nva.Val);

      //---checkpoint
      Trace.WriteLine(string.Format("User Event: sender={0}, checkpoint={1},
         val={2}", node.DisplayName, strCheckpoint, strLifetimeName));

      //---refresh and set scope 
      node.Snapin.ResultViewConsole.SelectScopeItem(node.HScopeItem); 
   }
   catch(Exception ex) 
   {
      Trace.WriteLine(string.Format("OnUserEvent_Lifetime - failed, " + 
                      "error = {0}",  ex.Message));
   }
}
#endregion

The CreateLifetimeNodeTree method has responsibility to create node in the snap-in and subscribe the requested delegates such as

• OnSelectEvent_Lifetime to handle activities when user click this node
• OnQueryProperties_Lifetime to handle a request to pop-up a properties form
• OnUserEvent_Lifetime to handle a post-process of the user form

Test

I created a separate solution to test the RMC:

• InterfaceSample - interface contract
• RemotingObjectSample - remote object
• WindowsFormClient - consumer

As you can see this test solution doesn't have a host server project, that's why the RMC comes to create one. The client is a simple windows form to ask a remote object for the specific section in the config file. Here is its screen shot:

Note that the msi file will install also this test sample, so it's easy to click for the WindowsFormClient icon in the RMC desktop folder to start test it.

Version

This is a pre-view version of the Remoting Management Console. I decided to release it before finishing all features what I have in my plan:

• incorporate the Remoting Probe
• help project
• drag&drop pre-configured channels and sinks
• creating a library of the custom channels and sinks
• enterprise version
• improve users interface

Conclusion

In this article I described a tool hosted by MMC that allows to administrate any remoting object without writing its host process. The Remoting Management Console tool will create automatically a remoting host process including its configuration file. The RMC becomes very useful tool especially during the deployment phase, where a configuration of the distributed objects need to be tuned based on the deployment environment.

The release version with features such as remoting probe and enterprise support to allow administrate the remoting host process remotely will give you a powerful administration tool for your product.

[1] Format for .NET Remoting Configuration Files

Roman Kiss

Welcome to the world of Windows Services
In the past, you had to be proficient in C++ to develop a Windows Service. Thankfully, the .NET platform opens the process to all .NET developers--albeit C#, VB.NET, J#, and so forth. These services can be automatically started when the computer boots, can be paused and restarted, and do not show any user interface.

You can create a service as a Microsoft Visual Studio .NET project, defining code within it that controls what commands are sent to the service and what actions should be taken when those commands are received. Commands sent to a service include starting, pausing, resuming, and stopping the service, and executing custom commands.

After you create and build the application, you can install it by running the command-line utility InstallUtil.exe and passing the path to the service's executable file, or by using Visual Studio's deployment features. You can then use the Services Control Manager to start, stop, pause, resume, and configure your service. Let's take a closer look at Windows Service classes.

Windows Service classes
You can create Windows Services with the help of the ServiceBase class in the System.ServiceProcess namespace. This class contains the following subset of events that interact with the Windows Service Control Manager (SCM):

Only the OnStart event accepts any type of parameter. The main starting point of a Windows Service execution is the Main method, which accepts no parameters. Now you're ready to create your own service.

Creating a Windows Service
At this point, you know which class and events to utilise, so let's create a sample service. Visual Studio .NET makes it simple to create a service using the code of choice:

1. To create a new Windows Service, pick the Windows Service option from your Visual Studio Projects (choose appropriate language), give your service a name, and click OK.
2. A Windows Service project is created with the default project name of WindowsService1 and a class name of Service1.
   using System;
   using System.Collections;
   using System.ComponentModel;
   using System.Data;
   using System.Diagnostics;
   using System.ServiceProcess;
   
   namespace WindowsService1
   {
   
   public class Service1 : System.ServiceProcess.ServiceBase
   {
             private EventLog log = null;
             private System.ComponentModel.Container components = null;
            public Service1()
           {
                 InitializeComponent();
            }
   
           static void Main()
            {
                System.ServiceProcess.ServiceBase[] ServicesToRun;
                ServicesToRun = new System.ServiceProcess.ServiceBase[] { new Service1()           };
                System.ServiceProcess.ServiceBase.Run(ServicesToRun);
           }
   
   private void InitializeComponent() {
           components = new System.ComponentModel.Container();
            this.ServiceName = "Service1";
   }
   
   protected override void Dispose( bool disposing ) {
        if( disposing ) {
           if (components != null) {
              components.Dispose();
          }
       }
       base.Dispose( disposing );
       log.WriteEntry("Service dispose", EventLogEntryType.Information);
       log.Close();
   }
   
   protected override void OnStart(string[] args) {
         log = new EventLog("Builder.com");
        log.WriteEntry("Service starting", EventLogEntryType.Information);
   }
   
   protected override void OnStop() {
        log.WriteEntry("Service stopping.", EventLogEntryType.Information);
     }
   }
   }

Notice that the code execution entry point (Main method) creates a new instance of the ServiceBase class (an object array) and adds an instance of your class to it. The use of the array demonstrates the ability to run more than one process within the service (notice the thread marker within the VB.NET code).

Just the beginning
You now have a basic Windows Service, but you still need to install and run it on a Windows computer. Also, the code will start, but what if you want or need it to run continuously based on a type of trigger?

I'll cover these topics in part 2, in which I'll show you how to install, run and schedule the service.

I covered the inner workings of a Windows Service developed with the .NET Framework. This included a somewhat rudimentary Windows Service application with both VB.NET and C#. This week, we'll install and execute the Windows Service. (Note: This story contains the complete code for part one and part two.)

Windows service installation
While console, Windows Form, and ASP.NET applications are easy to install by copying files, you must explicitly install Windows Service applications. Visual Studio .NET simplifies the installation process for Windows server applications. It displays a link in the Properties window of the Windows Service called Add Installer. When you select the link, the IDE adds the necessary installer classes to your project as part of a separate module.

This includes two classes: System.ServiceProcess.ServiceProcessInstaller and System.ServiceProcess.ServiceInstaller. Several properties may be set using the Properties window of each class. The most important property is Account within the ServiceProcessInstaller class. It specifies the Windows account under which the service runs (security context). The following options are available:

• LocalService: Service has extensive local privileges and presents the computer's credentials to remote servers.
• LocalSystem: Service has limited local privileges and presents anonymous credentials to remote servers.
• NetworkService: Service has limited local privileges and presents the computer's credentials to remote servers.
• User: A local or network account is specified. You may specify the necessary username and password via properties, or you may type them during installation. The Service uses the security context of the specified user account.

When an installer is added to the Service, the ProjectInstaller class is added. Defining properties via each class's Properties window results in an associated line of code in the corresponding ProjectInstaller class. The following code shows a sample installer for our C#-based Windows service with various properties defined, including the Account set to LocalService and ServiceName set to BuilderService.

using System;
using System.Collections;
using System.ComponentModel;
using System.Configuration.Install;
namespace WindowsService1 {
[RunInstaller(true)]
public class ProjectInstaller : System.Configuration.Install.Installer {
    public System.ServiceProcess.ServiceProcessInstaller serviceProcessInstaller1;
    private System.ServiceProcess.ServiceInstaller testInstaller;
    private System.ComponentModel.Container components = null;
    public ProjectInstaller() {
              InitializeComponent();
    }

protected override void Dispose( bool disposing ) {
     if(disposing) {
       if(components != null) {
           components.Dispose();
     } 
   }
    base.Dispose( disposing );
}
#region Component Designer generated code

private void InitializeComponent() {
     this.serviceProcessInstaller1 = new System.ServiceProcess.ServiceProcessInstaller();
     this.testInstaller = new System.ServiceProcess.ServiceInstaller();
    this.serviceProcessInstaller1.Account =  System.ServiceProcess.ServiceAccount.LocalService;
    this.serviceProcessInstaller1.Password = null;
   this.serviceProcessInstaller1.Username = null;
   this.testInstaller.DisplayName = "Test Installer";
   this.testInstaller.ServiceName = "BuilderService";
  this.testInstaller.StartType = System.ServiceProcess.ServiceStartMode.Automatic;
  this.Installers.AddRange(
               new System.Configuration.Install.Installer[] {
                    this.serviceProcessInstaller1,
                     this.testInstaller});
  }
#endregion
} }

With the installers added to the project, you may now install the Windows Service and run it on the target computer. Another approach within our project is how the service is started. There are three options:

• Manual: The user starts the Service.
• Disabled: The Service isn't available for use.
• Automatic: The Service starts automatically when the host computer starts.

In our example, I have the Service start automatically. With the Service properly compiled, we install it on the target computer via the Microsoft .NET Framework Installation utility (InstallUtil.exe) command-line tool. It allows you to easily install and uninstall our service. The compiled file (executable) or assembly is passed to it. Also, it provides the following command-line switches:

• /LogFile=[filename] - Contains the log indicating installation success/failure. The default is the AssemblyName.InstallLog.
• /LogToConsole=(true|false) - Signals whether console output is enabled.
• /ShowCallStack - Signals whether call stack is displayed if an exception is encountered.
• /u - Uninstalls the Service.

With our sample Service, the following line takes care of the installation:

InstallUtil WindowsService.exe

The line is run in the directory containing the assembly; otherwise, it would require the complete path to the assembly. After you install the new Service, it's located in the Services window of the Computer Management applet.

Triggering execution
Once you properly install the Service, it's triggered based upon the Service setting. Unfortunately, it's only executed when loaded or run by a user. You may augment this by adding a timer to the code, so the agent executes on a scheduled basis. The next VB.NET code listing shows our Service with a Timer object added. The timer is started when the Service starts, and it stops when the Service stops.

Imports System.Diagnostics
Imports System.ServiceProcess
Imports System.Timers
Public Class Service1
Inherits System.ServiceProcess.ServiceBase
Private log As EventLog
Private t As Timer
Public Sub New()
MyBase.New()
InitializeComponent()
End Sub
Protected Overloads Overrides Sub Dispose(ByVal disposing As Boolean)
If disposing Then
If Not (components Is Nothing) Then
components.Dispose()
End If
End If
log.WriteEntry("Service dispose", EventLogEntryType.Information)
log.Close()
MyBase.Dispose(disposing)
End Sub
<MTAThread()> _
Shared Sub Main()
Dim ServicesToRun() As System.ServiceProcess.ServiceBase
ServicesToRun = New System.ServiceProcess.ServiceBase() {New Service1}
System.ServiceProcess.ServiceBase.Run(ServicesToRun)
End Sub
Private components As System.ComponentModel.IContainer
<System.Diagnostics.DebuggerStepThrough()> Private Sub InitializeComponent()
components = New System.ComponentModel.Container
Me.ServiceName = "Service1"
End Sub
Protected Overrides Sub OnStart(ByVal args() As String)
log = New EventLog("Builder.com")
log.WriteEntry("Service Starting", EventLogEntryType.Information)
t = New Timer(3600000)
AddHandler t.Elapsed, AddressOf TimerFired
With t
.AutoReset = True
.Enabled = True
.Start()
End With
End Sub
Protected Overrides Sub OnStop()
log.WriteEntry("Service Stopping", EventLogEntryType.Information)
t.Stop()
t.Dispose()
End Sub
Private Sub TimerFired(ByVal sender As Object, ByVal e As ElapsedEventArgs)
' Deal with firing
End Sub
End Class.

Use the right tool
A Windows Service is an excellent application choice when working with administrative tasks or automating routine tasks. Add it to your toolbox and use it when the situation arises.

28 votes for this article. Popularity: 5.12. Rating: 3.54 out of 5.

• Download demo project - 22 Kb

For sometime I have been working on Remoting projects using .NET but every time I will always end up creating a console application to run as a remote server and host the remoting object in that. This definitely is not going to be case in real world applications. Most of the time you will require that your remote object is hosted in a server that is running all the time and does not require any user intervention like in Console application. You have couple of options for hosting e.g. WebServer, Managed Executables (e.g. Console App) or Component Services.

This article is not about what is .NET remoting. You can read about that in .NET documentation or in my other article .NET Remoting Spied On. This article is a combination of how to write a Windows Service Application formerly known as NT Service and how to host your remoting object in that service.

How To Create Windows Service Application

.NET online documentation has a complete section on “Creating and Configuring Windows Service Applications”. This chapter contains very good information on Introduction, Architecture, Security Issues, Install/Uninstall issues. So it would be a waste of time and space if I start discussing those. But there are certain things that are not very clear in that documentation. So I will try to explain those and show what all tools are available are in VS.Net to write Windows Service Applications.

In VS.Net, if you click on New/Project, you will see that under Visual C# Project types, there is one named Windows Service. This is the type you want to pick if want to write service application. This does not mean that you can write Windows Service applications using C# only. You can do it in any language. This article is going to focus on using C# only.

.NET framework provides System.ServiceProcess namespace that contains all the classes you need to write and install service applications. Every Windows Service application class has to be derived from ServiceProcess.SystemBase. For the demo project with this article, the definition looks as follows.

																public
																class PS_RemoteSrvrSrvc : System.ServiceProcess.ServiceBase 

By default wizard provides you with bare minimum skeleton for service application. It provides OnStart and OnStop methods, which are essential components of a service application. OnStart method gets called when the service starts automatically when system starts or if it is manually started from Service Control Manager. OnStop gets called when the service stops. There are other methods that your service application can implement but that depends on the architecture and options you set for the application. E.g. you can implement OnPause, OnContinue, OnShutdown methods. But if your service application does not support pause and continue, then there is no need to implement these methods. You can set the characteristics of your application by setting the values for Properties supported by ServiceBase class and I would strongly recommend that you take a look at these properties in the documentation. Since debugging a Windows Service application is not a trivial job, setting of EventLog properties is very important. And I would recommend using EventLog extensively in initial phase of your project so that you can log your trace messages in the event log.

How To Install Windows Service Application

The section on “Creating and Configuring Windows Service Applications” in documentation says that you need to add installer components to install the service on your system so that it gets added to Service Control Manager (SCM). .NET framework documentation covers this topic in “Configuring and Deploying your .NET application”. Lets see what needs to be done to add installer component for our Windows Service application.

.NET framework provided “installutil. In the folder where the executable for your service application resides, run this utility to install or uninstall the application. Following is the syntax for install and uninstall.

installutil myService.exe
installutil /u myService

When installutil utility runs, it looks for a class with attribute RunInstallerAttribute set to true. Therefore the first step in adding service installer to your application is to add a class with this attribute. In the demo project I have added PS_ServiceInstall derived from System.Configuration.Install.Installer to PS_RemoteServer namespace and have set the RunInstallerAttribute attribute.

[RunInstallerAttribute(true)]
    publicclass PS_ServiceInstall : Installer
{
.
.
}

In the constructor of this Installer class you can add the logic for installation. System.ServiceProcess.ServiceInstaller and System.ServiceProcess.ServiceProcessInstaller classes provide the functionality to add the Service and ServiceProcess installer component. Follow the following simple steps to add a bare minimum installer for your Windows Service application.

1. Add a class derived from System.Configuration.Install.Installer class.
2. Set the RunInstallerAttribute attribue for this class to True.
3. In the constructor, create new instance of ServiceProcessInstaller per service application and new instance of ServiceInstaller class for each service in the application.
4. Add these installer objects to the InstallerCollection of your Installer class.

ServiceInstaller and ServiceProcessInstaller has bunch of properties that can be used to set the attributes of the service. ServiceInstaller has the following properties.

• DisplayName: Sets the friendly name that identifies the service to the user
• ServiceName: Sets the name that system uses to identify the service.
• ServicesDependedOn: Specify the services that must be running for this service to run.
• StartType: Sets how and when the service will be started. The possible values for this property are Automatic, Manual or Disabled. Meaning that service will start automatically when system starts, the user will manually start the service from SCM or service will start in disabled mode.

ServiceProcessInstaller has some very important properties that concern the security issues with your service application.

• RunUnderSystemAccount: Specify if the service will be run under computer’s system account or under a certain user’s account. If this property is set to true then the service application will start under system account. This means it can start at system reboot without any user being logged on the system. But if this property is set to false, then during installation user will be presented with a login dialog to enter the user name and password that should be used for authentication.
• UserName: Sets the user name under which service will run. It is only required if RunUnderSystemAccount property is set as false.
• Password: Sets the password associated with the user account under which service will run. Like UserName property, this is only required if RunUnderSystemAccount property is set as false.
• HelpText: Sets the help text displayed for service installation options.

The methods associated with these two classes are called by Install utility during install and uninstall process. You don’t have to specifically call any of these methods in your Installer class.

																public PS_ServiceInstall()
{
        this.m_ServiceInstaller = new ServiceInstaller ();
        this.m_ServiceInstaller.StartType = ServiceStart.Manual;
        this.m_ServiceInstaller.ServiceName = "RemoteSystemInfo";
        this.m_ServiceInstaller.DisplayName = "Remote System Info";
        Installers.Add (this.m_ServiceInstaller);

        this.m_ProcessInstaller = new ServiceProcessInstaller ();
        this.m_ProcessInstaller.RunUnderSystemAccount = true;
        Installers.Add (this.m_ProcessInstaller);
}

How to host .NET Remoting Object

For hosting .NET Remoting objects in a server, you need to do following objects.

1. Create and register the channel of transport, the object will use for marshalling, with ChannelServices. E.g. you can use TCP, HTTP or SMTP channels.
2. Register your object with RemotingServices.

Before you can access the remote object, the server should be running and the above-mentioned tasks should have been completed. Therefore the best place to do this is in OnStart method of your service.

Collapse

																protected override void OnStart(string[] args)
{
EventLog.WriteEntry("RemoteSystemInfo: OnStart -- Entering");
        TCPChannel tcpChannel = new TCPChannel (8085);
        EventLog.WriteEntry("RemoteSystemInfo: OnStart -- Created Channel");

        ChannelServices.RegisterChannel (tcpChannel);
        EventLog.WriteEntry("RemoteSystemInfo:" + 
                 " OnStart -- Registered Channel");

        RemotingServices.RegisterWellKnownType ("PS_RemoteSrvr", 
             "PS_RemoteSrvr.PS_SystemInfoSrvr",
             "PS_SystemInfoSrvr", 
             WellKnownObjectMode.SingleCall);
        EventLog.WriteEntry("RemoteSystemInfo:" + 
             " OnStart -- RegisterWellKnownType Done");
        EventLog.WriteEntry ("RemoteSystemInfo: OnStart -- Leaving");
}

The above code is all that is required to host a simple .NET remote object in Windows Service Application. You may require some extra steps or procedure depending on the nature of the remoting object and method you will use to configure it. But idea is that you should accomplish all the tasks on OnStart method of service.

How To Use Demo Project

The demo project associated with this article is not doing any thing fancy. I wrote a utility class that gets the OS information. I have added a method GetOSInfo to my remoting object PS_SystemInfoSrvr. This method creates a new instance of PS_OSInfo object, which is implemented in PS_SystemInfoUtil project, and returns to the client. And then client can call the methods and properties implemented by PS_OSInfo class. I have included the configuration file, PS_SystemInfo.cfg, that client can use to configure access to the remote server. The client application is implemented in PS_RemoteSystemInfo project. Following code shows how the client application configures and accesses the remoting object.

																private
																void ConfigureRemoteServer ()
{
        try
        {
               RemotingServices.ConfigureRemoting ("PS_RemoteSystemInfo.cfg");
               this.m_RemoteInfoSrvr = (PS_SystemInfoSrvr)
                   Activator.GetObject (typeof (PS_SystemInfoSrvr),
                   "tcp://sultan:8085/PS_SystemInfoSrvr");

               PS_SystemOS sysOS = this.m_RemoteInfoSrvr.GetOSInfo ();
               string strSystemDir = sysOS.SystemFolder;
               string strOS = sysOS.OS;
               string strVersion = sysOS.ServicePack;
        }
        catch (RemotingException e)
        {
               Trace.WriteLine (e.Message);
        }
}

I have used TCP as my transport mechanism and “sultan” is my remote server where the service application hosting the remoting object is running. For you application you will need to provide the name or ip address of your server in configuration file or in GetObject call. If you want to run Client and Service app on same machine then simply use “localhost” as server name.

To install the service application, copy PS_RemoteSrvr.exe and PS_SystemInfoUtil.dll to the folder where you want to install it. On the command line, run installutil utility in that folder. Then open the Service Control Manager. There you will see the service application. It will not be started yet, because I have set the start type as Manual. Right click on it and Start it. Now your remoting object has been hosted in the service application. As long as the service application is running, your client application can access it.

On the client machine, you don’t need to run the instalutil utility. Simply run the PS_RemoteSystemInfo.exe. Put a break point in the ConfigureRemoteServer method and then you can see Remoting in action.

Do I Need VS.Net To write Service Application

You can definitely write Windows Service Application without VS.Net. You just need to create a class derived from System.ServiceProcess.ServiceBase class. Only advantage of using VS.Net is that it creates a skeleton for service application.

What Additional References Need To Be Added To Project

Remoting is implemented in Service.Runtime.Remoting so that needs to be added to your service as well as client application.

Naveen K Kohli

Published: November 2002

Last Revised: January 2006

Applies to:

• Remoting (Microsoft® .NET Framework 1.1)

See the "patterns & practices Security Guidance for Applications Index" for links to additional security resources.

See the Landing Page for a starting point and complete overview of Building Secure ASP.NET Applications.

Summary: Objects called using the .NET Remoting infrastructure can be hosted by ASP.NET, custom executables or Windows services. This How To shows you how to host a remote object in a Windows service and call it from an ASP.NET Web application. (7 printed pages)

Contents

Notes
Summary of Steps
Step 1. Create the Remote Object Class
Step 2. Create a Microsoft Windows&#174; Service Host Application
Step 3. Create a Windows Account to Run the Service
Step 4. Install the Windows Service
Step 5. Create a Test Client Application
Additional Resources

This How To describes how to host a remote object in a Windows service and call it from an ASP.NET Web application.

Notes

• Remote objects (that is, .NET objects accessed remotely using .NET Remoting technology) can be hosted in Windows services, custom executables, or ASP.NET.
• Clients communicate with remote objects hosted in custom executables or Windows services by using the TCP channel.
• Clients communicate with remote objects hosted in ASP.NET by using the HTTP channel.
• If security is the prime concern, host objects in ASP.NET and use the HTTP channel. This allows you to benefit from the underlying security features of ASP.NET and IIS.

For information about how to host a remote object in ASP.NET (with IIS), see article Q312107, "HOW TO: Host a Remote Object in Microsoft Internet Information Services."

• If performance is the prime concern, host objects in a Windows service and use the TCP channel. This option provides no built-in security.

Summary of Steps

This How To includes the following steps.

• Step 1. Create the Remote Object Class
• Step 2. Create a Microsoft Windows® Service Host Application
• Step 3. Create a Windows Account to Run the Service
• Step 4. Install the Windows Service
• Step 5. Create a Test Client Application

Step1. Create the Remote Object Class

This procedure creates a simple remote object class. It provides a single method called Add that will add two numbers together and return the result.

To create the remote object class

1. Start Microsoft Visual Studio® .NET and create a new Microsoft Visual C#® Class Library project called RemoteObject.
2. Use Solution Explorer to rename class1.cs as Calculator.cs.
3. In Calculator.cs, rename Class1 as Calculator and rename the default constructor accordingly.
4. Derive the Calculator class from MarshalByRefObject to make the class remotable.
   Copy Code

   public class Calculator : MarshalByRefObject
   

5. Add the following public method to the Calculator class.
   Copy Code

   public int Add( int operand1, int operand2 )
   {
     return operand1 + operand2;
   }
   

6. On the Build menu, click BuildSolution.

Step 2. Create a Windows Service Host Application

This procedure creates a Windows service application, which will be used to host the remote object. When the service is started it will configure the TCP remoting channel to listen for client requests.

Note   This procedure uses an Installer class and the Installutil.exe command line utility to install the Windows service. To uninstall the service, run Installutil.exe with the /u switch. As an alternative, you could use a Setup and Deployment Project to help install and uninstall the Windows service.

To create a Windows Service host application

1. Add a new Visual C# Windows Service project called RemotingHost to the current solution.
2. Use Solution Explorer to rename Service1.cs as RemotingHost.cs.
3. In RemotingHost.cs, rename the Service1 class as HostService and rename the default constructor accordingly.
4. At the top of the file, add the following using statement beneath the existing using statements.
   Copy Code

   using System.Runtime.Remoting;
   

5. Locate the Main method and replace the existing line of code that initializes the ServicesToRun variable with the following.
   Copy Code

   ServicesToRun = new System.ServiceProcess.ServiceBase[] { 
                                               new HostService() };
   

6. Locate the InitializeComponent method and set the ServiceName property to RemotingHost.
   Copy Code

   this.ServiceName = "RemotingHost";
   

7. Locate the OnStart method and add the following line of code to configure remoting. The fully qualified path to the configuration file will be passed as a start parameter to the service.
   Copy Code

   RemotingConfiguration.Configure(args[0]);
   

8. Add a new C# class file to the project and name it HostServiceInstaller.
9. Add an assembly reference to the System.Configuration.Install.dll assembly.
10. Add the following using statements to the top of HostServiceInstaller beneath the existing using statement.
    Copy Code

    using System.ComponentModel;
    using System.ServiceProcess;
    using System.Configuration.Install;
    

11. Derive the HostServiceInstaller class from the Installer class.
    Copy Code

    public class HostServiceInstaller : Installer
    

12. Add the RunInstaller attribute at the class level as follows.
    Copy Code

     [RunInstaller(true)]
    public class HostServiceInstaller : Installer
    

13. Add the following two private member variables to the HostServiceInstaller class. The objects will be used when installing the service.
    Copy Code

    private ServiceInstaller HostInstaller;
    private ServiceProcessInstaller HostProcessInstaller;
    

14. Add the following code to the constructor of the HostServiceInstaller class.
    Copy Code

    HostInstaller = new ServiceInstaller();
    HostInstaller.StartType = 
      System.ServiceProcess.ServiceStartMode.Manual;
    HostInstaller.ServiceName = "RemotingHost";
    HostInstaller.DisplayName = "Calculator Host Service";
    Installers.Add (HostInstaller); 
    HostProcessInstaller = new ServiceProcessInstaller();
    HostProcessInstaller.Account = ServiceAccount.User;
    Installers.Add (HostProcessInstaller);
    

15. Within Solution Explorer, right-click RemotingHost, point to Add, and then click Add New Item.
16. In the Templates list, click TextFile and name the file app.config.

    Configuration files with the name app.config are automatically copied by Visual Studio .NET as part of the build process to the output folder (for example, <projectdir>\bin\debug) and renamed as <applicationname>.config.

17. Click OK to add the new configuration file.
18. Add the following configuration elements to the new configuration file.
    Copy Code

    <configuration>
    <system.runtime.remoting>
      <application name="RemoteHostService">
        <service>
          <wellknown type="RemoteObject.Calculator, RemoteObject" 
                     objectUri="RemoteObject.Calculator" 
                       mode="Singleton" />
        </service>
        <channels>
          <channel ref="tcp" port="8085">
            <serverProviders>
              <formatter ref="binary" />
            </serverProviders>
          </channel>
        </channels>
      </application>
    </system.runtime.remoting>
    </configuration>
    

19. On the Build menu, click Build Solution.

Step 3. Create a Windows Account to Run the Service

This procedure creates a Windows account used to run the Windows service.

To create a Windows account to run the service

1. Create a new local user account called RemotingAccount. Enter a password and select the Password never expires check box.
2. In the AdministrativeTools programs group, click Local Security Policy.
3. Use the LocalSecurityPolicy tool to give the new account the Log on as a service privilege.

Step 4. Install the Windows Service

This procedure installs the Windows service using the installutil.exe utility and then start the service.

To install the Windows service

1. Open a command window and change directory to the Bin\Debug directory beneath the RemotingHost project folder.
2. Run the installutil.exe utility to install the service.
   Copy Code

   installutil.exe remotinghost.exe
   

3. In the SetServiceLogin dialog box, enter the user name and password of the account created earlier in procedure 3 and click OK.

   View the output from the installutil.exe utility and confirm that the service is installed correctly.

4. Copy the RemoteObject.dll assembly into the RemotingHost project output directory (that is, RemotingHost\Bin\Debug).
5. From the AdministrativeTools program group, start the Services MMC snap-in.
6. In the Services list, right-click Calculator Host Service, and then click Properties.
7. Enter the full path to the service's configuration file (remotinghost.exe.config) into the Start parameters field.

   Note   A quick way to do this is to select and copy the Path to executable field and paste it into the Startparameters field. Then append the ".config" string.

8. Click Start to start the service.
9. Confirm that the service status changes to Started.
10. Click OK to close the Properties dialog box.

Step 5. Create a Test Client Application

This procedure creates a test console application that is used to call the remote object within the Windows service.

To create a test client application

1. Add a new Visual C# Console application called RemotingClient to the current solution.
2. Within Solution Explorer, right-click RemotingClient, and then click Set as StartUp Project.
3. Add an assembly reference to the System.Runtime.Remoting.dll assembly.
4. Add a project reference to the RemoteObject project.
5. Add the following using statements to the top of class1.cs beneath the existing using statements.
   Copy Code

   using System.Runtime.Remoting.Channels;
   using System.Runtime.Remoting.Channels.Tcp;
   using RemoteObject;
   

6. Add the following test code to the Main method to call and invoke the Calculator object hosted by the Windows service.
   Copy Code

   TcpChannel chan = new TcpChannel();
   ChannelServices.RegisterChannel(chan);
   Calculator calc = (Calculator)Activator.GetObject(
                            typeof(RemoteObject.Calculator),
                    "tcp://localhost:8085/RemoteObject.Calculator");
   if (calc == null) 
     System.Console.WriteLine("Could not locate server");
   else 
     Console.WriteLine("21 + 21 is : " + calc.Add(21,21) );
   

7. On the Build menu, click BuildSolution.
8. Run the client application and confirm that the correct result is displayed in the console output window.

Additional Resources

For information about how to host a remote object in ASP.NET (with IIS), see article Q312107, "HOW TO: Host a Remote Object in Microsoft Internet Information Services".

Introduction

Microsoft Robotics Studio (MSRS), the first prerelease of which was announced several months ago, is going to become a powerful tool not just for robots control but also for a wide range of service-oriented applications. Its Concurrency and Coordination Runtime (CCR) considerably simplifies development of simultaneous and interrelated tasks and increases applications' responsiveness. Decentralized System Services (DSS) provides developers with light-weighted services-based tools to write and coordinate distributed applications.

Although MSRS supports Web user interfaces and even allows to run WinForms from inside of the DSS service, communication of DSS services with a non-MSRS application may be desirable. Particularly, such communication is required when MSRS-based servers respond to remote non-MSRS clients. This article presents a sample of such a communication. The connection is made using .NET 3.0 Windows Communication Foundation (WCF, formerly known as "Indigo") services. Some basic familiarity with MSRS and WCF is essential. Apart from Microsoft documentation, several useful links are given in the References paragraph at the end of this article.

Code Sample

Description

The code sample for the article consists of four projects (see the picture). Three of them, namely, PerformanceMonitor, FileWatcher, and Coordinator, are DSS of the same DSS host (node). The services have nothing to do with the actual robots control. Instead, in full compliance with their names, PerformanceMonitor periodically measures the % Processor Time performance counter, FileWatcher listens on changes in a given disk directory, and Coordinator coordinates activities of the formers and acts as gateway for this DSS node to the outside world. The shining outside world is represented by the forth project TheForm that is a WinForms application. TheForm and Coordinator communicate with WCF services. Each of the parties implements its own self-containing WCF service, and creates a proxy to connect the counterpart. TheForm implements a WCF service Notification with a http://<machine>:19191/Notification URI containing endpoints for the notification itself and the service metadata export. This service provides an interface (in the WCF parlance [ServiceContract]) TheForm.INotification implemented by the TheForm.Notification class. The service is defined in App.config file and opened in the StartNotificationService() method of the class TheForm.Helper. The DSS Coordinator has its own self-containing WCF service Coordinator http://<machine>:19190/Coordinator with [ServiceContract]Robotics.Coordinator.ICoordinator (file CoordinatorServiceType.cs) opened in an imperative form in the Robotics.Coordinator.CoordinatorServiceHost class. The client proxies for the above WCF services were generated using the SvcUtil.exe utility. Appropriate command files are included in the Coordinator (file NotificationProxyGenerator.cmd) and the TheForm (file CoordinatorProxyGenerator.cmd) Visual Studio projects. The commands in these files extract service metadata during service runtime.

The WCF service hosted by the Coordinator DSS receives commands sent by TheForm UI console. For simplicity, it has only one [OperationContract]ICoordinator.Command() with two parameters: a command name string and a typeless (of object type) command data specific to each command.  There are only three such commands in the sample: "notify me" to make Coordinator DSS a client of the TheForm's Notification WCF service, "set monitoring period" for PerformanceMonitor DSS, and "set watched directory" for FileWatcher DSS. The "notify me" command causes the DSS Coordinator to become a client of the Notification WCF service and call [OperationContract]TheForm.INotification.Notify() when the notification event occurred.

As it was stated above, the Coordinator DSS controls activities of other DSS services in this solution, gets notifications from them and, in its turn, notifies TheForm application. Thus, the Coordinator DSS sets a period for PerformanceMonitor and watches the directory for FileWatcher. This is achieved by including references to the PerformanceMonitor and FileWatcher proxies (FileWatcher.Y2006.M09.Proxy.dll and PerformanceMonitor.Y2006.M09.Proxy.dll, respectively), and posting the Replace verb to their main ports to replace the services states with new data (see classes implementing the interface IDssCommand in the file Commands.cs). ReplaceHandler() of PerformanceMonitor updates PerformanceMonitorState.timeout effectively changing monitoring period. Similarly ReplaceHandler() of FileWatcher updates FileWatcherState.watcherRootDir setting a new directory to listen on. Both PerformanceMonitor and FileWatcher DSS send notification to their subscription ports. The mechanism of communication between different DSS within one DSS node is explained (or rather "shown") in the ServiceTutorials shipped with Microsoft Robotics Studio CTP. See also comments in the sample's code.

In this sample, I don't care about DSS security restrictions. So in order to allow DSS to use the performance counter, listen to the changes in the disk directories, and communicate with WCF means, security restrictions are lifted for now (by commenting out the [PermissionSet] attribute of the DsspServiceBase-derived classes in all DSS). For simplicity, only synchronous calls to WCF services are used in the sample. Since the sample is intended to show just the concept, the error handling is primitive.

Installation of Code Source

First make sure that .NET 3.0 (currently RC August 2006) and MSRS (currently CTP October 2006) are installed on your machine. Then unzip sources to a _MsrsWcfWorkTogether directory just under MSRS main directory, start  Microsoft Robotics Studio Command Prompt, go to _MsrsWcfWorkTogether directory and run DevEnv.cmd file. VS 2005 will be opened with WCFConn.sln loaded to it. Check the project properties. Output path for all projects should be ..\..\..\bin\services\. For DSS services, the setting should be as follows:

Start external program: <Microsoft Robotics Studio main directory>\bin\DssHost.exe

Command line arguments: -port:50000 -tcpport:50001 -manifest:"_MsrsWcfWorkTogether/WCFConn/Coordinator/Coordinator.manifest.xml"

Working directory: <Microsoft Robotics Studio main directory>

Build solution in the following order. First, build FileWatcher and PerformanceMonitor projects. Then make sure that Coordinator has proper references to FileWatcher.Y2006.M09.Proxy.dll and PerformanceMonitor.Y2006.M09.Proxy.dll and build Coordinator project. Build TheForm project. Use files RunTheForm.cmd and RunCoordinator.cmd to run appropriate applications. For future MSRS releases, use the recommended converting procedure.

Installation of Demo

Unzip demo to directory <Microsoft Robotics Studio main directory>\bin\services and execute RunCoordinatorFromSvc.cmd and RunTheFormFromSvc.cmd files.

Note. This demo project works for the version of MSRS and WCF specified above.

Conclusion

A sample of collaboration between MSRS service and a WinForms application by means of WCF services is presented. WCF provides the developer with a range of transport adapter channels (HTTP, TCP, Named Pipes, Peer to Peer and MSMQ) as a means of transporting messages between the sender and receiver. Thus, the ability to communicate using WCF considerably extends the capabilities of MSRS services, particularly to serve as a server engine.

References

• Sara Morgan Rea.An Introduction to Programming Robots with Microsoft Robotics Studio.
• Jeffrey Richter. Concurrent Affairs: Concurrency and Coordination Runtime.
• Ingo Rammer. From .NET Remoting to the Windows Communication Foundation (WCF).
• Yasser Shohoud. Meet the WCF Channel Model - Part 1.

Igor Ladnik

Click here to view Igor Ladnik's online profile.

Introduction

As business becomes more global every day, there is an emerging need to make applications and services multi-lingual and culturally aware. The .NET framework already provides comprehensive support for internationalization, but it is not always clear how to apply this support to the design of services. In this article, I will describe some of the available globalization patterns for web services, and how to successfully apply them using the extensibility points provided by WCF. In addition, I will align some code samples with the recently released WCF working draft for Web Services Internationalization (WS-I18N).

Globalization Patterns

There are at least three different globalization patterns that can be applied to a WCF service during the design or development phase. These patterns are mutually exclusive; they can not be used together, so it is essential to know their differences before starting work.

• Locale Neutral: In this pattern, most aspects of the services are not locale-affected. This is the simplest case, and additional considerations are not required. For example, a “Calculator” service that performs arithmetic operations.
• Service Determined: Here, the service always runs in a determined locale, which can be the host’s default locale, or a locale specifically configured for that service. For example, a web service that always returns messages in English.
• Client Influenced: In this case, the service may run in a locale provided by the client application. As the “WS-I18N” states, the service is “influenced” because it can either consider the locale in which it is running or not depending on how the service is being implemented.

These patterns do not take into account situations in which different service implementations and data contracts are used to serve clients applications in a multilingual or cross-cultural setting.

Let’s look at each of these patterns in detail.

Locale Neutral

This is the simplest case, there is no need to consider or attend to any globalization feature.

[ServiceContract(Namespace="http://Microsoft.ServiceModel.Samples")]
public interface ICalculator
{
    [OperationContract]
    double Add(double n1, double n2);

    [OperationContract]
    double Subtract(double n1, double n2);
}
    
// Service class which implements the service contract.
public class CalculatorService : ICalculator
{
    public double Add(double n1, double n2)
    {
        return n1 + n2;
    }

    public double Subtract(double n1, double n2)
    {
        return n1 - n2;
    }
}

The code above is quite straightforward. It only performs some simple arithmetic operations, but, as you can see, these operations are not influenced by any locale. The operation’s output will always be the same, whether the host’s locale is English or French.

Service Determined

Service determined scenarios are useful when all the clients for the service are well-known, and all of them agree on the use of a fixed locale, for instance, American English. This specific locale is usually the host’s default locale, or a locale specifically configured for the service. All the threads running in the host have a default System.Globalization.CultureInfo instance, where you can get the proper locale, and use it for different purposes, like number formatting, calendaring, or retrieving specific messages from a resource file.

You can get that instance through the static properties CultureInfo.CurrentCulture and Thread.CurrentThread.CurrentCulture. The bad news is that there is a second instance of CultureInfo per thread, namely the UI display culture, that you can read using the static properties CultureInfo.CurrentUICulture and Thread.CurrentThread.CurrentUICulture.

As you prepare to code a service, you will probably decide to use CultureInfo.CurrentUICulture because the display culture is typically used by the ResourceManager class for resource loading in WinForm applications.

Let’s take a look to some code for a simple “HelloWorld” scenario:

				// Define a service contract.
[ServiceContract(Namespace="http://Microsoft.ServiceModel.Samples")]
public interface IHelloWorld
{
    [OperationContract]
    string HelloWorld();
}

// Service class which implements the service contract.
public class HelloWorldService : IHelloWorld
{
    public string HelloWorld()
    {
        return Messages.HelloWorld;
    }
}

In the code above, I defined a simple contract and implementation for a service that only returns a “Hello World” message. The Messages class seen here is a typed resource class, one of the new features in .NET 2.0. If you create a resource file in your application, “Messages.resx” for instance, you can use the tool “resgen.exe” to automatically generate a typed class, with a property for each message in the resource file. In addition, this typed class automatically loads the resource file corresponding to the current thread culture, i.e., the one you can get using the static properties CultureInfo.CurrentCulture and Thread.CurrentThread.CurrentCulture. This is definitely good news, since you no longer have to worry about loading the right resource file and getting the messages from it. The “Messages.resx” file in the application looks like this:

As a result, after executing the service, the client application will always receive the same “Hello World!!!” message, whether it is able to understand that message or not.

Client Influenced

This scenario is perhaps the most complex of the three, because the client needs to pass the expected locale in some way, and the service must decide whether it accepts that locale or not. The client and service also need to agree on the format and mechanism to exchange that locale. There are two ways to exchange the international preferences between the client and the service: an out-of-band mechanism through a message header, or an additional argument in the message body. In my opinion, the first option is usually preferable because it does not imply modifying each operation to include an additional argument. Since the Web Services Internationalization (WS-I18N) specification describes a mechanism to implement this scenario, I have chosen to align some code samples with the latest draft of this specification. In the following paragraphs, I will discuss the main aspects of this specification, and will then focus on a concrete implementation for WCF.

Web Services Internationalization (WS-I18N)

WS-I18N provides a mechanism to pass international preferences to a service invoked through SOAP, and to understand the format and language of any message returned. In other words, the main feature of this recently released specification is to influence the service with some cultural preferences specified by the client application. These preferences include:

• Locale or language preference
• Time zone
• Optional information

WS-I18N Elements

The main component of the WS-I18N specification is the “International” element. This element is a SOAP header that provides a mechanism for attaching international preferences and contextual information to a SOAP message targeted towards a specific receiver or SOAP actor. Thus, a SOAP message may have multiple “International” headers, each one for a different receiver (it is not possible to specify two different “International” headers for the same actor). The following sample shows a simple “International” header:

<i18n:international S:mustUnderstand=”true” S:actor=”http://myorg.uri”>
    <locale>en-US</locale>
    <tz>GTM-0300</tz>
    <preferences>
        ...
    </preferences>
</i18n:international>

As you can se in the above sample, some additional elements are specified in the “International” header. Let’s discuss all of them in detail:

• Locale: The “locale” element represents the requested user locale. The content of this element must be either a valid language tag (RFC3066bis) or one of the values “$default” or “$neutral” (same as Invariant Culture in .NET). For example, “en-US” for American English, or “es” for Spanish.
• Tz: The “tz” element represents the time zone of the client application or requester.
• Preferences: The “preferences” element represents a way to specify optional information and international preferences.

WS-I18N Implementation for WCF

So far, we have looked at three different globalization patterns, and have gone through a brief overview of the WS-I18N specification. We are now ready to start coding our implementation for WCF.

Creating the Contract Definition for the “International” Header

As the first step, we need to create a Data Contract for the “International” header. The data contract definition for a message header in WCF follows the same rules as that for normal messages. In the following code, we will see how to create the data contract for the desired header:

[DataContract(Name=”International”, 
  Namespace=”http://www.w3.org/2005/09/ws-i18n”)]  
public class International
{
    private string locale;
    private string tz;
    private List<Preferences> preferences;

    public International()
    {
    }

    [DataMember(Name = “Locale”)] 
    public string Locale
    {
        get { return locale; }
        set { locale = value; }
    }

    [DataMember(Name = “TZ”)] 
    public string Tz
    {
        get { return tz; }
        set { tz = value; }
    }

    [DataMember(Name=”Preferences”)]
    public List<Preferences> Preferences
    {
        get { return preferences; }
        set { preferences = value; }
    }
}

Here, I have defined a class with a property for each element in the header. Since locale and time zone are simple types, we can represent them with string properties. However, the “Preferences” element, by definition, can contain any custom information or XML data, so, we need to create a specific data type for that element.

public class Preferences : IXmlSerializable
{
    private XmlNode anyElement;

    public XmlNode AnyElement
    {
        get { return anyElement; }
        set { anyElement = value; }
    }    
        
    public XmlSchema GetSchema()
    {
        return null;
    }

    public void ReadXml(XmlReader reader)
    {
        XmlDocument document = new XmlDocument();
        anyElement = document.ReadNode(reader);
    }

    public void WriteXml(XmlWriter writer)
    {
        anyElement.WriteTo(writer);
    }
}

The serializer for data contracts in WCF supports serialization with IXmlSerializable types, but not with an XmlNode type. Fortunately, we can overcome this obstacle by defining a class that exposes an XmlNode property and implements the IXmlSerializable interface, so we know how to write and read that XML from an XML stream.

Adding the “International” Header to the SOAP Messages

Once we have the header definition, as second step, we need to include that header in every message that goes from the client application to the server. In WCF, we have two ways to perform this task: we can explicitly define a message contract for the service and then, include the “International” header in that contract, or we can use some extensibility point to automatically add the header in every message at runtime. In my opinion, the first option is quite more rigid than the second one, since we have to modify or create a message contract for each operation in order to include the header. On other hand, the “International” header is explicitly exposed in the WSDL definition for the service. We will explore both alternatives in the following paragraphs, so you can choose the one you consider better.

Let’s start working first on the explicit version, that is, including the “International” header in a service message contract.

[MessageContract()]
public class HelloWorldRequest
{
    [MessageHeader()] 
    public International International; 
}

To make things simpler, I only included the class representing the “International” header that we previously defined. This message contract does not specify any additional parameter in the message body or header. The message implementation for this service is also quite simple; just take a look at the code below:

				// Service class which implements the service contract.
public class HelloWorldService : IHelloWorld
{
    public HelloWorldResponse HelloWorldWithMessages(HelloWorldRequest request)
    {
        if (request.International != null)
        {
            Messages.Culture = new CultureInfo(request.International.Locale);
        }

        HelloWorldWithMessagesResponse response = 
            new HelloWorldWithMessagesResponse();

        response.Result = Messages.HelloWorld;
        return response;
    }
}

First of all, we have to verify that the “International” header came with the request message, otherwise, we will only receive an ugly “NullArgument” exception at the moment we use the header. Once we know that the header is there, we can use some of its properties, such as the Locale or Tz, to influence the locale settings in the service. In this sample, I am only changing the locale for the typed resource class, so it will try to load the proper resource file and return a “HelloWorld” message. Note: This code can generate an exception if the resource class is not able to find the file for the specified locale.

As I said before, using one of the WCF extensibility points is another way to include the header in the request messages to the service. Basically, WCF is divided into two layers, the lower-level channel layer that permits you to gain control over the messaging aspect of the applications, and the service layer that makes possible to build high-level applications without the need to deal with lower level aspects of the implementation. While we can develop extensions to plug our code in both layers, in this case, the service layer is usually the best option for simplicity sake. In the service layer, this can be done by means of Message Inspectors. As its name says, a Message Inspector is the mechanism provided by WCF to intercept and change SOAP messages. This is what we want to do in order to insert the “International” header in each message. The WCF application layer infrastructure provides two kinds of message inspectors: client message inspectors, which run on the client side, and service message inspectors, which do the same on the service side. For this reason, you will find two different interfaces, IClientMessageInspector for client inspectors, and IDispatchMessageInspector for service inspectors.

public interface IClientMessageInspector
{
    void AfterReceiveReply(ref Message reply, object correlationState);
    object BeforeSendRequest(ref Message request, IClientChannel channel);
}

The method names on this interface say everything: the BeforeSendRequest method is executed just before sending a request message to the service, and the AfterReceiveReply, just after receiving the response message from the service. Since WCF may run different instances of the same inspector before sending the message and after receiving it, in order to keep a state between both methods, the object correlation state is provided. The IDispatchMessageInspector interface is quite similar, and looks as follows:

public interface IDispatchMessageInspector
{
    object AfterReceiveRequest(ref Message request, IClientChannel channel, 
                               InstanceContext instanceContext);
    void BeforeSendReply(ref Message reply, object correlationState);
}

As part of our sample, we will have to implement both interfaces, a client inspector to add the custom header on the client side, and the service inspector to remove it on the service side.

First, we need to have our custom message inspector, which we will name InternationalizationMessageInspector, implementing the IClientMessageInspector and IDispatchMessageInspector interfaces. We will provide a constructor to specify the locale and time zone that can be included in the header.

public class InternationalizationMessageInspector : 
             IClientMessageInspector, IDispatchMessageInspector
{
    public InternationalizationMessageInspector(string locale, string timeZone)
    {
        this.locale = locale;
        this.timeZone = timeZone;
    }

Now, let’s turn to the rest of the implementation.

public object BeforeSendRequest(ref Message request, IClientChannel channel)
{
    International internationalHeader = new International();
            
    if(!String.IsNullOrEmpty(locale))
        internationalHeader.Locale = locale;

    if (!String.IsNullOrEmpty(timeZone))
        internationalHeader.Tz = timeZone;

    MessageHeader header = MessageHeader.CreateHeader(
                           WSI18N.ElementNames.International, 
                           WSI18N.NamespaceURI, internationalHeader);

    request.Headers.Add(header);
    return null;
}

The BeforeSendRequest implementation creates an instance of our “International” header class, and afterwards, it adds that instance to the Headers collection in the message received as a parameter in the method. On the other side, the message inspector should get the header from the message and process it.

public object AfterReceiveRequest(ref Message request, 
       IClientChannel channel, InstanceContext instanceContext)
{
    int index = request.Headers.FindHeader(
          WSI18N.ElementNames.International, WSI18N.NamespaceURI);

    request.Headers.UnderstoodHeaders.Add(request.Headers[index]);

    return null;
}

In this case, I only moved the header to the “UnderstoodHeaders” collection. This implicitly removes the header from the Headers collection, so if the header was marked as “MustUnderstand”, WCF does not throw an exception. There is no need to perform any additional process on the header. Finally, our service implementation must check whether the “International” header is in the “UnderstoodHeaders” collection or not, and execute some code after verifying that condition. The code I implemented to find the header in the service looks as follows:

public International GetHeaderFromIncomeMessage()
{
    MessageHeaders headers = 
      OperationContext.Current.IncomingMessageHeaders;

    foreach (MessageHeaderInfo uheader in headers.UnderstoodHeaders)
    {
          if (uheader.Name == “International” && uheader.Namespace == 
                                  “http://www.w3.org/2005/09/ws-i18n”)
        {
            International internationalHeader = 
              headers.GetHeader<International>(
              uheader.Name, uheader.Namespace);

            return internationalHeader;
        }
    }

    return null;
}

Then, I used the helper method to get the “International” header and set the resource manager with the locale preferences specified there.

[Microsoft.ServiceModel.Samples.InternationalizationAttribute()]
public string HelloWorld()
{
    International internationalHeader = 
       International.GetHeaderFromIncomeMessage();

    if (internationalHeader != null)
    {
        Messages.Culture = 
           new CultureInfo(internationalHeader.Locale);
    }
            
    return Messages.HelloWorld;
}

The service contract in this scenario is exactly the same as the one I used in the “Service Determined” pattern, no message contract or header definition is required. You probably noticed the existence of a “InternationalizationAttribute” definition just above the operation signature. That attribute is a IOperationBehavior implementation required to inject our message inspector at runtime in the message inspectors for the service. A IOperationBehavior is another extensibility point provided by WCF, it can be mainly used to customize the process of building a channel.

Collapse

public class InternationalizationAttribute : Attribute, IOperationBehavior
{
    private string locale;
    private string timeZone;

    public string Locale
    {
        get { return locale; }
        set { locale = value; }
    }

    public string TimeZone
    {
        get { return timeZone; }
        set { timeZone = value; }
    }

    public void ApplyClientBehavior(OperationDescription 
           operationDescription, ClientOperation clientOperation)
    {
        clientOperation.Parent.MessageInspectors.Add(new 
          InternationalizationMessageInspector(locale, timeZone)); 
    }

    public void ApplyDispatchBehavior(OperationDescription 
           operationDescription, DispatchOperation dispatchOperation)
    {
        dispatchOperation.Parent.MessageInspectors.Add(new 
                  InternationalizationMessageInspector()); 
    }
}

The “ApplyClientBehavior” and “ApplyDispatchBehavior” methods modify the client and service channels to include our MessageInspector implementation.

Conclusion

In this article, we saw three different patterns that can be applied in the design or development of a WCF service. In order to know which of these patterns is best for your service, you need to know whether the service is locale neutral or not, and the requirements for the client applications (the service consumers). We also discussed a concrete implementation of the WS-I18N specification using some of the extensibility points provided by WCF.

History

Uses the initial version for the WCF September RC release.

About Pablo Cibraro

Introduction

WCF (Windows Communication Foundation) is a great framework for developing service oriented applications. This article explains the steps needed to use a WCF service from a client application.

Background

The best starter guide for WCF I could find was this. It guides you step-by-step to create a WCF service and a client application. However, the steps needed to create the client application and call the methods exposed by the service did not sound so handy. The article says that before the client application can use the service, we should run svcutil.exe to generate the proxy classes. These proxy classes are then used to access the methods exposed by the service.

There must be a better option. This article explains how to add a Web Reference to a WCF service in a client application.

Using the code

Create a WCF service as per the steps explained in the Hello World sample. If you do not want to create the service from scratch, you can download the WCF Service Source.zip attached with this article.

Once you have the service ready, compile and run it. You will see the console window open up. At this stage, the service is ready, and client applications can call methods exposed by the service.

Most of you who have worked with .NET web services would certainly agree with me that Web References are the easiest way to invoke a web service. I was trying to do the same with the WCF service. However, I saw that the Service Discovery Operation failed to recognize the service because Metadata Publishing is not enabled.

The following configuration settings show how to enable Metadata Publishing on a WCF service:

<?xml version="1.0" encoding="utf-8" ?> 
<configuration>
 <system.serviceModel> 
  <services>
   <service name="HelloService.HelloService" 
       behaviorConfiguration="HelloService.HelloService" />
  </services>
  <behaviors>
   <serviceBehaviors>
    <behavior name="HelloService.HelloService" >
     <serviceMetadata httpGetEnabled="true" />
    </behavior>
   </serviceBehaviors>
  </behaviors>
 </system.serviceModel>
</configuration>

The above configuration settings will enable Metadata Publishing on the service.

Now, let us create a client application which accesses the HelloService. Either create an application from scratch, or you could use the WCF Client Source.zip attached with this article.

Follow the steps below to create a client application:

1. Create a VB.NET Console Application (or C# if you prefer it).
2. Add a Web Reference to the service with the following URL: http://localhost/hello (or the correct URL if you have modified the default service location).

The following code shows how to access the WCF service exposed by the server:

Dim o As New HelloService.HelloService
System.Console.WriteLine("Response from WCF Service: {0}", o.sayHi())

Points of Interest

The example above shows how easy it is to access a WCF service. The client application can simply add a Web Reference to the service, and can use it just like any one would do with an ASP.NET web service.

jacob.sebastian

Introduction

The reason for publishing this article is that I think that a lot of people are going to use the new .NET 3.0 WCF. It is simple to use, and seems very powerful. I have spend a lot of time debugging this program, and I hope that this article will prevent other people from getting the same headache that I had because of a funny security exception that I would get all the time. Use the code directly or as an inspiration. I assume that the reader is familiar with client/server coding, and will therefore not get into details. It is said that WCF is very dynamic regarding the transfer methods, and can be configured to use almost any communication standard which makes it suitable for many client/server applications. It does not matter if you use HTTP, TCP etc., to transfer data, and the optional SSL / Encryption makes the WCF even more suited for large scale solutions.

Background

The project is straightforward, really. The source contains some files that I used to develop the application. The source contains the ServiceLibrary that is the contract compiled into a simple DLL. Don't confuse the difference between the contract and the proxy. The contract is a sort of a way to communicate, and the proxy is a way to get access to another remote contract. The other two libraries are almost self-explaining, the WCFClient and the WCFService. The goal was to create a dynamic client server solution that is not bound by configuration files etc., but is more dynamic. Plus don't underestimate the fun writing the code :) Thanks to Gedebuk, Denmark.

The Proxy.cs code is auto-generated by svcutil.exe. If you need to re-create the Proxy.cs, start the service and run the command: "C:\Program Files\Microsoft SDKs\Windows\v6.0\Bin\svcutil.exe" http://localhost:8001/MyService /out:Proxy.cs.

Using the code

The code consists of two folders that are loaded into one project file.

How did I create the project?

1) Creating the ServiceLibrary.cs

I created the project by starting off with the ServiceLibrary. This library is compiled into a DLL which is used on the client (or clients for that matter). In WCF terms, this is the contract that the client must obey in order to be able to communicate with the server. This contract is in fact an interface that the client(s) communicates through. The ServiceLibrary contains all the methods that can be called by the client. In this example, it also holds the implementation for the service. The DataContract has the mark [DataContract] that indicates that it's an object that can be transferred. In WCF, it does not matter if it is a simple type, like a string, or a complex type like an object that is transferred over the wire. Below is a copy/paste from my contract.

Collapse

using System;
using System.Collections.Generic;
using System.Text;
using System.ServiceModel;
using System.Runtime.Serialization;

namespace ServiceLibrary
{
    // You have created a class library to// define and implement your WCF service.// You will need to add a reference to this// library from another project and add // the code to that project to host the// service as described below.  Another way// to create and host a WCF service is by// using the Add New Item, WCF Service // template within an existing project such// as a Console Application or a Windows // Application.

    [ServiceContract()]
    publicinterface IService1
    {
        [OperationContract]
        string MyOperation1(string myValue);
        [OperationContract]
        string MyOperation2(DataContract1 dataContractValue);
        [OperationContract]
        string HelloWorld(string str);
    }

    publicclass service1 : IService1
    {
        publicstring MyOperation1(string myValue)
        {
            return"Hello: " + myValue;
        }
        publicstring MyOperation2(DataContract1 dataContractValue)
        {
            return"Hello: " + dataContractValue.FirstName;
        }
        publicstring HelloWorld(string str)
        {
            return"Helloworld from " + str;
        }
    }

    [DataContract]
    publicclass DataContract1
    {
        string firstName;
        string lastName;

        [DataMember]
        publicstring FirstName
        {
            get { return firstName; }
            set { firstName = value; }
        }
        [DataMember]
        publicstring LastName
        {
            get { return lastName; }
            set { lastName = value; }
        }
    }
}

The code is something that the Visual Studio project generates for me. I've only added the HelloWorld part of this code. The VS environment did also generate a how-to on Adding a Service Reference. I've skipped that and deleted those parts. You can either configure the program from a configuration file that is a part of Visual Studio, or add the configuration in the code, or code the configuration. I have chosen to configure the service inside the code. One would argument about the ease of changing an XML file instead of recompiling the project if changes in the client/server relation occurs, but I have chosen to do this in order for the program to be able to configure itself in future implementations. This code will act as a core function in a rather large client/server solution where computers will contact other computers randomly via WCF. This requires the program to be able to change the runtime, and is the main reason for this code to be controlled in-code.

2) Creating the Service-Host Application

The service-host application is the program that holds the service that has the actual objects. This is the server if you like to call it that.

I created a Windows Forms project and added the following code:

Collapse

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
using System.Net;
using System.ServiceModel;
using System.ServiceModel.Description;

namespace WCFService
{
    public partial class MainForm : Form
    {
        private ServiceHost host = null;
        privatestring urlMeta, urlService = "";

        public MainForm()
        {
            InitializeComponent();
            Append("Program started ...");
        }

        void host_Opening(object sender, EventArgs e)
        {
            Append("Service opening ... Stand by");
        }

        privatevoid button1_Click(object sender, EventArgs e)
        {
            try
            {
                // Returns a list of ipaddress configuration
                IPHostEntry ips = Dns.GetHostEntry(Dns.GetHostName());

                // Select the first entry. I hope it's this maschines IP
                IPAddress _ipAddress = ips.AddressList[0];

                // Create the url that is needed to specify// where the service should be started
                urlService = "net.tcp://" + 
                    _ipAddress.ToString() + ":8000/MyService";

                // Instruct the ServiceHost that the type// that is used is a ServiceLibrary.service1
                host = new ServiceHost(typeof(ServiceLibrary.service1));
                host.Opening += new EventHandler(host_Opening);
                host.Opened += new EventHandler(host_Opened);
                host.Closing += new EventHandler(host_Closing);
                host.Closed += new EventHandler(host_Closed);

                // The binding is where we can choose what// transport layer we want to use. HTTP, TCP ect.
                NetTcpBinding tcpBinding = new NetTcpBinding();
                tcpBinding.TransactionFlow = false;
                tcpBinding.Security.Transport.ProtectionLevel = 
                   System.Net.Security.ProtectionLevel.EncryptAndSign;
                tcpBinding.Security.Transport.ClientCredentialType = 
                   TcpClientCredentialType.Windows;
                tcpBinding.Security.Mode = SecurityMode.None;
                // <- Very crucial// Add a endpoint
                host.AddServiceEndpoint(typeof(
                   ServiceLibrary.IService1), tcpBinding, urlService);

                // A channel to describe the service.// Used with the proxy scvutil.exe tool
                ServiceMetadataBehavior metadataBehavior;
                metadataBehavior = 
                  host.Description.Behaviors.Find<ServiceMetadataBehavior>();
                if (metadataBehavior == null)
                {
                    // This is how I create the proxy object// that is generated via the svcutil.exe tool
                    metadataBehavior = new ServiceMetadataBehavior();
                    metadataBehavior.HttpGetUrl = new Uri("http://" + 
                          _ipAddress.ToString() + ":8001/MyService");
                    metadataBehavior.HttpGetEnabled = true;
                    metadataBehavior.ToString();
                    host.Description.Behaviors.Add(metadataBehavior);
                    urlMeta = metadataBehavior.HttpGetUrl.ToString();
                }

                host.Open();
            }
            catch (Exception ex1)
            {
                Console.WriteLine(ex1.StackTrace);
            }
        }

        privatevoid button2_Click(object sender, EventArgs e)
        {
            host.Close();
        }

        void host_Closed(object sender, EventArgs e)
        {
            Append("Service closed");
        }

        void host_Closing(object sender, EventArgs e)
        {
            Append("Service closing ... stand by");
        }

        void host_Opened(object sender, EventArgs e)
        {
            Append("Service opened.");
            Append("Service URL:\t" + urlService);
            Append("Meta URL:\t" + urlMeta + " (Not that relevant)");
            Append("Waiting for clients...");
        }

        privatevoid Append(string str)
        {
            textBox1.AppendText("\r\n" + str);
        }
    }
}

The interesting part is of course the button1_Click which creates the service and makes the service public to other clients. Now for other clients to connect to this service, the service needs a contract. The contract is not something that one would write themselves, and that's why I use the scvutil.exe tool. On my PC, the tool is located at C:\Program Files\Microsoft SDKs\Windows\v6.0\Bin\svcutil.exe. In order to make the contract object (that is actually the proxy that clients connect to), we need to generate Proxy.cs (the name of the file is not relevant at all, could be foo.cs as well). This will happen in step 3.

3) Building the Proxy Object for Clients to Use

The proxy object is built from the service description that is located on port 8001 (check the code). It reads the meta data from the service, and constructs the contract that is needed by clients when they want to communicate with the service.

1. First, start the service and hit the "Start service" button. This creates the service. All meta info is published for other clients or tools to read them.
2. Second, run "C:\Program Files\Microsoft SDKs\Windows\v6.0\Bin\svcutil.exe" http://localhost:8001/MyService /out:Proxy.cs. This creates two files. A Proxy.cs file and an XML config file. I discard the config file because I'll configure the service inside the program. You should consider putting the "C:\Program Files\Microsoft SDKs\Windows\v6.0\Bin\svcutil.exe" http://localhost:8001/MyService /out:Proxy.cs in a bat file to make it easier for yourself. I have included my bat file for you to see. It resides in the "ProxyGenerator" folder.
   
   Next, I create a simple client and add relevant code to it.

4) Creating a Client Application and Adding Relevant Code to it

Now, we create a simple standard client program as a Windows Forms apllication. Once the files are generated (Proxy.cs and output.config <- can be suppressed), I add the Proxy.cs to my client program which is called WCFClient. Now, the client knows the contract and is able to obey it in order to create a communication channel to the service. One could compile the Proxy.cs into a DLL and simply add the DLL to the client (a cleaner way to add something that is crucial as a communication contract or interface, I think). For demonstration, we leave the Proxy.cs as it is and add it to the client project. Next, and the last step: we need to add some simple client code in order to retrieve the service proxy object. My client code looks like this:

Collapse

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
using System.ServiceModel;

namespace WCFClient
{
    public partial class Form1 : Form
    {
        string endPointAddr = "";

        public Form1()
        {
            InitializeComponent();
        }

        privatevoid button1_Click(object sender, EventArgs e)
        {
            if (textBox1.Text != "")
            {
                endPointAddr = "net.tcp://" + textBox2.Text + 
                               ":8000/MyService";
                NetTcpBinding tcpBinding = new NetTcpBinding();
                tcpBinding.TransactionFlow = false;
                tcpBinding.Security.Transport.ProtectionLevel = 
                  System.Net.Security.ProtectionLevel.EncryptAndSign;
                tcpBinding.Security.Transport.ClientCredentialType = 
                  TcpClientCredentialType.Windows;
                tcpBinding.Security.Mode = SecurityMode.None;

                EndpointAddress endpointAddress = 
                   new EndpointAddress(endPointAddr);

                Append("Attempt to connect to: " + endPointAddr);

                IService1 proxy = 
                  ChannelFactory<IService1>.CreateChannel(
                  tcpBinding, endpointAddress);

                using (proxy as IDisposable)
                {
                    Append("Message from server: " + 
                      (proxy.HelloWorld(textBox1.Text) + 
                      " back to you :)"));
                }   
            }
        }

        privatevoid Append(string str)
        {
            textBox3.AppendText("\r\n" + str);

Points of Interest

Well, I really had a lot of fun working with the code and writing the article. The most impressive thing, in my opinion, is that the transport layer very easily can be modified to use HTTP instead of TCP. I did not point that out in the article but that's also something nice to have. Being able to switch the transport layer from TCP (Secure SSL) into HTTP with some simple code, that's amazing! I did have some problems, though. The tcpBinding.Security.Mode = SecurityMode.None; is very crucial on both sides. I'm not sure what it does, but it does not turn off the security completely as I have read in my references. There is still SSL encryption, but on a lower level. It is possible to add certificates to the connection, which also makes the connection more secure.

History

• December 13^th 2006 - Project completed.

Bo Hansen

In Part 1, we defined what a service is, and also created a simple WCF service and client to demonstrate the process of creating and consuming services under WCF. In this article, we'll start exploring some of the more advanced communication options available under WCF. All the source code for the examples presented are available in the download for Part 1.

An All-In-One Service

Let's continue by implementing an example where the service and the client both exist in the same process! Why would anyone want to do this? Well, I’ve needed it, for one. Suppose you have a module that contains several services. The services are actually DB servers that abstract and isolate access to the database. Well, one of the services might actually need the functionality that is provided by another service (in the process). Since they are all in the same housing, you could instantiate the required service (class) locally. But then, you would be accessing the service differently than other clients, and you would also be bypassing the isolation and other facilities that the ServiceHost provides. In any case, this is just another way of doing things when the requirements are right. In a subsequent section, we’ll actually be doing the opposite, where we are creating a singleton and want only one instance of the service class. The following source shows the changes necessary to modify the LocalTimeService example.

Collapse

namespace AllInOneTimeService
{
    class Client
    {
        public bool keepClocking = true;
        LocalTimeProxy proxy = null;
        public Client()
        {
            proxy = new LocalTimeProxy();
        }
        public void ClockingThread()
        {
            while (keepClocking)
            {
                Console.WriteLine(proxy.GetLocalTime());
                Thread.Sleep(1000);
            }
            proxy.Close();
        }
        static void Main(string[] args)
        {
            Uri baseAddress = new 
              Uri(ConfigurationManager.AppSettings["basePipeTimeService"]);
            ServiceHost serviceHost = new 
              ServiceHost(typeof(LocalTimeService), baseAddress);
            serviceHost.Open();
            //The service is open for business
            Console.WriteLine("Service is running...." + 
                              "press any key to terminate.");
            //Start a client thread
            Client client = new Client();
            Thread thread = new Thread(new 
                   ThreadStart(client.ClockingThread));
            thread.Start();

            Console.ReadKey();
            client.keepClocking = false;

            //wait 2 seconds
            Thread.Sleep(2000);
            //Close up shop
            serviceHost.Close();
        }
    }
}

After the service is started, we simply instantiate a client. Of course, this is just to demonstrate that the service can be accessed by internal and external sources. Normally, it would be one service accessing another service as a result of a client request. The only other change of note is that the config file needs to define both the service and the client endpoints. Go ahead and start this version of the service. Then, start several instances of the standalone clients. As you can see, the service can be accessed from different sources (internal and external), and they are all serviced by the same host.

Two Spigots for the Price of One

The LocalTimeService examples that we've been using only supports IPC (internal clients using named pipes). Let’s change that, and add support for TCP clients. The cool thing about this is that we won’t have to change much, it will mostly be only config file changes. The code below is the only change we need to make to the service code. We’re using the AllInOne version of the service so that you can see how we can support both types of transport at the same time. The internal client will use named pipes, while the external client will use TCP.

static void Main(string[] args)
{
    Uri baseAddress = new Uri(
      ConfigurationManager.AppSettings["baseTcpTimeService"]);
    ServiceHost serviceHost = new ServiceHost(
      typeof(LocalTimeService), baseAddress);
    baseAddress = new Uri(
      ConfigurationManager.AppSettings["basePipeTimeService"]);
    serviceHost.AddServiceEndpoint(typeof(ILocalTime), 
              new NetNamedPipeBinding(), baseAddress);
    serviceHost.Open();
    ...
}

First, we instantiate ServiceHost, and pass the name of the endpoint that we want it to support (TCP). Then, we programmatically add a second endpoint (named pipe). All the required information is in the config file, as shown below:

Collapse

<configuration>
  <appSettings>
    <add key="baseTcpTimeService" 
         value="net.tcp://localhost:9000/LocalTimeService" />
    <add key="basePipeTimeService" 
         value="net.pipe://localhost/LocalTimeService" />
  </appSettings>
  <system.serviceModel>
    <services>
      <service name="LocalTimeService">
        <endpoint 
           address="" 
           binding="netTcpBinding" 
           contract="ILocalTime" 
         />
      </service>
    </services>
    <client>
      <endpoint name ="LocalTimeService"
                address="net.pipe://localhost/LocalTimeService"
                binding="netNamedPipeBinding"
                contract="ILocalTime" />
    </client>
  </system.serviceModel>
</configuration>

The only change that’s required on the standalone client is in the config file, as shown next:

<configuration>
  <system.serviceModel>
    <client>
      <endpoint name ="LocalTimeService"
                address="net.tcp://localhost:9000/LocalTimeService"
                binding="netTcpBinding"
                contract="ILocalTime" />
    </client>

  </system.serviceModel>
</configuration>

As we did before, go ahead and start the service, and then start several stand-alone clients. No difference, except that the external clients are using TCP to communicate with the service, while the internal clients use named pipes. Isn't that cool?! But wait, there’s more.

The Lazy Client

Let’s now consider a different service. This is a service that monitors the temperature in a reactor. It is very important that changes in the reactor temperature be detected as quickly as possible. So, each client needs to check with the service at very short intervals of time. And what would that be? Once a second, ten times a second, a hundred times a second? Clearly, if the number of clients is large, there would be a lot of wasted traffic if the temperature is not changing frequently. Alternatively, suppose the client decides to check the temperature every 100 milliseconds, there is still the possibility that the temperature may have changed a few times (up and down) in that span of time. So, if the client needed to know each change of temperature, then it would have missed a few.

So a better (or ‘more gooder’, as a friend of mine prefers) solution would be to implement a Publish/Subscribe pattern. The service (sensor) would simply monitor the temperature, and if the change happens to be above a specified threshold, it would send out a message to any client that had requested to be notified. The clients would just have to subscribe to the service and then wait for any notifications. When the notifications come, each client would do whatever it needed to do according to its role: log, alarm, control, etc. Here’s the code for a temperature sensor service:

Collapse

				//The interface the service exposes
[ServiceContract(Session = true, 
   CallbackContract = typeof(ITempChangedHandler))]
public interface ITempChangedPub
{
    [OperationContract(IsInitiating = true)]
    void Subscribe();
    [OperationContract(IsTerminating = true)]
    void Unsubscribe();
}
//The interface that clients must implement...
public interface ITempChangedHandler
{
    [OperationContract(IsOneWay = true)]
    void TempChanged(int newTemp);
}

[ServiceBehavior(InstanceContextMode = InstanceContextMode.Single)]
public class TempSensor : ITempChangedPub
{
    //a list of who's interested
    ArrayList subscribers = new ArrayList();
    TempSimulator sim;  //our temperature simulator
    public TempSensor()
    {
        //Start simulating the temperature
        sim = new TempSimulator(this);
        Thread simThread = new Thread(new 
               ThreadStart(sim.SimThread));
        simThread.Start();
    }
    public void Subscribe()
    {
        subscribers.Add(
          OperationContext.Current.GetCallbackChannel<ITempChangedHandler>());
    }
    public void Unsubscribe()
    {
        ITempChangedHandler caller = 
          OperationContext.Current.GetCallbackChannel<ITempChangedHandler>();
        foreach (ITempChangedHandler h in subscribers)
            if (h == caller)
            {
                subscribers.Remove(h);
                break;
            }
    }
    public void PublishTempChanged(int temp)
    {
        foreach (ITempChangedHandler h in subscribers)
            h.TempChanged(temp);
    }
    public void StopSim()
    {
        sim.runSim = false;
        Thread.Sleep(1000);
    }
}

A few things to note on the above code. First, you’ll notice that the service class has been decorated with a ServiceBehavior attribute. There are several options for this attribute, but it essentially specifies how we want to control the ‘instancing behavior’ of the service. In this situation, we specify ‘Single’ since we want only one instance of the service. It has to stick around to be able to receive the subscription messages from the clients. The ServiceBehavior attribute has two additional parameters specified for it. First, the Session=true indicates that the service will create and maintain a session for each client. The lifetime of the session is defined by the IsInitiating/IsTerminating properties of the OperationContract attribute. So the session can be kinda controlled by the client. Let’s take another look at that.

Consider the interface defined below that might be used to control AGVs. Automated Guided Vehicles (AGVs) are essentially self guided forklifts. They have a laser system on board with which they can tell where they are within a physical environment. And then you can control them pretty much like you would control a remote control car.

[ServiceContract(Session=true)]
public interface IAGVControl
{
    [OperationContract(IsInitiating=true)]
    int AcquireVehicle();
    [OperationContract(IsTerminating=true)]
    void ReleaseVehicle();
    [OperationContract]
    void MoveTo(int location);
    [OperationContract]
    void Load();
    [OperationContract]
    void Unload();
}

A client would first make a call to AcquireVehicle to establish a session (as well as get a physical AGV to manipulate). Now, the client can perform any number of operations with the vehicle. Possession of the vehicle is essentially controlled through session management! Of course, we know that with great power comes great responsibility. Once the client calls ReleaseVehicle, there better not be any subsequent requests made.

One last point on the previous TempSensor code. You’ll notice that the OperationContract attribute for the callback TempChanged has the IsOneway property set to true. This property defines the requirement (or lack thereof) for a reply message. Even if the return value is void, there will still be a reply message generated if the IsOneway property is set to false (the default). Requiring a reply message provides a mechanism to return exceptions thrown by the service back to the client. Also note that if you set IsOneway to true and you do have a return value, you’ll get an exception.

Now, here’s the rest of the code for the temperature service:

static void Main(string[] args)
{
    //Now start hosting the service
    TempSensor sensor = new TempSensor();
    Uri baseAddress = new Uri(
      ConfigurationManager.AppSettings["basePipeTempService"]);
    ServiceHost serviceHost = new ServiceHost(sensor, baseAddress);
    serviceHost.Open();
    Console.WriteLine("Service is running...." + 
                 "press any key to terminate.");
    Console.ReadKey();
    
    sensor.StopSim();

    serviceHost.Close();
}

The only thing to note on the above is that we create the service class object and then pass a reference to it to ServiceHost.

So, the temperature service provides an interface that lets clients subscribe and unsubscribe to temperature changes. In this case, the service will send a message to each client that has subscribed, whenever the temperature changes more than 5 degrees. There is nothing special about the subscribe/unsubscribe interface, you could call it whatever you want (in fact, you’ll need a different name if there is more than one thing that clients can subscribe to), and you can pass in parameters. For example, you might allow each client to specify at what granularity or temperature level that it wants to be notified. Of course, the service has to do a little more work, in this case, to keep track of which client wants what.

You’ll also notice that there is a second interface defined. That is the interface that the clients have to implement in order to receive notifications from the service. When the proxy gets created for the client, a ‘callback’ interface will also be included in order for the clients to be able to know what they have to implement. Here’s the proxy class for the service.

Collapse

[ServiceContract(CallbackContract=typeof(
                 ITempChangedPubCallback), Session=true)]
public interface ITempChangedPub
{
    [OperationContract]
    void Subscribe();
    
    [OperationContract]
    void Unsubscribe();
}

public interface ITempChangedPubCallback
{
    [OperationContract]
    void TempChanged(int newTemp);
}

public interface ITempChangedPubChannel : ITempChangedPub, 
                       System.ServiceModel.IClientChannel
{
}

public partial class TempChangedPubProxy : 
       System.ServiceModel.DuplexClientBase<ITempChangedPub>, 
       ITempChangedPub
{
    public TempChangedPubProxy(
           System.ServiceModel.InstanceContext callbackInstance) : 
           base(callbackInstance)
    {
    }
    
    public void Subscribe()
    {
        base.InnerProxy.Subscribe();
    }
    
    public void Unsubscribe()
    {
        base.InnerProxy.Unsubscribe();
    }
}

The temperature service client, then, is just slightly more complicated than the client for the LocalTimeService. The TempChanged client needs to do two things. First, it has to instantiate a class that implements the ITempChangedPubCallback interface so that the service can send messages back to the client. And the other thing the client needs to do is provide some kind of hosting for the callback, similar to what the ServiceHost provides for the service. This is how the message can be detected and routed to the right place. The class that provides that functionality is the InstanceContext class (if you look at the class definition, you'll notice it has a host member). When we create the InstanceContext, we pass it the handler class that will service the temperature change messages (has implemented ItempChangedPubCallback).

class TempChangedHandler : ITempChangedPubCallback
{
    public void TempChanged(int temp)
    {
        Console.WriteLine(temp.ToString());
    }
}
static void Main(string[] args)
{
    InstanceContext siteTempChangedHandler = null;
    TempChangedPubProxy proxyTempChanged;

    siteTempChangedHandler = new InstanceContext(new TempChangedHandler());
    proxyTempChanged = new TempChangedPubProxy(siteTempChangedHandler);
    proxyTempChanged.Subscribe();

    Console.WriteLine("Client is running....press any key to terminate.");
    Console.ReadKey();
    
    proxyTempChanged.Unsubscribe();
}

That’s the extent of the code, except for the endpoint definition in the config file. Here, we need to indicate both the ‘client’ endpoint (the service we’re talking to) as well as an endpoint definition for the client's callback.

Collapse

<configuration>
  <appSettings>
    <add key="basePipeTempChangedHandler" 
       value="net.pipe://localhost/TempSensorHandler" />
  </appSettings>
  <system.serviceModel>
    <services>
      <service 
      name="TempSensorHandler">
        <!-- use base address provided by host -->
        <endpoint name="pipeEndpoint" address=""
                  binding="netNamedPipeBinding"
                  contract="ITempChangedPubCallback" />
      </service>
    </services>
    <client>
      <endpoint name ="TempChangedPub"
                address="net.pipe://localhost/TempSensor"
                binding="netNamedPipeBinding"
                contract="ITempChangedPub" />
    </client>
  </system.serviceModel>
</configuration>

Start the service, and then start an instance of the client to test out the code. I’m curious to see if the temperatures does manage to stay around 100 over time.

Asynchronicity

Sometimes, the functionality to be provided by a service is a long process, and the client cannot afford to wait for the response. Under those circumstances, there are two different approaches to providing asynchronous access to the service. The first one is based on the .NET Asynchronous pattern where the disconnection is provided by the client side infrastructure. The second method uses a Duplex Communication pattern where the client implements a callback interface. Let’s take a look at each approach.

Consider the AGV application described previously. AGVs are very slow vehicles relative to the processing time of the system. They travel at best about 1 foot/second. So, to travel 10 feet, it would take 10 seconds. And there’s speedup, slowdown, and turning delays that also have an effect on the total time. So when a client sends a MoveTo request, it will need to wait a while before it gets back a response that the operation completed.

There is nothing special that needs to be done on the service side for asynchronous clients. All of the functionality is provided on the client side. So we’ll start with a service that implements the IAGVControl interface described previously. Here's the code for a class we'll call AGVController.

[ServiceBehavior(InstanceContextMode=InstanceContextMode.PerSession)]
public class AGVControl : IAGVControl
{
    public int AcquireVehicle()
    {
        int vehicleID = 0;
        return vehicleID;
    }
    public void ReleaseVehicle()
    {
        //place vehicle back in the pool
    }
    public void MoveTo(int location)
    {
        //This takes a long time...
        Thread.Sleep(5000);
    }
    public void Load()
    {
        //load it
    }
    public void Unload()
    {
        //unload it
    }
}

As you can see, there is (literally) nothing here. Except that the MoveTo operation takes 5 seconds to complete. So, any method calling MoveTo won’t return right away. The instancing behavior for the class is specified as PerSession. That means, ServiceHost will create an instance of AGVControl for each client session. And the session lifetime was defined with the interface using the IsInitiating/IsTerminating attributes. Compile AGVControl into a service DLL so that we can generate a proxy using svcutil. We’ll describe the proxy generation when we build the asynchronous client.

As usual, we need to build a host for the service. There is nothing different from the previous examples, so here it is.

static void Main(string[] args)
{
    Uri baseAddress = 
        new Uri(ConfigurationManager.AppSettings["basePipeAGVCtlr"]);
    ServiceHost serviceHost = 
        new ServiceHost(typeof(AGVControl), baseAddress);
    serviceHost.Open();
    Console.WriteLine("Service is running....press any key to terminate.");
    Console.ReadKey();
    serviceHost.Close();
}

<configuration>
  <appSettings>
    <add key="basePipeAGVCtlr" value="net.pipe://localhost/AGVControl" />
  </appSettings>
  <system.serviceModel>
    <services>
      <service name="AGVController.AGVControl">
        <endpoint 
           address="" 
           binding="netNamedPipeBinding" 
           contract="AGVController.IAGVControl" 
         />
      </service>
    </services>
  </system.serviceModel>
</configuration>

Compile and start the service to make sure everything is OK. Now, let’s turn our attention towards the client where all the magic takes place. Once again, the first thing we need is a proxy in order for the client to be able to do anything.

One of the options for svcutil is to generate asynchronous methods to match the Asynchronous pattern. Essentially, this means generating two method signatures for each service method, one to begin the asynchronous operation and one to end. The other item that’s required for the Asynchronous pattern is a callback method that will be called when the asynchronous operation has completed. That’s when we get the results from the service operation.

So, execute svcutil against the AGVControl service DLL that we created above. This will generate the ‘xsd’ and ‘wsdl’ files, as we have seen previously. Then, re-run svcutil, but this time, specify the *.xsd and *.wsdl files that were just created, and also include the ‘/a’ option. Svcutil will generate a proxy, with asynchronous signatures for each method that the service exposes.

Since svcutil is really just a little helper utility, I decided to do some editing on the resulting file. I know that the only method that takes a long time is the MoveTo method (I know that because I coded the delay). So, I only want to implement that one as an asynchronous operation, all others are to remain as synchronous calls. Here’s the edited version of the proxy:

Collapse

[ServiceContract]
public interface IAGVControl
{
    [OperationContract]
    int AcquireVehicle();
    [OperationContract]
    void Load();

    [OperationContract(AsyncPattern = true)]
    System.IAsyncResult BeginMoveTo(int location, 
           System.AsyncCallback callback, object asyncState);
     void EndMoveTo(System.IAsyncResult result);
 
    [OperationContract]
    void ReleaseVehicle();
    [OperationContract]
    void Unload();
}

public interface IAGVControlChannel : 
       IAGVControl, System.ServiceModel.IClientChannel
{
}

public partial class AGVControlProxy : 
       System.ServiceModel.ClientBase<IAGVControl>, 
       IAGVControl
{
    public AGVControlProxy()
    {
    }
    public int AcquireVehicle()
    {
        return base.InnerProxy.AcquireVehicle();
    }
    public void Load()
    {
        base.InnerProxy.Load();
    }
    public System.IAsyncResult BeginMoveTo(int location, 
           System.AsyncCallback callback, object asyncState)
    {
        return base.InnerProxy.BeginMoveTo(location, 
                               callback, asyncState);
    }
    public void EndMoveTo(System.IAsyncResult result)
    {
        base.InnerProxy.EndMoveTo(result);
    }
    public void ReleaseVehicle()
    {
        base.InnerProxy.ReleaseVehicle();
    }
    public void Unload()
    {
        base.InnerProxy.Unload();
    }
}

You’ll notice that the MoveTo operation has been replaced with two methods, BeginMoveTo and EndMoveTo. There are also a couple of extra parameters that were added to the BeginMoveTo method (in addition to the location parameter that was defined for MoveTo). Those are required in order to support the Asynchronous pattern. The first parameter is a callback delegate where we will specify what method needs to be called when the operation completes. The second parameter is a state parameter, and it’s usual to pass the proxy object so that the end operation can be called.

OkeeDokee, we are ready to build a client that will exercise the AGVControl service. This time, we’ll build a Windows Forms client, to make the UI more conducive to what we want. The figure below shows the sample application that is included in the download. We are using the shell application, simply to demonstrate the asynchronous operation, so there's not much code included.

All that we want to show here is that the MoveTo operation is indeed disconnected from the actual processing that is taking place at the service. To demonstrate that, the client code creates a separate thread that will update the status bar while the service is doing its thing and we are waiting for a reply (complete source is in the download for Part 1).

Collapse

public partial class Form1 : Form
{
    AGVControlProxy proxy = null;
    bool gotVehicle = false;
    bool gotResponse = false;
    ...
    private void btnMoveTo_Click(object sender, EventArgs e)
    {
        if (txtPosition.Text.Length > 0)
        {
            int position = System.Convert.ToInt32(txtPosition.Text);
            proxy.BeginMoveTo(position, MoveCallback, proxy);
            //Start a thread to display activity
            gotResponse = false;
            Thread thread = new Thread(new ThreadStart(WaitingThread));
            thread.Start();
        }
    }
    private void MoveCallback(IAsyncResult ar)
    {
        ((AGVControlProxy)ar.AsyncState).EndMoveTo(ar);
        gotResponse = true;
    }
    private void WaitingThread()
    {
        int waitCount = 1;
        while (gotResponse == false)
        {
            toolStripStatusLabel1.Text = 
                "Waiting..." + waitCount.ToString();
            waitCount++;
            Thread.Sleep(100);
        }
        toolStripStatusLabel1.Text = "Got response";
    }
    ...
}

Compile the client, and make sure you’ve got the service app running. Depress the Acquire button, and then the MoveTo button. You’ll see the status bar being updated until a response is received from the service. The callback method is what controls the termination of the thread so you also know when that occurred.

That's it for now. In Part 3 (the last one!), we'll complete the asynchronous examples by implementing the same functionality as above but utilizing a Duplex communication pattern. We will also look at the fourth transport type, message-queueing, and where that may be used.

Al Alberto

In Part 1 we defined what a service was and also created a simple WCF service and client to demonstrate the process of creating and consuming services under WCF. Part 2 continued with some examples of the various communication patterns that can be easily implemented with WCF. In this article we'll continue by completing the examination of asynchronous communication and then examine the fourth transport supported under WCF, message queue. Note that all the source code for the examples presented are available in the download for Part 1.

July CTP Update

I recently had the opportunity to install the July CTP. I compiled the sample source to see if there were any surprises. It seems that svcutil has had a few changes. And there were some naming changes that will generate some syntax errors if you compile the sample source as is. You should be able to easily identify and fix them, IntelliSense works so much better these days.

Asynchronicity Part du

So, in the last article we developed an example of asynchronous communication based on the .Net Asynch pattern. That functionality was provided entirely on the client and mostly implemented by the .Net infrastructure. Now we'll provide the same functionality (asynchronous communication) but this time we’ll use a Duplex Communication pattern. In this case both the client and the service share in the work. The mechanics are essentially the same as we saw for the Publish/Subscribe except that here there is a 1:1 correlation between the request and the response. Whereas for the Publish/Subscribe pattern, one request (subscription) resulted in many responses (publications). And for Publish/Subscribe there can be any number of clients subscribing to one publication. But in both cases the request is disconnected from the response. Just to be clear, the request is a message and the response is a separate message. Each one though follows a request/reply pattern based on the IsOneWay property setting. Does that make it less clear? Well, I better leave it at that.

For Duplex Communication the client makes a request of the service. The service will then, at some future time send a message back to the client with the results. The service also specifies what the client needs to ‘implement’ by providing a callback interface definition. And in processing the response, the  client behaves almost like a service. Let’s begin by defining a new version of the AGVController (call it AGVControllerD) that supports duplex communication so we can examine each of those points. Here is the revised service code.

[ServiceContract(Session = true, CallbackContract = typeof(IMoveToCallback))]
public interface IAGVControl
{
    ...
}
//What the client needs to implement
public interface IMoveToCallback
{
    [OperationContract(IsOneWay = true)]
    void MoveDone(int location);
}

[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerSession)]
public class AGVControl : IAGVControl
{
    private IMoveToCallback callback = null;
    public AGVControl()
    {
        callback = OperationContext.Current.GetCallbackChannel();
    }
    ...
    public void MoveTo(int location)
    {
        //This takes a long time...
        Thread.Sleep(5000);
        //Send a response
        callback.MoveDone(location);
    }
    ...
}

First thing you’ll notice is that the ServiceContract now specifies a callback interface. The service needs this in order to know what to call. Next is the actual definition of the callback interface that the client has to implement. Since we already know what to call we just need to know who to call. And that is the purpose of the statement in the constructor. Each instance of the service object (we've specified an instancing of per session so ServiceHost will create an instance of the service class for each client session) remembers whom it is communicating with. This is important because the client assumes that the service is maintaining some state (a vehicle) in between method calls. Then when the appropriate time comes the service can make a call back to the client.

One thing to note is that the callback interface is not limited to a single method. We have the same flexibility here as we had with the asynchronous client when we edited the proxy class. There we just implemented a Begin/End pair for one method. In this example we could define any or all of the service methods to also have a callback methods. To compare the two asynchronous examples in the same light, we are only defining a callback for the MoveTo operation. But we could certainly have defined a callback method for each of the service methods.

Compile the service dll and then run the svcutil against it to generate the proxy class. This time we don’t specify the ‘/a’ option. The host is the same as before. All that you’ll have to do is change references to AGVController with AGVControllerD (likewise the namespace in the config file).

Now let’s build the Duplex client. The main difference here is that we need to provide a class that implements the callback interface so that the service can talk back to us. The svcutil automatically includes the definition of the callback interface as part of the proxy. Just as we saw in the Publish/Subscribe example we need some kind of hosting on the client side in order for us to be able to receive the messages from the service. And that functionality is provided by the InstanceContext class just as before. Here is the code specific to the duplex client, everything else is the same as was for the asynchronous client.

public partial class Form1 : Form
{
    AGVControlProxy proxy = null;
    InstanceContext siteAGV = null;
    bool gotVehicle = false;
    public bool gotResponse = false;
    ...
    private void Form1_Load(object sender, EventArgs e)
    {
        siteAGV = new InstanceContext(new MoveCallbackHandler(this));
        proxy = new AGVControlProxy(siteAGV);
    }
    ...
}
public class MoveCallbackHandler : IAGVControlCallback
{
    Form1 parent;
    public MoveCallbackHandler(Form1 parent)
    {
        this.parent = parent;
    }
    public void MoveDone(int location)
    {
        parent.gotResponse = true;
    }
}

If you run this version of the client (make sure the service is running) you should see the same results for both implementations. So if the service provides for asynchronous communication great, but even if it doesn't you can still implement it on the client with just a slight amount of code and revising the proxy accordingly. One more thing, if the requirements are right you could provide both forms of communication on the service and let the client choose.

Queuing it

The fourth communication transport mechanism supported by WCF is the message queue (to be fair, some of the literature describes peer-to-peer communication as another transport type). Message queues are not something new to WCF. It has been a part of Windows but was not available on all versions, which I thought was a bad thing. I think the message queue is an excellent communication mechanism for the right applications. When would you use a message queue? When you need it! A typical situation is for applications that may not have access to the service at all times. They may at times be disconnected.

Another application might be a producer/consumer pattern where each may have different processing speeds. That is, suppose there are a number of data producers and each produces data in irregular cycles. It is possible for all of them to happen to send their data at the same time, which could overwhelm the consumer. So by using a message queue we are essentially spreading out the processing of the data over time. A typical example of this might be a voting application. The vote data might come in spurts because you can’t control when people will cast their vote. In other words the producers can do whatever/whenever they want, the consumer will never be overwhelmed (it will just take longer).

Another important use of a message queue is to tie two disparate systems together. Two applications might be separated not only in time and space but also in platform and language and they can still talk to each other using a message queue. You might be thinking “that’s what a service provides”. But remember that on the other side of the queue there doesn’t have to be a service. Needless to say, the usage of a queue should match the application requirements pretty closely.

To finish up the WCF journey let’s take a look at an implementation of a message queue. The application is an operator console utility that displays the state of various modules that might make up a system. The figure below represents a material handling system that has some robots, AGVs, conveyors, etc. Each of the modules in the system sends their state information to a central monitor application so that the operator can see at any time what each module is doing. Or if something failed s/he can see what immediately preceded the failure. The client modules themselves might be running at different locations and could have been implemented in different languages.

Each module is actually sending its state information to a queue and the monitor service processes the messages that are in the queue. As you’ll see, the client code does not provide any indication that the message is actually going to a queue. At the risk of overstating it...to me that is the beauty of WCF. Additionally, since the use of a message queue is simply defined as the endpoint, at some future time the system could be changed so that it did not use a queue but made direct calls to a service and the client code would not change at all. All that would need to change would be the configuration files to specify a different endpoint.

So a message queue behaves like Email, somebody sends you a message and it’s held somewhere until you go get it. Previously, if you implemented a message queue you had two choices in how you processed the messages. You could set up an event handler and the system would call your delegate any time there was a message in the queue or you could poll the message queue if you were looking for a specific message type. Under WCF using a message queue is completely transparent. Because outside of setting up the actual queue, there is no syntactical difference from the other transport types. On the client side you just make a method call as always. And on the service side you define an interface and a class that implements the interface just as you would for any of the other transport types. The only difference between this transport and the others is that a message queue has to exist in order to use it. OK, lets look at some of the code.

The QState Monitor is an MDI app that creates a window for each module that sends it a message. Any subsequent messages that are received from the same module will be displayed in the same window. The message is just two strings, one is the name of the module and the second string is the state information to be displayed. The download contains all of the code so we’ll just look at the WCF side of things. First let’s define the service.

[ServiceContract]
public interface IQSMonitor
{
    [OperationContract(IsOneWay = true)]
    void ModState(string strMod, string strState);
}

[ServiceBehavior(InstanceContextMode = InstanceContextMode.Single)]
public class QSMonitor : IQSMonitor
{
    QStateWnd parent = null;
    public QSMonitor(QStateWnd parent)
    {
        this.parent = parent;
    }
    public void ModState(string strMod, string strState)
    {
        parent.ProcessMessage(strMod, strState);
    }
}

As you can see there is nothing in the code that indicates that a message queue is being used. The actual message queue can be created programmatically or manually using the Computer Management Console (in Administrative Tools). If you create the queue manually then you can change the transport without affecting the code at all. Here’s the code for starting up the service.

...
ServiceHost host = null;
QSMonitor handler;

public QStateWnd()
{
//          To create the queue programmatically uncomment these lines.//          string queueName = ConfigurationManager.AppSettings["queueName"];//          if (!MessageQueue.Exists(queueName))//              MessageQueue.Create(queueName, false);

    handler = new QSMonitor(this);

    // Get base address for Msmq
    string baseAddress = ConfigurationManager.AppSettings["baseAddress"];
    host = new ServiceHost(handler, new Uri(baseAddress));
    // Open the ServiceHostBase to create listeners and start listening for // messages.
    host.Open();
    ...
}

There is nothing different here than the code required for the other transports that we used previously. The handler is the service class. We pass the handler a reference to the main window (QStateWnd) so that it can tell the main window when messages are received. The functionality to be performed for each message is actually defined in the QStateWnd class which is to display the message. Finally we just have to create a ServiceHost to host the service just as before.

The rest of the code is concerned with the mechanics of the application and is pretty straightforward. When the service class receives a message it just passes it to the main window, MDI frame. MDI frame classes maintain a list of the child windows that they own. We use that facility to keep track of what modules have already sent messages. Essentially we just iterate through the list of child windows and check their title bar text. When an MDI child window is created we assign the module name to the window title. This way we can match up the module that sent the message to a specific window.

That’s it, we create a new child window if the module name does not exist on any current window and if there already is an existing window we just add the state information to the window.

Finally here’s what the config file looks like when using a message queue.

Collapse

<configuration>
  <appSettings>
    <!-- use appSetting to configure MSMQ queue name -->
    <add key="queueName" value=".\private$\QSMonitor" />
    <add key ="baseAddress" value="net.msmq://localhost/private/QSMonitor"/>
  </appSettings>

  <system.serviceModel>
    <services>
      <service 
          name="QSMonitor">
        <!-- Define NetMsmqEndpoint -->
        <endpoint address="net.msmq://localhost/private/QSMonitor"
                   binding="netMsmqBinding"
                   bindingConfiguration="Binding1" 
                  contract="IQSMonitor" />
      </service>
    </services>

    <bindings>
      <netMsmqBinding>
        <binding name="Binding1" exactlyOnce="false">
          <security mode="None" >
          </security>
        </binding>
      </netMsmqBinding>
    </bindings>
  </system.serviceModel>
</configuration>

A couple of comments on the config file above because it’s pretty powerful stuff. I have not mentioned the binding classes much because there is just so much stuff there and the default classes provided by WCF have been sufficient. But you can create your own custom binding as well as customize the default binding classes to suit your requirement. Providing that capability programmatically is a very flexible feature but not surprising. What is really neat is that you have the same capabilities when using the configuration file route. In the above file we specified that we wanted to use the default netMsmqBinding binding. You’ll notice that there is an additional bindings section also in the file and that there is an additional property in the endpoint definition labeled-bindingConfiguration. What is happening here is that we are saying ‘use the default netMsmqBinding binding but with the following changes’. So if some of the default options of a particular binding are not suitable you can modify it from the configuration file! Why is this so amazing to me? It could be that I'm amazed by simple things or it could be that this gives us just a little more flexibility in our solution. If we can change something without having to re-compile, that's convenient. If it's already deployed, it's a life saver. And finally, there's a lot of functionality behind these options that we did not have to write a single line of code.

So why didI need to revise the default behavior? Well it wasn’t working. I tried a couple of options and then did some searching on the Net. It turns out that security is turned on by default for this binding. Security was not a requirement for me at that point (I’m sure I’ll have to cross that bridge soon enough). In any case all I had to do was to override the default settings to turn security off. That’s how we learn things most of times isn’t it? Through mistakes that lead to discoveries.

Anyway back to the current example. On the client side all that is needed is a simple proxy and the appropriate entries in the config file. Since we don’t have a service dll and since our service does not have a MEX endpoint, our only option is to roll our own proxy by hand. By the way, you can even create your proxies dynamically by using the ChannelFactory class. Generally there’s more than one way to do something in WCF. How’s that for flexibility?

A quick side note. If you do edit the proxies make sure that your parameter names match up on both sides. Parameters are identified by name, so if there is just the smallest typo, you’ll spend some time looking for why messages are not being processed. Even though they are being sent correctly and there are no exceptions. A free debugging option when using a message queue is the message queue itself! You can examine your messages in the message queue, if the service is not running. For the other transports you need some other utilities to be able to see the messages as they are crossing the wire.

Here’s the proxy and config file that the clients will need. There is a sample client in the download source.

[ServiceContract]
public interface IQSMonitor
{
[OperationContract(IsOneWay = true)]
void ModState(string strMod, string strState);
}
public interface IQSMonitorChannel : IQSMonitor, 
                                     System.ServiceModel.IClientChannel
{
}
public partial class QSMonitorProxy : System.ServiceModel.ClientBase, 
                                      IQSMonitor
{
    public QSMonitorProxy()
    {
    }
    public void ModState(string strMod, string strState)
    {
        base.InnerProxy.ModState(strMod, strState);
    }
}

<configuration>
  <system.serviceModel>
    <client>
      <endpoint name=""
                address="net.msmq://localhost/private/QSMonitor" 
                  binding="netMsmqBinding" 
                  bindingConfiguration="Binding1" 
                contract="IQSMonitor" />
    </client>
    <bindings>
      <netMsmqBinding>
        <binding name="Binding1" exactlyOnce="false">
          <security mode="None">
          </security>
        </binding>
      </netMsmqBinding>
    </bindings>
  </SYSTEM.SERVICEMODEL>
</configuration>

If you feel like experimenting, make the following change to the config file for both the service and the client.

    <add key ="baseAddress" value="net.pipe://localhost/QSMonitor"/>
    ...
    <endpoint address="net.pipe://localhost/QSMonitor"
               binding="netNamedPipeBinding"
              contract="IQSMonitor" />
    ...

Re-start the service and the client. You should see no difference in the results but what is happening under the cover changed quite a bit.

Heigh-Ho Silver Away!

There you have it, just enough knowledge on WCF to make you slightly dangerous. There's lots more to explore, there's the security side of communication, all the binding options, peer-to-peer and broadcast messages, and maybe even defining custom transports. You never know when that special requirement comes up that just does not fit the mold. So until next time Kemo Sabe...

Al Alberto

Introduction

I’m impressed! And that’s not an easy thing to do. I’ve been playing with the CTP (February 2006) release for a while now, and believe it or not, I think we may actually have something here. I have not had the time to explore the other ‘Foundation’ members (of WinFX), but from what I’ve seen of the Windows Communication Foundation (WCF), it really is a very nice package. Yes, I know that each time there is a new technology released, there is always some neat features. But in the past, I always thought that we were paying more (in complexity) than what we were getting (in functionality), can you spell COM? This time, it feels like we are getting the whole thing for free. It’s possible that it may be just my naïve perspective, but hey it’s all about me anyway.

I like to preface my articles with a disclaimer. The content in this article is simply my impressions and interpretation, and it should be read in that context. Even though the prose may at times seem like I know what I’m talking about, any similarity to actual facts may simply be coincidence. Enjoy the journey.

Why can’t we just talk?

The minute we stepped out of the DOS box, we realized that we were not alone any more, and we needed to learn to get along and communicate with the other inhabitants of the virtual world. DDE, OLE, COM, DCOM, and Remoting have been some of the attempts at providing mechanisms for two applications to be able to talk to each other. Remember how OLE and COM were described when first introduced? As the ‘foundation for all future products’. With hindsight, we can see that they were really just baby steps. Each one solved only a small part of the whole problem. So if they were baby steps, then WCF is certainly a giant leap. WCF provides a complete solution to the communication problem. And it does it with elegance and simplicity. Can you tell that I’m just a little enthusiastic?

Whether your requirement is to communicate with another module on the same machine, or another module implemented in a different language, or you need to communicate with a module that’s on a machine on the other side of the world, or you want to communicate with a module running on a different platform, or even communicate with a module that’s not even running!, yup, you can do it under WCF.

In my opinion, the beauty of WCF is that it is an ‘all-inclusive’ solution. It is the first one to provide a complete end-to-end solution covering the scope and depth of the problem. It is also the simplest from a programmer's point of view; you are always just making a method call. Yeah, I am sure that there is quite a bit of magic going on under the covers to support that simplicity of use.

Now, I have not explored every nook and cranny, or option, or possibility, but from what I’ve seen, it’s an excellent solution. At least for me, and as I said before…

What is a service?

Let’s see how much trouble I can get myself into here. I think that, in its most elemental form, a service is simply some functionality (code) running in some external process that is made available to other processes in a standard way. That’s pretty much the crux of it, except that in a standard way also encompasses platform and language neutrality.

So, by the above definition, a service really has two parts. First is the code that must be running somewhere in order to provide some functionality to clients. And second, there must be some generic mechanism that can be used by any process, regardless of the platform, language, or locality, that makes the service accessible. That generic mechanism has turned out to be XML and SOAP. Of course, there are some additional facilities required in order for a client to be able to know (or discover) what functionality the service makes available. But I think of those as supporting technologies.

There is also some glue that is required in order to tie the two parts of a service together. That glue is the code that will support the communication medium (transport) that is being used by the service and the client to talk to each other. Being lazy…I mean smart, we’ve come up with some generic glue also. This way, each service implementation does not have to re-invent the wheel. For Web Services, the generic glue is a Web Server. So, a Web Server provides a hosting environment for services that use HTTP as their transport mechanism. I would also like to suggest that Web Services are a special implementation of a service as defined above.

Here are the things that we will be examining in the rest of this article. How do you define a service? How do you implement a service? How do you host a service? How do you access and use a service? Once we have the basics nailed down, we’ll look at some of the more complex communication options that WCF facilitates.

So what is WCF?

Here is what WCF is for me:

WCF is an inter-application communication platform. It provides a common API that hides the underlying communication medium. It can be platform neutral, and it provides for locality indifference. Essentially, under WCF, I, as a programmer, do not need to know or care where the other end is or how the actual communication is taking place. To me, that is beautiful!

WCF is services based technology. It has, as its roots, Web Services, and thus XML and SOAP are its core technologies. WCF took the concept of Web Services and super-charged it. Much of the look and feel of WCF behaves like traditional Web Services. In fact, I like to think of WCF services as Web Services on steroids. You define WCF services much like Web Services. You can interrogate a known service for its methods with the same protocols that are available for Web Services. And you have very similar infrastructure requirements as are for Web Services. The main difference is that WCF has expanded the transports that are available to include TCP/IP, IPC (named pipes), and message queue-ing, in addition to HTTP. I think the focus of Web Services is to solve the interoperability problem, and the focus of WCF is to solve the much broader communication problem. And it has done this while still maintaining a uniform API as well providing more efficient mechanisms.

The most important feature from a developer perspective is that you don’t have to be concerned with what or how you are communicating. The code is the same, no matter what the final transport mechanism or locality of service might be.

Service Contracts-exposing functionality

Our WCF journey starts with how services define the functionality that they expose. Much of the infrastructure required to implement services under WCF is specified using declarative programming. That means, using attributes to specify functionality. The following shows how to declare an interface that will be exposed as a service:

[ServiceContract]
public interface ILocalTime
{
    [OperationContract]
    string GetLocalTime();
}

public class LocalTimeService : ILocalTime
{
    ...
}

The ServiceContract attribute specifies that the interface defines the functionality of a service. OperationContract is used to decorate each method that is to be exposed as part of the service. That is all that is required to create a WCF service. Just slightly more is required to actually deploy the service, which we’ll cover later on.

By the way, you don’t have to use interfaces when implementing a service, just like you don’t have to use an interface to define a class. You do have to specify what you want exposed through a service, explicitly. You can define anything else you want or need as part of the interface, but only methods, and only methods that get decorated with [OperationContract], will be exposed by the service.

Data Contracts-exposing data types

WCF also allows you to expose custom data types so that you are not restricted to simple data types of the CLR. These are simple structs with no methods associated with it. This can be a little confusing sometimes, because the same syntax is used for both services as well as for CLR definitions. Here’s an example of a DataContract that we will use.

[DataContract]
public class SensorTemp
{
    [DataMember]
    public int probeID;
    [DataMember]
    public int temp;
}

DataContract specifies the data type that you are exposing and, DataMember specifies the members that are part of the data type. As is the case with ServiceContract, you have to explicitly declare which members are to be exposed to external clients, using DataMember. What that means is that you can include anything else that you may want (or need) as part of the class definition, but only the members decorated with DataMember will be visible to clients.

Coding options in WCF

As we saw above, one of the options available to specify functionality under WCF is to use attributes. Attributes are translated by the compiler to generate much of the infrastructure required by WCF in order for us to create and use services.

The second way you can specify many of the options is through configuration files. This allows you to make changes without having to re-compile. Many of the WCF classes will automatically use default values from the config file. Here’s an example of an endpoint specified using config data (endpoints will be described shortly). First, the config file, then the code statement referencing the config file data:

<endpoint name ="LocalTimeService"
        address="net.pipe://localhost/LocalTimeService"
        binding="netNamedPipeBinding"
        contract="ILocalTime" />

LocalTimeProxy proxy = new LocalTimeProxy("LocalTimeService");

Finally, the third way of coding functionality is, of course, programmatically. Many of the things that you can do via attributes or config files can also be done programmatically. Here is the previous endpoint, defined programmatically:

Uri baseAddress = new Uri(ConfigurationManager.AppSettings["basePipeTimeService"]);
baseAddress = new Uri(ConfigurationManager.AppSettings["basePipeTimeService"]);
serviceHost.AddServiceEndpoint(typeof(ILocalTime), 
            new NetNamedPipeBinding(), baseAddress);

Endpoints

Endpoints are the ‘identity’ of a service. They define all the information that we need in order to establish and communicate successfully with a service. Endpoints are made up of three pieces of information: Address, Binding, and Contract. The address is obviously the location of the service, such as ‘net.pipe://localhost/LocalTimeService’. The binding specifies security options, encoding options, and transport options, which means a lot of options! Luckily, there is a collection of pre-defined bindings provided with WCF that we can use to make our life simpler. And finally, the contract is the actual interface that the service implements.

Implementing a WCF Service

So, a service is nothing more than a regular class that gets decorated with some special attributes. The attributes are then translated by the compiler to generate the special infrastructure code required to expose the class as a service to the world. In the following code, we first define an interface that has one method that returns the local time of where the service has been deployed. The LocalTimeService class then implements the interface, and thus exposes the functionality to the world, or at least to whomever is interested.

[ServiceContract]
public interface ILocalTime
{
    [OperationContract]
    string GetLocalTime();
}

[ServiceBehavior(InstanceContextMode = 
                 InstanceContextMode.PerCall)]
public class LocalTimeService : ILocalTime
{
    public string GetLocalTime()
    {
        return DateTime.Now.ToShortTimeString();
    }
}

That’s all that’s needed to create a WCF service. If you compile the above code into a DLL (a library), you will have created a service. Of course, there is a little more needed in order to have something that’s useable. We need two other pieces in order to complete the service. We need something that will be able to load the service DLL when a client requests the functionality of the service. And we need something that will be able to listen on a communication port, and look through everything that is being received to see if it matches what we are responsible for, our service contract.

Deploying a WCF Service

There are a number of ways to deploy our service. First, if we implement our service to support HTTP, then we could deploy our service just like a regular Web Service, using IIS. If we want to support some of the other transports, then we could deploy the service using Windows Activation Service (WAS), which is an enhancement available in IIS 7.0. If either of these is not suitable or we want more control over the service, then the other solution is to build our own hosting environment by using ServiceHost. ServiceHost is a class available in WCF to host services, almost like a mini IIS, just for our service. We can implement ServiceHost in any housing available under Windows, in a console app, a Windows executable, or a Windows service (formerly NT service).

ServiceHost will listen on whatever channel we specify for our service, using whatever protocol we specify, and call our service whenever a client request for our specific service comes in. That’s a lot of bang for just a couple of lines of code. All that we need to do is tell ServiceHost the endpoint that it is responsible for and the class that it should instantiate when a matching message is received. Here’s the code that’s required to host the LocalTimeService in a console app:

class TimeService
{
    static void Main(string[] args)
    {
        Uri baseAddress = new Uri(
          ConfigurationManager.AppSettings["basePipeTimeService"]);
        ServiceHost serviceHost = new ServiceHost(typeof(LocalTimeService),
                                                         baseAddress);
        serviceHost.Open();
        Console.WriteLine("Service is running....press any key to terminate.");
        Console.ReadKey();
        serviceHost.Close();
    }
}

You can now compile the service. However, if you try to run it, you’ll get an error message indicating that you haven’t provided ServiceHost with an endpoint. As we saw above, you can specify endpoints either programmatically, or by using the configuration file. The nice thing about using configuration is that you can change it at any time and you don’t have to recompile. As we’ll see later, you can specify multiple endpoints for a service, depending on the clients that you want to support. And if at some point later, you decide to not support a specific transport, you just have to edit the configuration file.

Here’s the config file that we’ll need for the LocalTimeService:

<configuration>
  <appSettings>
    <add key="basePipeTimeService" 
         value="net.pipe://localhost/LocalTimeService" />
  </appSettings>
  <system.serviceModel>
    <services>
      <service name="LocalTimeService">
        <endpoint 
           address="" 
           binding="netNamedPipeBinding" 
           contract="ILocalTime" 
         />
      </service>
    </services>
  </system.serviceModel>
</configuration>

Let’s examine the entries in the config file. You should note that there could be as many entries as needed. For example, there could be several endpoints that the service supports (different transports). There is also only one service being specified in this example, but there could be several services provided in the same housing. You can see that the endpoint has three properties: address, binding, and contract. The binding indicated is referencing the standard netNamedPipeBinding provided in WCF. There are various default binding classes provided for each transport. You can see the options for each in the docs.

I will say here that you too will encounter the “zero application (non-infrastructure) endpoints” exception at some point. There won’t be too many clues as to what exactly is not matching up, so you’ll have to scrutinize the text. Make sure that you have the correct namespaces specified.

Now you can execute the application, and the service will be available to any client that knows how to communicate with it.

Proxies

Just by saying we want to go to New York and we are going to go by car, does not get us there. We need a car to actually get us there. Having a completely defined endpoint is not enough. We need something (code) that will actually take the endpoint as a parameter and allow us to do what we want to do, call a method. And that something is a proxy.

As was the case in the past with COM, proxies take care of all the low level plumbing (serializing and packaging our parameters) so that we just need to make the call. We don’t care how they are forced through the ‘spigot’ or how they are pulled out on the other side.

And as we’ve also had in the past, there is a utility that will create the proxies for us. However, this is one area of WCF that needs some improvement. And I’m guessing this functionality will become incorporated into Visual Studio in future releases. At least, I would hope so. To create a proxy, you need to use the command line utility, svcutil, which has a number of switches that are not all or well documented. But hey, I’m not complaining, it’s a small inconvenience for a whole lot of major improvements. And it’s still only Beta.

So, you run svcutil against your service DLL and bam! You got your proxy class. There are other options, like if the service has a MEX endpoint, you can direct it to the service, and it will extract the service information dynamically from the service. This is essentially the same functionality provided through Studio when creating a Web Service, and we use the ‘Add Web Reference’ dialog. What I really want is for Visual Studio to automatically generate the proxies since it has all the information in the source files to begin with! But as I said, I’m not complaining. ;)

Currently then, creating the proxy is a two step process. First, you run svcutil against your service DLL, which will create the schema (XSD) and WSDL files. Then, you invoke svcutilagain, but this time, you run it against the output it just created (*.xsd, *.wsdl).

The svcutil will generate ‘output.cs’ as the default file name, unless you specify otherwise, I normally just rename it. There are also options to just generate DataContracts or just ServiceContracts, and also an option to generate a client config file. Here’s the proxy file for the LocalTimeService, with some portions edited for readability. There’s not much there, since all the magic occurs in ClientBase.

[ServiceContract]
public interface ILocalTime
{
    [OperationContract]
    string GetLocalTime();
}

public interface ILocalTimeChannel : ILocalTime, 
                 System.ServiceModel.IClientChannel
{
}

public partial class LocalTimeProxy : 
       System.ServiceModel.ClientBase<ILocalTime>, ILocalTime
{
    
    public LocalTimeProxy()
    {
    }
    public string GetLocalTime()
    {
        return base.InnerProxy.GetLocalTime();
    }
}

Consuming a WCF Service

So now, the next logical step is to build a client that knows how to consume the service that is being provided. The client code only needs two things: the proxy that allows it to communicate with the service, and the endpoint to the service. Here’s one version of a client that consumes the LocalTimeService:

Collapse

class Client
{
    public bool keepClocking = true;
    LocalTimeProxy proxy = null;
    public Client()
    {
        proxy = new LocalTimeProxy();
    }
    public void ClockingThread()
    {
        while (keepClocking)
        {
            Console.WriteLine(proxy.GetLocalTime());
            Thread.Sleep(1000);
        }
        proxy.Close();
    }
    static void Main(string[] args)
    {
        Client client = new Client();

        //Create a separate thread to request the time once a second
        Thread thread = new Thread(new ThreadStart(client.ClockingThread));
        thread.Start();

        Console.WriteLine("Service is running....press" + 
                          " any key to terminate.");
        Console.ReadKey();

        client.keepClocking = false;
        //wait 2 seconds
        Thread.Sleep(2000);
    }
}

Not much to this client. All that it's doing is making a call to the service method GetLocalTime(), once a second. As you can see, the client code has no indication as to what or where the other end of the method call is. Nor what mechanism is actually being used to make the connection. It is just a simple class method call! As we look at other examples, you'll keep seeing the simplicity of coding that is provided under WCF. And here is the config file that specifies the endpoint to the service which is required by the client.

<configuration>
  <system.serviceModel>
    <client>
      <endpoint name ="LocalTimeService"
                address="net.pipe://localhost/LocalTimeService"
                binding="netNamedPipeBinding"
                contract="ILocalTime" />
    </client>

  </system.serviceModel>
</configuration>

Compile and run the client. Start several instances. Just make sure that the service is started before you start the clients, otherwise nobody will be listening.

That’s it for the basics in getting services listening and consuming services. In Part 2, we'll build some examples that will demonstrate WCF's support for the various communication patterns. The download includes all of the source code for the sample applications described in the articles.

Al Alberto

Introduction

This article discusses about some features of the service model of WCF which is part of .NET 3.0. It demonstrates how to host multiple instances of the same service and contract in a Windows Forms application. Those services are then consumed by a client form belonging to the same application and by the same client form but created from another application. It demonstrates how to create singleton services and consume them without using any configuration file.

Background

As I was abroad and I couldn't carry with me my model train control station, I decided to write a simple simulator so I could continue to work on the bigger software I'm designing and that drives the control station.

First of all, I had to create a simple simulation of the locomotives that run on the track and that the control station can pilot. As I recently attended a WCF training, I thought that it would be a good practice to write this part using the new WCF service model. Years ago, I would have written some COM servers to simulate the locomotives, but technology has evolved, and the new service model developed for .NET 3.0 is far more powerful than was COM.

In fact, what I want to simulate is the locomotive DCC decoder. This little piece of hardware is used to control a locomotive on a track referenced by its address. The control station sends commands to change the speed, the direction, and switch the lights. It also can read the status of the device by its address. It can easily be simulated by a singleton service. There is no problem of scalability as the locomotives are going to run on a single machine and their number won't be big, neither the connections to a given locomotive. First, I wanted to use a Sharable instance for the service, but this instance mode has disappeared in the latest release of WCF…

Using the code: Service contract

Here is how the interface to simulate a simple locomotive decoder looks like:

Collapse

[ServiceContract]
public interface IDCCLocomotiveContract
{    
    /// Gets the running direction of that locomotive/// </summary>/// <returns></returns>
    [OperationContract(IsOneWay=false)]
    Direction GetDirection();
    /// <summary>/// Changes the direction of that locomotive/// </summary>/// <param name="direction">New direction</param>
    [OperationContract]
    void ChangeDirection(Direction direction);
    /// <summary>/// Sets the new speed value/// </summary>/// <param name="speed">Speed value (0 - 28)</param>
    [OperationContract]
    void SetSpeed(byte speed);

    /// <summary>/// Gets the current locomotive speed/// </summary>/// <returns>Speed value</returns>
    [OperationContract(IsOneWay=false)]
    byte GetSpeed();

    /// <summary>/// Switch the main light/// </summary>/// <param name="state">ON if true, OFF if false</param>
    [OperationContract]
    void SwitchLight(bool state);

    /// <summary>/// Gets the main light status/// </summary>/// <returns>true if ON, false otherwise</returns>
    [OperationContract(IsOneWay=false)]
    bool GetLightState();
}

Service implementation

WCF allows managing the instance behavior just by using an attribute parameter for the class that implements the service. There are three different instance modes. When using the PerCall mode, every time you call the service, you get a fresh instance. That means that all data are lost between calls. The PerSession mode maintains a session between each call until the proxy is released. The PerSession is the default mode so you don't have to specify it. Finally, the Single mode keeps the same instance of the service until the server itself is shutdown. Take note that in earlier versions of WCF (May CTP and before), the PerCall was the default mode and that there was a Sharable mode that doesn't exist anymore.

Here is how the implementation of this simple service looks like:

Collapse

				/// <summary>
				/// Implements the IDCCLocomotiveContract
				/// </summary>
[ServiceBehavior(InstanceContextMode=InstanceContextMode.Single)]
class DCCLocomotiveService : IDCCLocomotiveContract, IDisposable
{    
    const byte        
        MaxSpeed = 28,        
        MinSpeed = 0;
    protected byte m_speed = 0;
    protected bool m_light = false;
    protected Direction m_direction = Direction.Forward;
         
    public Direction GetDirection()
    {
         return m_direction;
    }

    public void ChangeDirection(Direction direction)
    {
         m_direction = direction;
    }

    public void SetSpeed(byte speed)
    {
         if (speed >= MinSpeed && speed <= MaxSpeed)
             m_speed = speed;
    }

    public byte GetSpeed()
    {
         return m_speed;
    }

    public void SwitchLight(bool state)
    {
         m_light = state;
    }

    public bool GetLightState()
    {
         return m_light;
    }
}

Demo applications

I created two simple applications. The "locomotive factory" behaves like when you put the locomotive on the track, and the "Locomotives monitor" allows watching the parameters of the locomotives. The locomotive factory is a window application that starts one server per locomotive. Each server gets an address related to the address of the locomotive. It has one endpoint for the locomotive contract. I chose this implementation because I wanted to be able to stop the server like when you remove a locomotive from the track. For testing purposes, I made it possible to the factory to control the locomotives from a control dialog box. First, I wanted to use one service and several endpoints for the locomotives, but it was not possible because all the endpoints must be created before the service host is started.

I use an XML file that contains the list of the available locomotives. Basically, I use the address and the name. A checkbox list is created from that file. When you check an element, it starts the locomotive server and creates the endpoint for it. When you uncheck the element, it stops the server.

The main user interface of the "Locomotive factory" is shown at the beginning of the article.

A button allows sending commands to the given locomotive from a dialog box. This is where I found a strange behavior. In my first draft, I was creating the ServiceHost instance in the same thread as the application. When I was calling a method on the IDCCLocomotiveContract instance I got from a ChannelFactory in the dialog box, it was failing with a timeout. However, the same call from the same ChannelFactory from another application was working.

Hosting the Service

I designed a simple class that creates the ServiceHost instance in a different thread than the one of the application. It seems that a Windows Forms application introduces restrictions due to the window messaging, and I suppose that there is some interference between this messaging and the one used by WCF. This class creates a Thread that starts the ServiceHost for my contracts and waits until the application stops it. It uses a simple pattern to stop it, with a boolean that triggers the end of the thread method. A thread must not be stopped using the Abort method, because in our case, it must close the ServiceHost. A call to Abort would let the ServiceHost open.

Collapse

class ThreadedServiceHost<TService, TContract>
{    
    const int SleepTime = 100;    
    private ServiceHost m_serviceHost = null;    
    private Thread m_thread;    
    private string         
        m_serviceAddress,        
        m_endpointAddress;    
        private bool m_running;    
        private Binding m_binding;

    public ThreadedServiceHost(        
        string serviceAddress, 
        string endpointAddress, Binding binding)
    {
         m_binding = binding;
         m_serviceAddress = serviceAddress;
         m_endpointAddress = endpointAddress;

         m_thread = new Thread(new ThreadStart(ThreadMethod));
         m_thread.Start();
    }

    void ThreadMethod()
    {
        try
        {
            m_running = true;
            // Start the host
            m_serviceHost = new ServiceHost(
                 typeof(TService), 
                 new Uri(m_serviceAddress));
            m_serviceHost.AddServiceEndpoint(
                typeof(TContract), 
                m_binding, 
                m_endpointAddress);
                m_serviceHost.Open();

            while (m_running)
            {
                // Wait until thread is stopped
                Thread.Sleep(SleepTime);
            }

            // Stop the host
            m_serviceHost.Close();
        }
        catch (Exception)
        {
            if (m_serviceHost != null)
            {
                m_serviceHost.Close();
            }
        }
    }

    /// <summary>/// Request the end of the thread method./// </summary>
    public void Stop()
    {
        lock (this)
        {
            m_running = false;
        }
    }
}

Proxy for the Service

An interesting issue of my application is that I don't know by advance the number of locomotives and their addresses, so I don't use any App.Config file in my construction. I don't use any proxy as well but the ChannelFactory that allows creating a proxy on the fly. I use a NetTcpBinding which is OK for a local service and can eventually be used in Windows distributed environment. The ChannelFactory takes an interface derived from the contract of your service and the IChannel interface. It then dynamically creates a proxy to your service that you can use as if you where using the interface of your contract.

Below is the code that I use to create the proxy with my service:

				// Creates the corresponding endpoint
EndpointAddress endPoint = new EndpointAddress(    
    new Uri(string.Format(Constants.LocoServerBaseAddress, 
    address) + address));

// Creates the proper binding
System.ServiceModel.Channels.Binding binding = new NetTcpBinding();

// Creates channel factory with the binding and endpoint
m_dccLocoFactory = new ChannelFactory(binding, endPoint);
m_dccLocoFactory.Open();

// Creates the channel and opens it to work with the service
m_locoChannel = m_dccLocoFactory.CreateChannel();
m_locoChannel.Open();

The interface to create this proxy using the ChannelFactory is as follows:

				///<summary>
				/// Interface used to create the Proxy for IDCCLocomotiveContract
				///</summary>
interface IDCCLocomotiveChannel : IDCCLocomotiveContract, IClientChannel
{
}

The ChannelFactory is used in a dialog box that can be configured either to send commands to the locomotive service or to watch the different parameters.

Here is a copy of the two versions of that dialog box which are in fact implemented by the same code:s

Locomotive control is a child window form of the Locomotive Factory while the Locomotive Monitor is a child window form of the Locomotives Monitor, a simple application that connects to a locomotive service, given its address.

Like for a real locomotive decoder, the locomotive service doesn't provide any notification. A locomotive decoder is a passive device that cannot send information to the control station by its own. In order to reflect changes in the different clients, each client must manage its own pooling.

Points of Interest

You can dig into the complete code of this simple application, and I hope it will give you some ideas of what you could do with the new service model of WCF. Of course, this is just a glimpse at this very powerful framework for Service Oriented Application (SOA). WCF is a very complete framework to develop SOA based applications in the Microsoft world. However, as it is based on open standards like WS-*, applications can be designed to interoperate with other applications that comply to those standards regardless of the technology that implements it.

Even if it is a simple demo of what can be done with WCF, this should help those who are discovering this new service model. Doing it, I discovered as few interesting points such as hosting the services in a Forms application which requires to use a specific thread for the service. I also found out that if you need to start and stop individual instances of the same service, you cannot use multiple endpoints, but must use a host for each of your instance.

Another interesting point is the creation of dynamic hosts and proxies as their addresses depend on a list and is unknown by advance.

Olivier ROUIT

The following piece of code shows how to install/uninstall a given service and register it with SCM calling appropriate APIs using P/Invoke in C#

Contents

1. Introduction
2. Objectives.
3. Prerequisites.
4. Package.
5. To Run The Sample.
6. Configuration Files.
7. Assembly References from client assembly.
8. Code blocks in client source file CRemoteObjClient.cs
9. Code blocks in client source file CRemoteObjServer.cs
10. Walkthrough.
11. References.

Introduction

.NET Remoting is a framework for developing distributed applications. It is the successor to DEC/RPC/DCOM. Simply put, Remoting allows an application (Remoting Client) to instantiate a type (Remotable class) on a remote server (Remoting server) across network. Communication between client and server object (Instance of Remotable class) hosted by a Remoting Server is channeled through a "proxy" – representation of server object on client side.

Remoting Server can be a simple console application, a Windows Service or hosted on IIS. It's responsible for hosting server objects and publishes them to the outside world. A Remoting client is any application that consumes the published server object.

There're many tutorials on this broad subject. Unfortunately, most are lacking, in one way or another, in coverage of basic maneuvers a developer needs to know. The purpose of this article is to supplement MSDN and to provide a complete coverage of basic remoting tasks in one short article.

Objectives of the tutorial

The tutorial will cover the following topics.

• Basic Remoting , Programmatic Configuration (channel/type), Config files, LeaseTime, new, Activator.GetObject (server-activated object, or SAO) and Activator.CreateInstance (client activated object, or CAO)
• How to implement interface for remote class, and interact with remote object through interface.
• Passing custom/user-defined objects between remote object and client.
• Asynchronous method calls on remote object.
• Events and remoting: How client can subscribe to events generated by remote object.

This tutorial does not cover the following topics.

• Hosting server from IIS [Ref - 2,7]
• Delayed loading of channels
• Tracking services
• ClientSponsor and sponsoring mechanism [Ref 5]
• Custom formatter, sinks, channels – that's where things actually get complicated. [Ref 1]
• SoapSuds

Prerequisites

• .NET Delegates and events.
• Asynchronous programming. IAsyncResult, BeginInvoke, EndInvoke, WaitHandle... etc.

Package

• dnetremoting.zip

Overall Architecture

• ReadMe: dnetremoting.doc (That's this document.)
• Project folders, classes and overall structure:

[Editor Note - hyphens/spaces have been used in the table contents to prevent scrolling]

To run the sample

1. Run server executable.
2. Run client executable.

Server and client are both C# console apps. Pay attention to console output.

Configuration files

Before Remoting client and Remoting Server can begin to communicate, two pieces of information must first be properly configured, whether you're on server side or client side:

Communication channel

• Communication channel: port number, protocol, uri/url. <channel> tags in configuration files. (Both server and client side)

NOTE: You don't need to specify port number for client side.

Type (Remotable class) to be published or consumed:

• Resource to be published and activation mode (config file for remoting server) <service> tag in configuration files (Remoting server side).
• Resource to be consumed (config file for remoting client) <client> tag in configurations files (Remoting client side).

Two configuration options:

• Using XML configuration files:
  • RemotingConfiguration.Configure("cremoteobjserv.config");
• Configure setting programmatically:

  //Configure channel:
  ChannelServices.RegisterChannel(httpchannel);
  //Register TYPE for server-activated objects (SAO):
  RemotingConfiguration.RegisterWellKnownServiceType(
    typeof(nsCRemoteObj.CRemoteObj), //Type"CRemoteObjURI", //"object URI" (NOT URL to remoting server!)
    WellKnownObjectMode.SingleCall //Activation mode: SingleCall or Singleton
  );
  //Register TYPE for client-activated objects (CAO):
  RemotingConfiguration.RegisterActivatedType(
    Typeof(nsCRemoteObj.CRemoteObj) );

Note: There're two types of server object: SAO (server activated object) and CAO (client activated object). SAO can be further divided into two types: singlecall and singleton. Here's a brief description.

• Server-Activated Object (SAO) = Well-known Object.
• Client Activated Object (CAO).

SAO

SingleCall - A new instance of the remotable class is created every time a client invokes a method through proxy.

Lifetime: Instance remains in memory for duration of method call.

This is stateless.

Singleton - The Singleton Instance is created on first method call.

Lifetime: This instance stays in memory until "Lease" expires.

This is Stateful. Only one instance of Singleton-SAO is instantiated on remoting server. Multiple Remoting Clients are serviced by same Singleton-SAO. Multiple remoting clients can communicate through one instance of Singleton SAO.

CAO

• Instantiated on remote server as soon as the remoting client requests that an instance be created through Activator.CreateInstance or new keyword. This is in contrast to SAO where server objects are created upon first method call.
• Lifetime: Just as Singleton-SAO, object stays in memory until "Lease" expires.
• Stateful. Each CAO instance services only the remoting client responsible for its creation. Therefore, if you have multiple Remoting Client, each gets their own instance of CAO.

Single-call SAO is the most scalable option among the three and is most suitable in a load-balanced environment. Singleton-SAO and CAO offers more flexibility that:

• Remoting clients have complete control over a server object's lifetime.
• Server objects are stateful. CAO maintains states across multiple requests/method call. Singleton-SAO maintains states across multiple Remoting Client.

Sample configuration files

Server side

Server activated. File name: cremoteobjserv(wellknown).config

Client side

Server-activated. File name: cremoteobjclient(wellknown).config

In addition to type and channel information, configuration file may contain setting such as object lifetime, security... Example: lifetime of Singleton SAO and CAO remote object can be configured in <lifetime> tag in a config file:

Remote object lives as long as CurrentLeaseTime>0. When the object first got instantiated, CurrentLeaseTime = leaseTime. From this point on, CurrentLeaseTime starts decrementing until the next method call, or that a "sponsor" extend the "lease". On next method call (if lease has not yet expired), CurrentLeaseTime is reset to renewOnCallTime. On the other hand, if CurrentLeaseTime decrement to zero before next method call arrives, the object is marked for garbage collection. If this happens, the next method call will be serviced by a new instance of the remote class. In short, "server-activated Singleton" and "client activated" remote object lives for as long as CurrentLeaseTime>0. Lifetime setting can also be configured programmatically:

				using System.Runtime.Remoting.LifetimeServices;
LifetimeServices.LeaseTime = TimeSpan.FromMinutes(3);
LifetimeServices.RenewOnCallTime = TimeSpan.FromMinutes(3);

For more information about leasing mechanism and sponsoring mechanism, refer to MSDN under the topic "Lifetime Leases" [Ref 5] and "Remoting Example: Lifetimes" [Ref 8].

Assembly References from "client" assembly

• Reference to interface assembly (i.e.. "Project" menu>"Add Reference">select interface CRemoteObjInterface.dll)

Code blocks in client source file CRemoteObjClient.cs

Basically, client source is separated into two mutually exclusive blocks – marked by the following tags in client's source code CRemoteObjClient.cs:

<BLOCK X-Y>

... code block ...

<BLOCK X-Y END>

You should comment out BLOCK 1 when you want to run code in BLOCK 2, and vice versa.

• BLOCK 1: remote object is published as server-activated object.
• BLOCK 2: remote object is published as client-activated object.

So, depending on setting in CRemoteObjServer, you may wish to comment out one of the blocks before you compile and execute. In addition, <BLOCK 2-A> and <BLOCK 2-B> are mutually exclusive.

• BLOCK 2-A configures channel/type information by loading the config file, then instantiate remote object with "new" keyword.
• BLOCK 2-B configures channel/type information programmatically. Proxy is retrieved with call to Activator.CreateInstance(..)

So, again, comment out one of the two before compile and execute.

namespace nsCRemoteObjClient

{ //nsCRemoteObjClientclass CRemoteObjClient

{ //CRemoteObjClient

1. Delegate to CRemoteObj.SetupUser()
2. Signature: public string SetupUser(string sname, string spasswd, out string sTime)
3. Refer to <BLOCK 1-C>

publicdelegatestring SetupUserDelegate(...);
[STAThread]
staticvoid Main(string[] args)
{ //Main()//Scenario 1: "server-activated" remote object. 

<BLOCK 1>

try

{ //try-A

<BLOCK 1-A>

Retrieve interface/proxy:

• Illustrates how to retrieve proxy via: Activator.GetObject(...)
• Cast proxy into IRemoteObj: further separation between provider and supplier.

<BLOCK 1-A END>

<BLOCK 1-B>

• LeaseTime
• Invoke method on remote object through interface.

<BLOCK 1-B END>

<BLOCK 1-C> Asynchronous programming/remoting

• Illustrates asynchronous calls on remote objects and how to pass parameters into/out of methods exposed by remote object using BeginInvoke, EndInvoke.
• Illustrates how to pass user defined object to/from remote object.

<BLOCK 1-C END>

} //try-Acatch(Exception err)
{
}

<BLOCK 1 END>

• Scenario 2: "client-activated" remote object.

<BLOCK 2>

try

{ //try-B

<BLOCK 2-A>

• Illustrates how to configure channel information using config file.
• Illustrates how to instantiate remote object with "new" keyword.

<BLOCK 2-A END>

<BLOCK 2-B>

Illustrates how to retrieve proxy to remote object via

Activator.CreateInstance(...)

<BLOCK 2-B END>

<BLOCK 2-C>

• Illustrate how to invoke method through proxy.
• Illustrates how to subscribe to events generated by remote object.

<BLOCK 2-C END>

} //try-Bcatch(Exception err)
{
}

<BLOCK 2 END>

    } //Main()
  } //CRemoteObjClient
} //nsCRemoteObjClient

Code blocks in server source file

• Block 1: Option 1: programmatic registration of channel and type information thru:

ChannelServices.RegisterChannel
RemotingConfiguration.RegisterWellKnownServiceType

• Block 2: Option 2: Configure by loading xml config file:

RemotingConfiguration.Configure("cremoteobjserv.config");

Again, you comment out OPTION 1 if you're using OPTION 2, and vice versa.

Walkthrough

• Remoting Basic, configuration (channel/type): programmatic, config files. LeaseTime, "new", Activator.GetObject (for server-activated) and Activator.CreateInstance (for client activated)
• Config files: See previous section.

LeaseTime

• Change config file, and run application in different activation mode: server-activated SingleCall, server-activated Singleton, client-activated.
• Run the client. Comment out <BLOCK 2> and <BLOCK 1-C>. Pay attention that obj.AuthenticateLoser is invoked in <BLOCK 1-B>
• Monitor server console and objID. Default LeaseTime is 300-sec for Singleton, if time elapsed between method calls is greater than 300sec, a new instance of remote object gets created each call when remote object runs under the following mode:
  • server-activated Singleton.
  • Client-activated

Lease configuration can be found in server config file:

<lifetime leaseTime="100MS" sponsorshipTimeout="50MS" 
    renewOnCallTime="100MS" leaseManagerPollTime="10MS" />

In <BLOCK 1-B>, time between consecutive method calls is 101 ms. That's a little over 100 sec. So, every method call should be serviced by a new instance – therefore a different objID. Adjust lease configuration and observe. For server-activated SingleCall, a new instance service every method call.

NOTE: objID is a randomly generated object ID assigned to an instance of remote object CRemoteObj – take a look at constructor.

"new" keyword: Instead of Activator.GetObject or Activator.CreateInstance, we can use "new" to instantiate the remote object. However, if you choose to configure channel and type information via config file, you may instantiate remote object using "new" keyword. However, "new" implies that you'll be instantiating CRemoteObj – as opposed to interface IRemoteObj. This further implies that your client assembly must reference CRemoteObj assembly.

Activator.GetObject: Take a look at CRemoteObjClient.cs <BLOCK 1-A>

IRemoteObj obj = (IRemoteObj) Activator.GetObject(
typeof(IRemoteObj),
"http://localhost:8085/CRemoteObjURI"
);

Activator.CreateInstance: Take a look at CRemoteObjClient.cs <BLOCK 2-B>

//Note that it references CRemoteObjServer – not the remote object.object[] attrs = { new UrlAttribute(
  "tcp://localhost:8086/CRemoteObjServer") };
ObjectHandle handle = (ObjectHandle) Activator.CreateInstance(
  "CRemoteObj", 
  "nsCRemoteObj.CRemoteObj", 
  attrs);
CRemoteObj obj = (CRemoteObj) handle.Unwrap();

How to implement interface for remote class, and interact with remote object through interface.

Interface: IRemoteObj (CRemoteObjInterface.cs)

If we instantiate remote object via Activator's static methods, it'd be unnecessary for client assembly to reference remote object's assembly. This provides further separation between the remote object and the client. If client side settings are loaded from config file instead, remote object has to be instantiated using "new" keyword. This implies client has to reference remote object's assembly.

Take a look at the source code. Pay attention to the architecture and assembly references.

Passing custom/user-defined objects between remote object and client.

User defined class: CProfile (defined in CRemoteObjInterface.cs)

//ATTENTION: Must be marked Serializable to pass //user-defined object in/out of remote object.
[Serializable] 
publicclass CProfile
{
  publicstring fname;
  publicstring lname;
  publicstring user;
  publicstring passwd;
  //... other stuff...
};

Method: CRemoteObj.UpdateProfile (defined in CRemoteObj.cs)

The method takes a CProfile object as argument, and return a CProfile object.

public CProfile UpdateProfile(CProfile p)
{
//...other stuff...return pout;
}

The method is also exposed by interface IRemoteObj, although it's not necessary. Call to method is trivial. Now, let's take a look at <BLOCK 1-C> in client's source file CRemoteObjClient.cs.

CProfile p = new CProfile("John", "Kennedy", "JFK", "ace");
CProfile p2 = obj.UpdateProfile(p);
Console.WriteLine("UpdateProfile completed. return p2 passwd: {0}", 
    p2.passwd);

Asynchronous method calls on remote object.

Take a look at <BLOCK 1-C> in client's source file CRemoteObjClient.cs.

//ATTENTION://Delegate for CRemoteObj.SetupUser:publicdelegatestring SetupUserDelegate(
    string string1, string string2, outstring string3);

//...other stuff...

Main(...)
{

<BLOCK 1-C>

Wrap SetupUser in a delegate before calling BeginInvoke:

• SetupUserDelegate d = new SetupUserDelegate(obj.SetupUser);

Invoke CRemoteObj.SetupUser asynchronously:

string sTime;
IAsyncResult ar = d.BeginInvoke(
  "Dexter",
  "AceInOpen",
  out sTime,
  null,
  null
);
//Blocks the current thread until obj.AuthenticateLoser completes.
ar.AsyncWaitHandle.WaitOne(); 
if(ar.IsCompleted)
{
  //Retrieving output: //(a) "output variable" sTime//(b) "return variable" value.string ret = d.EndInvoke(out sTime, ar);
  Console.WriteLine("obj.SetupUser return. sTime:{0}{1}" +
  "return value: {2}", sTime, Environment.NewLine, ret);
}

//...other stuff...

<BLOCK 1-C END>

//...other stuff...
}

Events and remoting: How client can subscribe to events generated by remote object.

The event handler is declared in the interface module CRemoteObjInterface.

Routing mechanism: Here's the sequence of things that takes place when client invoke the AuthenticateLoser:

That's it. I hope this article provide a good coverage of most basic maneuvers that would be expected of a component developer. Go through the source code and play around with different configurations. You should be well on your way to building distributed applications and harness power offered by .NET Remoting.

References

• REF-1 .NET Remoting Customization Made Easy by Motti Shaked
  • http://www.codeproject.com/csharp/customsinks.asp
• REF-2 MSDN online: Remoting Example: Hosting in Internet Information Services (IIS)
  • http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconremotingexamplehostinginiis.asp
• REF-3 MSDN online: Remote Object Configuration
  • http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconremoteobjectschannels.asp
• REF-4 MSDN online: Asynchronous Programming Overview
  • http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpovrasynchronousprogrammingoverview.asp
• REF-5 Other MSDN references:
  • "Asynchronous Delegates Programming Sample"
  • "Asynchronous Remoting"
  • "Asynchronous Programming Overview"
  • "Lifetime Leases"
• REF-6 SoapSuds vs. Interfaces in .NET Remoting by Ingo Rammer
  • http://www.ingorammer.com/RemotingFAQ/SoapSudsOrInterfaces.html
• REF-7 Hosting Remote object in IIS – A Remoting sample by Sandeep Alur
  • http://www.developersdex.com/gurus/articles/573.asp?Page=3
• REF-8 MSDN online: Remoting Example: Lifetimes
  • http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconremotingexamplelifetimes.asp

raymond.fung

Introduction

A good architecture and design are necessary for the development of a successful application. The success of an application lies in its robustness and maintainability. These qualities are governed by the design and architectural choices that you make at the start of the project. Using the correct architecture is a key to ensuring the performance and scalability of an application. However, most of the time, you must maintain a balance between performance and scalability, probably favoring one more than the other, depending on the requirements.

In this article, you will learn about the factors that will help you to determine whether to trade performance for scalability, or vice-versa. The overhead that is incurred when you provide the ability to scale a distributed application frequently leads to a decrease in performance. When you scale an existing application, you either scale up or scale out. Scaling up, which is most frequently used in client/server scenarios, is the process of adding hardware, such as more or faster RAM, disks, and processors; scaling out is the process of adding more servers. You can use a combination of the two mechanisms. However, if your applications are not designed for processing on multiple computers, you must scale up. Therefore, the issue you face when you design your distributed applications is whether to enable scaling or to focus on the performance of the application. The decision between performance and scalability is not a simple choice between one or the other: a correctly designed distributed application, designed to scale out, can perform better than traditional client/server applications. Generally, however, the more scalable an application is, the more the performance suffers. The hardware that you deploy has a big effect on the design and on the tradeoffs that you must consider.

Your design choices affect the scalability and performance of your application. To make the right choices, you must have a clear understanding of the application requirements and the features of .NET Remoting. Taking your requirements into consideration, you must make decisions about the following factors: activation model, channel and formatter, implementing the common assembly, synchronous or asynchronous calls, events, and the default object lifetime.

Activation model

The manner in which a remote object is activated has a large effect on the affinity, state management, load balancing, performance, and scalability of your Remoting application. Based on these factors, and whether and how they apply to your architecture, you can implement either server-activated objects (SAO) or client-activated objects (CAO).

Server-activated objects

You use SAOs when you have more than one server providing services to clients. When you use SAOs, any one of the available servers that receives the request will be able to service the request. You can use either Single-Call SAOs or Singleton SAOs. You use Single-Call SAOs when you do not have to maintain the state of the objects. On the other hand, if you must perform state management, you use Singleton SAOs.

Client-activated objects

CAOs work well when you are using a single-server approach. When you are using a single-server approach, you do not provide load balancing or failover clustering, and you use components that maintain state for their specific client. With CAOs, you can obtain total control over object creation and the lifetime of the remote object.

Channel and formatter

Choosing the appropriate channel and formatter will affect the speed of message transfer and interoperability. The environment in which you want to deploy your Remoting application determines the channel and formatter that should be used.

Channel

In .NET Remoting, there are two channel types to choose from: Transmission Control Protocol (TCP) and Hypertext Transfer Protocol (HTTP).

• The TCP channel (TCPChannel class) provides maximum performance for a Remoting solution. The TCP channel does not provide built-in authentication and authorization checks. Therefore, use the TCP channel if your Remoting solution is deployed in a trusted environment without any firewalls.
• Use the HTTP channel (HTTPChannel class) when you need interoperability or when you need to allow communication through a firewall.

Formatter

In .NET Remoting, you have the option of using either the SOAP formatter or the binary formatter. Like the binary formatter, both TCP and HTTP channels can work with SOAP. Choose SOAP when you need interoperability and in applications that cross platform boundaries. The SOAP formatter is not optimal in performance because it is based on XML. This adds a performance overhead because of XML's self-descriptive tags and metatags.

Both the TCP and HTTP channels support the binary formatter. Choose the binary formatter when performance is the priority. The binary formatter reduces the size of data transmitted and is therefore faster.

Implementing the common assembly

Using generic and reusable assemblies enables you to quicken the application development process and, to a degree, allows a successful architecture to be re-used. You can implement a common assembly either by deploying it locally as a private assembly or by embedding the assembly in the Global Assembly Cache (GAC). Choose to implement the common assembly in a GAC when you must provide compatibility between the various versions of your libraries. If both the server and the client use the common assembly, then you can implement it by using interfaces, abstract classes, stub base classes, or Soapsuds-generated proxies.

Interfaces are suitable for hiding the implementation from the definition and can be used to avoid deploying the common assembly for the client. Abstract classes have certain characteristics in common with interfaces. However, abstract classes cannot be instantiated, though they can and should contain implementation code. The difference between interfaces and abstract classes, however, is that abstract classes can be passed as parameters to methods in different application domains. Stub base classes are similar to interfaces and abstract classes in that stub base classes are used as the framework of the remote type. However, you can create an instance of a class from a stub base class. The Soapsuds-generated proxies are most frequently used with non-Microsoft Web services that you want to wrap in a proxy. As the name suggests, Soapsuds-generated proxies can be used only with SOAP calls.

Options for a Common Assembly:

• Interfaces: An interface defines a set of properties, methods, and events. Unlike classes, interfaces do not provide implementation. You define an interface as a separate entity from the classes that implement it. When a class implements an interface, it must implement all the methods that are declared in that interface. An interface must define the methods that set and get data. However, the interface will not implement these methods. You use an interface to define a protocol of behavior that any class can implement. Use interfaces to:
  • Capture similarities among unrelated classes without artificially forcing a class relationship.
  • Declare the methods that one or more classes are expected to implement.
  • Reveal an object’s programming interface without revealing its class.
• Abstract base classes: An abstract class has one or more abstract methods. Abstract classes act as expressions of general concepts from which you can derive more classes that are specific. An abstract class serves as a base class from which other classes can inherit properties and methods. You cannot create an object of an abstract class type; however, you can pass references to abstract class types. You use abstract base classes to provide default behavior or to define families.
• Stub base classes: You cannot directly instantiate an abstract class or an interface. If you want to create your remote object on the client directly by using the new operator, you can define the remote type in the common assembly as a non-abstract class. A stub class is intended as the framework of your remote type; using a stub class is much like using an interface or abstract class. You should still implement the remote type as a class, which is derived from the stub, in the server. Because the stub is not abstract, it is possible to accidentally create a local instance of the stub base class instead of a remote object.
• SOAPSuds-generated proxies: SOAPSuds is a command-line tool that generates an assembly containing a proxy class representing the remote object. The SOAPSuds tool can generate code in addition to an assembly. You can also use SOAPSuds to generate a proxy from a remote object hosted on another computer, provided the object is hosted using an HTTP channel. To use a SOAPSuds-generated proxy, your channel must use the SOAP formatter.
• Factory design pattern: Most implementations of the Factory pattern use two abstract classes, Factory and Product, to provide the invariant interfaces. Although you could use pure interfaces to implement the factory pattern, the use of abstract classes enables you to place common instance behavior in the abstract class. In addition, abstract classes offer versioning benefits over pure interfaces.

When implementing the factory design pattern, follow these guidelines:

• Do not directly create an instance of the CAO on the server. Use an SAO instead, which acts like a factory and returns the actual CAO object to the client.
• Ensure that the SAO factory has one or more methods to create the CAO object.
• Do not expose the implementation of the CAO to the client. Create an interface and let the client use this interface to make calls on the CAO object.
• Do not expose the server code (remote object implementation) to the client. Distribute the interfaces.

Synchronous versus asynchronous calls

You can invoke remote calls by using synchronous or asynchronous calls. Choosing the most appropriate remote calling method lets you increase the responsiveness of your application and possibly improve performance.

Synchronous calls

Use synchronous calls when you do not need parallel processing of client requests. The advantage of using synchronous calls is that you catch return values and throw exceptions immediately. The disadvantage of using synchronous calls is that the responsiveness of the application is slower because the Remoting server has to wait until all clients acknowledge and then process the callback.

Asynchronous calls

If you require good client responsiveness, consider invoking remote method calls asynchronously. For example, use asynchronous calls with Microsoft Windows Forms applications. However, if your client is an ASP.NET application, invoking methods asynchronously and then blocking the calling thread to pick up return values could lead to ThreadPool starvation. Also, if the server goes down, exceptions are thrown at the client. This is because the client is not aware of the state of the server. The only real solution to this problem is a periodic recycling of the client application.

Whether to use events

Use of events and callbacks can cause overhead on the server because the server holds references to all the clients that registered an interest in a published service. Regardless of whether you use synchronous or asynchronous calls to register events, problems can occur at either the client or the server. To improve responsiveness, you can use Message Queuing (also known as MSMQ). Message Queuing enables the server to send messages to clients without having to wait for an acknowledgement from the client.

Whether to use the default object lifetime

.NET Remoting uses the lease sponsor process to manage the lifetime of an object. The default lifetime of an object is set to five minutes. To determine the appropriate object lifetime for your application, you must strike a balance between the resource usage on the server and the performance implications of frequently destroying and re-creating objects. Following are the general guidelines that you can use when you must change the default lifetime of an object:

• Use a longer lease time for objects whose creation incurs a high performance overhead.
• If you use objects whose creation incurs a high performance overhead, increase the default lease timeouts so that the object remains longer.
• Use shorter lease times for objects that consume many shared resources.
• If you create objects that use shared resources, use a shorter lease time for the object. When you reduce the default lifetime, the object is destroyed and resources are released quickly.

Hosting Options

Hosting remote applications on Microsoft Internet Information Services (IIS) involves less development work than hosting applications in Windows services. However, performance with IIS is slower than with Windows services because hosting applications in IIS adds the overhead of a Web server. Also, IIS supports only the HTTP protocol. Because of this limitation, you cannot take advantage of the performance of TCP, which is a protocol with far less overhead. Windows services are useful if the computer does not have an IIS Web server installed on it for security reasons. It is also easier for technical support personnel to manage Windows services and to make sure that the services are running as they should. Finally, if you do not have to host Web pages, using Windows services is a better option because you do not have to maintain a Web server, which requires specific product support knowledge and additional server resources.

Best Practices for Remoting:

Use Remoting for appropriate scenarios

.NET Remoting is the preferred communication mechanism for single process, cross– application domain communication. For communication across processes, across servers, or across deployment or trust boundaries, ASP.NET Web services are generally the recommended option because they are built on industry standards that make it easy to achieve interoperability. However, if state and raw performance—which can be achieved with the TCP channel and the binary formatter—are important, and if interoperability is not a concern, Remoting is a better choice.

Design chunky interfaces

Chatty interfaces result in multiple roundtrips to perform a single logical operation. To reduce the number of roundtrips and thereby increase performance, use chunky interfaces. In a chunky interface, you transfer the necessary data in a single roundtrip. In contrast, chatty interfaces are typically attributed by means of properties. This means that you set a number of properties and then run one or more methods. This is generally appropriate for Object Oriented Programming (OOP), but it is not a suitable option for Remoting.

Use efficient data types

It is important that you use the most efficient data types with Remoting. For example, if you use a DataSet object to store data, the object can hold multiple tables and can be serialized and deserialized to Extensible Markup Language (XML) with a single method call. However, you must realize that using DataSet objects can increase the network traffic because of the serialization and deserialization to XML.

Use SingleCall SAOs whenever possible

A Single-Call object has a unique instance for each client request. Therefore, Single-Call objects live only for the life of the method call. These objects do not maintain state information because they are destroyed after servicing the method. Because Single-Call objects do not store state information, they are free from synchronization code and therefore remove the overhead of state management. Single-Call objects hosted in IIS, using the HTTP channel, provide maximum scalability for your .NET Remoting solution.

Avoid blocking operations

In Remoting, blocking means that, while a process is running, other processes must wait until the running process finishes execution. Therefore, if many long-running operations are occurring in your application at the same time, many threads are blocked while waiting for the other processes to finish execution. This situation leads to low throughput and low CPU utilization. You must identify any potential tasks that can run at the same time and design your application to support these tasks. Designing your application in this way leads to better request/response performance for your Remoting servers.

In trusted server environments, use the TCP channel and the binary formatter

In trusted server environments, you do not have any firewalls. Therefore, for best performance, use the TCP channel with binary formatters. Also, because you have a trusted environment, you do not have to implement additional security mechanisms, such as encryption of data. For example, in an intranet, if all users authenticate against a domain, you could allow access to the Remoting application to all domain users.

Control object lifetime and avoid in-memory state management

You must control object lifetimes to be able to effectively manage the creation of objects and to release the resources associated with objects. Also, you must avoid storing state in memory. Poor in-memory state management hampers scalability and performance and might make failover support impossible.

About alaac#

Contents

    Introduction

    Probe Internals

       Concept and Design

         Interface contract

         What is published

         Publisher

         Checkpoints

         Plug-in

         Installation

    Usage

         Subscribers

         SoapProbeSubscriber2

    WebService Analyzer Studio

         Analyzing First Sample

        Test environment

    Conclusion

Introduction

Consuming a Web Service in distributed .NET applications is fully transparent using the web service client proxy. When the client invokes a method on the proxy, the SOAP infrastructure packs all information into the message SoapClientMessage and passes it through the communication network to the web server, where its ASP.NET dispatcher forwards the message to the proper worker process. This worker process (aspnet_wp.exe) unpacks the message to obtain the information for invoking a method on the web service. The result of the SOAP call goes back to the caller in the same manner using the message SoapServerMessage.

The SOAP Messages travel through the SOAP infrastructure located on both ends - client and sever. Using the SOAP extension feature makes it easy to plug-in a custom process for each processing stage and publish its state.

Subscribing to the WebService Probes, we can obtain a knowledge base of the business workflows, which can be used for their post-processing tasks such as monitoring, analyzing, modeling, simulation, tuning, error catch tracer (like an aircraft black box) etc.

This article describes how to design and implement the loosely coupled SoapMessage Publisher (called as the WebService Probe) using the SOAP extensions and COM+ Event System notifications. Also I will give you a lite tool - WebService Analyzer Studio to see how to subscribe and use the Probe notifications and business workflows between the web services and their consumers. For instance, you can catch the consumer call - HttpRequest and then simulate it many times from the Analyzer. It is a useful SOAP tool for any stage of the development and production environment.

Let's look in-depth at the WebService Probe. I am assuming that you have a knowledge of the SOAP and Web Service infrastructure. Also, have a look at the similarl concept of the Probe for remoting, described in my previous article [1].

Probe Internals

Concept and Design

The concept of loosely coupled message notifications is based on using the COM+ Event Publisher/Subscriber design pattern, where the event call is fired in the proper place of the SOAP Extension. The following picture shows this:

The SOAP ends exchange information using the SoapClientMessage and SoapServerMessage respectively in the Request/Response design pattern. ASP.NET has an extensibility mechanism for calling XML web services using SOAP built-in. This feature is based on overriding the SoapExtension methods to intercept the call at specific stages in the message processing on either the client or the server side.

The message can be intercepted in the following processing stages:

• BeforeSerialize
• AfterSerialize
• BeforeDeserialize
• AfterDeserialize

The Probe uses the AfterSerialize and AfterDeserialize stages to publish the SOAP request messsage and SOAP response message at the ends. The publisher fires the events all the time, without any knowledge of the subscriber in the loosely coupled manner. To stop the publishing it is necessary to unregister the Probe from the web service.

Note that the SoapExtension object life is short; only during the Before and After message processing stages at the same end. The SoapExtension object is initiated each time when the SOAP Message has been created. According to the above picture, there are four different instances of the SoapExtension, actually each end only creates two of them. This is absolutely correct when we are handling a web service - see more details at the [2].

The Probe uses the internal SOAP header _SoapProbeTicket as a passport to travel through all the processing stages at the both ends. This is a logical header per each call (sample session) and it holds the message ID (GUID).

The Probe only fires a local event call (that's the limitation of the COM+ Event Service, where an event class and their subscribers have to be on the same machine). Using a persistent subscriber such as SoapProbeSubscriber (included in this solution), the event call can be forwarded to the Enterprise subscriber using .NET Remoting.

Interface contract

The contract between the Publisher and Subscriber is represented by the SoapEventClass, which is an event meta class derived from the ISoapProbe interface.

Collapse

[Guid("927B319E-BF79-429b-8CA0-118FBF9724CD")]
public interface ISoapProbe
{
   [OneWay]
   void WriteLogMessage(
      DateTime timestamp,    //timestamp of the sample 
      string strSource,      //sourcer
      string strDest,        //destination - url webservice
      string strAction,      //action - webmethod
      string strMsgType,     //type of the call
      string strMsgId,       //identifier - guid
      object objMsgBody);    //http headers + soap envelop
}

[Guid("C515BB2F-664B-4afa-A40F-CD15D119C7E8")]
[EventClass]
[Transaction(TransactionOption.NotSupported)] 
[ObjectPooling(Enabled=true, MinPoolSize=25, MaxPoolSize=100)]
[EventTrackingEnabled]
publicclass SoapEventClass : ServicedComponent, ISoapProbe
{
   publicvoid WriteLogMessage(
      DateTime timestamp,    //timestamp of the sample 
      string strSource,      //sourcer
      string strDest,        //destination - url webservice
      string strAction,      //action - webmethod
      string strMsgType,     //type of the call
      string strMsgId,       //identifier - guid
      object objMsgBody      //http headers + soap envelop
   )
{
   thrownew Exception("This class can be called only by the COM+ Event System");
}

The contract has only one method passing the SOAP Message contents and additional info about the source to the subscriber(s). This method is [OneWay] attributed, which is important for the remoting subscriber.

What is published

The Probe publishes a SAOP Extension state using the interface contract via the WriteLogMessage method with the following arguments, where:

• timestamp is the checkpoint DateTime

• strSource is the identifier of the stage, action, error, etc.

• strDest is the url address of the web service

• strAction is the web method

• strMsgType is the type of the event call. There are the following types generated by the Probe:

  								public
  								class SoapMessageType
  {
    publicconst string ClientReq = "0-SoapClientRequest";
    publicconst string ServerReq = "1-SoapServerRequest";
    publicconst string ServerRsp = "2-SoapServerResponse";
    publicconst string ClientRsp = "3-SoapClientResponse";
    publicconst string ClientReqErr = "0-SoapClientRequest_Err";
    publicconst string ServerReqErr = "1-SoapServerRequest_Err";
    publicconst string ServerRspErr = "2-SoapServerResponse_Err";
    publicconst string ClientRspErr = "3-SoapClientResponse_Err";
  }

• strMsgId is the GUID of the session call. Each call has own unique guid generated by the probe and using for all messages related with this call. It's travels in the SoapProbeTicket header.

• objMsgBody represents the log message body. It's a dictionary of the HttpHeaders and SOAP envelopes.

The following code snippet shows how objMsgBody is constructed:

Collapse

				//prepare a log message for its publishing 
				private
				void Write(string source, string msgType, string url, string action)
{
   string[] headers = null;
   HttpContext hc = HttpContext.Current;
   if(hc != null) 
   {
      NameValueCollection nvc = HttpContext.Current.Request.Headers;
      headers = new string[nvc.Count];
      for(int ii=0; ii<nvc.Count; ii++) 
      {
         headers[ii] = nvc.GetKey(ii) + "=" + nvc[ii];
      }
   }

   //soap stream
   newStream.Position = 0;
   StreamReader sr = new StreamReader(newStream);
   string strSoap = sr.ReadToEnd();
   newStream.Position = 0;

   //
   Hashtable htSoapMsg = new Hashtable();
   htSoapMsg[SoapMessageBody.HttpHeaders] = headers;
   htSoapMsg[SoapMessageBody.SoapStream] = strSoap;

   //publishing in manner of the fire & forget
   delegatePublisher delegator = new delegatePublisher(Publisher);
   delegator.BeginInvoke(DateTime.Now, source, url, action, msgType, 
                         m_ProbeTicket.ticketId, htSoapMsg, null, null);
}

Publisher

The Probe Publisher is simply and straightforward code. Its responsibility is to initiate the Event class and invoke the contract method on that class. The following code snippet shows this:

Collapse

				private
				void Publisher(
      DateTime timestamp,    //timestamp of the sample 
      string strSource,      //sourcer
      string strDest,        //destination - url webservice
      string strAction,      //action - webmethod
      string strMsgType,     //type of the call
      string strMsgId,       //identifier - guid
      object objMsgBody      //http headers + soap envelop
      ) 
{
   try 
   {
      //publishing
      using(SoapEventClass sec = new SoapEventClass()) 
      {
         sec.WriteLogMessage(timestamp, strSource, strDest, strAction, strMsgType,
                             strMsgId, objMsgBody);
      }
   }
   catch(Exception ex) 
   {
      Trace.WriteLine(string.Format("{0}[{1}]:Publisher catch = {2}",
                      this.GetType().FullName, this.GetHashCode(), 
                      ex.Message));
   }
}

Note that the Publisher runs in the background process using the delegate design pattern - see the previous code snippet implementation. This solution allows us to isolate the publisher from the subscribers. Because the publishers (worker threads) are running in the thread pool, there is no guarantee of their order in which they have been generated. It means that the Response message can be received before its Request one. So, the contents of the log message such as timestamp, id, and type are efficient to identify their order.

Checkpoints

Basically, there are four checkpoints suitable to publish their state marked as 0, 1, 2 and 3. The checkpoint calls the Publisher to make an event call to the Event System in the fire-forget manner.

The Probe fires the following events;

• 0 - SoapClientRequest
• 1 - SoapServerRequest
• 2 - SoapServerResponse
• 3 - SoapClientResponse

in the AfterSerialize and AfterDeserialize stages of the message processing. The following code snippet shows the checkpoints in the SoapExtension class:

Collapse

				public override void ProcessMessage(SoapMessage message) 
{
   switch (message.Stage) 
   {
      case SoapMessageStage.BeforeSerialize:
         SoapTicket(message);        //passportbreak;

      case SoapMessageStage.AfterSerialize:
         WriteOutput(message);       //publish state: 0-SoapClientRequest,//2-SoapServerResponsebreak;

      case SoapMessageStage.BeforeDeserialize:
         Copy(oldStream, newStream); //get the soap stream
         newStream.Position = 0;
         break;

      case SoapMessageStage.AfterDeserialize:
         SoapTicket(message);        //passport 
         WriteInput(message);        //publish state: 1-SoapServerRequest,//3-SoapClientResponsebreak;

      default:
         thrownew Exception("invalid stage");
   }
}

Plug-in

The Probe can be plugged into the SOAP infrastructure performing in one of the following ways:

• programmatically using the SoapProbeAttribute for the specified web method. In this case the client and server sides need a reference to the SoapMessageProbe assembly. This is a tight design pattern and hard coded solution. Note that this solution is suitable when only a specified web method on the server is going to be analyzed.

• administratively using the config file and <soapExtensionTypes> tag in the <webServices> config section.

  <configuration>
    <system.web>
      <webServices>
        <soapExtensionTypes>
          <add type="RKiss.SoapMessageProbe.SoapProbe, SoapMessageProbe, 
                     Version=1.0.1002.16362,Culture=neutral, 
                     PublicKeyToken=719b2bb9abf58c2d" priority="0" group="0" />
        </soapExtensionTypes>
      </webServices>
    </system.web>
  </configuration>

  There are two possibilities using the <soppExtensionTypes> in the config file. The first place is to modify the machine.config file, which it will automatically plugged the Probes for all web services on the box. The other option is to modify only an application config file such as the .exe.config or web.config files. I am recommending to use this option, it's controllable and loosely coupled with the application. See the Analyzer solution, where the Probes can be registered/unregistered to/from the specified web service on the fly.

In the both cases the SOAP infrastructure requires the type of the SOAP extension and access to its assembly (the best way is to install the Probe's assemblies into the GAC). The Probe doesn't have any config properties to be initialized during the c'tor time. It's a stateless object following the web service rules.

Note that the changes made in the .exe.config file will take effect after restarting its application. In the other applications such as ASP.NET where a web.config file is used, it's not necessary to manually restart the application - the web server will automatically refresh it.

Installation

The WebServiceProbe solution consists of the following projects:

• SoapMessageProbe.dll: this is the assembly of the SOAP extension
• SoapProbeEventClass.dll: this is an assembly of the event meta class and interface contract
• SoapProbeSubscriber2.dllthis is an assembly of the persistent subscriber to distribute the event calls remotely

Additionally there are also projects using the SOAP Probe:

1. SoapProbeSubscriber.dll - Analyzer subscriber
2. WebServiceAnalyzerStudio.exe - GUI to explore the SOAP Messages published by the Probes

Installation steps:

1. Launch the InstallSoapProbe.bat file to perform installation of the assemblies into the GAC and registry of the Enterprise Services in the COM+ Catalog.

2. Create administratively a persistent subscription for the SoapProbeSubscriber using the COM+ Explorer and Subscription Wizard. See the following picture:

At this time, the WebService Probe is installed on your machine and ready to use it. But ..., you will see no response from the Probe until you plug the Probe into the application and its subscriber is launched (locally or remotely).

The first condition has been described earlier, now we'll look at the second one - Subscriber - more closely.

Usage

The WebService Probe usage is dependant on its Subscriber. The Probe without using any subscriber is a passive publisher to fire an event for "null". Let's look at for them:

Subscribers

There can be many different subscribers designed and implemented for the WebService Probes. From the simplest one, (like writing the messages to the file system) to more complicated business control loops based on the strobed business knowledge base. Some solutions can be leaded to a more sophisticated model than the main application.

Basically, the Subscribers are divided into the following two groups:

• passive, where received information is used for post-processing such as monitoring, analyzing, modelling, simulation and other off-line tools.
• active, where received information is used to control business model - its workflow such as tuning, balancing and etc. - on-line solutions.

I included one simple Subscriber to distribute the event call on the Enterprise Network using .NET Remoting. Here are some details:

SoapProbeSubscriber2

This is a poolable ServicedComponent derived from the ISoapProbe interface. The object is initialized by the constructor string which represents a URL address of the remoting server object. Based on this string the remoting channel is registered either programmatically or administratively using the config file. Note that this component is activated as a server, so its host process is dllhost.exe and that's the reason why the config file is located in the %WINDIR%\system32 folder.

The Event method received the call from the Probe publisher and then forwarding it to the remoting infrastructure. It looks like a small bridge between the event system and remoting. Here is its implementation:

Collapse

				#region ISoapProbe
   [OneWay]
   publicvoid WriteLogMessage(
        DateTime timestamp, //timestamp of the sample 
        string strSource, //sourcer
        string strDest, //destination - url webservice
        string strAction, //action - webmethod
        string strMsgType, //type of the call
        string strMsgId, //identifier - guid
        object objMsgBody //http headers + soap envelop
        )
{
   try 
   {
      //fire & forget
      DelegateWriteLogMessage sn = new DelegateWriteLogMessage(onNotify);
      sn.BeginInvoke(timestamp, strSource, strDest, strAction, strMsgType,
                      strMsgId,objMsgBody, null, null);
   }
   catch(Exception ex) 
   {
      string msg = string.Format("Subscriber2.WriteLogMessage failed. Error={0}",
                                 ex.Message); 
      Trace.WriteLine(msg);
   }
} 

privatevoid onNotify(
       DateTime timestamp, //timestamp of the sample 
       string strSource, //sourcer
       string strDest, //destination - url webservice
       string strAction, //action - webmethod
       string strMsgType, //type of the call
       string strMsgId, //identifier - guid
       object objMsgBody //http headers + soap envelop
       )
{
   try
   {
      ISoapProbe robj = (ISoapProbe)Activator.GetObject(typeof(ISoapProbe), 
                                                        strTargetUrl);
      robj.WriteLogMessage(timestamp, strSource, strDest, strAction,
                            strMsgType, strMsgId, objMsgBody);
   }
   catch(Exception ex) 
   {
      string msg = string.Format("Subscriber2.onNotify failed. Error={0}", 
                                 ex.Message); 
      Trace.WriteLine(msg);
   }
}
#endregion

As you can see, the call spawns the worker thread to invoke the remoting method. Note that the remoting method is an [Oneway] attributed, so there is no waiting time for its response.

As a target object any remoting object derived from ISoapProbe using the standard (tcp/http) or custom channels such as MSMQ, WebService, etc. can be used: see my articles [3] and [4].

How powerful is the SOAP details published by the Probe is shown in my included solution called WebService Analyzer Studio? Here are more details:

WebService Analyzer Studio

The WebService Analyzer Studio is the GUI Subscriber to the WebService Probe(s) to explore the SOAP messages between the web services and their consumers. It has been designed and implemented (using the "as it is" methodology) to demonstrate power of the published knowledge base by SOAP Probe. It can be used for developing, testing and tracing the web service issues during the product lifecycle. Note that the Analyzer is a fully isolated, loosely coupled design pattern from your web services and their consumers.

The major features of the WebService Analyzer Studio:

• plug-in/unplug the Probes to/from the applications and web services on the fly

• storing the incoming samples from the Soap Probes in the TreeView layout

• exploring the samples (source, headers, soap, etc.)

• simulate the captured Request sample

• timestamp measurement

• soap message control flow

• storing samples in the circulated manner

• filtering samples on Error

• forwarding incoming samples to the remoting object

• subscribing to the Event System locally and remotely using the loosely coupled design pattern

• customizing the Analyzer behaviour on the fly

• store/load the customized option to/from the xml file

• it's free

The concept of the WebService Analyzer Studio is based on exploring the incoming event calls into the TreeView layout. Basically, there are two kinds of panels with the splitter. The left panel is dedicated to the probes, simulation of the SOAP Request calls and customizing. The second one, on the right side is for storing the incoming samples: event calls into the TreeView layout for the post-processing examination.

Probes Tab

The following screen shoot shows the list of the applications where the SOAP Probe has been registered or unregistered. The Analyzer will take care to modified or created config file for this application. The original config file (if it exists) is renamed for backup purposes. The TreeView nodes are persisted into the analyzer xml file and loaded during the start up process.

Simulation Tab

The incoming Request samples (client or server) can be selected for their simulation. This selection will make a send a copy of the sample to the Simulator Tab:

Clicking on the Run selection of the pop-menu of the HttpRequest node causes the POST Request to be sent to the web service. Its SOAP Envelope is a copy of the original one. Based on this Request call, the simulator will receive HttpResponse - see the above screen shoot. This is a great feature of the Analyzer, which allows to simulate a client's request in the post-processing manner. For instance, we can simulate the Request calls which cause the exception on the web method to debug the business rules, validation, etc. in the web service.

Customize Tab

Some Analyzer properties can be customized using the following PropertyGrid control.

You can configure storing the samples into the TreeView control such as number of samples, circulation mode, filtering on error or keeping the original formatted SOAP Envelop. For instance: the Analyzer can be hooked to the web service and store the SOAP error messages only in circulated storage with a specified number of samples.

Note that this feature is opened to enhance the Analyzer option. For instance, the triggering option can wait for a specified sample and then start or stop the storing samples in the storage.

Samples panel

This right-hand panel is dedicated to storing the incoming samples into the TreeView layout based on the general or the action node (web method node) option. All nodes are read-only. The TreeView layout is organized like is shown in the following screen shoot:

The samples can be expanded to show their contents including name, schema, value, etc. The first SOAP message initiates the sample session identified by the unique ID (GUID).

Some interesting pop-menu features:

• F2 Option - allows to modify properties

• F7 Simulate - request to simulate this message

• F9 Mark - mark the sample timestamp as a reference point for the time measurement between the samples. This feature allows to see timing control flow between any samples in milliseconds. It's valuable information when a performance issue is arising.

The Analyzer can be disconnected from the incoming samples by pressing the Master Switch on the status bar. The green icon indicates that the analyzer is connected to the Probe (either via the Event System or Remoting).

That's all for the WebService Analyzer Studio and I hope you will enjoy it. Now it's the time to make a first sample analyzing.

Analyzing First Sample

I built the TestSample solution to demonstrate capability of the WebService Analyzer Studio. You can fond it in the separate folder \Test:

1. TestWebService - ASP.NET Web Service
2. TestWebForm - ASP.NET Web Application (client)
3. TestWinForm - Windows Application (client)

The Probe and Analyzer have been implemented using .NET SP2 and tested on Windows 2000 Advanced Server and Windows 2000 Professional. It should be work without any problem also on XP machines.

Before using this test, the ASP.NET projects have to be deployed and installed on your web server. The TestSample solution is very simple like the "Hello world". The client invokes the web methods Test or Echo with many different types of the arguments included DataSet.

Test environment

First of all, it's necessary to have a functional test environment for TestSample solution without using the SOAP Probe and Analyzer. Be sure that their application config files have no plug-in of the SoapMessageProbe type in the webServices tag. Then try to make a quick test pressing the Test or Echo button on the Windows and Web Clients. After that, we can step-in to the using the SOAP Probe, (I am assuming that the SoapMessageProbe has been already installed - see Instalation).

There can be more scenarios to analyze the Web Service consuming. Depending from the Probe locations there can be the following major scenarios:

I. SOAP Probe on the client side

This is a simple scenario analyzing the web service consumer side - the Windows Application. The SOAP Probe is plugged-in to the SOAP extension of the web service client proxy. Here are the test steps:

1. Be sure that the applications such as SoapProbeEventClass and SoapProbeSubscriber are in the COM+ Catalog.

2. Launch the WebServiceAnalyzerStudio program

3. Be sure that the Analyzer is subscribed to the Event System (check the tooltip icon on the status bar)

4. Select the Probes Tab

5. Modify your Windows application path (full path name of the assembly, no extension)

6. Click on Register on the pop-menu

7. If the Registration succeeded, the Probe has been plugged-in to TestWindowsForm.exe.config.

8. In this moment, the test environment is ready to make a test

9. Press the Test or Echo Button on the client program

10. You should see two received samples by the Analyzer (Samples panel).

11. Now, the samples can be explored.

12. Select the node: 0-SoapClientRequest

13. Click Simulate on the pop-menu

14. Go to the Simulation panel and select the node: HttpRequest

15. Click the Run on the pop-menu

16. You should see the HttpResponse on the Simulation panel. Note that the Simulation using the POST/GET requests communication to the web service, so there are no samples published by the probe.

17. Repeat step 9 to capture more samples by the Analyzer.

II. SOAP Probe on the Web Server side

This scenario requires access to the Web Server and a decision where the Analyzer has to be located. There are the following choices:

1. Web Server - the solution is using the local Event System

2. Local Network - the solution is using the persistent subscription. Be sure it's enabled and the constructor string is addressed to your remote machine)

3. Web Server and Network - the solution is using the local Event System and persistent subscription

Let's select the first choice. The test steps are:

1. Be sure that the applications such as SoapProbeEventClass and SoapProbeSubscriber are in the COM+ Catalog.

2. Launch the WebServiceAnalyzerStudio program

3. Be sure that the Analyzer subscribed to the Event System (check the tooltip icon on the status bar)

4. Select the Probes Tab

5. Modify your web service and web application path (full path name of the assembly, no extension)

6. Click Register on the pop-menu for each of them Application nodes

7. If the Registration succeeded, the Probe has been plugged-in to their web.config files

8. In this moment, the test environment is ready to make a test

9. Press the Test or Echo Button on the client program

10. You should see, four received samples by the Analyzer (Samples panel).

11. Now, the samples can be explored.

12. Select the node: 0-SoapClientRequest or 1-SoapServerRequest

13. Click Simulate on the pop-menu

14. Go to the Simulation panel and select the node: HttpRequest

15. Click Run on the pop-menu

16. You should see the HttpResponse on the Simulation panel and captured samples by the Analyzer.

17. Repeat the step 9 to capture more samples by the Analyzer.

When the above test is working, you can close the Analyzer program and launch it on the Local Network using the .NET Remoting feature. This case will require you to enable the persistent subscription SoapProbeSubscriber and set it up properly such that the URL address of the remote Analyzer located in the Construct string is correct.

Major .NET technologies and techniques used in this solution

• XML Web Services

• SOAP and SOAP extensions

• COM+ Event System

• Remoting

• Windows Form

• TreeView Controls

• XmlDocument

• HttpRequest

• Multi-threading techniques

• Updating GUI in the background process

• Loosely coupled design patterns

Conclusion

Using LCE WebService Probes in the Distributed Application Framework to strobe the business workflow gives you an additional post-processing Knowledge Base which can be used for many things. This is an incremental development pyramid based on developing the suitable subscribers. In this article, I presented one of them - WebService Analyzer Studio - which is a small tool to examine the contents of the SOAP Messages.

References:

[1] http://www.codeproject.com/useritems/RemotingProbe.asp

[2] //MS.NETFrameworkSDK/cpguidenf/html/cpconalteringsoapmessageusingsoapextensions.htm

[3] http://www.codeproject.com/csharp/msmqchannel.asp

[4] http://www.codeproject.com/cs/webservices/remotingoverinternet.asp

Roman Kiss