Using internal within the domain layer

There is a very nice trick you can do with the internal key word that I think is worth writing about. If you want to implement an Active Record class, such as customer.Save(), sometimes we might not want the presentation layer to have access to this method directly and pass via an application layer.

so the presentation layer code will call something like this:

customerService.SaveCustomer(customer) instead of customer.Save()

The reason is that within the application layer we might want to handle error handling and logging, work that normally does not belong in the domain. With internal it is very possible. First you have to place your Customer in its own assembly. Company.Domain.dll and your presentation would be in its own assembly as well Company.Presentation.dll

Now the methods and even properties you don't want the UI to access directly are marked as internal

// Customer class
internal Save()
{
   // save the information within customer
}

The application layer needs to be within the same assembly as the domain, so its has access to internal members. Now our application layer can do something like this:

public CustomerService
{
     public SaveCustomer(Customer cust)
     {
        try
        {
            //delegate the work to domain, 
            //the Save method is visible to the application layer
            cust.Save();    
        }
        catch(Exception e)
        {
             Logger.LogException(e); // perform logging 
        }
     }
}

You can even take the idea further by marking certain properties as internal, so the presentation layer will not see them at all.

This is just one way of limiting the visibility of members and properties of a class, and I believe it is an elegant and nice solution when you want to control member visibility between the presentation layer and Active Record domain classes.

One last note...

I am not a big fan of active record and believe more in repositories, however active record has its place in DDD, it works well when the class maps well to the persistence layer.

So... remember, not everything should be public, some data should be kept "internal" to the domain.

A note about EndInvoke()

I think it is important to mention something about the EndInvoke. You should know that calling EndInoke is not optional, if you don't call it there will be some sort of memory leak. Even if you don't need to know when you method finished executing, and even if there are no output parameters and return value parameters you need analyse, its a good idea to call Endinvoke. Don't forget that you will not know about exceptions if you don't call EndInvoke... so just call it...

I know my fire and forget example may seem like its optional, but its not.

I will also update my article to include this information.

More information http://www.interact-sw.co.uk/iangblog/2005/05/16/endinvokerequired

Coming soon...

Locking objects at the application layer

How to implement pessimistic locking without using a database or a data access layer. Providing the management to "check-out", "check-in" objects at the application layer.

Plug-ins

How to build a dynamic winform application using plug-in design

Model View Presenter with Async method invocation

How to use Model View Presenter design pattern, with async method invocation to never freeze the UI and create a flexible user interface.

As soon as I have a little time (between changing diapers)... I will write down all these juicy articles.

.NET Links

My .NET Links Collection

Web casts and videos
.NET Rocks
Channel 9
NetFX
Windows Workflow
Windows Presentation Foundation

Logging Using the Composite Pattern

• Download source code - 48.4 Kb

Introduction

In this article, I will explain how I solved a common problem I used to have regarding logging within my business layer. Normally, I would have a function call from my presentation layer to my business layer; however, once in the business layer, I had no access to the presentation layer anymore. There are many ways to solve this problem. In the MFC days, a Doc / View approach based on the Observer pattern was used. In .NET, we can use custom events to notify the presentation layer that something happened. But, in this article, I will show the Composite pattern in action, and some of its nice advantages.

The Requirements

Suppose we had a function in our business layer that performs a lot of updates. It would be nice that during all these updates, we log the exact action taking place. We want to easily log a string describing the activity to one of, all of, or some of the following loggers: TextBox, ListBox, text file and/or the EventLog.

Creating the ILogger Interface

To keep the example simple, I will implement a simple ILogger interface that only requires a logger class to implement its own way of logging an activity.

public interface ILogger
{
    void LogMessage(string strMessage);
}

Creating Logger Classes

Create the following logger classes:

• Text box logger - logs a message into a text box
  
• List box logger - adds a message to the list
  
• File logger - logs a message into a file
  
• EventLog logger - logs a message into the system event log

ListBox Logger

Notice that the ListBox and TextBox loggers are thread safe, by using the InvokeRequired method.

class ListBoxLogger : ILogger
{
    ListBox m_listBox;
    public ListBoxLogger(ListBox listBox)
    {
        m_listBox = listBox;
    }

    public void LogMessage(string strMessage)
    {
        MethodInvoker logDelegate = delegate 
        {
            m_listBox.Items.Add(strMessage);
        };

        if (m_listBox.InvokeRequired)
            m_listBox.Invoke(logDelegate);
        else
            logDelegate();
    }
}

TextBox Logger

class TextBoxLogger : ILogger
{
    private TextBox m_textBox;
    public TextBoxLogger(TextBox txtBox)
    {
        m_textBox = txtBox;
    }

    public void LogMessage(string strLogMessage)
    {
        MethodInvoker logDelegate = delegate { m_textBox.Text = strLogMessage; };
        if (m_textBox.InvokeRequired)
            m_textBox.Invoke(logDelegate);
        else
            logDelegate();
    }
}

File Logger

class FileLogger : ILogger
{
    private string m_strFileName;
    private object m_sync = new object();
    public FileLogger(string strFileName)
    {
        m_strFileName = strFileName;
    }

    public void LogMessage(string strMessage)
    {
        lock (m_sync)
        {
            using (StreamWriter writer = new StreamWriter(m_strFileName))
            {
                writer.WriteLine(strMessage);
            }
        }
    }
}

Notice that the FileLogger is thread-safe, and that it opens and closes the file before writing to it. This guarantees that the message is flushed after each call to LogMessage.

EventLog Logger

class EventLogger : ILogger
{
    public EventLogger()
    {

    }

    public void LogMessage(string strMessage)
    {
        EventLog.WriteEntry("Logger", strMessage);
    }
}

Using the ILogger Object

So far, there is nothing special here; we can have a function that takes a ILogger object and allow us to log messages. For example:

private void DoSomthing(ILogger logger)
{
    for(int i=0; i < 10; i++)
    {
        logger.LogMessage("Logging a message " + i.ToString());
     
    }
}

The client code looks like this:

