Introduction

The ASP.NET membership feature reduces the amount of code you have to write to authenticate users and store their credentials. To quote MSDN:

“The ASP.NET membership gives you a built-in way to validate and store user credentials. You use the ASP.NET membership with Forms authentication and / or with the ASP.NET login controls for authenticating users.”

The membership provider needs to be specified in the Web.config configuration file. You can use your own custom provider or one of the default providers that ships with the .NET Framework, such as the SqlMembershipProvider provider.

All of the user related data is stored in a set of tables used by the ASP.NET membership system. In most cases you’ll use one set of tables per web application. However you can also reuse the same set to store the user credentials of multiple web applications. This effectively enables you to create one web application that acts as a portal allowing you to log in to one of these “virtual” applications.

However this isn’t possible out of the box. You have some work ahead of you, before you can support such dynamic applications.

Let’s get started…

Table Of Contents

• Introduction
• Application Context
• Dynamic Applications SqlMembershipProvider
• Login Control
• FormsAuthenticationHelper
• DynamicApplicationsModule
• FormsAuthenticationTicketExtensions
• PasswordRecovery & ChangePassword Controls
• Web Application Demo
• Summary
• Download

Application Context

Let’s start by examining the following Web.config entry:

Listing 1 – Web.Config ASP.NET Membership Configuration

<membership defaultProvider="SqlProvider">
  <providers>
    <clear />
    <add name="SqlProvider"
        type="System.Web.Security.SqlMembershipProvider"
        connectionStringName="YourConnectionStringName"
        applicationName="MyApplication"
      ... />
  </providers>
</membership>

These settings setup your web application to use the SqlMembershipProvider to manage your user credentials. All of the data related to your users is stored in the default ASP.NET membership tables.

Remark: This article is not a primer on ASP.NET membership, you should be familiar with it. Use the ASP.NET SQL Server Registration Tool (aspnet_regsql.exe) for setting up your database.

As mentioned before you can store the user credentials of multiple web applications in the same set of tables. Each web application separates their user data by partitioning them, in what I call, an application context. This application context is defined by the applicationName property of the membership provider. As you can see in Listing 1 the application name is “MyApplication”.

The SqlMembershipProvider uses this setting to determine in which context it should operate, all of the user data tied to this application name will be accessible by the ASP.NET membership library and login controls.

Unfortunately this setting is statically defined in the Web.config. You cannot easily change it during runtime. If you want to support dynamic applications, you need a way to control the value of the provider’s ApplicationName property. The solution lies in creating your very own ASP.NET Membership provider.

Top of page

Dynamic Applications SqlMembershipProvider

The SqlMembershipProvider retrieves the value for its ApplicationName property from the configuration settings contained in the Web.config file. We want to change the value which the getter of this property returns.

When logging in the user should make his intentions clear, in other words he has to specify which of the virtual applications he wants to access. For this purpose I require that the user not only specifies his username and password but also the virtual application he wants to access. From the user’s point of view I call this virtual application, the domain.

For example, suppose you have established a Sql Server database called AspNetMembership which contains the ASP.NET membership tables. This database contains the following virtual applications defined in the aspnet_Applications table:

• Northwind
• AdventureWorks

Each virtual application contains a user with the username “cgeers”. Now if I want to log in to the Northwind application I have to enter my username as “Northwind\cgeers”. For the AdventureWorks application this would be “AdventureWorks\cgeers”.

The part preceding the username is the application name or as far as the user is concerned this is the domain he has to enter in order to specify which virtual application he wants to access. The domain and the username are separated by a backslash.

When the user logs in using the ASP.NET Login control we have to extract the domain he entered and store this in a location which our custom membership provider can access. However we have to take into account that ASP.NET operates in a multithreaded environment. Each request received by ASP.NET is handled by a separate thread. We can’t store the domain in just any location, otherwhise other incoming requests might overwrite it. It must be tied to a single request.

The ideal place to store contextual information that is tied to an individual request is the current Http context. This contextual information is encapsulated by the HttpContext class.

Start up Visual Studio and create a new blank solution called “AspNetDynamicApplications”. Next add a new Class Library project to the solution named “CGeers.Web.Security”. Add references to the System.Configuration and System.Web assemblies. Our custom provider will descend from the default SqlMembershipProvider so these references are required.

Figure 1 – Visual Studio Solution

Rename the automatically generated Class1.cs file to DynamicApplicationsSqlMembershipProvider.cs and add the code shown in Listing 2.

Listing 2 – DynamicApplicationsSqlMembershipProvider

public class DynamicApplicationsSqlMembershipProvider : SqlMembershipProvider
{
    #region Fields

    private const string ApplicationNameSetting = "ApplicationName";

    #endregion

    public override string ApplicationName
    {
        get
        {
            HttpContext context = HttpContext.Current;
            if (context == null)
            {
                throw new InvalidOperationException("Http context cannot be null.");
            }

            string applicationName = String.Empty;
            if (context.Items.Contains(ApplicationNameSetting))
            {
                if (!String.IsNullOrEmpty((string)context.Items[ApplicationNameSetting]))
                {
                    applicationName = (string)context.Items[ApplicationNameSetting];
                }
            }
            return applicationName;
        }
        set
        {
            base.ApplicationName = value;
        }
    }
}

As you can see our custom membership provider descends from the default SqlMembershipProvider and overrides the ApplicationName property. We aren’t concerned with the setter, only with the getter. When the provider reads the ApplicationName property we get a handle to the current Http context by calling the static Current property of the HttpContext class. The obtained HttpContext object has a key/value collection property called Items. This collection stores the application name in an entry identified by the key “ApplicationName”. The name of this key is something you have to determine at design time.

Now each time our custom membership provider needs to determine the application name it calls the ApplicationName property which retrieves the value from the current Http context. This works in ASP.NET’s multithreaded environment as each request is tied to its own Http context.

Top of page

Login Control

Now that we a custom membership provider that retrieves the value for its ApplicationName property from the currect Http context, we still have to figure out a way to actually store the application name in the Http context.

The first time that a user specifies the virtual application or domain he wants to access is when he logs in. As mentioned earlier the user has to enter his username in the format <domain>\<username>. We have to create our own Login control which descends from the ASP.NET Login control. Upon user authentication we need to extract the entered domain and save it in the current Http context.

Add a new project using the Class Library template to your solution called “CGeers.Web.UI.WebControls”. Add the following references to the project:

• System.Configuration
• System.Web
• CGeers.Web.Security

Next delete the automatically generated Class1.cs file and add a new class called DynamicApplicationsLogin. Since the code for this class is quite lengthy I’ve chosen to break it up into several listings. After each listing a brief explanation of the code is added.

Listing 3 – DynamicApplicationsLogin Control Private Properties

public class DynamicApplicationsLogin : Login
{
    #region Fields

    private string _fullUserName;

    #endregion

    #region Properties