// pass the File Logger
DoSomthing(new FileLogger("C://LogMessage.txt")); 
// txtBox is a text box control on the form
DoSomthing(new TextBoxLogger(textBox));

Introducing the CompositeLogger

But what if I want to log to all my loggers at the same time, or what if I want to log to only some of my loggers? To solve this requirement, I create a new logger called a Composite Logger.

// Logger of composite of loggers
class CompositeLogger : ILogger
{
    private ILogger[] m_loggerArray;
    
    // pass a ILoggers that are part of this composite logger
    public CompositeLogger(params ILogger[] loggers)
    {
        m_loggerArray = loggers;
    }

    public void LogMessage(string strMessage)
    {
        // loop around all the loggers, and log the message.
        foreach (ILogger logger in m_loggerArray)
            logger.LogMessage(strMessage);
    }
}

Let's Use Our Composite Logger to "Configure" Which Loggers to Use

Using all the loggers:

CompositeLogger compositeLogger =   
        new CompositeLogger(new TextBoxLogger(textBox),
                            new ListBoxLogger(listBox),
                            new FileLogger("C:\\LogPattern.txt"),
                            new EventLogger() );

Creating a composite logger with only TextBoxLogger and ListBoxLogger:

CompositeLogger compositeLogger =   
        new CompositeLogger(new TextBoxLogger(textBox),
                            new ListBoxLogger(listBox));

Because our composite logger implements ILogger like all the other loggers, we can pass it to a function that expects an ILogger object type.

DoSomthing(compositeLogger);

Testing the Composite Logger in a Thread

Let’s test our composite logger in a separate thread, just to make sure we can update the UI from a thread other than the UI-thread.

// create a composite logger with all the loggers
CompositeLogger compositeLogger =
    new CompositeLogger(
            new TextBoxLogger(textBox),
            new ListBoxLogger(listBox),
            new FileLogger("C:\\LogPattern.txt"),
            new EventLogger());

// create a anonymous function to call DoSomthing
ParameterizedThreadStart threadDelegate = delegate(object obj)
{
    ILogger logger = (ILogger)obj;
    DoSomthing(logger);
};

// Do Somthing in a thread
Thread t = new Thread(threadDelegate);
t.Start(compositeLogger);

Conclusion

Notice that I am now able to pass an ILogger object to a method within the business layer or to the data layer, and provide an easy way to log a message. This is done by using the ILogger interface, and therefore, your business layer or data layer requires no extra references to File.Io, or Windows.Forms, it only needs to have a reference to ILogger. It is also nice that you can easily add and remove loggers by using your composite Logger. Thank you for reading, have a good day!

.NET Enum The Next Level

Introduction

In this article, I am going to explore enums a little further. I am not going to cover the basic information about enums (you can always refer to MSDN for details). My biggest beef with enum is that it only represents numeric data. It is flexible to represent different integral types, but it can not hold a string. Enums do support the ToString() function, however with limitation (I will go into it in more details, later in the article). Basically, I want to be able to make my enumeration element be associated to more than just an integer value, to achieve this I will use Reflection and Attributes and try to keep my example as simple as possible.

Using ToString() with enums

Let's create a simple enumeration...

    public enum EmployeeType
    {
        RegularEmployee,
        StoreManager,
        ChainStoreManager,
        DepartmentManager,
        Supervisor
    }

Based on this simple plain vanilla enumeration, we can get the following information: a String representation using ToString().

   EmployeeType employee = EmployeeType.ChainStoreManager;
   Console.WriteLine(employee.ToString());
   Console.WriteLine(EmployeeType.ChainStoreManager.ToString());

The output is the same for both lines of code:

ChainStoreManager
ChainStoreManager

But what if I wanted to get "Chain Store Manager" with spaces? You can not create an enum type that contains spaces, your code wouldn't compile. There are a lot of solutions to this problem.

1. Create a mapping between enums and strings (using arrays, or hashtables).
   
2. Using the enum ToString() as a key for a language resource file.
   
3. Use a litte bit of reflection... I will explore option 3...

Using attributes with enums

In order to associate a string with an enumeration, I used Attributes. I will start with a simple exmaple that will assocate my enumeration with a string.

    public class EnumDescriptionAttribute : Attribute
    {
        private string m_strDescription;
        public EnumDescriptionAttribute(string strPrinterName)
        {
            m_strDescription = strPrinterName;
        }

        public string Description
        {
            get { return m_strDescription; }
        }
    }

EnumDescriptionAttribute is a simple attribute that holds a string. The attribute has a single property to return the description. For now, I am going to keep it as simple as possible. Now that I have my description attribute, I will assocate it with each enum element.

public enum EmployeeType
{
    [EnumDescription("Regular Employee")]
    RegularEmploye,
    [EnumDescription("Store Manager")]
    StoreManager,
    [EnumDescription("Chain Store Manager")]
    ChainStoreManager,
    [EnumDescription("Department Manager")]
    DepartmentManager,
    [EnumDescription("On Floor Supervisor")]
    Supervisor
}

Getting the attribute value from an enum

In order to get the attribute value from an enumeration, I have to use Reflection. Here is an example:

// setup the enum
EmployeeType employee = EmployeeType.ChainStoreManager;

// get the field informaiton
FieldInfo fieldInfo = employee.GetType().GetField("ChainStoreManager");

// get the attributes for the enum field
object[] attribArray = fieldInfo.GetCustomAttributes(false);

// cast the one and only attribute to EnumDescriptionAttribute
EnumDescriptionAttribute attrib =
    (EnumDescriptionAttribute)attribArray[0];

// write the description
console.WriteLine("Description: {0}", attrib.Description);

Output: Chain Store Manager

The most important line of code is: FieldInfo fieldInfo = employee.GetType().GetField("ChainStoreManager");. Notice that I hardcoded the enum element name ChainStoreManager, but if you go back and look at the ToString() function, you can see that I could have used ToString() instead.

A Generic function to get the description

Notice I used ToString() on the Enum...

public static string GetEnumDescription(Enum enumObj)
{
    FieldInfo fieldInfo =
        enumObj.GetType().GetField(enumObj.ToString());

    object[] attribArray = fieldInfo.GetCustomAttributes(false);
    if (attribArray.Length == 0)
        return String.Empty;
    else
    {
        EnumDescriptionAttribute attrib =
            attribArray[0] as EnumDescriptionAttribute;

        return attrib.Description;
    }
}

Let's associate more than just a string to our enum elements

So far, we only associated a description to our enumeration element. However, it is fully possible to associate any type of data to our enum. To show this, I am going to create a new enumeration (similar to the first one).

public enum ManagerType
{
    StoreManager,
    ChainManager,
    Superivor
}

I am also creating a new attribute class, ManagerAttribute, that inherits from EnumDescription, and provides two additional pieces of information (Min Salary and Max Salary).

public class ManagerAttribute : EnumDescriptionAttribute
{
    private int m_intMinSalary;
    private int m_intMaxSalary;
    public ManagerAttribute(string strDescription,
        int intMinSalary,
        int intMaxSalary) : base(strDescription)
    {
        m_intMinSalary = intMinSalary;
        m_intMaxSalary = intMaxSalary;
    }

    public ManagerAttribute(string strDescription)
        : base(strDescription)
    {

    }

    public int MinSalary
    {
        get {return m_intMinSalary;}
        set { m_intMinSalary = value; }
    }
    public int MaxSalary
    {
        get { return m_intMaxSalary;}
        set { m_intMaxSalary = value; }
    }
}

Now, I am going to associate a ManagerAttribute to each enum element. Notice that I am using the set properties within my ManagerAttributes, so the code is more readable

public enum ManagerType
{
    [Manager("Store Manager", MinSalary=40000, MaxSalary=100000)]
    StoreManager,
    [Manager("Chain Manager", MinSalary=50000, MaxSalary=110000)]
    ChainManager,
    [Manager("Store Supervisor", MinSalary=30000, MaxSalary=50000)]
    Superivor
}

Next step is improving our generic function to allow us to get any type of EnumDescriptionAttribute; using Generics this is easily done!

public static T GetAttribute<T>(Enum enumObj) where T : EnumDescriptionAttribute
{
    // get field informaiton for our enum element
    FieldInfo fieldInfo = enumObj.GetType().GetField(enumObj.ToString());

    // get all the attributes associated with our enum
    object[] attribArray = fieldInfo.GetCustomAttributes(false);

    if (attribArray.Length == 0)
        return default(T);
    else
    {
        // cast the attribute and return it
        T attrib = (T)attribArray[0];
        if (attrib != null)
            return attrib;
        else
            return default(T);
    }
}

Helper functions

So far we have got two helper functions, one to obtain a simple string description of an enum, and the other function, a more generic function to obtain any attribute that inherits from EnumDescriptionAttribute. You can add these helper functions to a class like EnumHelper; but in this example, I decided to simply add them to the existing EnumDescriptionAttribute.

public class EnumDescriptionAttribute : Attribute
{
    private string m_strDescription;
    public EnumDescriptionAttribute(string strEnumDescription)
    {
        m_strDescription = strEnumDescription;
    }

    public string Description { get { return m_strDescription; } }

    public static string GetEnumDescription(Enum enumObj)
    {
        FieldInfo fieldInfo = enumObj.GetType().GetField(enumObj.ToString());
        object[] attribArray = fieldInfo.GetCustomAttributes(false);
        if (attribArray.Length == 0)
            return String.Empty;
        else
        {
            EnumDescriptionAttribute attrib = attribArray[0]
                as EnumDescriptionAttribute;

            return attrib.Description;
        }
    }
    public static T GetAttribute<T>(Enum enumObj)
        where T : EnumDescriptionAttribute
    {
        FieldInfo fieldInfo = enumObj.GetType().GetField(enumObj.ToString());
        object[] attribArray = fieldInfo.GetCustomAttributes(false);
        if (attribArray.Length == 0)
            return default(T);
        else
        {
            T attrib = (T)attribArray[0];
            if (attrib != null)
                return attrib;
            else
                return default(T);
        }
    }
}

Finally... Let's see it all together

To get a string description, we can simple code this:

string desc =
    EnumDescriptionAttribute.GetEnumDescription(EmployeeType.DepartmentManager);

To get a ManagerAttribute, we can code this:

ManagerAttribute manager =
    EnumDescriptionAttribute.GetAttribute<ManagerAttribute>(
    EmployeeType.DepartmentManager);

Console.WriteLine("Manager: {0}, Min Salary: {1}, Max Salary {2}",
    attrib.Description,
    manager.MinSalary,
    manager.MaxSalary);

Now you can see that you can use attributes to associate addtional information to an element of an enum.

Conclusion

Okay, so you can see that it is not hard to associate additional information to your enumeration element by simply using some attributes and reflection. However, it is important to note that I do not believe attributes should replace common business objects. I simply wanted to show that an enum does not have to only represent an integral value. As you read in this article, you can associate your enum to a string or any other class. One of the nice advantages of using attributes is that it is easy to implement and it makes the code readable. You can see how readable the ManagerType enumeration is with the implementation of the ManagerAttribute. It is easy to know exactly what each enumeration item contains. I hope you enjoyed reading this article, and I welcome all comments or questions about it.

Asynchronous Method Invocation

Introduction

In this article, I am going to explain asynchronous method calls and how to use them. After playing with delegates, threads, and asynchronous invocation for so long, it would be a sin not to share some of my wisdom and knowledge on the subject, so hopefully, you won’t be looking at an MSDN article at 1 AM wondering why you decided to go into computers. I will try to use baby steps and lots of examples… Overall, I will cover how to call methods asynchronously, how to pass parameters to such methods, and how to find out when a method completes execution. Finally, I will show the Command Pattern in use for simplifying some of the code. The big advantage with .NET asynchronous method invocation is that you can take any method you have in your project, and you can call it asynchronously without touching the code of your method. Although most of the magic is within the .NET framework, it is important to see what is going on in the back, and that’s what we are going to study here.