    private string ApplicationName
    {
        get
        {
            string[] data = base.UserName.Split(@"\".ToCharArray(), 2);
            string applicationName = (data.Length == 2) ? data[0] : String.Empty;
            return applicationName;
        }
    }

    private string BaseUserName
    {
        get
        {
            string[] data = base.UserName.Split(@"\".ToCharArray(), 2);
            string userName = (data.Length == 2) ? data[1] : base.UserName;
            return userName;
        }
    }

    #endregion

   // ...
}

As you can see the DynamicApplicationsLogin control descends from the standard ASP.NET Login control and a field called _fullUserName and two private properties ApplicationName and BaseUserName are added.

Since the user enters the domain and username into the same TextBox control we need to split up these parts. As you might guess the ApplicationName property extracts the domain and the BaseUserName returns the username. For example if the user enters Northwind\cgeers, the ApplicationName property would return “Northwind” and the BaseUserName property would return “cgeers”.

Listing 4 – DynamicApplicationsLogin Control OnAuthenticate Method

protected override void OnAuthenticate(AuthenticateEventArgs e)
{
    HttpContext context = HttpContext.Current;
    if (context == null)
    {
        throw new InvalidOperationException("Http context cannot be null.");
    }
    MembershipProvider provider = Membership.Provider;
    if (provider == null)
    {
        throw new InvalidOperationException("MembershipProvider cannot be null.");
    }
    provider = provider as DynamicApplicationsSqlMembershipProvider;
    if (provider == null)
    {
        throw new InvalidOperationException("The specified MembershipProvider must be of type DynamicApplicationsSqlMembershipProvider.");
    }

    // Store the application name in the current Http context's items collections
    context.Items["ApplicationName"] = ApplicationName;

    // Validate the user
    _fullUserName = UserName;
    UserName = BaseUserName;
    base.OnAuthenticate(e);
}

Next you need to override the Login control’s OnAuthenticate method to make sure that the user is validated inside the correct application context (virtual application).

First this method retrieves a reference to the current Http context, then it checks if the loaded membership provider is indeed our custom DynamicApplicationsSqlMembershipProvider. Then the entered domain or application name is stored in the current Http context’s Items collection so that our membership provider can retrieve the correct value for its ApplicationName property.

Last but not least the UserName property’s value is set to only contain the UserName by assigning the BaseUserName property to it. The private _fullUserName field temporarily stores the value the user entered (domain\username). You’ll see how this field is used later on.

After the application name has been stored in the Http context and the UserName property only contains the username the base implementation is called, this causes the username to be validated inside of the correct application context.

Listing 5 -DynamicApplicationsLogin Control OnLoginError Method

protected override void OnLoginError(EventArgs e)
{
    UserName = _fullUserName;
    base.OnLoginError(e);
}

Override the OnLoginError method and before calling the base implementation assign the _fullUserName field to the UserName property. When authenticating the user (OnAuthenticate method) the UserName property must only contain the username and not the domain, but when the authentication fails you need to make sure that the text the user entered in the TextBox control representing the UserName is reset to the value the user initially entered. Otherwhise it might be confusing for the user if the domain he entered disappears.

Listing 6 – DynamicApplicationsLogin Control OnLoggedIn Method

protected override void OnLoggedIn(EventArgs e)
{
    UserName = _fullUserName;
    HttpContext context = HttpContext.Current;
    if (context == null)
    {
        throw new InvalidOperationException("Http context cannot be null.");
    }

    string userName = BaseUserName;
    MembershipUser user = Membership.GetUser(userName);
    if (user != null)
    {
        string userData = String.Format("AN={0};", ApplicationName);
        HttpCookie cookie = FormsAuthenticationHelper.StoreUserDataInAuthenticationCookie(userName, userData, RememberMeSet);

        // Manually add the cookie to the Cookies collection
        context.Response.Cookies.Add(cookie);
    }
}

To finish the DynamicApplicationsLogin Control you need to override the OnLoggedIn method. The application name is stored in the UserData property of a FormsAuthenticationTicket. This authentication ticket is used by forms authentication to identify an authenticated user. Here we store it in a cookie and add it to the current Http context’s response. Later on, you’ll see why this is required.

Top of page

FormsAuthenticationHelper

It you take a look at Listing 6, you’ll see that the cookie containing the Forms Authentication ticket is created by a helper class called FormsAuthenticationHelper. This is a static helper class which only contains one method, namely StoreUserDataInAuthenticationCookie.

Add a new class called FormsAuthenticationHelper to the CGeers.Web.Security project and add the code shown in Listing 7.

Listing 7 – FormsAuthenticationHelper

public static class FormsAuthenticationHelper
{
    public static HttpCookie StoreUserDataInAuthenticationCookie(string userName, string userData, bool persistent)
    {
        if (String.IsNullOrEmpty(userName))
        {
            throw new InvalidOperationException("UserName cannot be null or empty.");
        }
        if (String.IsNullOrEmpty(userData))
        {
            throw new InvalidOperationException("User data cannot be null or empty.");
        }

        // Create the cookie that contains the forms authentication ticket
        HttpCookie cookie = FormsAuthentication.GetAuthCookie(userName, persistent);

        // Get the FormsAuthenticationTicket out of the encrypted cookie
        FormsAuthenticationTicket ticket = FormsAuthentication.Decrypt(cookie.Value);

        // Create a new FormsAuthenticationTicket that includes our custom user data
        FormsAuthenticationTicket newTicket = new FormsAuthenticationTicket(ticket.Version,
                                                                            ticket.Name,
                                                                            ticket.IssueDate,
                                                                            ticket.Expiration,
                                                                            persistent,
                                                                            userData);

        // Update the cookie's value to use the encrypted version of our new ticket
        cookie.Value = FormsAuthentication.Encrypt(newTicket);

        // Return the cookie
        return cookie;
    }
}

The StoreUserDataInAuthenticationCookie(…) method retrieves the cookie for the specified user (userName parameter) that contains the forms authentication ticket. Next the cookie is decrypted in order to access the FormsAuthenticationTicket object. Then a new FormsAuthenticationTicket is created based on the old ticket and the value contained in the userData parameter is stored within this ticket. As a last step, the new FormsAuthenticationTicket object is stored within an encrypted cookie.

Remark: The DynamicApplicationsLogin control stores sends this cookie back to the user, so the client needs to support cookies!

Top of page

DynamicApplicationsModule

Let’s recapitulate what we have so far.

• DynamicApplicationsSqlMembershipProvider: A custom membership provider that dynamically determines in which application context (application name) to operate.
• DynamicApplicationsLogin Control: A custom Login control that stores the domain (or application name) in the Http context of the ASP.NET request. This value is read by our custom membership provider.

So we have our custom membership provider that is able, per request, to determine the application context in which to operate and we have a custom Login control that identifies this context by requiring that users precede their username with a domain (= application name).

This works quite well if your web application only consists out of a login page. Remember that the custom membership provider determines the application context by reading the application name stored in the current Http context. With each request you make, a new Http context is created. When logging in the application name is explicitly stored within the Http context. However for any subsequent requests this is not the case. Somehow we have to make sure that the Http context is correctly initialized with the application name with each request after the user has logged in.

As mentioned earlier, the DynamicApplicationLogin control sends an encrypted cookie to the user after having successfully logged in. This cookie contains the application name and is sent along with each subsequent request. Voila, now all we need is a way to insert some logic into the ASP.NET request pipeline, in order to read the contents of this cookie and store the retrieved application name in the Http context.

A Http module is perfect for this situation. An Http module is called on every request and runs before and after a request is processed.

Add a new class called DynamicApplicationsModule to the CGeers.Web.Security project. This class needs to implement the IHttpModule interface. The code for this Http module is displayed in Listing 8.

Listing 8 -DynamicApplicationsModule

public class DynamicApplicationsModule : IHttpModule
{
    #region Fields

    private const string ApplicationNameSetting = "ApplicationName";

    #endregion

    #region IHttpModule Members

    public void Dispose()
    { }

    public void Init(HttpApplication context)
    {
        context.AuthenticateRequest += DetermineApplicationName;
    }

    #endregion

    private static void DetermineApplicationName(object sender, EventArgs e)
    {
        // Access the current Http application.
        HttpApplication application = sender as HttpApplication;
        if (application == null)
        {
            throw new InvalidOperationException("Http application cannot be null.");
        }

        // Get the HttpContext for the current request.
        HttpContext context = application.Context;
        if (context == null)
        {
            throw new InvalidOperationException("Http context cannot be null.");
        }

        // Read the application name stored in the FormsAuthenticationTicket
        string applicationName = String.Empty;
        if (context.Request.IsAuthenticated)
        {
            FormsIdentity identity = context.User.Identity as FormsIdentity;
            if (identity != null)
            {
                FormsAuthenticationTicket ticket = identity.Ticket;
                if (ticket != null)
                {
                    applicationName = ticket.GetApplicationName();
                }
            }
        }

        // Store the application name in the Items collection of the per-request http context.
        // Storing it in the session state is not an option as the session is not available at this
        // time. It is only available when the Http application triggers the AcquireRequestState event.
        context.Items[ApplicationNameSetting] = applicationName;
    }
}

The Init(…) method initializes a Http module and prepares it to handle requests. Here the HttpApplication’s AuthenticateRequest event is hooked to the DetermineApplicationName event handler.

The DetermineApplicationName(…) event handler checks if its dealing with an authenticated request and if so retrieves the FormsAuthentication ticket that was sent along by the client.

This ticket identifies the application context in which to operate. The application name is extracted from the ticket using the FormsAuthenticationTicket’s GetApplicationName() method. This is an extension method, I’ll address it in the following section.

Finally after extracting the application name from the ticket it is stored within the Http context so that our custom membership provider can read it.

Top of page

FormsAuthenticationTicketExtensions

Add a new class called FormsAuthenticationTicketExtensions to the CGeers.Web.Security project and add the code shown in Listing 9.

Listing 9 – FormsAuthenticationTicketExtensions

internal static class FormsAuthenticationTicketExtensions
{
    public static string GetApplicationName(this FormsAuthenticationTicket ticket)
    {
        // Check if the application name (AN=) is stored in the ticket's userdata.
        string applicationName = String.Empty;
        List<string> settings = new List<string>(ticket.UserData.Split(';'));
        foreach (string s in settings)
        {
            string setting = s.Trim();
            if (setting.StartsWith("AN="))
            {
                int startIndex = setting.IndexOf("AN=") + 3;
                applicationName = setting.Substring(startIndex);
                break;
            }
        }
        return applicationName;
    }
}  

As you can see in Listing 6 the DynamicApplicationLogin Control saves the application name in the UserData property of the FormsAuthenticationTicket by preceding it with the prefix “AN=”. Thus this extension method needs to take this into account when retrieving the application name from a FormsAuthenticationTicket.

Remark: Feel free to improve on the way the application name is stored within the ticket, but remember to implement the same system for the DynamicApplicationsLogin Control and this extension method.

Top of page

PasswordRecovery & ChangePassword Controls

Similar to the DynamicApplicationsLogin Control I’ve created controls that descend from the ASP.NET PasswordRecovery and Changepassword controls. If you want a user to be able to retrieve his password and/or change it, then you need to use these controls. They make sure that everything is executed within the correct application context.

The implementation is very similar to that of the DynamicApplicationsLogin control so I will not list the code of these controls here. If you want to check out the source code of these controls, then download the source code accompanying this article. You can find these controls in the CGeers.Web.UI.WebControls project.

• DynamicApplicationsPasswordRecovery: When a user wants to retrieve his password he has to enter his username. Just as with the Login control he needs to precede his username with the domain (= application name). The DynamicApplicationsPasswordRecovery control takes care of the rest and makes sure the username is verified within the correct application context.
• DynamicApplicationsChangePassword: Use this control on a page that requires that the user is logged in. In other words make sure that the user is already operating within the correct application context. Changing ones password happens to delete the cookie that stores the FormsAuthenticationTicket that contains the application name. This control solves this by generating a new cookie after the password has been changed.

Top of page

Web Application Demo

The source code accompanying this article also contains a demo web application project that demonstrates the DynamicApplicationsSqlMembershipProvider, the new Login controls, our custom Http module…and so on.

Figure 2 – Visual Studio Solution

In order to run this demo application please follow these steps:

1. Create an Sql Server database called PortalDatabase.
2. Register the ASP.NET Membership tables in this database using the ASP.NET SQL Server Registration Tool.
3. Add a connection string to the Web.config in the connectionStrings section pointing to the newly created database.
4. Add the necessary configuration settings to register the DynamicApplicationsMembershipProvider as the default ASP.NET membership provider. You still need to define a default value for its applicationName setting.
5. Start the ASP.NET Configuration website and create a new user. This user will be created for the application you specified in step 4.
6. Change the default application name for the ASP.NET membership provider. Relaunch the ASP.NET Configuration website and create another user account.
7. Add the DynamicApplicationModule to the httpModules section.
8. Make sure the authentication method is set to Forms and that cookies are enabled.

After following these steps you should be ready to run the demo web application. You created a database which contains two applications and a user for each application.

When you start the web application you are able to log in to each application by specyfing the application name (domain) followed by a backslash and the username. Ofcourse the user’s password is required too.

The Login controls we created take care of the rest and make sure that you are operating within the correct application context. Any subsequent calls with the ASP.NET membership library will trigger the custom membership provider to return the correct application name thus making sure these calls operate within the correct application context.

Remark: The demo web application’s Web.config file contains comments that specify everything that you need to do in order to properly setup the application. Be sure to check it out.

Top of page

Summary

This article showed you how can take use of the ASP.NET membership system to create a portal application that allows users to log in to one of many virtual applications.

The first key to realizing this is to create a custom membership provider that makes sure you operate within the correct application context by retrieving the value for the ApplicationName property from a storage location that is tied to an individual request.

By creating a custom Login control that descends from the standard ASP.NET Login control we are able to determine which application the user wants to access.

By encapsulating this information in an encrypted cookie we are able to automatically identify the application the user wants to access for each of his requests.

Top of page

Download

You can find the source code for this article on the Download page of this blog.

Top of page

Introduction

Most of the time when I need to consume a web service I do so using a .NET client built upon the Windows Communication Foundation (WCF). In most cases the web service in question has also been developed using .NET’s WCF.

About 8 years ago I used PHP as my primary tool for building web sites. At the time I used versions 3 & 4. Recently I had the opportunity to brush up my PHP skills by building a couple of small sites using PHP 5. Besides lending itself more towards object orientend programming I noticed that they added support for SOAP by adding the SoapClient class.

As PHP is still widely used it is not unimaginable, but likely very probably that PHP developers out there need to consume a web service that has been developed with WCF. This article explains how to create WCF services that offer support for PHP clients and how such clients can consume these services.

Let’s start coding…

Table Of Contents

• Introduction
• WCF Service
• Hosting The Service
• PHP Client
• MessageContract
• Revised PHP Client
• Summary
• Download

WCF Service

Before we can start consuming a WCF service we obviously need to create one. Let’s build a web service that offers exactly one method, namely for uploading a file to the server which hosts it.

Start an instance of Visual Studio and create a new blank solution called “WcfWithPhp”. Next add a WCF Service Library project and call it CGeers.Wcf.Services. A bunch of automatically generated files will be added to this project. Rename the IService1.cs file to IFileUploadService.cs and replace the generated code with the code shown in the following listing.

Listing 1 – IFileUploadService

[ServiceContract]
public interface IFileUploadService
{
    [OperationContract]
    bool Upload(Stream stream);
}

This is by far one of the simplest possible setups for a service that enables you to upload a file. The only parameter which you have to supply is the file itself (Stream parameter). Afterwards you’ll receive a boolean indicating if the upload succeeded or failed.

Now let’s quickly provide an implementation for this service contract. Rename the Service1.cs file to FileUploadService.cs and delete all of the boilerplate code. Your code should end up resembling the following structure:

Listing 2 – FileUploadService

public class FileUploadService : IFileUploadService
{
    public bool Upload(Stream stream)
    {
        try
        {
            // Generate a random filename
            // ...

            // Read the incoming stream and save it to file
            // ...
            return true;
        }
        catch (Exception)
        {
            // Gulp
            return false;
        }
    }
}

The listing above doesn’t show you the code for the actual implementation. Don’t fret about it, you can consult it in the source code accompanying this article. The code isn’t optimal, but this “Hello, World”-ish example it is sufficient.

The service generates a random filename based on a Guid and then reads the incoming stream and saves it to file. Afterwards it return true. If any exceptions should occur they are swallowed and the service will return false indicating that the upload failed. It’s not good practice to just swallow every possible exception, but once again this is just “illustrative code”.

As a final step delete the App.config file from the WCF Service Library project. In the next step we’ll setup a console application that acts as a host for our service.

Top of page

Hosting The Service

Add a new Console Application project to your solution named ConsoleHost. Add a reference to the System.ServiceModel assembly (WCF) and to the CGeers.Wcf.Services project. Then add the following code to the Main(…) method.

Listing 3 – Hosting The Service

static void Main()
{
    ServiceHost host = new ServiceHost(typeof(FileUploadService));
    host.Open();
    Console.WriteLine("FileUpload Service Host");
    Console.WriteLine("Service Started!");
    foreach (Uri address in host.BaseAddresses)
    {
        Console.WriteLine("Listening on " + address);
    }
    Console.WriteLine("Press any key to close the host...");
    Console.ReadLine();
    host.Close();
}

A service host for the FileUpload service type is created and opened. The service’s configuration is included in the application’s configuration file. So add an App.config file to the project and configure the service as shown below.

Listing 4 – Configuring The Service (App.config)

<system.serviceModel>
  <services>
    <service behaviorConfiguration="MyServiceBehavior"
             name="CGeers.Wcf.Services.FileUploadService">
      <endpoint address=""
                binding="basicHttpBinding"
                contract="CGeers.Wcf.Services.IFileUploadService">
        <identity>
          <dns value="localhost" />
        </identity>
      </endpoint>
      <endpoint address="mex" binding="mexHttpBinding"
                contract="IMetadataExchange" />
      <host>
        <baseAddresses>
          <add baseAddress="http://localhost:8731/FileUploadService" />
        </baseAddresses>
      </host>
    </service>
  </services>
  <behaviors>
    <serviceBehaviors>
      <behavior name="MyServiceBehavior">
        <serviceMetadata httpGetEnabled="True"/>
        <serviceDebug includeExceptionDetailInFaults="False" />
      </behavior>
    </serviceBehaviors>
  </behaviors>
</system.serviceModel>

As you can see there is nothing special about this particular configuration. Two endpoints are made available, one for the service itself and another one for exposing it’s metadata (mex). The transport medium is the HTTP protocol so we can choose one of the interoperable http-enabled bindings.

However since the client application will be build using PHP built-in SoapClient class we have to opt for the basicHttpBinding as it conform to the WS-I Basic Profile 1.1 and PHP offers no additional support for any other standards.

Run the console application to make sure it builds and executes correctly. When the application is running you should be able to enter the service’s address in your favorite browser. The result should be the familiar web service test page.

Figure 1 – FileUploadService Test Page

Top of page

PHP Client

The PHP script which consumes the service is built using PHP 5.2.0, served by Apache 2.2.3 and running on Windows XP. Your setup might differ, but make sure that your PHP 5.x version supports the SoapClient class.

Make sure that the ConsoleHost application is running while you execute your script. The actual script is surprisingly simple.

Listing 5 – PHP Client Script

<?php

// Function to read the contents of a file
function GetFileContents( $filename ) {
  $handle = fopen($filename, "r");
  $contents = fread($handle, filesize($filename));
  fclose($handle);
  return $contents;
}

// Create a new soap client based on the service's metadata (WSDL)
$client = new SoapClient("http://localhost:8731/FileUploadService?wsdl");

// Specify the file to upload
$filename = "test.txt";

// Specify the parameters for the Upload(...) method as an associative array
$parameters = array("stream" => GetFileContents($filename));

// Upload the file
$result = $client->Upload($parameters);

// Check if the upload succeeded
if ($result) {
    echo $filename . " uploaded";
}
else {
    echo $filename . " upload failed";
}

?>

The comments in the code adequately explains what it performs. To recap, a soap client is created using the service’s metadata (WSDL), the contents of the file you want to upload are read and put in an associative array. Then the client calls the Upload method and passes in this array to actually upload the file. Finally the return value is checked to determine whether the upload succeeded.

If you execute the PHP script a couple of times you will see a number of GUID-named .dat files appearing in the same folder that hosts your ConsoleHost.exe application.

Figure 2 – Uploaded files

While testing my script I choose to upload a simple text file (test.txt), but any file will do. Just make sure to adjust your PHP script accordingly. When uploading large files your WCF service might time out and throw an exception. You need to adjust your service’s timeout settings in this case.

Top of page

MessageContract

The “Hello, World” example I choose for this article enables you to upload a file. I particularly choose this functionality as it lends itself quite easily to implement the MessageContract attribute. As you can see in Listing 1 the Upload(…) method only takes only one parameter, namely a stream of the file itself. When using a stream to upload a file (or any arbitrary data) it can be the only parameter passed in the body of the request.

Since we are using the HTTP transport and SOAP it can be the only parameter in the body of the soap message / envelope. If we want to send extra parameters along, then we have to insert these in the header of the request / SOAP message. This is where the MessageContract attribute comes to the rescue. It helps us shape the SOAP envelope and determine what is placed in the header and what is placed in the body of the SOAP message.

Suppose we want to send the original filename and filesize (expressed in bytes) along with the actual file itself (Stream parameter). To do this add a new class FileUploadInputParameter to the CGeers.Wcf.Services project and add the following code to it:

Listing 6 – FileUploadInputParameter

[MessageContract]
public class FileUploadInputParameter
{
    [MessageHeader(MustUnderstand = true)]
    public string FileName { get; set; }

    [MessageHeader(MustUnderstand = true)]
    public int FileSize { get; set; }

    [MessageBodyMember(Order = 1)]
    public Stream Stream { get; set; }
}

By decorating the FileUploadInputParameter class with the MessageContract attribute you define a strongly-typed class that corresponds to a SOAP message. Using the MessageHeader and MessageBodyMember attribute you can specify which properties of the class are respectively placed in the header and which are to be inserted in the body.

Remark: WCF states that when using the MessageContract attribute in your service operation that you cannot mix it with regular serializable parameters. Either only use custom message types (= class types decorated with the MessageContract attribute) or only use regular serializable parameters for the input parameters and return value of your service operation.

This means we have to use a custom message type for the return value of our service operation as well. Since this is only a boolean let’s quickly wrap it in a new class type and decorate it with the necessary attributes. Add a new class FileUploadReturnValue to the CGeers.Wcf.Services project and add the code shown in Listing 7 to it.

Listing 7 – FileUploadReturnValue

[MessageContract]
public class FileUploadReturnValue
{
    [MessageBodyMember(Order = 1)]
    public bool UploadSucceeded { get; set; }
}

This message type does not include any headers and places one single boolean named UploadSucceeded in the body of the envelope.

Voila, the message contracts are in place. Let’s add a new service operation to our service (IFileUploadService.cs). Very originally I’ve named it UploadWithMessageContract(…).

Listing 8 – UploadWithMessageContract(…) Service Operation

[OperationContract]
FileUploadReturnValue UploadWithMessageContract(FileUploadInputParameter file);

The implementation of this new service operation in the FileUploadService class is very simular to that of our regular Upload(…) method. The only difference is that instead of generating a random filename based on a Guid we use the filename provided to us. Also note that the return value (true / false) is being wrapped in our custom message type (FileUploadReturnValue).

Listing 9 – UploadWithMessageContract Implementation

public FileUploadReturnValue UploadWithMessageContract(FileUploadInputParameter file)
{
    try
    {
        // Read the incoming stream and save it to file
        SaveFile(file.FileName, file.Stream);
        return new FileUploadReturnValue {UploadSucceeded = true};
    }
    catch (Exception)
    {
        // Gulp
        return new FileUploadReturnValue {UploadSucceeded = false};
    }
}

Since the Upload(…) and UploadWithMessageContract(…) methods both use the same code for saving the incoming file I’ve moved this code to a separate helper method named SaveFile(string filename, Stream stream). Check the accompanying source code to see the code for this method.

Top of page

Revised PHP Client

We have to revise our PHP client a bit before we can call the new UploadWithMessageContract(…) method. Here’s the adjusted code:

Listing 10 – Revised PHP Client

<?php

// Function to read the contents of a file
function GetFileContents( $filename ) {
  $handle = fopen($filename, "r");
  $contents = fread($handle, filesize($filename));
  fclose($handle);
  return $contents;
}

// Create a new soap client based on the service's metadata (WSDL)
$client = new SoapClient("http://localhost:8731/FileUploadService?wsdl");

// Specify the file to upload
$filename = "test.txt";

// Twee headers (FileName & Length) wordt in de SOAP envelope geplaatst
$headers[] = new SoapHeader('http://tempuri.org/',
                            'FileName',
                            "test.txt");

$headers[] = new SoapHeader('http://tempuri.org/',
                            'FileSize',
                            filesize($filename));

$client->__setSoapHeaders($headers);

// Specify the parameters for the Upload(...) method as an associative array
$parameters = array("Stream" => GetFileContents($filename));

// Upload the file
$result = $client->UploadWithMessageContract($parameters);

// Check if the upload succeeded
if ($result->UploadSucceeded) {
    echo $filename . " uploaded";
}
else {
    echo $filename . " upload failed";
}

?>

The only adjustments made here all the creation of the soap headers and their injection into the SOAP message. The rest is simular to that of the example shown in Listing 5. Because the response message has also been wrapped inside a custom message type the check to read the response is also slightly different.

Top of page

Summary

I hope you enjoyed this article which demonstrated the interoperability between .NET and PHP 5 using web services. Exchanging data over the HTTP transport using SOAP (v1.1) messages is a breeze between these two technologies.

Setting up your WCF service and exposing it through an endpoint which uses the httpBasicBinding enables PHP clients to consume these services through the SoapClient class. Service operations which require data to be included through the use of SOAP headers (MessageContract attribute) can also be called using PHP 5 built-in SOAP supported provided ofcourse that you include this information in the headers.

Top of page

Download

You can find the source code for this article on the Download page of this blog.

The source code only contains the C# code for the WCF service. The entire PHP code for creating the clients can be found in Listing 5 & 10.

Top of page

Introduction

The subject of this article is a tad less modern than the previous two articles: WCF over HTTPS & MEF. Instead of focusing on a modern technology such as WCF or the upcoming Managed Extensibility Framework, I have a craving to write an article about the good ol’ FileSystemWatcher Class.

It’s been around since .NET 1.0 but the other day when I was composing the article about MEF it was brought back to my attention. MEF contains a DirectoryCatalog type, which allows you to specify a directory that contains assemblies that in turn contain extensions (exports) for your application.

In an earlier preview of MEF the DirectoryCatalog type automatically detected new assemblies placed inside of this directory and refreshed the loaded extensions. However this functionality has been dropped in favor of a Refresh() method which you have to call yourself. In other words you are now responsible for detecting new additions to said directory.

The main focus of this article is on how to use the FileSystemWatcher class type effectively for monitoring a directory for new, incoming files. Enough introductionary chit-chat, let’s get to the meat of it…

Table Of Contents

• Introduction
• Hello, World!
• The Basics
• Handling The Created Event
• Large Volumes
• Asynchronous Processing
• Applied to MEF
• Summary
• Download

Hello, World!

I usually build demo applications in order to get my point accross and this article is no different. Let us not ponder about MEF’s DirectoryCatalog type but instead focus on a more “Hello, World!”-ish example.

Imagine an application which needs to monitor a directory for newly added text files. These text files needs to be processed and deleted afterwards .

In the real-world you would probably use a Windows service for this type of application as no real GUI is needed, but since this is a demo and some kind of output is preferable the .NET’s universe black gold comes in handy. You guessed it, let’s create another fancy console application.

For starters fire up Visual Studio and create a new blank solution called “FileSystemWatcher”. Next add a new console application project named “ConsoleMonitor”. We’re now ready to lay the groundwork…

Top of page

The Basics

In order to setup a FileSystemWatcher for the purpose of monitoring a directory you need hook it up properly. The following properties and events relate to our demo:

Properties:

• Path: Identifies the path of the directory to watch
• Filter: Filter used to determine which files are monitored (e.g.: *.txt, *.xml…etc.)
• EnableRaisingEvents: The most important one of all. By default it is false, but you need to set it to true to enable the FileSystemWatcher instance. If you don’t do this then it will not raise any events when files are created, deleted, changed…etc. In a Windows service you would set this property to true upon starting the service and to false when stopping it.

Another useful property is IncludeSubDirectories. By default it is set to false, but by setting it to true the FileSystemWatcher will also monitor the subdirectories found within the specified path.

Events:

• Created: This event is triggered whenever a file or directory in the specified path is created. By specifying a filter you opt to only receive notifications for the type of files you specified.

Similarly the events Changed, Deleted and Renamed are also available. Their name implies when they are triggered. Since the focus of our demo only deals with newly created files we don’t need these. Feel free to explore these events on your own.

Let’s setup the basics for our console application. Your code should resemble that of Listing 1:

Listing 1 – Monitoring A Directory

class Program
{
    private static FileSystemWatcher watcher;

    static void Main()
    {
        // Make the directory being monitored exists
        Assembly assembly = Assembly.GetCallingAssembly();
        string path = Path.Combine(Path.GetDirectoryName(assembly.Location), "input");
        if (!Directory.Exists(path))
        {
            Directory.CreateDirectory(path);
        }

        watcher = new FileSystemWatcher {Path = path, Filter = "*.txt"};

        watcher.Created += file_Created;
        watcher.EnableRaisingEvents = true;

        Console.WriteLine("Press any key to close this application...");
        Console.ReadLine();
    }

    static void file_Created(object sender, FileSystemEventArgs e)
    {
        // Process the file
    }
}

The code checks for a directory “Input” in the location of the executing assembly and creates if not available. Then a FileSystemWatcher instance is being setup to monitor this directory for any new text files. If a new text file is created within this directory then the file_Created(…) event handler will be triggered.

Top of page

Handling The Created Event

Being an event handler the file_Created(…) method receives two parameters, namely the Sender and an EventArgs descendant. The Sender is the FileSystemWatcher instance itself and for the EventArgs you receive a FileSystemEventArgs instance. It contains a few useful properties describing the newly created file.

• ChangeType: The type of directory event that occured (e.g.: Changed, Created, Deleted, Renamed). Is an enumeration of type WatcherChangeTypes.
• FullPath: The fully qualified path of the file.

We only need to concern ourselves with the FullPath property. At first sight you might process the files in the following manner:

Listing 2 – Processing A File

static void file_Created(object sender, FileSystemEventArgs e)
{
    // Process the file
    // ...

    // Delete the file after it has been processed
    File.Delete(e.FullPath);
}

This might sometimes work and on other occasions an IOException will be thrown indicating that the file is currently being used by another process.

This is caused by the fact that the FileSystemWatcher triggers the Created event immediately after the first byte of the new file has been written. It does not wait to trigger this event until the file has been completely created or uploaded.

Processing the files directly from within this event handler will eventually result in one or more IOExceptions being thrown because the creation process might still be busy creating the file and thus disallow another process from accessing it.

I have not found a proper solution to this problem and upon searching the net I found out that the following approach is usually implemented:

Listing 3 – IsFileUploadComplete

private static bool IsFileUploadComplete(string path)
{
    try
    {
        using (File.Open(path, FileMode.Open, FileAccess.Read, FileShare.None))
        {
            return true;
        }
    }
    catch (IOException)
    {
        return false;
    }
}

The above piece of code tries to open the file exclusively for reading. If it fails an IOException is thrown indicating that the file is still being used by another process. If you have a better approach please suggest it by posting a comment or e-mailing me directly.

The event handler for the Created event is then implemented as follows:

Listing 4 – Revised file_Created(…) Event Handler

{
    // Check if the file has been completely created / uploaded
    int maximumProcessRetries = 5;
    int delayBeforeRetry = 5000;

    int attempts = 0;

    while (true)
    {
        if (IsFileUploadComplete(e.FullPath))
        {
            // Process the file
            // ...

            break;
        }
        attempts += 1;
        if (attempts >= maximumProcessRetries)
        {
            // Log the error and send out notifications
            /// ...etc.
            break;
        }
        Thread.Sleep(delayBeforeRetry);
    }

    // Delete the file after it has been processed
    File.Delete(e.FullPath);
}

When a new file is created an attempt to exclusively access the file is made. If it fails the thread waits for a certain amount of time before trying again. This is repeated for a maximum number of X times. Feel free to adjust the code and perhaps make the number of retries or the delay configurable.

Not the nicest solution, but effective for most times the FileSystemWatcher is put to use…

Top of page

Large Volumes

Until now processing the files has been handled directly within the event handler attached to the FileSystemWatcher’s Created event. This poses no problem if you only need to handle the occasional file, but can be problematic if you need to process large batches of files.

Each FileSystemWatcher allocates a buffer of 8 Kb that contains all the information about the files that cause events to be raised. When a large number of files are created in the directory being monitored and the processing of each file takes up a considerable amount of time then this buffer may fill up. Any events that arrive after the buffer has been filled up will be lost. No exceptions or notifications will be thrown for these missing events.

The most obvious to circumvent this issue (or at least postpone it) is to increase the size of the buffer. This can be done by setting the InternalBufferSize property of the FileSystemWatcher.

To quote MSDN: “The file system changes stored in this buffer can use up to 16 bytes of memory, not including the file name. If there are many changes in a short time, the buffer can overflow. This caused the component to lose trackof changes in the directory.“.

So simply increasing the buffer size might do, but it also has a ramification, namely that it is quite expensive as the memory is non paged and cannot be swapped out to disk. It is better to use a small buffer and filter out any notifications you do not require.

There is another possible solution to postpone a buffer overflow from occuring. By handling the events you monitor, the Created event in this case, as quickly as possibly you remove the information tied to the event from the buffer so that it can reclaim this space. Credit where credit is due as this is proposed by Rohan Warang, read his article on csharp-codesamples.com.

To implement this we need to asynchronously process the files. As soon as the event is triggered we queue the full path to the file in a Queue which in turn will be processed by a worker thread. The duty of the event handler tied to the Created event is reduced to adding a string (the file path) to a queue.

Let’s realize this. Add a new class to the console application project named FileProcessor. Add the following code:

Listing 5 – FileProcessor Class

public class FileProcessor
{
    private readonly Queue<string> files = new Queue<string>();

    public void EnqueueFile(string path)
    {
        files.Enqueue(path);
    }
}

The code for the event handler attached to the created event can then be minimized to this:

Listing 6 – Queuing The File

//...
private static readonly FileProcessor fileProcessor = new FileProcessor();
//...
static void file_Created(object sender, FileSystemEventArgs e)
{
    fileProcessor.EnqueueFile(e.FullPath);
}

Top of page

Asynchronous Processing

How the files are actually asynchronously processed by a FileProcessor instance has little to do with the FileSystemWatcher but let’s quickly cover it to get it out of the way.

Start by adding the following fields to the FileProcessor class.

Listing 7 – FileProcessor Fields

#region Fields

private readonly Queue<string> files = new Queue<string>();
private Thread thread;
private readonly EventWaitHandle waitHandle = new AutoResetEvent(true);
private static readonly object lockObject = new object();

// Volatile is used as hint to the compiler that this data
// member will be accessed by multiple threads.
// http://msdn.microsoft.com/en-us/library/7a2f3ay4(VS.80).aspx
private volatile bool shouldStop = false;

#endregion

Obviously we need to declare a new queue which contains a list of String types (the paths to the files) and a new separate thread. Since this queue is accessed by multiple threads we need a lock object for synchronization purposes. The other fields waitHandle and shouldStop are used to determine if the second thread should continue with executing its worker method.

With these fields in place the EnqueueFile(…) method can be revised.

Listing 8 – Enqueuing The File Revised

public void EnqueueFile(string path)
{
    // Queue the file
    lock (lockObject)
    {
        files.Enqueue(path);
    }

    // Initialize and start the worker thread when the first file is queued
    // or when it has been stopped and thus terminated.
    if (thread == null || shouldStop)
    {
        thread = new Thread(new ThreadStart(Work));
        thread.Start();
    }
    // If the thread is waiting then start it
    else if (thread.ThreadState == ThreadState.WaitSleepJoin)
    {
        waitHandle.Set();
    }
}

The file is added to the queue. If it is the first file than the worker thread is created and started, if not then a check is performed to see if the waithandle should be signaled. The worker method is coupled to a worker method by using the ThreadStart delegate. This worker method aptly named Work() contains no parameters or return type and is implemented as follows:

Listing 8 – The Method That Executes On The Worker Thread

private void Work()
{
    while (!shouldStop)
    {
        string path = String.Empty;
        lock (lockObject)
        {
            if (files.Count > 0)
            {
                path = files.Dequeue();
            }
        }

        if (!String.IsNullOrEmpty(path))
        {
            // Process the file
            ProcessFile(path);
        }
        else
        {
            // If no files are left to process then wait
            waitHandle.WaitOne();
        }
    }
}

This method dequeues an item of the queue and hands it off to the ProcessFile(…) method for further processing. The ProcessFile(…) method basically contains the code shown in Listing 4. The IsFileUploadComplete(…) method (Listing 3) is also moved to the FileProcessor method as a private helper method. The volatile shouldStop boolean is checked wether or not the FileProcessor should continue to process the queue. This enables you to add a method called StopProcessing() which you can call to stop the processing. Enqueuing another file afterwards would restart it.

This basically sums up the internal workings of the FileProcessor type. Please consult the accompanying source code for a working example.

Top of page

Applied To MEF

Let’s briefly bring up MEF again. When using a DirectoryCatalog to import all the exports available in the assemblies listed in the directory to which the catalog is tied, it is possible to use the FileSystemWatcher to monitor it. You only need to call the DirectoryCatalog’s Refresh() method when new assemblies are added.

Listing 10 – Refreshing A DirectoryCatalog

static void file_Created(object sender, FileSystemEventArgs e)
{
    directoryCatalog.Refresh();
}

Top of page

Summary

Voila, that wraps up my article about the FileSystemWatcher. Though not the hottest or most modern topic I think it is still usefull today for various situations.

When using it you should be careful to make sure that the Created event is triggered as soon as the first byte of the file is written, not when the file has been completely created / uploaded. The internal buffer of the FileSystemWatcher can also overflow if your processing of the files takes up too much time while incoming notifications are still being generated.

I’ve tested this approach using 10.000 files and the default buffer size without any problems, which should be adequate enough for most the situations.

Top of page

Download

You can find the source code for this article on the Download page of this blog.

Top of page

Introduction

Yesterday, on a sunny sunday morning I was catching up on some blog reading. One post in particular caught my eye, namely A Whirlwind Tour Through The Managed Extensibility Framework by Bart De Smet.

The Managed Extensibility Framework, or MEF, is a new library that will eventually be part of the .NET 4.0 Framework. It enables you to easily create extensible applications that support a plugin model. A lot of modern, popular applications such as FireFox, Winamp, Visual Studio…etc. already provide a plugin / add-in model that allows you to add your own plugins if you want to extend the functionality of the application.

Making your application extensible in the past was certainly possible but you had to create the infrastructure from scratch. Well, no more! MEF allows you to expose certain parts of your application in which you can import built-in or external extensions.

Let’s discover the wonderful world of MEF by building a demo application…

Table Of Contents

• Introduction
• MEF Preview
• Hello, World!
• Extensibility
• Importing ILogger Implementations
• Export ILogger Implementations
• Catalogs
• Summary
• Download

MEF Preview

Although the .NET 4.0 Framework has not been released yet, you can download a preview of MEF on Codeplex. At the time of writing the latest release is preview 6. Go ahead and download it.

After extracting the contents of the MEF_Preview_6.zip file you’ll get an entire solution. You only to need to add a reference to the assembly called System.ComponentModel.Composition.dll found in the bin folder to the projects which you want to MEF-enable.

For more information you can consult the MEF Programming Guide on CodePlex.

Top of page

Hello, World!

Before entering the world of MEF let’s first setup an example application which we can rewrite later on. Start up Visual Studio and create a new blank solution called “Mef” and add a new ConsoleApplication project aptly named ConsoleApplication.

I prefer Console applications for short demos as I don’t have to bother with any GUI design. As for the code of this ingenious application please take a look at Listing 1. Prepare to be amazed at the complexity of the code…

Listing 1 – Hello, World! Console Application.

class Program
{
    static void Main()
    {
        ConsoleLogger logger = new ConsoleLogger();
        logger.Log("Hello, World!");
        Console.ReadLine();
    }
}

public interface ILogger
{
    void Log(string message);
}

public class ConsoleLogger : ILogger
{
    public void Log(string message)
    {
        Console.WriteLine(message);
    }
}

As you can see one interface, ILogger, is declared which contains a method Log(string message) which takes one string parameter called message. The ConsoleLogger class provides an implementation for this interface and writes the message parameter out to the console window.

Finally the Main(…) method of the console application instantiates a ConsoleLogger object and calls it’s Log(…) method in order to print a message to the console window. It can’t get much simpler than this…

Remark: Listing 1 shows all the code as if it were located in the same source file. If you prefer you can place it in seperate code files. I have done so for the source code accompanying this article.

Top of page

Extensibility

Suppose I don’t want to limit my “logging application” to only be able to log messages to the Console window. I’m not going to look at the console window 24/7, so it might come in handy if the application was able to log it’s messages to more than one target. Instead of printing messages to the console window it could e-mail them, write them to an event log, to a file…etc.

Let’s create another implementation for our ILogger and rewrite the application to support multiple loggers.

Listing 2 – Supporting Multiple Loggers

class Program
{
    public static IEnumerable<ILogger> Loggers { get; set; }

    public static void Log(string message)
    {
        foreach(ILogger logger in Loggers)
        {
            logger.Log(message);
        }
    }

    static void Main()
    {
        Loggers = new List<ILogger> {new ConsoleLogger(), new FileLogger()};
        Log("Hello, World!");
        Console.ReadLine();
    }
}

public class FileLogger : ILogger
{
    public void Log(string message)
    {
        // Write the message to a file
    }
}

Voila, now our application supports multiple loggers. In the future you can add additional loggers by adding them the Loggers collection in the Main(…) method. But that means changing the source code of the application and recompiling it. Wouldn’t it be neat if the application was smart enough to figure out which Logger implementations it would need to use? Enter MEF…

Top of page

Importing ILogger Implementations

In it’s most simplest form MEF is as simple as 1-2-3. First you need to define the needed parts (Imports & Exports) and then you hand them over to MEF so that the framework can compose the parts.

To MEF-enable our logging application only three simple steps need to be followed. First we need to create, what I like to call, an extensibility point for our application.

From our application’s point of view it needs to collect all the ILogger implementations it can find and add them to a collection. Let’s rewrite our logging logic once again.

Add new class Logger to the console project and paste in the following code.

Listing 3 – Logger class

public class Logger
{
    public Logger()
    {
        Loggers = new List<ILogger>();
    }

    public IEnumerable<ILogger> Loggers { get; set; }

    public void Log(string message)
    {
        foreach (ILogger logger in Loggers)
        {
            logger.Log(message);
        }
    }
}

The static Main(…) method could then simply log it’s message this way:

Listing 4 – Instantiating A Logger

...
Logger logger = new Logger();
logger.Log("Hello, World!");
...

But first the different ILogger implementations need to be added to the Loggers property of the Logger object. This collection property of type IEnumerable<ILogger> is going to act as our “extensibility point”.

Listing 5 – ImportMany Attribute

[ImportMany(typeof(ILogger))]
public IEnumerable<ILogger> Loggers { get; set; }

By decorating the Loggers property with the ImportMany attribute we are basically notifying the MEF framework that this property accepts ILogger implementations or exports.

Remark: MEF also offers an Import attribute if you only want to import one instance instead of an entire collection. You can read more about declaring imports in the MEF Programming Guide.

Top of page

Export ILogger Implementations

As it stands now the logging logic is being handled by the Logger class and all the console application does is create a Logger object and call it’s Log(…) method. If you were to run the application now nothing would be logged.

We still need to tell MEF were it can find the ILogger implementations. We need to mark the ILogger implementations or export them in MEF parlance.

Listing 6 – Export Attribute

[Export(typeof(ILogger))]
public class ConsoleLogger : ILogger
{
    // ...
}

[Export(typeof(ILogger))]
public class FileLogger : ILogger
{
    // ...
}

By decorating the ConsoleLogger and FileLogger class types with the Export attribute you make them available to the MEF framework. By specifying the type of the ILogger interface the framework will be able to bind these types to our “extensibility point” we created earlier.

Top of page

Catalogs

The imports and exports are also called composable parts. Now that all the parts are in place to form our compisition the last thing we need to do is to tell MEF how it should bind the exports to the imports. This is done using catalogs.

Using a catalog you can list all of the ILogger implementations you want to provide to the Logger class. Add the following code to the Main(…) method of the console application:

Listing 7 – TypeCatalog

TypeCatalog catalog = new TypeCatalog(typeof(ConsoleLogger), typeof(FileLogger));
CompositionContainer container = new CompositionContainer(catalog);
container.ComposeParts(logger);

The above example creates a TypeCatalog and adds the ConsoleLogger and FileLogger types to it. Next a CompositionContainer is created passing in the catalog. The container then composes all of the parts using our Logger instance. The magic that happens in the container makes sure that our loggers get instantiated and added to the IEnumerable<ILogger> collection of the Logger object.

Starting the application now will log the “Hello, World!” message to the Console window and to file. However when you want to create a new logger type you still need to adjust the code and add the new type to the TypeCatalog. That’s not what we want. Luckily MEF provides you with different types of catalogs. Consider the following examples:

Using the AssemblyCatalog type you can discover all of the exports in a given assembly. In this example the currently executing assembly is used but any other will do.

Listing 8 – AssemblyCatalog

AssemblyCatalog catalog = new AssemblyCatalog(Assembly.GetExecutingAssembly());

Listing 9 – DirectoryCatalog

DirectoryCatalog catalog = new DirectoryCatalog(@"c:\temp\loggers");

Using a DirectoryCatalog you can scan all of the assemblies in a specified directory. This catalog type will certainly come in handy if you plan on building your own plugin system. Third party providers can then create their own plugins and place them in a certain directory so that the application can detect them.

To enable this for our logging application please follow these steps:

1. Move the ILogger interface to a new class library project called Interface. Add a reference to the Interface library from the console application project.
2. Add a new class library project called ThirdPartyLogger. Add references to the Interface library and the System.ComponentModel.Composition assembly.
3. Add a new logger type to the ThirdPartyLogger library. Make sure it implements the ILogger interface and is marked with the Export attribute.
4. Compile the ThirdPartyLogger project and place the resulting assembly in the directory specified by the DirectoryCatalog.

An example third party logger could be a logger that sends every message out via e-mail (not that I’m advocating e-mail as a logging tool):

Listing 10 – Third Party Logger

[Export(typeof(ILogger))]
public class EmailLogger : ILogger
{
    #region ILogger Members

    public void Log(string message)
    {
        // Log the message to e-mail
        // ...
    }

    #endregion
}

And luckily you can use multiple catalogs specifying difference sources by setting up an aggregate catalog.

Listing 11 – AggregateCatalog

AssemblyCatalog assemblyCatalog = new AssemblyCatalog(Assembly.GetExecutingAssembly());
DirectoryCatalog directoryCatalog = new DirectoryCatalog(@"c:\temp\loggers");

AggregateCatalog catalog =
    new AggregateCatalog(new ComposablePartCatalog[] { assemblyCatalog, directoryCatalog });

The code abode creates instances the AssemblyCatalog and DirectoryCatalog type and aggregates them in a AggregateCatalog instance. This instance can then be used by a CompositionContainer.

Top of page

Summary

I hope this article sparked your interest in the Managed Extensibility Framework or MEF, which will be included in the upcoming .NET Framework 4.0. By simply following three steps, namely: Import, Export and Compose you can easily create an extensible application and offer alot of additional functionality to your users even if the application has already been deployed.

By building in the necessary extensibility points you can prepare for the unknown and allow your application to be extended without recompiling it.

Top of page

Download

You can find the source code for this article on the Download page of this blog.

Top of page

Introduction

A couple of weeks ago I was asked to write a web service that needed to provide a single operation (method) that allowed the user to upload a file using a Secure Sockets Layer (SSL / HTTPS) .

Although they changed their minds and went for a solution using a VPN connection, I still decided to create the web service in case they went back on their decision again.

This article outlines the steps you need to follow in order to create a service to upload a file over HTTPS using WCF. And it’s been quite a while since I wrote my last article for this blog. I figured this would make an interesting topic…

Table Of Contents

• Introduction
• WCF Service Contract
• Service Implementation
• Hosting The Service
• Configuring The Host
• SSL Certificate
• Client Application
• Authenticate The Server
• Authenticate The Client
• Summary
• Download

WCF Service Contract

Let’s start by laying the groundwork for the WCF Service. As stated the service must enable users to upload a file to the web server which hosts it. Thus the resulting service contract only contains one method, aptly named Upload(…).

Start by opening up Visual Studio 2008 and create a new blank solution called WcfOverHttps. Next add a new WCF Service Library titled CGeers.Wcf.Services. This class library contains some automatically generated files (IService1.cs, Service.cs, App.config). Rename the IService.cs file to IFileUploadService.cs.

Figure 1 – Solution Explorer

The code for the service contract is displayed in Listing 1:

Listing 1 – Service Contract

[ServiceContract(Namespace = "http://cgeers.wordpress.com/wcf/services")]
public interface IFileUploadService
{
    [OperationContract]
    FileReceivedInfo Upload(FileInfo fileInfo);
}

As you can see displayed in Figure 1 and Listing 1 above they mention two other classes, namely:

1. FileInfo
2. FileReceivedInfo

These classes are both decorated with the MessageContract attribute. To upload the file I opted to use streaming. WCF stipulates that the parameter that holds the data to be streamed must be the only parameter in the method.

You could opt to change the type of the fileInfo parameter to Stream, but then you cannot send any additional information about the file along with it. You can circumvent this issue by creating a new class which contains all of the information you want to transmit. By decorating this class with the MessageContract attribute you can use this class (or message) as a parameter or return type in your service operations.

The FileInfo class specifies the structure of a SOAP envelope for a particular message.

Listing 2 – FileInfo class

[MessageContract]
public class FileInfo
{
    [MessageHeader(MustUnderstand = true)]
    public string FileName { get; set; }

    [MessageHeader(MustUnderstand = true)]
    public long Length { get; set; }

    [MessageBodyMember(Order = 1)]
    public Stream Stream { get; set; }
}

As you can see in Listing 2 the FileInfo class contains three properties. Apart from the actual file (Stream property) the filename and length of the file are also provided.

By applying the MessageHeader attribute to the FileName and Length propery you place this information in the header of the SOAP message. When streaming a file the body of the SOAP message must only contain the actual file itself. By applying the MessageBodyMember attribute to the Stream property you place it in the body of the SOAP message.

If your service operation contains a parameter of a type which has been decorated with the MessageContract attribute then all of the parameters and the return type used in this operation must be of a type to which this attribute has been applied.

You cannot mix parameters of a primitive type with message contracts. For instance if you want the Upload(…) method to return a boolean indicating if the upload succeeded or failed then you have to wrap this in another message contract.

Listing 3 displays how to setup the return value as a message contract. Apart from the boolean value (body) the header of this SOAP message contains the filename of the uploaded file and an optional message property which contains some information about why the upload failed.

Listing 3 – FileReceivedInfo class

[MessageContract]
public class FileReceivedInfo
{
    [MessageHeader(MustUnderstand = true)]
    public string FileName { get; set; }

    [MessageHeader(MustUnderstand = true)]
    public string Message { get; set; }

    [MessageBodyMember(Order = 1)]
    public bool UploadSucceeded { get; set; }
}

If you try to mix message contracts and parameters of a primitive type you’ll receive the following error message:

System.InvalidOperationException: The operation ‘Method’ could not be loaded because it has a parameter or return type of type System.ServiceModel.Channels.Message or a type that has MessageContractAttribute and other parameters of different types. When using System.ServiceModel.Channels.Message or types with MessageContractAttribute, the method must not use any other types of parameters.

Top of page

Service Implementation

Now that the contract for the service has been established it’s time to provide an actual implementation for it.

Start by renaming the Service1.cs file to FileUploadService.cs and add a reference to the System.Configuration assembly.

Listing 4 displays the code for implementing the service. The code is pretty straightforward. Check out the comments in the code for more explanation. Basically it reads the incoming stream and saves it to a file using familiar .NET code.

The Upload(…) method’s return type is of the FileReceivedInfo type. If the upload succeeds the UploadSucceeded property is set to true, if it fails this property is set to false and the message property is populated with the message property of the exception that occured.

Listing 4 – Service Implementation

[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerCall,
    ConcurrencyMode = ConcurrencyMode.Single)]
public class FileUploadService : IFileUploadService
{
    #region IFileUploadService Members