Synchronous vs. Asynchronous

Let me try to explain synchronous and asynchronous method invocations with an example, because I know people on The Code Project like to see code and not read War and Peace (not that I have anything against this book).

Synchronous method invocation

Suppose we have a function Foo() that takes 10 seconds to execute.

private void Foo()
{
    // sleep for 10 seconds.
    Thread.Sleep(10000);
}

Normally, when your application calls the function Foo(), it will need to wait 10 seconds until Foo() is finished and control is returned to the calling thread. Now, suppose you want to call Foo() 100 times, then we know that it would take 1000 seconds for the control to return to the calling thread. This type of a method invocation is Synchronous.

1. Call Foo()
   
2. Foo() is executed
   
3. Control goes back to the calling thread

Let's now call Foo() using delegates because most of the work we will do here is based on delegates. Luckily for us, there is already a delegate within the .NET framework that allows us to call a function that takes no parameter and has no return value. The delegate is called MethodeInvoker. Let's play with it a little.

// create a delegate of MethodInvoker poiting
// to our Foo() function.
MethodInvoker simpleDelegate = new MethodInvoker(Foo);

// Calling Foo
simpleDelegate.Invoke();

Even with the example above, we are still calling Foo() synchronously. The calling thread still needs to wait for the Invoke() function to complete until the control is returned to the calling thread.

Asynchronous method invocation

But what if I wanted to call Foo() and not wait for it to finish executing? In fact, to make things interesting, what if I didn’t care when it is finished? Let’s say, I just wanted to call Foo 100 times without waiting for any of the function calls to complete. Basically, doing something called Fire and Forget. You call the function, you don’t wait for it, and you just forget about it. And… let’s not forget! I am not willing to change a line of code in my super complicated fancy Foo() function.

// create a delegate of MethodInvoker poiting to
// our Foo function.
MethodInvoker simpleDelegate = new MethodInvoker(Foo);

// Calling Foo Async
for(int i=0; i<100; i++)
    simpleDelegate.BeginInvoke(null, null);

Let me make a few comments about the code above.

• Notice that BeginInvoke() is the line of code that executes the Foo() function. However, the control is returned to the caller right away, without waiting for Foo() to complete.
  
• The code above does not know when a call to Foo() completes, I will cover that later.
  
• BeginInvoke() is used instead of Invoke(). For now, don’t worry about the parameters this function takes; I will cover that in more detail later.

What is the magic that .NET is doing in the background

Once you ask the framework to call something asynchronously, it needs a thread to do the work. It can not be the current thread, because that would make the invocation synchronous (blocking). Instead, the runtime queues a request to execute the function on a thread from the .NET Thread Pool. You don’t really need to code anything for it, all of it happens in the background. But, just because it is all transparent doesn’t mean you should care about it. There are a few things to remember:

• Foo() is executed on a separate thread, a thread that belongs to the .NET Thread Pool.
  
• A .NET Thread Pool normally has 25 threads in it (you can change that limit), and each time Foo() is called, it is going to be executed on one of these threads. You can't control which one.
  
• The Thread Pool has its limits! Once all the threads are used, an async method invocation is queued until one of the threads from the pool is freed. This is called Thread Pool Starvation, and normally when it comes to that, performance is compromised.

Don’t dive too deep into the thread pool, you might run out of oxygen!

So, let's see an example of when the Thread Pool is starved. Let's modify our Foo function to wait for 30 seconds, and also let it report the following:

• Number of avaible threads on the pool
• If the thread is on the thread pool
• The thread ID.

We know that initially the thread pool contains 25 threads, so I am going to call my Foo function asynchronously 30 times (to see what happens after the 25^th call).

private void CallFoo30AsyncTimes()
{
    // create a delegate of MethodInvoker
    // poiting to our Foo function.
    MethodInvoker simpleDelegate =
        new MethodInvoker(Foo);

    // Calling Foo Async 30 times.
    for (int i = 0; i < 30; i++)
    {
         // call Foo()
        simpleDelegate.BeginInvoke(null, null);
    }
}

private void Foo()
{
    int intAvailableThreads, intAvailableIoAsynThreds;

    // ask the number of avaialbe threads on the pool,
    //we really only care about the first parameter.
    ThreadPool.GetAvailableThreads(out intAvailableThreads,
            out intAvailableIoAsynThreds);

    // build a message to log
    string strMessage =
        String.Format(@"Is Thread Pool: {1},
            Thread Id: {2} Free Threads {3}",
            Thread.CurrentThread.IsThreadPoolThread.ToString(),
            Thread.CurrentThread.GetHashCode(),
            intAvailableThreads);

    // check if the thread is on the thread pool.
    Trace.WriteLine(strMessage);

    // create a delay...
    Thread.Sleep(30000);

    return;
}

Output window:

Is Thread Pool: True, Thread Id: 7 Free Threads 24
Is Thread Pool: True, Thread Id: 12 Free Threads 23
Is Thread Pool: True, Thread Id: 13 Free Threads 22
Is Thread Pool: True, Thread Id: 14 Free Threads 21
Is Thread Pool: True, Thread Id: 15 Free Threads 20
Is Thread Pool: True, Thread Id: 16 Free Threads 19
Is Thread Pool: True, Thread Id: 17 Free Threads 18
Is Thread Pool: True, Thread Id: 18 Free Threads 17
Is Thread Pool: True, Thread Id: 19 Free Threads 16
Is Thread Pool: True, Thread Id: 20 Free Threads 15
Is Thread Pool: True, Thread Id: 21 Free Threads 14
Is Thread Pool: True, Thread Id: 22 Free Threads 13
Is Thread Pool: True, Thread Id: 23 Free Threads 12
Is Thread Pool: True, Thread Id: 24 Free Threads 11
Is Thread Pool: True, Thread Id: 25 Free Threads 10
Is Thread Pool: True, Thread Id: 26 Free Threads 9
Is Thread Pool: True, Thread Id: 27 Free Threads 8
Is Thread Pool: True, Thread Id: 28 Free Threads 7
Is Thread Pool: True, Thread Id: 29 Free Threads 6
Is Thread Pool: True, Thread Id: 30 Free Threads 5
Is Thread Pool: True, Thread Id: 31 Free Threads 4
Is Thread Pool: True, Thread Id: 32 Free Threads 3
Is Thread Pool: True, Thread Id: 33 Free Threads 2
Is Thread Pool: True, Thread Id: 34 Free Threads 1
Is Thread Pool: True, Thread Id: 35 Free Threads 0
Is Thread Pool: True, Thread Id: 7 Free Threads 0
Is Thread Pool: True, Thread Id: 12 Free Threads 0
Is Thread Pool: True, Thread Id: 13 Free Threads 0
Is Thread Pool: True, Thread Id: 14 Free Threads 0
Is Thread Pool: True, Thread Id: 15 Free Threads 0

Let’s make a few notes about the output:

• Notice, first of all, that all the threads are on the thread pool.
  
• Notice that each time Foo is called, another thread ID is assigned. However, you can see that some of the threads are recycled.
  
• After calling Foo() 25 times, you can see that there are no more free threads on the pool. At this point, the application “waits” for a free thread.
  
• Once a thread is freed, the program grabs it right away, calling Foo(), and still there are 0 free threads on the pool. This continues to happen until Foo() is called 30 times.

So right away, not doing anything too fancy, we can make a few comments about calling methods asynchronously.

• Know that your code will run in a separate thread, so some thread safety issues may apply. This is a topic on its own, and I will not cover it here.
  
• Remember that the pool has its limits. If you plan to call many functions asynchronously and if they take a long time to execute, Thread Pool Starvation might occur.

BeginInvoke() and EndInvoke()

So far we saw how to invoke a method without really knowing when it is finished. But with EndInvoke(), it is possible to do a few more things. First of all, EndInvoke will block until your function completes execution; so, calling BeginInvoke followed by EndInvoke is really almost like calling the function in a blocking mode (because the EndInvoke will wait until the function completes). But, how does the .NET runtime know how to bind a BeginInvoke with an EndInvoke? Well, that’s where IAsyncResult comes in. When calling BegineInvoke, the return object is an object of type IAsyncResult; it is the glue that allows the framework to track your function execution. Think of it like a little tag to let you know what is going on with your function. With this little powerful super tag, you can find out when your function completes execution, and you can also use this tag to attach any state object you might want to pass to your function. Okay! Let’s see some examples so this doesn't become too confusing... Let's create a new Foo function.

private void FooOneSecond()
{
    // sleep for one second!
    Thread.Sleep(1000);
}

private void UsingEndInvoke()
{
    // create a delegate of MethodInvoker poiting to our Foo function.
    MethodInvoker simpleDelegate = new MethodInvoker(FooOneSecond);

    // start FooOneSecond, but pass it some data this time!
    // look at the second parameter
    IAsyncResult tag =
        simpleDelegate.BeginInvoke(null, "passing some state");

    // program will block until FooOneSecond is complete!
    simpleDelegate.EndInvoke(tag);

    // once EndInvoke is complete, get the state object
    string strState = (string)tag.AsyncState;

    // write the state object
    Trace.WriteLine("State When Calling EndInvoke: "
        + tag.AsyncState.ToString());
}

What about Exceptions, how do I catch them?

Now, let's make it a little more complicated. Let me modify the FooOneSecond function and make it throw an exception. Now, you should be wondering how you will catch this exception. In the BeginInvoke, or in the EndInvoke? Or is it even possible to catch this exception? Well, it is not in the BeginInvoke. The job of BeginInvoke is to simply start the function on the ThreadPool. It is really the job of the EndInvoke to report all the information about the completion of the function, and this includes exceptions. Notice the next snippet of code:

private void FooOneSecond()
{
    // sleep for one second!
    Thread.Sleep(1000);
    // throw an exception
    throw new Exception("Exception from FooOneSecond");
}

Now, let's call FooOneSecond and see if we can catch the exception.

private void UsingEndInvoke()
{
    // create a delegate of MethodInvoker poiting
    // to our Foo function.
    MethodInvoker simpleDelegate =
        new MethodInvoker(FooOneSecond);

    // start FooOneSecond, but pass it some data this time!
    // look at the second parameter
    IAsyncResult tag = simpleDelegate.BeginInvoke(null, "passing some state");

    try
    {
        // program will block until FooOneSecond is complete!
        simpleDelegate.EndInvoke(tag);
    }
    catch (Exception e)
    {
        // it is here we can catch the exception
        Trace.WriteLine(e.Message);
    }

    // once EndInvoke is complete, get the state object
    string strState = (string)tag.AsyncState;

    // write the state object
    Trace.WriteLine("State When Calling EndInvoke: "
        + tag.AsyncState.ToString());
}

By running the code, you will see that the exception is only thrown and caught when calling EndInvoke. If you decide to never call EndInvoke, then you will not get the exception. However, when running this code within the debugger, depending on your exception settings, your debugger might stop when throwing the exception. But that is the debugger. Using a release version, if you don’t call EndInvoke, you will never get the exception.

Passing parameters to your method

Okay, so calling functions without parameters is not going to take us very far, so I am going to modify my super fancy and sophisticated Foo function to take a few parameters.

private string FooWithParameters(string param1,
               int param2, ArrayList list)
{
    // lets modify the data!
    param1 = "Modify Value for param1";
    param2 = 200;
    list = new ArrayList();

    return "Thank you for reading this article";
}

Let's call FooWithParameters using BeginInvoke and EndInvoke. First of all, before we do anything, we must have a delegate that matches the signature of this method.

public delegate string DelegateWithParameters(string param1,
                       int param2, ArrayList list);