    public FileReceivedInfo Upload(FileInfo fileInfo)
    {
        try
        {
            // Determine to which directory the file needs to be uploaded
            string uploadDirectory =
                ConfigurationManager.AppSettings["uploadDirectory"];
            if (String.IsNullOrEmpty(uploadDirectory))
            {
                throw new InvalidOperationException("...");
            }

            // Try to create the upload directory if it does not yet exist
            if (!Directory.Exists(uploadDirectory))
            {
                Directory.CreateDirectory(uploadDirectory);
            }

            // Check if a file with the same filename is already 
            // present in the upload directory. If this is the case 
            // then delete this file
            string path = Path.Combine(uploadDirectory, fileInfo.FileName);
            if (File.Exists(path))
            {
                // Check if the file is read-only
                if ((File.GetAttributes(path) & FileAttributes.ReadOnly) ==
                    FileAttributes.ReadOnly)
                {
                    File.SetAttributes(path, FileAttributes.Normal);
                }
                File.Delete(path);
            }

            // Read the incoming stream and save it to file
            const int bufferSize = 2048;
            byte[] buffer = new byte[bufferSize];
            using (FileStream outputStream = new FileStream(path,
                FileMode.Create, FileAccess.Write))
            {
                int bytesRead = fileInfo.Stream.Read(buffer, 0, bufferSize);
                while (bytesRead > 0)
                {
                    outputStream.Write(buffer, 0, bytesRead);
                    bytesRead = fileInfo.Stream.Read(buffer, 0, bufferSize);
                }
                outputStream.Close();
            }
            return new FileReceivedInfo
                       {
                           FileName = fileInfo.FileName,
                           Message = String.Empty,
                           UploadSucceeded = true
                       };
        }
        catch (Exception ex)
        {
            return new FileReceivedInfo
                       {
                           FileName = fileInfo.FileName,
                           Message = ex.Message,
                           UploadSucceeded = false
                       };
        }
    }