Think of BeginInvoke and EndInvoke as cutting our function into two separate methods. The BeginInvoke is responsible for accepting all the input parameters followed by two additional parameters every BeginInvoke has (callback delegate, and a state object). The EndInvoke is responsible for returning all output parameters (parameters marked with ref or out) and a return value, if there is one. Let's go back into our example to find out what are considered input parameters and what are output parameters. param1, param2, and list are all considered input parameters, and therefore, they will be accepted as arguments to the BeginInvoke method. The return value of type string is considered an output parameter, and therefore, it will be the return type for EndInvoke. The cool thing is that the compiler is able to generate the correct signature for BeginInvoke and EndInvoke based on the declaration of your delegate. Notice that I decided to modify the values of my input parameters just to examine if the behaviour is as I expect it to be without calling BeginInvoke and EndInvoke. I also re-allocate the ArrayList that is passed to a new ArrayList. So, try to guess what the output is going to be...

private void CallFooWithParameters()
{
    // create the paramets to pass to the function
    string strParam1 = "Param1";
    int intValue = 100;
    ArrayList list = new ArrayList();
    list.Add("Item1");

    // create the delegate
    DelegateWithParameters delFoo =
        new DelegateWithParameters(FooWithParameters);

    // call the BeginInvoke function!
    IAsyncResult tag =
        delFoo.BeginInvoke(strParam1, intValue, list, null, null);

    // normally control is returned right away,
    // so you can do other work here...

    // calling end invoke to get the return value
    string strResult = delFoo.EndInvoke(tag);

    // write down the parameters:
    Trace.WriteLine("param1: " + strParam1);
    Trace.WriteLine("param2: " + intValue);
    Trace.WriteLine("ArrayList count: " + list.Count);
}

Let's see our FooWithParameters again, just so you don't need to scroll up.

private string FooWithParameters(string param1,
        int param2, ArrayList list)
{
    // lets modify the data!
    param1 = "Modify Value for param1";
    param2 = 200;
    list = new ArrayList();

    return "Thank you for reading this article";
}

Let me give you the three lines from the output window after calling EndInvoke():

param1: Param1
param2: 100
ArrayList count: 1

Okay, let’s analyze all this. Even when my function modifies the values of the input parameters, we don’t get to see those changes after calling EndInvoke. The string is a mutable type, therefore, a copy of the string is created, and the change is not passed back to the caller. Integers are value types, and they create a copy when passed by value. Finally, re-creating the ArrayList is not returned to the caller because the reference to the ArrayList is passed by value, and in fact, re-creating the ArrayList is simply creating a new allocation for ArrayList assigning the "copied" reference that was passed. In fact, that reference is lost, and normally considered as a memory leak; but luckily for us, the .NET garbage collector will eventually grab it. So, what if we wanted to get back our new allocated ArrayList and the rest of the changes we did to our parameters? What do we need to do? Well, it is simple; we simply have to tag the ArrayList as a ref parameter. Just for fun, let’s also add output parameters just to show how EndInvoke is changed.

private string FooWithOutAndRefParameters(string param1,
        out int param2, ref ArrayList list)
{
    // lets modify the data!
    param1 = "Modify Value for param1";
    param2 = 200;
    list = new ArrayList();

    return "Thank you for reading this article";
}

Let us see what is considered an output parameter and what is considered an input parameter…

• Param1 is an input parameter, it will only be accepted within BeginInvoke.
  
• Param2 is input and output; therefore, it will be passed to both BeginInvoke and EndInvoke (EndInvoke will give us the updated value).
  
• list is passed by reference, and therefore, it is too going to be passed to both BeginInvoke and EndInvoke.

Let’s see how our delegate looks like now:

public delegate string DelegateWithOutAndRefParameters(string param1,
                out int param2, ref ArrayList list);

and finally, let's look at the function that calls FooWithOutAndRefParameters:

private void CallFooWithOutAndRefParameters()
{
    // create the paramets to pass to the function
    string strParam1 = "Param1";
    int intValue = 100;
    ArrayList list = new ArrayList();
    list.Add("Item1");

    // create the delegate
    DelegateWithOutAndRefParameters delFoo =
      new DelegateWithOutAndRefParameters(FooWithOutAndRefParameters);

    // call the beginInvoke function!
    IAsyncResult tag =
        delFoo.BeginInvoke(strParam1,
            out intValue,
            ref list,
            null, null);

    // normally control is returned right away,
    // so you can do other work here...

    // calling end invoke notice that intValue and list are passed
    // as arguments because they might be updated within the function.
    string strResult =
        delFoo.EndInvoke(out intValue, ref list, tag);

    // write down the parameters:
    Trace.WriteLine("param1: " + strParam1);
    Trace.WriteLine("param2: " + intValue);
    Trace.WriteLine("ArrayList count: " + list.Count);
    Trace.WriteLine("return value: " + strResult);
}

Here is the output:

param1: Param1
param2: 200
ArrayList count: 0
return value: Thank you for reading this article

Notice that param1 does not change. It is an input parameter, and param2 was passed as an output parameter and was updated to 200. The array list has been reallocated, and now we see that it is pointing to a new reference of zero elements (the original reference is lost). I hope that now you understand how parameters are passed with BeginInvoke and EndInvoke. Let’s move on to looking at how to be notified if a non-blocking function is completed.

What they don’t want you to know about IAsyncResult

You should be wondering how EndInvoke is able to give us the output parameters and the updated ref parameters. Or, better yet, how EndInvoke is able to throw that exception we threw in our function. For example, say we called BegineInvoke on Foo, and then Foo finished executing, and now, we normally would call EndInvoke, but what if we decide to call EndInvoke 20 minutes after Foo is finished? Notice that EndInvoke will still give you those output or ref parameters, and it would still throw that exception (if one was thrown). So, where is all that information stored? How come EndInvoke is able to get all that data long after the function is completed? Well… the key is with the IAsyncResult object! I decided to explore this object a little more, and as I suspected, it is this object that keeps all the information regarding your function call. Notice that EndInvoke takes one parameter, it is an object of type IAsyncResult. This object contains information such as:

• Is the function completed?
  
• A reference to the delegate used for BeginInvoke
  
• All output parameters and their values
  
• All ref parameters and their updated values
  
• Return value
  
• An Exception if one was thrown
  
• And more…

IAsyncResult may seem very innocent, because it is just an interface to a few little properties, but in fact, it is an object of type System.Runtime.Remoting.Messaging.AsyncResult.

Now, if we dig a little deeper, we will find that AsyncResult contains an object called _replyMsg of type System.Runtime.Remoting.Messaging.ReturnMessage, and what do you know… the holy grail has been found!

I had to shrink the above image so you won’t need to scroll to the right to read it, you can simply click on the image to view it

We can clearly see our return value, our output parameter, and our ref parameters. There is even an exception property to hold the exception. Notice that I expanded, in the debug window for OutArgs to show, the value 200 and a reference to the newly allocated ArrayList. You can also see in the property ReturnValue, the string “Thank you for reading this article”. If we had an exception, then the EndInvoke would throw it for us to catch it. I think this is proof enough to conclude that all the information regarding your function call is saved with that little IAsyncResult object you get back from BeginInvoke, it is like a key to your data. If we lose this object, we will never know our output parameters, ref parameters, and return value. It will also not be possible to catch an exception without this object. It’s the key! You lose it, and the info is lost forever in the maze of the .NET runtime… OK, getting a little carried away here. I think I made my point.

Using the Callback delegate, Hollywood style "Don’t call me I will call you!"

At this point, you should understand how parameters can be passed, how to pass state, and understand the fact that your method is executed on a thread within the ThreadPool. The only thing I didn’t really cover is the idea of being notified when the method is finished executing. After all, blocking and waiting for the method to finish does not accomplish much. In order to be notified when a method is complete, you must supply a callback delegate on the BeginInvoke. OK, example! Look at the following two functions:

private void CallFooWithOutAndRefParametersWithCallback()
{
    // create the paramets to pass to the function
    string strParam1 = "Param1";
    int intValue = 100;
    ArrayList list = new ArrayList();
    list.Add("Item1");

    // create the delegate
    DelegateWithOutAndRefParameters delFoo =
        new DelegateWithOutAndRefParameters(FooWithOutAndRefParameters);

    delFoo.BeginInvoke(strParam1,
        out intValue,
        ref list,
        new AsyncCallback(CallBack), // callback delegate!
        null);
}

private void CallBack(IAsyncResult ar)
{
    // define the output parameter
    int intOutputValue;
    ArrayList list = null;

    // first case IAsyncResult to an AsyncResult object, so we can get the
    // delegate that was used to call the function.
    AsyncResult result = (AsyncResult)ar;

    // grab the delegate
    DelegateWithOutAndRefParameters del =
        (DelegateWithOutAndRefParameters) result.AsyncDelegate;

    // now that we have the delegate,
    // we must call EndInvoke on it, so we can get all
    // the information about our method call.

    string strReturnValue = del.EndInvoke(out intOutputValue,
        ref list, ar);
}

In here, you can see that we passed a delegate to the function CallBack when calling BeginInvoke. .NET will call us when the method FooWithOutAndRefParameters completes execution. As before, we all know that we must call EndInvoke if we want to get our output parameters. Notice that in order to call EndInvoke, I needed to do some gymnastics to get the delegate.

AsyncResult result = (AsyncResult)ar;
// grab the delegate
DelegateWithOutAndRefParameters del =
    (DelegateWithOutAndRefParameters) result.AsyncDelegate;

Wait a minute! On which thread is the call-back executed on?

After all, the callback is invoked by .NET using your delegate, but still it is .NET that calls this delegate. It is your right and duty to know on which thread your code is executed on. To give a clear picture of what is going on, I decided to yet again modify my Foo function to include thread information and add a delay of 4 seconds.

private string FooWithOutAndRefParameters(string param1,
        out int param2, ref ArrayList list)
{
    // log thread information
    Trace.WriteLine("In FooWithOutAndRefParameters: Thread Pool? "
        + Thread.CurrentThread.IsThreadPoolThread.ToString() +
        " Thread Id: " + Thread.CurrentThread.GetHashCode());

    // wait for 4 seconds as if this functions takes a while to run.
    Thread.Sleep(4000);

    // lets modify the data!
    param1 = "Modify Value for param1";
    param2 = 200;
    list = new ArrayList();

    return "Thank you for reading this article";
}

I also added thread information to the callback function:

private void CallBack(IAsyncResult ar)
{
    // which thread are we on?
    Trace.WriteLine("In Callback: Thread Pool? "
        + Thread.CurrentThread.IsThreadPoolThread.ToString() +
        " Thread Id: " + Thread.CurrentThread.GetHashCode());

    // define the output parameter
    int intOutputValue;
    ArrayList list = null;

    // first case IAsyncResult to an AsyncResult object,
    // so we can get the delegate that was used to call the function.
    AsyncResult result = (AsyncResult)ar;

    // grab the delegate
    DelegateWithOutAndRefParameters del =
        (DelegateWithOutAndRefParameters) result.AsyncDelegate;

    // now that we have the delegate, we must call EndInvoke on it, so we
    // can get all the information about our method call.
    string strReturnValue = del.EndInvoke(out intOutputValue, ref list, ar);
}

I decided to execute FooWithOutAndRefParameters multiple times, using a button on my form.

private void button4_Click(object sender, EventArgs e)
{
    CallFooWithOutAndRefParametersWithCallback();
}

Let’s see the output after pressing my button thrice (calling the function thrice):

In FooWithOutAndRefParameters: Thread Pool? True Thread Id: 7
In FooWithOutAndRefParameters: Thread Pool? True Thread Id: 12
In FooWithOutAndRefParameters: Thread Pool? True Thread Id: 13
In Callback: Thread Pool? True Thread Id: 7
In Callback: Thread Pool? True Thread Id: 12
In Callback: Thread Pool? True Thread Id: 13