    #endregion
}

Top of page

Hosting The Service

Now that the service has been setup it’s time to create a host for it. To keep things simple a console application will do. Add a new Console Application project to your solution named ConsoleHost. Next add references to the System.ServiceModel assembly and the CGeers.Wcf.Services project.

The code for the Main(…) method of the console application is slim and simple. Take a look at Listing 5.

Listing 5 – Hosting the FileUpload service

static void Main(string[] args)
{
    ServiceHost host = new ServiceHost(typeof(FileUploadService));
    host.Open();
    Console.WriteLine("FileUpload Service Host");
    Console.WriteLine("Service Started!");
    foreach (Uri address in host.BaseAddresses)
    {
        Console.WriteLine("Listening on " + address);
    }
    Console.WriteLine("Press any key to close the host...");
    Console.ReadKey();
    host.Close();
}

A new ServiceHost instance is created for the FileUploadService type and the host is then started. But before you launch the console application you still need to configure the service. Instead of doing this through code I opted to do this via an application configuration file. The next section addresses how you can easily configure your service.

Top of page

Configuring The Host

Start by adding an application configuration (App.config) file to the ConsoleHost project. Next specify the directory in which the service should save the incoming files.

Listing 6 – Upload directory

<appSettings>
  <add key="uploadDirectory" value="C:\temp\upload" />
</appSettings>

Now add a node to the configuration file. Within this node three child nodes will be added in order to configure the service. The first such node specifies the service’s behavior.

Listing 7 – Service Behavior

<behaviors>
  <serviceBehaviors>
    <behavior name="FileUploadServiceBehavior">
      <serviceMetadata httpGetEnabled="False" httpsGetEnabled="True" />
      <serviceDebug includeExceptionDetailInFaults="False" />
    </behavior>
  </serviceBehaviors>
</behaviors>

The behavior specifies that the service should not propagate exception details and that it’s metadata should be shared over HTTPS (httpsGetEnabled) instead of HTTP (httpGetEnabled).

Next up is the binding for the service. Since the goal is to use HTTPS the built-in BasicHttpBinding fits the bill. A couple of its properties need to be tweaked to fit the needs of the service, namely:

1. transferMode: Set it to Streamed to enable streaming.
2. messageEncoding: The message encoding is set to MTOM encoding which is a mechanism for transmitting binary attachements with SOAP messages.
3. maxReceivedMessageSize: Set to 64 megabytes to allow large files to be uploaded.
4. maxBufferSize: Set to 64 kilobytes.
5. receiveTimeout: Set to 10 minutes. If the file fails to upload within this time frame an exception will be thrown.

Remark: Configure these settings according to the needs of your application. For my application a maximum of 64 Mb for the file size and 64 KB for the buffer are sufficient.

Listing 8 – The Binding

<bindings>
  <basicHttpBinding>
    <!-- buffer: 64KB; max size: 64MB -->
    <binding name="FileUploadServiceBinding"
             transferMode="Streamed"
             messageEncoding="Mtom"
             maxReceivedMessageSize="67108864" maxBufferSize="65536"
             closeTimeout="00:01:00" openTimeout="00:01:00"
             receiveTimeout="00:10:00" sendTimeout="00:01:00">
      <security mode="Transport">
        <transport clientCredentialType="None" />
      </security>
    </binding>
  </basicHttpBinding>
</bindings>

Last but not least is the configuration for the service itself.

Listing 9: FileUploadService configuration

<services>
  <service behaviorConfiguration="FileUploadServiceBehavior"
    name="CGeers.Wcf.Services.FileUploadService">
    <endpoint address="" binding="basicHttpBinding" contract="CGeers.Wcf.Services.IFileUploadService"
              bindingConfiguration="FileUploadServiceBinding">
      <identity>
        <dns value="localhost" />
      </identity>
    </endpoint>
    <endpoint address="mex" binding="mexHttpsBinding" contract="IMetadataExchange" />
    <host>
      <baseAddresses>
        <add baseAddress="https://127.0.0.1:8741/FileUploadService/" />
      </baseAddresses>
    </host>
  </service>
</services>

The service’s ABC’s are specified and it’s hooked up to the behavior and binding we configured earlier. The address https://127.0.0.1:8741/FileUploadService/ is specified as being the location of the service. As you can see in the service’s binding the security is set to Transport which requires that you provide an HTTPS based address.

Remark: Note that for the metadata exchange (mex) the mexHttpsBinding is specified and not the default mexHttpBinding.

If you run the ConsoleHost project now you receive the following result:

Figure 2 – ConsoleHost

Top of page

SSL Certificate

If you run the ConsoleHost project now and enter the address https://127.0.0.1:8741/FileUploadService/ in a browser you’ll receive an error. Before you can proceed , you need to bind an SSL Certificate to port 8741 for the IP address 127.0.0.1.

First you need to create an SSL certificate. You can do this using the makecert.exe command-line utility. Just start a new Visual Studio command prompt and enter the following command in order to create a X509 certificate which will be used for SSL communication on the localhost (127.0.0.1).

makecert.exe -sr LocalMachine -ss My -n CN=127.0.0.1 -sky exchange -sk -pe

After this command is executed, the new certificate with the private key is created and stored in the LocalMachine Personal store. To see it, use the MMC-certificate snap-in.

After executing this command your new certificate is created and stored in the LocalMachine Personal store. Open the MMC-certificate snap-in to see it.

1. Click Start, Run and enter the command “mmc”
2. Click OK to start the MMC console
3. Click File | Add/Remove snap-in…
4. In the resulting dialog that pops up click the Add option and choose the Certificates snap-in
5. Confirm your changes by closing the dialog windows

Afterwards you can view you new certificate in the MMC console as displayed in Figure 3.

Figure 3 – MMC Console Certificates snap-in

Next you need to bind this new certificate to the port 8741. Return to the Visual Studio command prompt and enter the following command to do so:

httpcfg.exe set ssl -i 127.0.0.1:8741 -h cfdf5d1140b94614d047dd77c7bd4d4d4422e1c9 -Personal

Replace the “cfdf5d1140b94614d047dd77c7bd4d4d4422e1c9″ value with the thumbprint of your own certificate. You can retrieve the thumbprint using the Certificates MMC snap-in as shown in Figure 3. Be sure to remove all the spaces.

If you rerun the ConsoleHost application after creating the certificate and binding it to 127.0.0.1:8741 you should receive the standard WCF service test page after entering the address https://127.0.0.1:8741/FileUploadService/ in a browser.

Figure 4 – FileUploadService

Top of page

Client Application

Voila, now that the file upload service is ready we can begin to consume it. Let’s test this…

Add a new console application project named ConsoleClient to your solution. Next add a reference to the System.ServiceModel assembly. When done start the ConsoleHost application in non-debug mode. We need to add a reference to this service to the client application. For this the service needs to be up and running.

Right click on the ConsoleClient project within the Solution Explorer and choose “Add Service Reference…”. The Add Service Reference dialog is displayed. Enter the address of the service (https://127.0.0.1:8741/FileUploadService/) in the address field and click Go. The SSL certificate will be presented to the calling application (= Visual Studio). You’ll be prompted to accept the certificate. Click Yes to proceed.

Figure 5 – SSL Certificate Security Alert In Visual Studio 2008

Rename the namespace ServiceReference1 to ServiceReferences and click Advanced. The Service Reference Settings dialog is shown. Make sure that the option “Always generate message contracts” is checked. Click OK to close this dialog. Click OK once more to let Visual Studio add the service reference and generate the necessary proxy classes.

Remark: If you don’t check the option “Always generate message contracts” then the message contract’s properties will appear as individual parameters in the proxy. And for the result type you’ll only get the property that is marked as the body of the SOAP message.

Unchecked the Upload(…) method on the proxy will be generated as such:

Listing 10: Always Generate Message Contracts

bool Upload(string fileName, long length, Stream stream);

instead of

FileReceivedInfo Upload(FileInfo fileInfo);

Once the necessary proxy classes have been generated consuming the service is an easy task. Consider the following code in the Main(…) method of the ConsoleClient application.

Listing 11 – ConsoleClient Application

using (FileUploadServiceClient proxy = new FileUploadServiceClient())
{
    FileStream inputStream = File.Open(@"c:\temp\uploadtest.txt", FileMode.Open);

    ServiceReferences.FileInfo fileInfo =
        new ServiceReferences.FileInfo("uploaded.txt", inputStream.Length, inputStream);
    FileReceivedInfo info = proxy.Upload(fileInfo);
    if (info.UploadSucceeded)
    {
        Console.WriteLine(String.Format("File {0} uploaded", info.FileName));
    }
    else
    {
        Console.WriteLine(String.Format("File {0} upload failed", info.FileName));
        Console.WriteLine(info.Message);
    }
    Console.WriteLine();
    Console.ReadLine();
}

Top of page

Authenticate The Server

Make sure the ConsoleHost application is still running and start the ConsoleClient application for the first time. Upon hitting the line of code that calls the Upload(…) method on the proxy you’ll receive the following error message:

Could not establish trust relationship for the SSL/TLS secure channel with authority ‘127.0.0.1:8741′.

This means that the server (ConsoleHost) presented the SSL certificate to the client application during the handshake and the client did not validate it. Thus a trusted relationship for the SSL/TLS secure channel could not be established.

To solve this problem add the following code to the beginning of the Main(…) method of the ConsoleClient application.

Listing 12 – Validating The Server

ServicePointManager.ServerCertificateValidationCallback += customXertificateValidation;

The code for the customXertificateValidation(…) method is as follows:

private static bool customXertificateValidation(object sender, X509Certificate cert,
    X509Chain chain, SslPolicyErrors error)
{
    X509Certificate2 certificate = (X509Certificate2)cert;
    if (certificate.Subject == "CN=127.0.0.1" && !String.IsNullOrEmpty(certificate.Thumbprint) &&
        certificate.Thumbprint.ToLower() == "cfdf5d1140b94614d047dd77c7bd4d4d4422e1c9")
    {
        return true;
    }
    return false;
}

When the customXertificateValidation(…) method is called (callback) by WCF to validate the server certificate you have the opportunity to inspect the certificate (= cert parameter). In this example the value of the Subject and Thumbprint are checked in order to validate the identity of the server. If they match then the server is authenticated, if not then the SSL connection cannot be established.

Remark: Feel free to adjust the validation of the SSL certificate to suit your own needs.

Upon running the client again after applying these changes you’ll receive the message “File uploaded.txt uploaded”.

Top of page

Authenticate The Client

At this point you could consider your file upload service complete, but one crucial item remains. Namely authenticating the client by the server.

I don’t want anyone who happens to stumble upon my service to be able to upload files to the web server. To block unauthorized users we have to validate the client. Luckily WCF allows you do so without much hassle.

Let’s return to the CGeers.Wcf.Service project for a while. Add a reference to the System.IdentityModel assembly and add a new class called CustomUserNameValidator.

Listing 13 – CustomUserNameValidator

public class CustomUserNameValidator : UserNamePasswordValidator
{
    public override void Validate(string userName, string password)
    {
        if (userName != "Christophe" || password != "WCFRocks!")
        {
            // This throws an informative fault to the client.
            throw new FaultException("Incorrect username or password");
        }
    }
}

This class derives from the UserNamePasswordValidator which can be found in the System.IdentityModel.Selectors namespace. Only one method needs to be overriden, namely the Validate(…) method. Here you need to specify your own custom code in order to validate the provided username and password. Just throw a FaultException if you cannot validate the user.

Next you need to configure the ConsoleHost application so that it uses the CustomUserNameValidator class in order to validate the clients. Open the App.config file of the ConsoleHost application and adjust the following settings:

For the basicHttpBinding set the required clientCredentialType of the transport security to Basic. This requires that the client present the necessary credentials (username & password).

Listing 14 – Adjusting The Binding

...
<security mode="Transport">
  <transport clientCredentialType="Basic" />
</security>
...

Then add the following bit of configuration to the service behavior to tell the service how to validate the client credentials.

Listing 15 – Adjusting The Service Behavior

...
<serviceCredentials>
  <userNameAuthentication
    userNamePasswordValidationMode="Custom"
    customUserNamePasswordValidatorType="CGeers.Wcf.Services.CustomUserNameValidator, CGeers.Wcf.Services" />
</serviceCredentials>
...  

The service is now correctly setup and requires the client to provide the necessary credentials. If you run the ConsoleClient application now you’ll receive the following error message:

The HTTP request is unauthorized with client authentication scheme ‘Anonymous’. The authentication header received from the server was ‘Basic realm=”"‘.

The configuration for the client application needs to reflect the changes we made to the service. Right click on the service reference and choose “Update Service Reference”.

Running the client application again will now result in the following error message:

The HTTP request was forbidden with client authentication scheme ‘Basic’.

You still need to adjust the client application so that it passes the correct credentials to the service. Add the following lines of code to the ConsoleClient’s Main(…) method.

Listing 16 – Client Credentials

...
proxy.ClientCredentials.UserName.UserName = "Christophe";
proxy.ClientCredentials.UserName.Password = "WCFRocks!";
...

That’s it! The client will now present valid credentials to the service and an SSL connection will be established.

Remark: The username and password validation in this article is kept short for illustrative purposes. Replace this with you’re own validation logic in real-world applications. A better approach would be to validate the username and password against a database containing the user’s credentials.

Top of page

Summary

I hope you enjoyed this tutorial on how to transfer files over HTTPS using WCF. To recap what we’ve covered from a developer’s point of view:

• Streaming a file over WCF
• Configuring a WCF service for communication over HTTPS(directories)
• Generating and binding a test SSL certificate to a port
• Consuming a service over HTTPS
• Authenticating the server
• Authenticating the client

Any comments, questions, tips…etc. are always appreciated.

Top of page

Download

You can find the source code for this article on the Download page of this blog.

Top of page

Introduction

In March I went to the Microsoft TechDays in Belgium. The last session I attended was about Microsoft’s Live Services and the Live Framework used for programming against these services. To showcase all this the Live Mesh service was used.

Live Mesh allows you to easily synchronize files with all of your devices. I tend to visualize it as an online hard drive or repository where I can deposit files which I wish to share amongst my devices such as my laptop at work, my PDA…etc.

You simply have to sign up for a Mesh account and install the Live Mesh client on the devices you want to synchronize. Once the client has been installed all that remains is to add a local folder to Live Mesh. The client will then make sure this folder is synchronized automatically between all of your devices.

Your Live Mesh account allows you to manage the connected devices and Live Mesh folders. For example you can opt to choose between which devices you want to synchronize a certain folder.

When you place a new file into a Live Mesh folder, the client will upload this file to your online Mesh account. The clients on your other devices will be notified as soon as they are up and running and will synchronize with your online Mesh account. So you always have a copy of your data floating around somewhere on the cloud.

There is more to it than this, but this is the gist of it. The goal of this article is to demonstrate just how easy it is to use the Live Framework to program against the Live Mesh service. With a small amount of code you’ll be able to create folders and store files in your Mesh account.

Table Of Contents

• Introduction
• Getting Started
• Live Framework Resource Model
• Connecting To The Live Services
• Listing Mesh Objects
• Mesh Object Resources
• Creating A Directory
• Adding A File
• Retrieving A File
• Summary
• Download

Getting Started

To get started you need to obtain the Live Framework Client. A separate sandbox environment has been setup for developers who wish to test and evaluate the Live Framework and the Live Services.

Since both are still in beta phase, you need to sign up for the community technology preview (CTP) program waiting list.

To do so just follow these steps:

1. Visit the Live Mesh website
2. Click on the link Developers listed at the bottom of the screen
3. Sign up for an account. You need to fill in the “Azure Services Invitations Program” form.

After registering for a Windows Azure account, you’ll have to be patient and wait until the good folks at Microsoft mail you an invitation code. In my case it took about 6 hours, but I’ve heard from other people that they’d have to wait a couple of days or even weeks.

Note: How does Windows Azure relate to Mesh? Simple: The Windows Azure platform, which is Microsoft’s platform for cloud computing, contains the Live Services which power Mesh. Using the Live Services API allows you to program against Mesh. Take a look at this blog post for more information.

After obtaining a Windows Azure account, you’ll get an invitation code for the Microsoft .NET Services and Microsoft SQL Services. After activating this invitation code you can request another one for the Live Services. You can register for a Live Services account at the Azure Services Developer Portal.

It’s quite a hassle and you’ll have to wait for about a week for all the invitation codes to be sent. Last but not least you’ll need to get access to the developer version of Live Mesh. Be aware, this version is different from the consumer version of Live Mesh! Both operate in their own sandbox. If you wish to install them side by side, please consult this forum post.

The required software (SDK & Tools) and documentation for programming against the Live Framework Mesh can be downloaded here.

You can recognize the Developer Live Mesh client by this icon in the system tray.

Figure 1 – Live Mesh Developer Client System Tray Icon

After all accounts have been created and the SDK has been setup you’re finally ready to go…

Note: To setup these accounts you’ll need to use your Windows Live Id.

Mike Tautly has put up a nice screencast on how to get started with Live Mesh, check it out here.

Top of page

Live Framework Resource Model

Before proceeding further a bit of information on the storage hierarchy of Mesh is advisable. The Live Framework encapsulates more than just Mesh as you can see in the following image.

Figure 2 – Live Framework Resource Model

Let’s focus solely on Mesh. Using a bottom-up approach the first item of interest is the data entry object. A data entry is the actual data stored in your Mesh, it can be a picture, a pdf, zip archive…etc. You are not confined to only storing files. You can, for example, also store objects as data entries.

Moving up one level you can see that a collection of data entries is maintained by a data feed, which in its turn is part of a mesh object. A data feed is usually a collection of data entries of the same type. So a data feed might be a collection of data entries which all represent pictures. I say usually, because it is really up to you to determine what you want to store in the data entries.

A mesh object (MeshObject class) describes the object that you want to share. There is one MeshObject for each object (e.g. folder) that you want to synchronize between your devices. Each MeshObject can have one or more data feeds and each data feed can have one or more data entries.

Just like with the data entries you determine how many data feeds a MeshObject contains and what kind of collections (data entries) these feeds contain. So a MeshObject describes an object that you wish to share and synchronize between your devices. It defines what to share and amongst which devices, a.k.a. the mapping.

To recap, for synchronizing folders and files, Mesh adds a single MeshObject for each Live Mesh folder. Each MeshObject has one data feed which contains a collection of data entries. The data entries are the actual files stored in the folder.

Top of page

Connecting To The Live Services

The source code accompagnying this article aims at demonstrating how to establish a connection with the Live Services, querying and creating resources (directories) and uploading / downloading a file.

Note: The purpose of the source code is to show how to operate with Live Mesh through the Live Framework API, not on how to write robust code. So exception handling and such is skipped. Feel free to add your own.

Well, for starters let’s begin with the initial task of establishing a connection. Connecting to the Live Services is as easy as following these steps:

1. Start up Visual Studio 2008 (be sure to check if you have SP1 installed)
2. Create a new blank solution called “LiveMesh” and add a console project aptly named ConsoleApplication
3. Add references to the following Dll assemblies which are part of the Live Framework SDK:Microsoft.LiveFX.Client.dll, Microsoft.LiveFX.ResourceModel.dll and Microsoft.Web.dll.If you used the default installation location they should be located in the following directory: “C:\Program Files\Microsoft SDKs\Live Framework\v0.91\API Toolkits\.Net Library”
4. Add a new class called LiveMesh to the project. Listing 1 lists the code for this class.

Listing 1 – LiveOperatingEnvironment class (LOE)

public class LiveMesh
{
  #region Fields

  private const string serverUri = "https://user-ctp.windows.net";
  private readonly LiveOperatingEnvironment environment = new LiveOperatingEnvironment();

  #endregion

  #region Constructor(s)

  public LiveMesh(string userName, string password)
  {
      UserName = userName;
      Password = password;
  }

  #endregion

  #region Properties

  public string UserName { get; set; }
  public string Password { get; set; }

  #endregion

  #region Methods

  public bool Connect()
  {
      // Using the LiveItemAccessOptions class you can specify if you want to auto-load
      // relations and if you wish to receive notifications.
      LiveItemAccessOptions options = new LiveItemAccessOptions(true);

      // Create a user token. You  need to pass a token based on your Windows Live Id
      // to the LOE object's connect method. The GetWindowsLiveAuthenticationToken() is
      // an extension method which resides in the Microsoft.LiveFX.ResourceModel namespace.
      string credential = new NetworkCredential(UserName, Password, serverUri).GetWindowsLiveAuthenticationToken();

      // Connect and retrieve the Mesh object
      environment.Connect(credential, AuthenticationTokenType.UserToken, new Uri(serverUri), options);

      // When connected the Mesh property of the LOE object will be set.
      return environment.Mesh != null;
  }

  #endregion
}

This class has a constructor which takes two strings, namely the username and password of your Windows Live Id. The variable serverUri contains the address of the Live Framework server to which you need to connect.

Everything in this class (which will be expanded in the rest of this text) pretty much revolves around the LiveOperatingEnvironment (LOE) class, it is the main entry point into the Live Framework.

The LiveMesh class’s Connect method in turn calls the LOE class’ Connect method which takes a user token, the server Uri and some options. Read the comments in the code segment above for more information on how these parameters are configured.

Let’s quickly test the LiveMesh class. The code in Listing 2 doesn’t need any further explanation.

Listing 2- Connecting to your Mesh

using System;

namespace ConsoleApplication
{
    class Program
    {
        private const string userName = "xxxxx@xxxxx.com";
        private const string password = "xxxxx";

        static void Main(string[] args)
        {
            LiveMesh myMesh = new LiveMesh(userName, password);

            bool connected = myMesh.Connect();
            if (connected)
            {
                Console.WriteLine("Connected");
            }
            else
            {
                Console.WriteLine("Could not establish connection");
            }

            Console.ReadLine();
        }
    }
}

Note: Don’t forget to replace the userName and password values with your own.

Top of page

Listing Mesh Objects

To list the objects present in your Mesh a simple Linq query suffices. Add the following method to your LiveMesh class.

Listing 3 – GetMeshObjects() method

public class LiveMesh
{
    // ...

    #region Methods

    public IEnumerable<MeshObject> GetMeshObjects()
    {
        return from o in environment.Mesh.CreateQuery<MeshObject>().Execute()
               select o;
    }

    #endregion

    // ...
}

As you can see the Linq query follows the pattern shown in figure 2, the Live Framework Resource Model. The Mesh property of the LiveOperatingEnvironment instance is queried and all the Mesh objects are returned (Service Endpoint -> Mesh -> Mesh Objects). Now let’s foreach this collection and take a look at the results.

Listing 4 – Foreaching the Mesh objects

// List the MeshObjects in your Mesh
IEnumerable<MeshObject> meshObjects = myMesh.GetMeshObjects();
foreach(var meshObject in meshObjects)
{
    Console.WriteLine(meshObject.Resource.Title);
}

The output:

Figure 3 – My Mesh Objects

The folders “Pictures” and “Blog” were two folders I created using the Live Mesh Developer version website (Live Desktop). Feel free to create your own folders using the site and check if they show up in the query results.

There are two ways to query Mesh. You could also rewrite the query shown in Listing 3 as such:

Listing 5 – CreateQuery<T> Versus Entries

return from o in environment.Mesh.MeshObjects.Entries select o;

What’s the difference? CreateQuery<T> executes server side while using the Entries collection will be executed client-side. The latter case will result in more objects being sent over the wire. For a more in-depth explanation check out this excellent blog post.

Note: If you only want to return Mesh objects which are folders, then add this where clause: where o.Resource.Type == “LiveMeshFolder”.

Top of page

Mesh Object Resources

Now that you know how to obtain your Mesh objects, let’s retrieve the resources (data entries) of such a Mesh object. In order words let’s list the files of a Live Mesh folder.

Add the method shown in Listing 6 to your LiveMesh class.

Listing 6 – GetFilesOfFolder() method

public IEnumerable<DataEntry> GetFilesOfFolder(MeshObject meshObject)
{
    // Obtain the data feed. 
    // A Mesh Object representing a folder only has one data feed.
    // It's title is LiveMeshFiles.
    DataFeed feed = (from f in meshObject.CreateQuery<DataFeed>().Execute()
                     where f.Resource.Title == "LiveMeshFiles"
                     select f).First();
    if (feed == null)
    {
        throw new InvalidOperationException("MeshObject does not have any data feeds");
    }
    return from e in feed.CreateQuery<DataEntry>().Execute() select e;
}

Let’s update the foreach loop in the Main method.

Listing 7 – Updated Main method

// ...

// List the MeshObjects in your Mesh
IEnumerable<MeshObject> meshObjects = myMesh.GetMeshObjects();
foreach(var meshObject in meshObjects)
{
    Console.WriteLine(meshObject.Resource.Title);
    Console.WriteLine();

    IEnumerable<DataEntry> files = myMesh.GetFilesOfFolder(meshObject);
    foreach(var file in files)
    {
        Console.WriteLine(String.Format("\t{0}", file.Resource.Title));
    }
    Console.WriteLine();
}

// ...

Figure 4 – Mesh Object Resources (files)

Just place some files in your Mesh folders using the Live Desktop to test this code.

Top of page

Creating A Directory

Great, you can now query your Mesh objects and their resources. But how about actually creating a folder without resorting to the Live Desktop?

Again, a short and simple amount of code is all you need. Add the following two methods to your LiveMesh class.

Listing 8 – DirectoryExists() and CreateDirectory() methods

public bool DirectoryExists(string directory)
{
    var q = (from o in environment.Mesh.CreateQuery<MeshObject>().Execute()
             where o.Resource.Type == "LiveMeshFolder" && o.Resource.Title == directory
             select o).FirstOrDefault();
    return q != null;
}

public void CreateDirectory(string directory)
{
    // Do not create the directory if it already exists
    if (DirectoryExists(directory))
    {
        return;
    }

    // Create a new Mesh object and set its type
    MeshObject newDirectory = new MeshObject(directory) {Resource = {Type = "LiveMeshFolder"}};

    // Add the new object to your Mesh
    environment.Mesh.MeshObjects.Add(ref newDirectory);

    // Create a data feed, set its type and handler
    DataFeed feed =
        new DataFeed("LiveMeshFiles")
        { Resource = { Type = "LiveMeshFiles", HandlerType = "FileSystem" } };

    // Add the data feed to the new Mesh object
    newDirectory.DataFeeds.Add(ref feed);
}

The method DirectoryExists() checks if a folder already exists within Mesh, the second method CreateDirectory() creates a new folder and adds a data feed to it.

Note: The code contains some hardcoded strings such as LiveMeshFolder, LiveMeshFiles, FileSystem…etc. Feel free to improve on the design (make them constants for example), but these strings are needed if you want to retrieve / create the correct Mesh objects. Mesh allows you to store more than just folders and files.

Top of page

Adding A File

To enable your LiveMesh class to add files to a folder add the methods shown in Listing 9 to the class.

• FindDirectory(): This method checks if a given directory exists in your Mesh and returns the MeshObject if found.
• GetMimeType(): Determines the mime type of a file.
• AddFileToDirectory(): Retrieves the MeshObject for a Live Mesh folder, loads its data feed and adds a new file to the feed’s data entries.

Listing 9 – Adding A File

public MeshObject FindDirectory(string directory)
{
    return (from o in environment.Mesh.CreateQuery<MeshObject>().Execute()
            where o.Resource.Type == "LiveMeshFolder" &&
                  o.Resource.Title == directory
            select o).FirstOrDefault();
}

private static string GetMimeType(string path)
{
    string mimeType = "application/unknown";
    string ext = Path.GetExtension(path).ToLower();
    Microsoft.Win32.RegistryKey regKey = Microsoft.Win32.Registry.ClassesRoot.OpenSubKey(ext);
    if (regKey != null && regKey.GetValue("Content Type") != null)
    {
        mimeType = regKey.GetValue("Content Type").ToString();
    }
    return mimeType;
}

public void AddFileToDirectory(string directory, string path)
{
    MeshObject meshObject = FindDirectory(directory);
    if (meshObject == null)
    {
        return;
    }
    DataFeed feed = (from f in meshObject.CreateQuery<DataFeed>().Execute()
                     where f.Resource.Type == "LiveMeshFiles"
                     select f).First();
    Stream fileStream = File.Open(path, FileMode.Open, FileAccess.Read);
    feed.DataEntries.Add(fileStream, path, GetMimeType(path));
    // Make sure all devices will get synchronized.
    feed.SyncEntries.Synchronize();
    feed.Update();
}

You can now add a file to a Live Mesh folder by calling the AddFileToFolder(directory, path) and the file will be uploaded to your Mesh. Check the Online Desktop to verify that it has been uploaded.

Listing 10 – Uploading About.txt

// ...
myMesh.AddFileToDirectory("My new folder", "About.txt");
// ...

Top of page

Retrieving A File

We’re almost there. The only thing that remains to be done is to retrieve a file from Mesh. The GetFileByFilename() method shown in Listing 11 allows you to do just that.

It queries all the Mesh objects and returns the first data entry whose resource title matches the given filename.

Listing 11 – GetFileByFilename() method

public DataEntry GetFileByFilename(string filename)
{
    IEnumerable<MeshObject> meshObjects = GetMeshObjects();
    foreach(var meshObject in meshObjects)
    {
        DataFeed feed = (from f in meshObject.CreateQuery<DataFeed>().Execute()
                         where f.Resource.Type == "LiveMeshFiles"
                         select f).First();
        if (feed != null)
        {
            DataEntry dataEntry = (from e in feed.CreateQuery<DataEntry>().Execute()
                                   where e.Resource.Title == filename
                                   select e).FirstOrDefault();
            if (dataEntry != null)
            {
                return dataEntry;
            }
        }
    }
    return null;
}

For example let’s search for the text file About.txt which we added in the previous section.

Listing 12 – Retrieving a file

// Retrieve a file
DataEntry dataEntry = myMesh.GetFileByFilename("About.txt");
if (dataEntry != null)
{
    MemoryStream stream = new MemoryStream();
    dataEntry.ReadMediaResource(stream);
    stream.Seek(0, SeekOrigin.Begin);
    StreamReader reader = new StreamReader(stream);
    Console.WriteLine(reader.ReadToEnd());
}

Once the DataEntry has been found you can call its ReadMediaResource() method to obtain a stream. The rest of the code reads the stream and writes the contents to the console.

Top of page

Summary

I hope you enjoyed this brief introduction to Live Mesh and the Live Framework. Let’s recap what we’ve covered from a developer’s point of view:

• Connecting to the Live Operating Environment (Live Services)
• Listing resources (directories)
• Add (uploading) files to Mesh
• Retrieving (downloading) files from Mesh

Any comments, questions, tips…etc. are always appreciated.

Top of page

Download

You can find the source code for this article on the Download page of this blog.

Top of page

Introduction

For this article / tutorial I will demonstrate a quick and easy way on how to use data access objects (DAO’s) with the Entity Framework.

These data access objects form a layer between the business logic and the database access technology. The idea is that the business logic should remain ignorant of the technology used to access the database. Using this “DAO pattern” you can more easily interchange this backing technology.

In the text to come this will be demonstrated by setting up a simple domain model which will be modelled using the Entity Framework. Next a layer of DAO’s will be created on top of this domain model.

The business logic will only use these DAO’s to request or send back data from or to the underlying data store. How these CRUD operations are handled is entirely up to the implementation of the DAO’s and should be of no concert to the business logic.

By decoupling the business objects from the backing data store you can more easily switch to another database access technology such as for say Linq To Sql.

Table Of Contents

• Introduction
• The Various Parts
• Domain Model
• The Database
• Modelling The Domain
• DAO Interfaces
• DAO Implementation
• Business Logic
• A Quick Demo
• Summary
• Download

The Various Parts

Let’s quickly iterate the various parts of the architecture we’re trying to achieve by illustrating them.

Figure 1 – The Various Parts

1. Data Store: The underlying data store for this article is, as usual, Microsoft SQL Server 2005 Express.
2. Domain: The domain will be modelled by the Entity Framework upon the tables found in the database.
3. Data Access Objects (DAO’s): The DAO’s are responsible for communicating with the domain in order to retrieve and pass data from and back to the underlying data store.
4. Business Logic: The domain-specific logic that makes the application actually do stuff will be handled in the business logic or “Manager” layer. This layer consists out of manager class types who’s sole responsability is to handle the coordination of work. It uses DAO’s to retrieve and manipulate data. The actual CRUD operations are handled by the DAO’s. This layer should remain ignorant about how this is actually implemented.

Remark: As you may have noticed I skipped the fifth part shown in figure 1. Normally you should create a separate Data Transfer Object (DTO) for each of the objects found in your domain. These DTO’s should only carry data and should not contain any logic so that they can be easily serialized and deserialized, they are meant to only transfer data between two points. In this case the DAO’s and the business logic layer.

For this article I’ve choosen to use the domain objects generated by the Entity Framework as DTO’s. Although this has the disadvantage of establishing a coupling between the Entity Framework and the business logic layer (a reference to System.Data.Entity is required).

Use them strictly as DTO’s and don’t call any Entity Framework specific methods on them in the business logic layer or any other layer except in the layer that houses the DAO’s. In order words keep the coupling at the absolute minimum. Depending on the scope of the project this is acceptable in my humble opinion.

I hope version 2 of the Entity Framework offers better support for DTO/POCO objects. The IPOCO pattern they have chosen to follow for this first release makes this scenario not impossible but certainly tedious to achieve.

Top of page

Domain Model

Let’s quickly establish a small and simple domain model. Let’s ponder the following class diagram…

Figure 2 – Simple domain model

The above figure gives you an overview of a simple domain model. As you can see all domain objects are descendant from the BaseClass type.

The left branch of the class diagram displays an abstract class type Person which has two properties called FirstName and Name. Two concrete classes, namely Developer and Analyst in turn derive from this type and add a property specific to themselves.

The Developer class has a property named PreferedLanguage containing the developer’s programming language of choice and the Analyst type contains the methodology he likes to use to manage his projects.

On the right branch two types are located. An abstract class type titled Task which has a Name project to identify the task and a concrete implementation of this abstract type called Project which adds a Deadline property to signal when the project should be completed.

This domain model represents a collection of developers and analysts and the projects they are working on. Now we need to map this logical model to external data. In other words these objects need to be mapped to tables in a database.

Top of page

The Database

To model the domain I’ve opted for the bottom-up approach. We start at the bottom by creating our database and then generate a domain/object model using the Entity Framework based on the previously created database. The other way around (Top-down approach) is certainly feasible, but in this case it isn’t the fastest approach.

Start by creating a new database named “Projects” by using SQL Server Management Studio Express (or any other tool). Only three tables are required, figures 3, 4 & 5 show you the structure of these tables.

Figure 3 – Person table

The Developer and Analyst domain objects both map to the Person table. For the left branch depicted in the domain model (figure 2) I’ve gone for the table-per-hierarchy storage model.

A developer and analyst are represented by different types in the domain model but derive from the same base type. However in the data store their data is stored in the same table, all that is required is a descriminator column.

The descriminator column in this case is called PersonType (int) and if it is equal to one the person is a developer or if equal to two an analyst.

Figure 4 – Project table

For the right branch only one table is needed. As you can see it is quite simple and has all the columns needed to represent the properties of the Project domain object.

If you were to create more descendants of the abstract Task type this table would also need a descriminator column if you were to opt for the table-per-hierarchy approach.

Figure 5 – ProjectsPerPerson table

The last table ProjectsPerPerson links persons (developers and analysts) to zero or multiple projects. Although this relation is not directly obvious by looking at figure 2 a person can have zero or multiple projects and a project can be worked upon by zero or multiple persons.

Remark: The source code accompagnying this article contains an Sql script containing the necessary DDL statements so that you can quickly setup this database.

Top of page

Modelling The Domain

Now that the database has been setup let’s proceed to model the domain or object model.

Fire up Visual Studio, create a new blank solution called “EntityFrameworkDao” and add a new class library titled “Domain”. Delete the automatically generated file Class1.cs and add a new ADO.NET Entity Data Model. Call it “Domain.edmx”.

When the Entity Data Model wizard pops up choose to generate the model from the database, but only add the Person table to begin with. You should end up with a model containing only one entity, namely Person.

You now have to manually break up this entity into three separate entities being Person, Developer and Analyst. Instead of explaining this step-by-step I suggest you take a look the following screencast by Rob Bagby. He does an excellent job at explaining it (Also take a look at his blog).

When that is done update the model from the database and add the Project table. Since this table does not contain a descriminator column there is no need to break it up into other entities.

Last but not least add the ProjectsPerPerson table to the model. This will not result in a new entity being added but will insert a many-to-many relationship between the Person and Project entities.

Be sure to rename the entity sets and navigation properties to something more meaningful. You should end up with an entity data model resembling the following screenshot.

Figure 6 – The Entity Data Model

You could go as far as to have the Person and Project type share a common base type as shown in figure 2, but I’ve chosen not to do this as it would disable me from setting a different entity set name on those entities.

Top of page

DAO Interfaces

If you recall figure 1 which lists the various parts required to setup our architecture we have now arrived at the third part, namely the nitty-gritty of this article being the Data Access Objects (DAO’s). The business logic layer will only obtain DTO’s or domain objects in this case through the use of DAO objects, it will not directly query the Entity Data Model.

To further decouple the business logic layer from the Entity Framework we will only program against interfaces which the DAO objects will implement. This way you can provide an implementation of the DAO interfaces that target the Entity Framework, another one that targets Linq To Sql…and so on. Since the business logic layer only programs against the DAO interfaces it does not care about the actual implementation.

Remark: Of course this will work optimally if we don’t return domain objects to the business logic layer but DTO’s as previously mentioned. Since we’ve choosen to directly return domain objects our implementation still has a coupling to the Entity Framework.

But as said I find it acceptable if you threat these domain objects strictly as DTO’s in the business logic layer. This keeps the coupling as minimal as possible so you don’t have too much work should you ever need to replace the Entity Framework.

Should you “convert” these domain objects to DTO’s the business logic layer and any other layer on top of that (e.g. Presentation Layer) are not affected at all if you change the implementation of the DAO’s.

Let’s move on to the interfaces. Add a new code library named “Contracts” to the solution.

First we declare an all general purpose interface called IDao from which all the other DAO interfaces will descend. It declares three methods. Save(…) for adding / updating an entity, Delete(…) for deleting an entity and SaveChanges() to persist the changes.

Listing 1 – IDao Interface

public interface IDao<TEntity>
{
    TEntity Save(TEntity entity);
    void Delete(TEntity entity);
    void SaveChanges();
}

Listing 2 lists the other Dao interfaces found in the Contracts code library. As you can see the IDeveloperDao, IAnalystDao and IProjectDao interfaces each declare one method that needs to be implemented.

Listing 2 – Dao Interfaces

public interface IPersonDao : IDao<Person>
{ }

public interface IDeveloperDao : IPersonDao
{
    IEnumerable<Developer> GetDevelopers();
}

public interface IAnalystDao : IPersonDao
{
    IEnumerable<Analyst> GetAnalysts();
}

public interface IProjectDao : IDao<Project>
{
    IEnumerable<Project> GetProjectsOfPerson(Person person);
}

Finally we also want to relieve the business logic layer from having to instantiate the DAO’s directly. To achieve this a factory will be used which needs to implement the following IDaoFactory interface.

Listing 3 – IDaoFactory interface

public interface IDaoFactory
{
    IPersonDao GetPersonDao();
    IDeveloperDao GetDeveloperDao();
    IAnalystDao GetAnalystDao();
    IProjectDao GetProjectDao();
}

Top of page

DAO Implementation

Before building an Entity Framework implementation of the DAO interfaces we first have to develop a helper class and an extension method for the ObjectContext type.

Listing 4 – ObjectContextManager class

public class ObjectContextManager
{
    private static readonly ProjectsEntities context = new ProjectsEntities();
    private ObjectContextManager() { }
    public static ProjectsEntities Context { get { return context; } }
}

Each DAO object will share the same ObjectContext in order to communicate with the Entity Data Model. The ObjectContextManager class provides a static Context property which will always return the same ObjectContext instance. Don’t fret too much about the implementation of the ObjectContextManager class, I kept it very short for illustrative purposes. Feel free to improve on this, e.g. by providing a more generic approach so that it can be reused for each ObjectContext type.

Remark: Be careful in which type of application you use the ObjectContext as it is not thread safe. For more information on this topic have a look at my previous article Entity Framework ObjectContext.

Listing 5 – ObjectContext GetEntitySetName() extension method

public static class ObjectContextExtensions
{
    public static string GetEntitySetName(this ObjectContext context, string entityTypeName)
    {
        var container = context.MetadataWorkspace.GetEntityContainer(context.DefaultContainerName, DataSpace.CSpace);
        string entitySetName = (from meta in container.BaseEntitySets
                                where meta.ElementType.Name == entityTypeName
                                select meta.Name).FirstOrDefault();
        return entitySetName;
    }
}

The GetEntitySetName(…) extension method of the ObjectContext type returns the entity set name of a given entity. You’ll see in a second how this is used. This extension method queries the Entity Framework’s metadata in order to retrieve the entity set name. Have a look at Stefan Cruysberghs article to learn how to do this.

Now that the ground work has been laid, let’s finish up. Most of the DAO’s will share the same code, so let’s encapsulate this in an abstract base class. Take a look at the EntityDao type in Listing 6.

Listing 6 – EntityDao type

public abstract class EntityDao<TEntity> : IDao<TEntity> where TEntity : EntityObject, new()
{
    #region Helper methods

    protected ProjectsEntities Context
    {
        get
        {
            return ObjectContextManager.Context;
        }
    }

    private string entitySetName;
    protected string EntitySetName
    {
        get
        {
            if (String.IsNullOrEmpty(entitySetName))
            {
                entitySetName = Context.GetEntitySetName(typeof(TEntity).Name);
            }
            return entitySetName;
        }
    }

    #endregion

    #region IDao<TEntity> Members

    public TEntity Save(TEntity entity)
    {
        Context.AddObject(EntitySetName, entity);
        SaveChanges();
        return entity;
    }

    public void Delete(TEntity entity)
    {
        Context.DeleteObject(entity);
        SaveChanges();
    }

    public void SaveChanges()
    {
        Context.SaveChanges();
    }

    #endregion
}

This makes implementing the DOA interfaces a piece of cake.

Listing 7 – DAO’s

public class PersonDao : EntityDao<Person>, IPersonDao
{ }

public class DeveloperDao : PersonDao, IDeveloperDao
{
    #region IDeveloperDao Members

    public IEnumerable<Developer> GetDevelopers()
    {
        return Context.People.OfType<Developer>();
    }

    #endregion
}

public class AnalystDao : PersonDao, IAnalystDao
{
    #region IAnalystDao Members

    public IEnumerable<Analyst> GetAnalysts()
    {
        return Context.People.OfType<Analyst>();
    }

    #endregion
}

public class ProjectDao : EntityDao<Project>, IProjectDao
{
    #region IProjectDao Members

    public IEnumerable<Project> GetProjectsOfPerson(Person person)
    {
        return from project in Context.Projects
               where project.People.Any(p => p.Id == person.Id)
               select project;
    }

    #endregion
}

Implementing the IDaoFactory interface is equally simple.

Listing 8 – DaoFactory class

public class DaoFactory : IDaoFactory
{
    #region IDaoFactory Members

    public IPersonDao GetPersonDao()
    {
        return new PersonDao();
    }

    public IDeveloperDao GetDeveloperDao()
    {
        return new DeveloperDao();
    }

    public IAnalystDao GetAnalystDao()
    {
        return new AnalystDao();
    }

    public IProjectDao GetProjectDao()
    {
        return new ProjectDao();
    }

    #endregion
}

Top of page

Business Logic

For brevity’s sake (a bit too late at this point) let’s create a simple and light-weight manager class to represent the business logic layer for this article.

Listing 9 – PersonManager class

public class PersonManager
{
    private readonly IDaoFactory daoFactory;

    public PersonManager(IDaoFactory daoFactory)
    {
        this.daoFactory = daoFactory;
    }

    public IEnumerable<Developer> GetDevelopers()
    {
        IDeveloperDao dao = daoFactory.GetDeveloperDao();
        return dao.GetDevelopers();
    }

    public IEnumerable<Analyst> GetAnalysts()
    {
        IAnalystDao dao = daoFactory.GetAnalystDao();
        return dao.GetAnalysts();
    }

    public IEnumerable<Project> GetProjectsOfPerson(Person person)
    {
        IProjectDao dao = daoFactory.GetProjectDao();
        return dao.GetProjectsOfPerson(person);
    }
}

Forgive me for not adding too much logic in this class. Using the PersonManager class you can query the developers, analysts and find out on which projects a particular person (developer or analyst) is working.

Remark: The constructor of the PersonManager class requires that you pass it an object which implements the IDaoFactory interface. This allows you to use your favorite dependency injection library in order to pass in any IDaoFactory implementation. This is all you need to do in order to interchange which DAO implementation will be used by the business logic.

Top of page

A Quick Demo

Let’s put all this code to practice in a demo application. To quickly achieve this let’s create a new Console application. Add the code shown in Listing 10.

Listing 10 -Console Application Demo

class Program
{
    private static readonly IDaoFactory daoFactory = new DaoFactory();
    private static readonly PersonManager manager = new PersonManager(daoFactory);

    private static void ListProjects(Person person)
    {
        IEnumerable<Project> projects = manager.GetProjectsOfPerson(person);
        foreach (var project in projects)
        {
            Console.WriteLine("\t{0}; Deadline: {1}", project.Name, project.Deadline);
        }
    }

    static void Main()
    {
        IEnumerable<Developer> developers = manager.GetDevelopers();
        foreach(var developer in developers)
        {
            Console.WriteLine(String.Format("{0} {1}, {2}", developer.FirstName, developer.Name, developer.PreferedLanguage));
            ListProjects(developer);
        }

        IEnumerable<Analyst> analysts = manager.GetAnalysts();
        foreach (var analyst in analysts)
        {
            Console.WriteLine(String.Format("{0} {1}, {2}", analyst.FirstName, analyst.Name, analyst.Methodology));
            ListProjects(analyst);
        }

        Console.ReadLine();
    }
}

This code displays all the developers and analysts and shows the projects on which each person is working. The output should look something like this.

Figure 7 – Output

Top of page

Summary

This article shows you one possible approach on how to use Data Access Objects (DAO’s) together with the entity framework. I encourage the use of Data Transfer Objects (DTO’s) together with DAO’s if you want to go through the hassle of doing so. If done correctly you should wind up with a business logic layer that’s completely discoupled from the domain model.

This article skipped the use of DTO’s altogether and uses the domain objects themselves as DTO’s. This remains a viable option in my humble opinion as long as you strictly treat them as such.

The only disadvantage is that this requires you to add a reference to the System.Data.Entity assembly to each layer / project that sits on top of the DAO / domain layer thus establishing a coupling, although minimal, to the Entity Framework.

Another disadvantage is that the domain model is too tightly coupled to the Entity Framework technology because each domain object has several attributes and implements at least three interfaces which are all specific to the Entity Framework. Hopefully the EF team will address these Persistence Ignorance issues in the next release.

Dispite some disadvantages I personally feel that the Entity Framework offers too much too ignore and can certainly be a more than useful ORM tool.

For further reading I strongly recommend Vijay P. Mehta’s book “Pro LINQ Object Relational Mapping with C# 2008“.

Top of page

Download

You can find the source code for this article on the Download page of this blog.

Top of page

Introduction

It’s been a good two months since the last post. Today I finally found some spare time to write a new article about .NET. This will be the first article on this blog focusing solely on the Entity Framework. More in particular about using the Entity Framework in different environments such as Windows Applications and in an ASP.NET environment.

The Entity Framework has some drawbacks that will hopefully be addressed in the second release, but in its current state it’s already a really useful technology to use for database access.

This article will not discuss every feature of the Entity Framework as that would entail writing an entire book. The primary focus is on how to deal with the ObjectContext in different environments such as a regular Windows Application and a Web Application (ASP.NET). Let’s get started…

Table Of Contents

• Introduction
• ObjectContext
• Demo Solution
• Windows Application
• Shared ObjectContext
• ObjectContext in ASP.NET
• Summary
• Download

ObjectContext

As you may be aware every object returned by a query (Linq To Entities, Entities SQL…) is automatically attached to an object context. This context tracks the changes applied to these objects so that it can later figure out how to persist these changes to the underlying data store.

This object context is represented by a class fittingly named ObjectContext. The ObjectContext encapsulates a couple of things, namely:

• The connection to the underlying data store (database)
• Metadata describing the Entity Data Model (EDM)
• An ObjectStateManager for tracking changes to the objects

As you will see in the next sections how you deal with the ObjectContext depends on the target platform of your application.

Top of page

Demo Solution

Let’s quickly setup up a demo project that we can use throughout the rest of this text. First let us create a simple database using SQL Server consisting out of two tables [Customer] and [Order].

The following two figures list the columns for each of these tables. You can find the DDL statements to build this database in the source code accompagnying this article.

I’ve called my database “Westwind” but feel free to choose a more appropriate name.

Figure 1 – Customer table

Figure 2 – Order table

The [Order] table contains a foreign key connecting it’s CustomerId column to the Id column of the [Customer] table. Thanks to this relation we can easily navigate back and forth between the Customer and Order entities in the resulting Entity Data Model (EDM).

Now fire up Visual Studio 2008 and create a new blank solution named “ObjectContext” and add a class library to it (C#) titled “DAL” (short for Data Access Layer). Delete the automatically generated class Class1 and add a new ADO.NET Entity Data Model called “Westwind.edmx”.

Using the resulting wizard choose the option “Generate from database” to let Visual Studio generate an Entity Data Model based upon the previously created database. After the model is generated the necessary references to the required assemblies are automatically added to the project.

Figure 3 – ObjectContext Solution

The Entity Data Model contains two entities, namely Customer and Order. I’ve renamed the Entity Set Name properties of the Customer and Order entities respectively to Customers and Orders. As a last step the navigation property Order on the Customer entity has been renamed to Orders as a customer can have one or more orders.

Figure 4 – Westwind Entities

Voila, that concludes setting up the demo project. Let’s move on to the next section…

Remarks

• Be sure you have the first service pack installed for both the .NET Framework 3.5 and Visual Studio 2008 as both are required in order to be able to work with the Entity Framework.
• The example is kept as simple as possible in order to focus solely on the subject of this article. It’s not a guideline on how to organize your projects into different layers and such.

Top of page

Windows Application

I’ve added some dummy data to the table using SQL Server Management Studio Express. There are three customer and each has exactly one order.

Figure 5 – Customer Data

Figure 6 – Order Data

Regular Windows Applications (Console, WinForms, WPF…) are the easiest to work with in regard to handling the ObjectContext. Let’s demonstrate this using a Console application.

Add a new Console application and add a reference to the DAL project and the System.Data.Entity assembly. Next add an application configuration file (App.config) and copy the connection string found in the App.config file of the DAL project. Finally add the code of Listing 1 to the main method.

Listing 1 – ObjectContext in a Console application

using (var context = new WestwindEntities())
{
    // Query all the orders.
    var q = from o in context.Orders.Include("Customer") orderby o.Total select o;
    foreach(var order in q)
    {
        Console.WriteLine(String.Format("{0} {1} has an order costing {2}.",
                                        order.Customer.Firstname, order.Customer.Lastname,
                                        order.Total));
    }
    Console.WriteLine();

    // Update the first order.
    Order firstOrder = q.FirstOrDefault();
    if (firstOrder != null)
    {
        firstOrder.Total += 10;
        context.SaveChanges();
    }

    // Display the order once more.
    foreach (var order in q)
    {
        Console.WriteLine(String.Format("{0} {1} has an order costing {2}.",
                                        order.Customer.Firstname, order.Customer.Lastname,
                                        order.Total));
    }

    Console.ReadLine();
}

A new connection (context) is made to the database and the orders are queried and displayed. Next the first order found is updated and finally the orders are displayed once more.

All this happens using the same ObjectContext (see the using statement). It tracks the changes made to the order objects and generates the necessary SQL to persist these changes in the database upon the call to context.SaveChanges().

Figure 7 – The Output

If you’re interested in finding out what the generated SQL looks like I recommend using the AnfiniL’s SQL Express Profiler tool. It’s free and easy to use.

Top of page

Shared ObjectContext

You can as the previous example has shown create an ObjectContext when needed and dispose of it immediately after. However you can also choose to share the same ObjectContext accross multiple methods, instances…etc. if you want to limit the amount of ObjectContext instances in your application.

One way of doing this is to encapsulate the ObjectContext in a class that adheres to the singleton pattern. Take a look at the code in Listing 2.

Listing 2 – Shared ObjectContext

public class SharedObjectContext
{
    private readonly WestwindEntities context;

    #region Singleton Pattern

    // Static members are lazily initialized.
    // .NET guarantees thread safety for static initialization.
    private static readonly SharedObjectContext instance = new SharedObjectContext();

    // Make the constructor private to hide it. 
    // This class adheres to the singleton pattern.
    private SharedObjectContext()
    {
        // Create the ObjectContext.
        context = new WestwindEntities();
    }

    // Return the single instance of the ClientSessionManager type.
    public static SharedObjectContext Instance
    {
        get
        {
            return instance;
        }
    }   

    #endregion

    public WestwindEntities Context
    {
        get
        {
            return context;
        }
    }
}

The following Listing shows how you would use this shared ObjectContext.

Listing 3 – Usage Of The Shared ObjectContext

WestwindEntities context = SharedObjectContext.Instance.Context;

var q = from o in context.Orders.Include("Customer") orderby o.Total select o;

foreach (var order in q)
{
    Console.WriteLine(String.Format("{0} {1} has an order costing {2}.",
                                    order.Customer.Firstname, order.Customer.Lastname,
                                    order.Total));
}

Console.ReadLine();

You can find this code in the ConsoleSharedObjectContext project included in the demo source code.

Remark: Limit the scope of the ObjectContext. It is recommended to use the ObjectContext instance within a using statement. This ensures that the resources associated with the ObjectContext are automatically disposed when the using statement exists. Make sure your application benefits from a shared ObjectContext, for instance if you bind control to objects maintained by the ObjectContext.

Top of page

ObjectContext in ASP.NET

To quote MSDN: “The ObjectContext class is not thread safe. The integrity of data objects in an ObjectContext cannot be ensured in multi-threaded scenarios.”.

This rules out using the afore mentioned approach in an ASP.NET environment as it is inheritly multi-threaded. Each request is handled by a separate thread. To circumvent the problem the solution is to use an ObjectContext per Http request. The following Listing shows one possible approach.

Listing 4 – ObjectContext Per Http Request

public static class ObjectContextPerHttpRequest
{
    public static WestwindEntities Context
    {
        get
        {
            string objectContextKey = HttpContext.Current.GetHashCode().ToString("x");
            if (!HttpContext.Current.Items.Contains(objectContextKey))
            {
                HttpContext.Current.Items.Add(objectContextKey, new WestwindEntities());
            }
            return HttpContext.Current.Items[objectContextKey] as WestwindEntities;
        }
    }
}

To demonstrate its usage add a new Web Application project to the solution, add the necessary references to the DAL project and the System.Data.Entity assembly. Finally add the connection string to the Web.config file.

Open up the default.aspx page in design view and add a GridView. Add the following code to the code-behind in the Page_Load(…) event handler to bind some data to the grid.

Listing 5 – Default.aspx.cs code-behind

protected void Page_Load(object sender, EventArgs e)
{
    WestwindEntities context = ObjectContextPerHttpRequest.Context;
    GridView1.DataSource = from c in context.Customers select c;
    GridView1.DataBind();
}

The output is a list of the customers.

Figure 8 – The Output In ASP.NET

Top of page

Summary

While there is much debate going on about the Entity Framework I certainly feel that this first release offers a valid alternative to any prior existing data access technologies.

Working with the Entity Framework entails dealing with the ObjectContext. As demonstrated the way the ObjectContext is too be handled depends on the target platform. Sharing the ObjectContext on one thread poses no problem (Windows Applications), however as soon as you end up in a multi-threaded environment (ASP.NET) you must implement some custom logic to ensure the integrity of the data objects within the ObjectContext.

Top of page

Download

You can find the source code for this article on the Download page of this blog.

Top of page

Introduction

Last week I was reading some articles about using WCF, the Entity Framework and how to transport entities across the service boundary. One of the articles I encountered included a demo project that made use of the Model View Presenter (MVP) pattern.

Having explored the demo project I thought it might be interesting to write an article about this pattern. Your favorite search engine will happily supply you with a plethora of links to other articles that explain this pattern thoroughly.

For this article I’ve decided to supply a concrete implemention and to focus less on the theory behind the pattern.

Let’s roll…

Table Of Contents

• Introduction
• The Pattern
• Model
• Business Layer
• View
• Presenter
• ASP.NET User Interface
• WinForms User Interface
• Summary
• Download

The Pattern

Of course a bit of theory is required, so let’s get it out of the way.

As you can deduct from the name the MVP pattern consists out of three distinct parts: the Model, View and Presenter. Each of these parts play their own role in establishing a separation of concerns between the presentation, business and data access layer.

The Model is responsible for handling the data access, the Presenter communicates with the Model and passes data from and to it. The View receives data from the Presenter and passes data back, it never communicates directly with the Model. The Presenter is the go-between for the View and Model.

Figure 1 – MVP Pattern Interaction

The image above depicts the View as implementing an interface. The presentation layer be it an ASP.NET, WinForms or WPF applications needs to implement one or more view interfaces. The Presenter in turn communicates with the View implementation through this interface, it knows nothing about the actual implementation itself.

This provides a loose coupling and prevents your code from being dependant on the technology used for the Presentation Layer. The idea is that you should be able to replace this layer without it affecting your business and data access logic.

This might all seem a little vague, but things should clear up once we move on to the following points which provide an actual implementation of this pattern. For the example an ASP.NET application will be used.

Top of page

Model

The most logical place to start with is the Model. Since it is responsible for handling data access and storage we first need to establish a physical data store. For this I used SQL Server 2005 Express, created a new database called Southwind and added one table titled Customer. The table has 3 fields, namely:

• Id: Unique identifier (GUID) & Primary key
• Firstname: nvarchar(50)
• Lastname: nvarchar(50)

That’s it for the database. Let’s fire up Visual Studio 2008 and create a new blank solution named AvpPattern. Next add a class library titled “Database”.

Normally I’d give the project a name that follows the pattern “Company.Product.Library”, but for simplicity’s sake let’s keep it short and simple. Also delete the autogenerated class1.cs file after the project has been added to the solution.

Let’s create a model from the database using the Entity Framework (EF). So be sure you are using Visual Studio 2008 and have Service Pack 1 installed for Visual Studio and the .NET Framework 3.5. You can download the service packs here.

Add a Entity Framework data model to the class library by selecting Add, New Item, ADO.NET Entity Data Model from the project’s context menu in the Solution Explorer. Visual Studio will now show the Entity Data Model Wizard. Name the model Southwind and let Visual Studio generate the model for you. When asked which database objects you want to include in your model just select the Customer table from the tables node.

Remark: If you are not familiar with generating data models with the Entity Framework I highly suggest this training video from Alex James. It shows you how to build a simple Entity Data Model from scratch.

Figure 2 shows the resulting entity data model. The model can’t get much simpler than this. This is done on purpose to keep things as simple as possible and to keep the focus on the MVP pattern.

Figure 2 – Entity Data Model

Be sure to rename your EntityTypes and EntitySets to an appropriate name after the data model has been generated. The rule of thumb is to use a single noun for the EntityType and a plural for the EntitySets. So in this case our EntityType should be named Customer and the EntitySet Customers. The name for the EntityType is already ok as it inherits it from the Customer table, so just select the Customer EntityType and adjust its Entity Set Name property.

Figure 3 – Entity Set Name

The Entity Framework will automatically generate a partial class for the Customer table. You can choose to extend this partical Customer class if you want to. To prevent your custom additions from being erased when regenerating the model put this code in a separate class file. This is simular to working with strongly typed datasets. For the article this is not required however.

Figure 4 – Solution Explorer

Top of page

Business Layer

Now that the model is in place let’s add a business layer on top of it where we can define our custom business logic. For simplicity’s sake I will keep the amount of code limited in this layer.

Note that these layers only enforce a logical separation (n-layer), not a physical one (n-tier). The layers all reside on the same machine, though you could certainly choose to disbribute them across multiple machines / tiers and create a truly distributed or n-tier application.

To setup the Business Layer add a new class library to the solution and call it Business. Next rename the default Class.cs file to CustomerManager.cs. Also add references to the previously created class library Database and to the System.Data.Entity assembly.

Listing 1 displays the CustomerManager class which contains some business logic for working with the Customer entity from the Entity Data Model (EDM). The code is pretty much self-explanatory.

Listing 1 – CustomerManager class

using System.Collections.Generic;
using System.Linq;
using Database;

namespace Business
{
    public class CustomerManager
    {
        private readonly SouthwindEntities context;

        #region Constructor(s)

        public CustomerManager()
        {
            context = new SouthwindEntities();
        }

        #endregion

        #region Methods

        // Retrieve a generic list of Customer entities.
        // This method will return all the customers found in the Customer table.
        public List<Customer> GetCustomers()
        {
            var q = from c in context.Customers
                    select c;
            return q.ToList();
        }

        #endregion
    }
}

Figure 5 – Updated Solution

Remark: Setting up an n-tier application would include introducing a Service Layer which the Presentation Layer calls into. The Service Layer then utilizes the business objects found in the Business Layer. There is no direct association between the Presentation and Business Layer anymore, the Service Layer acts as an intermediate. In a future article I will address this by showing how to transport EF Entities across the service boundary.

Top of page

View

The Business Layer only contains one useful method, namely “List<Customer> GetCustomers()”. The Presenter in the MVP pattern will call this method on the CustomerManager business object in order to deliver the data to the view.

The example application only shows a list of customers using the MVP pattern. This might be a bit of overkill, but it’s kept as simple as possibly by design. The main goal of this “Hello World!” type of application is to get the idea across of how to implement this pattern. The actual functionality offered by the application is not that important.

The actual view implementation (ASPX page, WinForms, WPF…etc.) will need to implement a view interface. The view implementation needs to create an instance of the Presenter and pass itself as a parameter in its constructor. The Presenter’s constructor has one parameter which is the type of the view interface.

Listing 2 lists the IView interface which we will implement shortly in an ASP.NET ASPX page. It has one event named PrepareView. The PrepareView event uses a delegate whose signature specifies that it returns nothing and takes no parameters.

The View should only raise these kind of “empty events” as to signify to the Presenter that some action should be performed. The action in this case signifies that the Presenter should refresh the list of Customers that the view implementation maintains. The Presenter can access this list of customers through the IList<Customer> Customers property which is declared as part of the interface.

Listing 2 – View Interface

public delegate void VoidEventHandler();

public interface IView
{
    event VoidEventHandler PrepareView;
    IList<Customer> Customers { set; }
}

To add the view interface to your project first add a new class library project to the solution called Presentation. Next add a new interface and copy and paste the code shown in the above listing. The Presentation code library will also contain the Presenters and the interfaces they implement.

I separate the view interfaces and presenters in a separate code library so that you can easily share them between multiple “view frameworks” such as ASP.NET, WinForms, WPF…etc. Figure 6 shows how I’ve chosen to organise this code library.

Figure 6 – Updated Solution

Don’t forget to add references to the Database and Business projects and the System.Data.Entity assembly.

Top of page

Presenter

For the final part of the MVP pattern we need to provide a Presenter. The CustomersPresenter class shown in Listing 3 takes a reference to an IView implementation in its constructor. This way it can communicate with the view without actually knowing anything about the actual implementation. It is this loose coupling that makes the MVP pattern so suitable for different “view frameworks”.

Also in the constructor all the events of the view interface are hooked up to an event handler. In this case there is only one event. The PrepareView event is hooked up to the view_PrepareView event handler. This in turn calls the Presenter’s private method GetCustomers() which returns a “refreshed” Customers collection and assigns it to the Customers collection maintained by the view implementation.

Listing 3 – CustomersPresenter class

public class CustomersPresenter : ICustomersPresenter
{
    #region Fields

    private readonly IView view;

    #endregion

    #region Constructor(s)

    public CustomersPresenter(IView view)
    {
        // Save a reference to the view
        this.view = view;

        // Hook up an event handler for the events of the view
        view.PrepareView += view_PrepareView;
    }

    #endregion

    #region Private methods

    private List<Customer> GetCustomers()
    {
        return new CustomerManager().GetCustomers();
    }

    #endregion

    #region ICustomersPresenter Members

    public virtual void view_PrepareView()
    {
        view.Customers = GetCustomers();
    }

    #endregion
}

The above Presenter also implements an interface. In the sample source code this interface is left empty. I’ve only put it there for illustrative purposes. You can flesh out this interface if you desire. You might need it for your favorite unit testing framework to mock presenters for example.

Top of page

ASP.NET User Interface

So the view or ASPX page in our case only needs to implement the view interface and trigger the PrepareView event in order to receive an updated customers list from the Presenter. The view itself does not communicate with the database or Business Layer directly. The Presenter handles the communication with the Business Layer which retrieves the data by addressing the Model (or Data Access Layer if you will).

To finish up this article let’s see how this all comes together in an ASP.NET demo project. Add a new project using the ASP.NET Web Application project template to the solution. Add references to the Presentation and Database projects and the System.Data.Entity assembly.

Add a GridView named “GridView1″ and a Button named “btnRefresh” to the Default.aspx page. Add the code in Listing 4 to the code behind of the page.

Listing 4 – Default.aspx Code Behind

public partial class _Default : System.Web.UI.Page, IView
{
    private CustomersPresenter presenter;

    protected override void OnInit(EventArgs e)
    {
        presenter = new CustomersPresenter(this);
    }

    protected void Page_Load(object sender, EventArgs e)
    {
        if (!IsPostBack)
        {
            PrepareView();
        }
    }

    protected void btnRefresh_Click(object sender, EventArgs e)
    {
        PrepareView();
    }

    #region IView Members

    public event VoidEventHandler PrepareView;

    public IList<Database.Customer> Customers
    {
        set
        {
            GridView1.DataSource = value;
            GridView1.DataBind();
        }
    }

    #endregion
}

All the code behind of the ASPX page does is implement the IView interface, create a Presenter and pass an IView implementation, being itself, into its constructor. Then all that remains is to trigger the PrepareView() event of the IView interface at the appropriate times.

During the creation of the Presenter an event handler is automatically assigned to this event which makes sure that when it is triggered the Presenter knows how to update the Customers collection maintained by the page. The page itself knows nothing of where this data is coming from or how it is retrieved. The dumber a view the better.

When viewing this page in a browser this is the result:

Figure 7 – ASP.NET Website Demo

Remark: Don’t forget to add the connectionstring required by the Entity Framework to the web.config configuration file. You can find the connectionstring in the App.config file of the Database class library project. It was inserted there automatically when Visual Studio generated the Entity Data Model.

Of course the connection strings in supplied in the sample source code won’t work on your computer as they were constructed against a local database of mine. So be sure to adjust them accordingly.

Figure 8 – Updated Solution

Top of page

WinForms User Interface

As the final step of this article let’s create a view using a Windows Forms application just to show you how flexible the MVP pattern really is. The steps to do this are nearly identical to the previous example of creating an ASP.NET website. Add a new Windows Forms application to your solution and add references to the Database and Presentation project and the System.Data.Entity assembly.

Next add a DataGridView and Button control to the form. The code for the form is displayed in the listing below. It is almost identical to that of the Default.aspx page. Also don’t forget to add the Entity Framework connection string to the App.config configuration file.

Listing 5 – Form1.cs code

using System;
using System.Windows.Forms;
using Presentation.Presenters;
using Presentation.ViewInterfaces;

namespace WindowsFormsApplication
{
    public partial class Form1 : Form, IView
    {
        private CustomersPresenter presenter;

        public Form1()
        {
            InitializeComponent();

            presenter = new CustomersPresenter(this);
        }

        private void Form1_Load(object sender, EventArgs e)
        {
            PrepareView();
        }

        private void btnRefresh_Click(object sender, EventArgs e)
        {
            PrepareView();
        }

        #region IView Members

        public event VoidEventHandler PrepareView;

        public System.Collections.Generic.IList<Database.Customer> Customers
        {
            set
            {
                dataGridView1.DataSource = value;
            }
        }

        #endregion
    }
}

Voila, we’re finally done. Note that although the ASP.NET and WinForms example are almost identical in code this might not be the case in more complex applications. The types of interactions in these two types of user interfaces are vastly different and coming up with a presenter you can use in all situations might not be that clear cut.

Figure 9 – Windows Forms Application Demo

Figure 10 – Updated Solution

Top of page

Summary

For this article the classic interpretation of the MVP pattern was used and demonstrated by implementing it an ASP.NET solution. The original MVP pattern is deemed “retired” ever since Martin Fowler announced so. The pattern can be split into two camps now, being:

• Passive View
• Supervising Controller

Read this Microsoft Patterns & Practices article for more information.

I wrote this article to supply a concrete implementation of the MVP pattern as I was exploring it at the time. However it might be wise to stay clear of it and wait until Microsoft releases the ASP.NET MVC framework. For those wishing to mimic an Model-View-Controller (MVC) framework now I suggest reading this article by Microsoft Patterns & Practices.

Remark: The MVP pattern is a derivative of the Model View Controller pattern (MVC). At the time of this writing Microsoft is currently busy developing the ASP.NET MVC Framework. When mapping out the architecture for a new website project I suggest checking out this framework.

The main difference between the MVP and MVC patterns can be pinpointed to who is responsible for handling the user input such as keyboard and moue events. In the MVP pattern the GUI itself is responsible and needs to delegate them to the Presenter through events. In the MVC pattern the controller is responsible for handling these events.

Top of page

Download

You can find the source code for this article on the Download page of this blog.

Top of page

Introduction

The purpose of this article is to create a slick looking and easy to use menu for an ASP.NET enabled website. In order to accomplish this we’ll use the standard functionality of the ASP.NET Menu web control and enhance the look purely by using Cascading Style Sheets (CSS).

For those of you familiar with CSS the title of this article will surely ring a bell. The CSS used to enhance the look and feel of the ASP.NET Menu control is decribed in a widely known article on A List Apart, entitled “Sliding Doors of CSS“.

The CSS used to improve the look and feel of the menu is thoroughly explained in the article on A List Apart. Credit when credit is due. Thank Douglas Bowman for supplying us with the CSS. Be sure to read his article first if you are not familiar with it.

The focus of this article is on how to simulate such a menu in an ASP.NET environment. Let’s get started…

Table Of Contents

• Introduction
• Sitemap
• CSS Friendly Adapters
• Styling The Menu
• Sub Menu
• Finishing Up
• Summary
• Download

Sitemap

Let’s fire up Visual Studio 2008 and create a new project using the ASP.NET Web Application project template. This template will automatically add a default web form appropriately named “Default.aspx”. Open it in the editor and add the Menu control from the Toolbox which you can find under the Navigation tab. If you run the website now you’ll wind up staring at a blank page. For the menu to display anything it first has to be bound to some data.

The easiest way to define data for the menu control to use and enable the visitors to navigate through the website is to bind it to a site map. Add a new site map item to the project using the proposed name of “Web.sitemap”. The site map is an Xml file that organizes the pages of the site in a hierarchical manner. An added advantage is that it is automatically referenced by the SiteMapDataSource control.

Next add some pages to the sitemap as displayed in the listing below.

Listing 1 – Web.sitemap

<?xml version="1.0" encoding="utf-8" ?>
<siteMap xmlns="http://schemas.microsoft.com/AspNet/SiteMap-File-1.0" >
    <siteMapNode url="" title=""  description="">
      <siteMapNode url="Default.aspx" title="Home"  description="Take me back to the dasboard" />
      <siteMapNode url="Products.aspx" title="Products"  description="Browse our catalog" />
      <siteMapNode url="Download.aspx" title="Download"  description="Download neat stuff" />
      <siteMapNode url="Forum.aspx" title="Forum"  description="Ask questions on our forum" />
      <siteMapNode url="Contact.aspx" title="Contact"  description="Contact us" />
    </siteMapNode>
</siteMap>

Now add a SiteMapDataSource control to the page and set the DataSourceID property of the menu control to the Id of the data source. Also set the Orientation property of the menu control to horizontal as it defaults to vertical. Last but not least set the ShowStartingNode property of the SiteMapDataSource to false. If you don’t do this only the root node will be displayed and we don’t want to include this base node in the menu. Your code should now resemble the code displayed in Listing 2.

Listing 2 – Default.aspx

<asp:Menu ID="Menu1" runat="server" DataSourceID="SitemapDataSource1" Orientation="Horizontal"></asp:Menu>
<asp:SiteMapDataSource ID="SiteMapDataSource1" runat="server" ShowStartingNode="False" />

If you view the page in a browser now you should see a functional, yet boring menu.

Figure 1 – Plain horizontal menu

ASP.NET Menu control in action

Top of page

CSS Friendly Adapters

Before we can start applying CSS to the menu there is another issue that needs to be addressed first. If you take a look at the resulting HTML code that is generated when you request the default.aspx page you’ll notice that the menu control does not generate the most flexible HTML code. By default it wraps each menu item in a table. This does not lend itself for easily applying CSS. It would be better if the Menu control generated an unordererd list which contains all the menu items.

Luckily the generated HTML can be adjusted by using control adapters. Control adapters allow you to render the HTML you prefer. Thankfully such control adapters are readily available on CodePlex. The CSS Friendly Control Adapters kit provides pre-built control adapters, including one for the ASP.NET Menu control.

To use the CSS Friendly Control Adapters follow these steps:

• Download the latest release. Download the version containing the source code and not the compiled assembly.
• Add the downloaded project to your solution.
• Download the CSSFriendlyAdapters.browser file and add it to the App_Browsers folder of your ASP.NET Website project.

It is necessary to use the source code and compile the CSSFriendly.dll assembly ourselves because we need to tweak some of the CSS used by the adapters later on in this article.

When adding the CSSFriendly project to your solution the Visual Studio Conversion Wizard will popup. Just execute the conversion, everything should go smoothly. When the conversion has completed all that remains is to add a reference to the CSSFriendly project from the ASP.NET Website project.

Just run the website and take a look at the generated HTML code now.

Listing 3 – CSS Friendly HTML code

<div class="AspNet-Menu-Horizontal" id="Menu1">
    <ul class="AspNet-Menu">
        <li class="AspNet-Menu-Leaf  AspNet-Menu-Selected">
            <a href="/Default.aspx" class="AspNet-Menu-Link  AspNet-Menu-Selected" title="Take me back to the dasboard">Home</a>
        </li>
        <li class="AspNet-Menu-Leaf">
            <a href="/Products.aspx" class="AspNet-Menu-Link" title="Browse our catalog">Products</a>
        </li>
        <li class="AspNet-Menu-Leaf">
            <a href="/Download.aspx" class="AspNet-Menu-Link" title="Download neat stuff">Download</a>
        </li>
        <li class="AspNet-Menu-Leaf">
            <a href="/Forum.aspx" class="AspNet-Menu-Link" title="Ask questions on our forum">Forum</a>
        </li>
        <li class="AspNet-Menu-Leaf">
            <a href="/Contact.aspx" class="AspNet-Menu-Link" title="Contact us">Contact</a>
        </li>
    </ul>
</div>

Things are looking up now.

Remark: The CSSFriendlyAdapters.browser file allows you to specify which CSS Friendly control adapters should be used. I make a habbit of commenting all of the adapters except the ones I want to use. This way no other controls are “adapted” and they’ll keep generating the default HTML.

Top of page

Styling The Menu

As you can see from the code displayed in the listing above the adapter for the menu control automatically injects the necessary CSS classes for the <ul>, <li> and <a> tags. This saves us the trouble from having to define these.

It is also quite common for a single page to contain more than a single adapter control such as a menu. If you want a distinct look and feel for each control then set the CssSelectorClass for the adapted control. For instance, you might set the value of the CssSelectorClass property as follows:

Listing 4 – CssSelectorClass property

<asp:Menu ID="Menu1" runat="server" DataSourceID="SitemapDataSource1" Orientation="Horizontal" CssSelectorClass="PrettyMenu">

The result is that the HTML code generated by the adapted control will be contained within a new layer (<div>).

Listing 5 – Wrapping the generated HTML code

<div class="PrettyMenu" id="Menu1">
<!-- Other HTML code -->
</div>

Note that this property is specific to the CSS Friendly Adapters. It is a custom (expando) attribute which you can set for the controls supported by this library. It you require more information about the way the Friendly Adapters work, then please consult the following links:

• ASP.NET 2.0 CSS Friendly Control Adapters: The Walkthrough
• ASP.NET 2.0 CSS Friendly Control Adapters: The White Paper

With the CssSelectorClass generating a separate layer (<div>) around the menu and the automatically injected CSS classes in place we are finally ready to commence styling the menu.

The CSS used is simular to that of the A List Apart article. As mentioned before the focus of this article isn’t on the structure of the CSS but rather on how to apply it to the ASP.NET Menu control in order to obtain a neat looking tabular menu. The finished result can be seen in Figure 2.

Figure 2 – The Finished result

Fancy menu in action

On the download page you can find the source code for this article. It contains the style sheet and the necessary images. Just perform the following steps to recreate the finished result:

• Add a Theme called “Default” under the ASP.NET folder Asp_Themes
• Add the existing images found in the compressed file containing the source code for this article under the newly create theme folder
• Add a style sheet called global.css to the Default theme
• Copy the contents of my global.css style sheet and paste them into your style sheet
• Open the web.config file and set the Theme property for the <Pages> node to Default. (See Listing 6)

Listing 6 – Web.config excerpt

<system.web>
  <!-- ... -->
  <pages theme="Default">
    <!-- ... -->
  </pages>
  <!-- ... -->
</system.web>

The CSS used in my solution is simular to that of the article on A List Apart, but there are some changes. Mainly the changes correlate to the CSS structure applied by the CSS Friendly Adapters.

In order to apply the CSS the correct structure needs to used. When styling a control whose HTML is adjusted by a Friendly Adapter I find it handy to use diagrams mentioned in the white paper. These diagrams clearly show you how the CSS is structured.

You can find the diagram for the menu control here.

Top of page

Sub Menu

One question I frequently came accross on a lot of forums is how to implement a horizontal sub menu which changes when the user selects a different tab from the top level menu. To create this we first need to adjust our site map.

Listing 7 shows the adjusted site map.

Listing 7 – Web.sitemap with “sub menu items”

<?xml version="1.0" encoding="utf-8" ?>
<siteMap xmlns="http://schemas.microsoft.com/AspNet/SiteMap-File-1.0" >
    <siteMapNode url="" title=""  description="">
      <siteMapNode url="Default.aspx" title="Home"  description="Take me back to the dasboard">
        <siteMapNode url="About.aspx" title="About us" description="" />
        <siteMapNode url="Foo.aspx" title="Foo" description="" />
        <siteMapNode url="Bar.aspx" title="Bar" description="" />
      </siteMapNode>
      <!-- ... -->
</siteMap>

For brevity’s sake Listing 7 only displays the sub menu items (nodes) for the Home node. Check out the Web.sitemap in the source code for the complete version. Now when you browse the website using this site map you’ll see the effect shown in Figure 3.

Figure 3 – Sub menu items

Sub menu items in action

To disable this effect set the MaximumDynamicDisplayLevels property of the menu control to zero as shown in Listing 8.

Listing 8 – MaximumDynamicDisplayLevels property

<asp:Menu ID="Menu1" runat="server" DataSourceID="SitemapDataSource1"
          Orientation="Horizontal" CssSelectorClass="PrettyMenu"
          MaximumDynamicDisplayLevels="0">

Next add a second Menu and SiteMapDataSource control and set their properties as shown in Listing 9.

Listing 9 – Sub menu control

<asp:Menu ID="Menu1" runat="server" DataSourceID="SitemapDataSource1"
    Orientation="Horizontal" CssSelectorClass="PrettyMenu"
    MaximumDynamicDisplayLevels="0">
</asp:Menu>
<asp:Menu ID="Menu2" runat="server" DataSourceID="SitemapDataSource2"
    Orientation="Horizontal" CssSelectorClass="PrettySubMenu">
</asp:Menu>
<asp:SiteMapDataSource ID="SiteMapDataSource1" runat="server" ShowStartingNode="False" />
<asp:SiteMapDataSource ID="SiteMapDataSource2" runat="server" StartingNodeOffset="1" ShowStartingNode="False" />

We basically tell the second menu that it should display the second level of nodes found in the site map and that it should not display the starting node which corresponds to the selected tab of the first menu.

Also the CssSelectorClass for the second menu is set to PrettySubMenu. The CSS for this menu is simular to the first menu. Download the source code if you want to check it out. Running the website now will give you this spiffy result.

Figure 4 – Styled sub menu items

Styled Sub Menu Items

Top of page

Finishing Up

One last issue needs to be resolved. In order to illustrate this issue the project needs to be reorganized.

First let’s add a master page to the project called Site.master. Move the code, the menus and data sources, from the Default.aspx page to the master page and place it just before the first content place holder in the body. Afterwards you can safely delete the Default.aspx page.

Now let’s add a few Web Content Form items to the project. Add Web Content Forms that correspond to the items of the first node of the site map and its sub nodes, namely:

• Default.aspx
• About.aspx
• Foo.aspx
• Bar.aspx

Be sure to choose Site.master as the master page for each of these web content forms. The other pages mentioned in the Web.sitemap are purely there for illustrative purposes.

Launch the site again, and navigate to the Foo page. This will reveal the issue.

Figure 5 – Selection issue

Which Top Level Menu is selected?

Because we have navigated to the bottom level in the site map the top level menu does not know which menu item it should mark as selected. We will need do some coding in the master page’s code behind in order to solve this.

Listing 10 shows you the necessary morsel of code.

Listing 10 – Selecting the correct top level menu item

namespace MenuWebApplication
{
    public partial class Site : System.Web.UI.MasterPage
    {
        private static string ExtractBaseUrl(string url)
        {
            return url.Contains("?") ? url.Remove(url.IndexOf('?')) : url;
        }

        protected void Page_Load(object sender, EventArgs e)
        {
            Menu1.DataBind();

            // Which node in the site map is currently selected?
            SiteMapNode currentNode = SiteMap.CurrentNode;
            if (currentNode != null)
            {
                // Obtain the Url of the currently selected node's parent node.
                string parentUrl = String.Empty;
                SiteMapNode parentNode = currentNode.ParentNode;
                if (parentNode != null)
                {
                    parentUrl = ExtractBaseUrl(parentNode.Url);
                }

                // Obtain the Url of the currently selected node.
                string currentUrl = ExtractBaseUrl(currentNode.Url);

                // Iterate the top level menu tier.
                foreach (MenuItem menuItem in Menu1.Items)
                {
                    // Compare the menu item's Url against the currently 
                    // selected node's Url or the Url of its parent.
                    string menuItemUrl = ExtractBaseUrl(menuItem.NavigateUrl);
                    if ((currentUrl == menuItemUrl) || (parentUrl == menuItemUrl))
                    {
                        // If either matches then mark the top level menu item as selected.
                        Menu1.Items[Menu1.Items.IndexOf(menuItem)].Selected = true;
                        break;
                    }
                }
            }
        }
    }
}

Now you are free to select any of the sub menu items. It’s corresponding top level menu item will stay selected to give the visitor a visual clue as to where he currently is located within the website.

Figure 6 – Selection issue fixed

Sub Menu Item Tracking

Top of page

Summary

It’s quite a bit of work to establish a fancy tabular menu with a context sensitive horizontal sub menu but in the end you wind up with a slick looking and user friendly menu.

I suggest that you implement such a menu in a user control and include that user control on your web site’s master page. In most cases one such menu will be used throughout the entire website.

If you have any comments or suggestions I’ll be glad to hear them.

Top of page

Download

You can find the source code for this article on the Download page of this blog.

Top of page