Notice that my Foo function is executed thrice, one after the other, on three separate threads. All the threads are on the thread pool. Notice also that the callback is also executed thrice, respectively, and they are all on the thread pool too. What makes this interesting is that, the callback seems to be executed on the same thread ID as Foo. Thread 7 executes Foo; 4 seconds later, the callback is also executed on thread 7. The same with thread 12 and 13. It is like the callback is a continuation of my Foo function. I pressed my button many times, trying to see if the callback will ever be called on a thread Id other then the one Foo is executed on, I was not able to achieve that. If you think about it, it makes total sense. Imagine, .NET would grab a thread to call Foo and then grab another thread to call the callback, that would be a waste! Not to mention that if your thread pool is starved, you will end up waiting for a free thread just to call the callback! That would have been a disaster.

Using the Command Pattern to clean things up!

Okay! Let's face it, things are getting a little messy. We have a BeginInvoke, EndInvoke, a callback, and they are all over the place! Let's try to use the Command Pattern to clean up the method invocation. Using the Command Pattern is simple and easy. Basically, you create a Command object that implements a simple interface like:

public interface ICommand
{
    void Execute();
}

It it time that we stop using our useless Foo function everywhere, and try to do something more real! So, let's create a scenario that is more realistic. Say, we have the following:

• We have a user Form that contains a grid that displays customer rows.
  
• The Grid is updated with rows based on a search criteria of customer ID. However, the database is far, far away, and it takes 5 seconds to get the customer dataset; we do not wish to block the UI while we are waiting.
  
• We have a nice business object that is responsible to get our customer dataset based on a customer ID.

Suppose this was our Business Layer. To keep the example simple, I hard-coded what would normally come from a data layer.

public class BoCustomer
{
    public DataSet GetCustomer(int intCustomerId)
    {
        // call data layer and get customer information
        DataSet ds = new DataSet();
        DataTable dt = new DataTable("Customer");
        dt.Columns.Add("Id", typeof(int));
        dt.Columns.Add("FirstName", typeof(string));
        dt.Columns.Add("LastName", typeof(string));

        dt.Rows.Add(intCustomerId, "Mike", "Peretz");
        ds.Tables.Add(dt);

        // lets make this take some time...
        System.Threading.Thread.Sleep(2000);
        return ds;
    }
}

Now, let's create our Command, which is responsible to update the grid based on the customer ID.

public class GetCustomerByIdCommand : ICommand
{
    private GetCustomerByIdDelegate m_invokeMe;
    private DataGridView m_grid;
    private int m_intCustmerId;

    // notice that the delegate is private,
    // only the command can use it.
    private delegate DataSet GetCustomerByIdDelegate(int intCustId);

    public GetCustomerByIdCommand(BoCustomer boCustomer,
        DataGridView grid,
        int intCustId)
    {
        m_grid = grid;
        m_intCustmerId = intCustId;

        // setup the delegate to call
        m_invokeMe =
            new GetCustomerByIdDelegate(boCustomer.GetCustomer);
    }

    public void Execute()
    {
        // call the method on the thread pool
        m_invokeMe.BeginInvoke(m_intCustmerId,
            this.CallBack, // callback!
            null);
    }

    private void CallBack(IAsyncResult ar)
    {
        // get the dataset as output
        DataSet ds = m_invokeMe.EndInvoke(ar);

        // update the grid a thread safe fasion!
        MethodInvoker updateGrid = delegate
        {
            m_grid.DataSource = ds.Tables[0];
        };

        if (m_grid.InvokeRequired)
            m_grid.Invoke(updateGrid);
        else
            updateGrid();
    }
}

Notice that the GetCustomerByIdCommand takes all the information it needs to execute the command.

• The grid to update.
  
• The customer ID to search.
  
• A reference to the business layer.

Also notice that the delegate is hidden within the Command object, so the client doesn’t need to know the inner working of the Command. All the client needs to do is build the Command and call Execute on it. We all know by now that asynchronous methods invocation is done on the ThreadPool, and we should all know by now that it is not healthy to update the UI from the ThreadPool or any other thread other then the UI thread! So, to fix this problem, we hide this implementation within the Command, and check based on the Grid if InvokeRequired() is true. If it is true, we use Control.Invoke to make sure the call is marshaled to the UI thread. (Notice, I am using the .NET 2.0 features of creating anonymous methods.) Let's see how the form is creating the command and executing it!

private ICommand m_cmdGetCustById;
private void button1_Click(object sender, EventArgs e)
{
    // get the custmer id from the screen
    int intCustId = Convert.ToInt32(m_txtCustId.Text);

    // use the buisness layer to get the data
    BoCustomer bo = new BoCustomer();

    // create a command that has all the tools to update the grid
    m_cmdGetCustById = new GetCustomerByIdCommand(
        bo, m_grid, intCustId);

    // call the command in a non blocking mode.
    m_cmdGetCustById.Execute();
}

Notice, that Execute is non-blocking. But before you go nuts and create a million command classes, keep these in mind:

• The Command Pattern may cause class explosion, so choose your weapon wisely.
  
• In my case, it would have been easy to create a base class to my command that has the logic to update a grid in a thread-safe manner, but I kept my example simple.
  
• It would also be acceptable to pass the TextBox into the command object so it can grab the input in a more dynamic way and allow the command to be called anytime without re-creating it.
  
• Notice that the delegate, BeginInvoke, EndInvoke, callback, and our crazy code to make sure the UI is updated in a thread safe manner is all encapsulated in my Command, which is a good thing!

Conclusion

Phew! It took me almost a week to write this fun article. I tried to cover all the important aspects of calling a method in a non-blocking mode. Here are a few things to remember:

• Delegates will contain the correct signature for BeginInvoke and EndInvoke, you should expect all output parameters and exceptions to come out when calling EndInvoke.
  
• Don’t forget you take juice from the ThreadPool when using BeginInvoke, so don’t overdue it!
  
• If you plan to use a callback, it might be a good idea to use the Command Pattern to hide all the nasty code that goes with it.
  
• Personally, the UI should only be blocked when doing UI stuff, so now you have no excuse!

Thank you for reading, have a wonderful day, and happy .NET coding everyone!