Introduction
During the development of a GSM Modem API, I found I was repeating a lot of code for encapsulating the synchronous versions of asynchronous method templates. The common pattern for such code implements asynchronous methods with the same name as the synchronous versions, by prefixing the begin and end method with 'Begin' and 'End', respectively. This means that for each set of two asynchronous method pairs, you need another method to synchronize them - in a library of any significant size, this makes for considerably more work.
This article explains how to write a custom tool which utilises the content of the asynchronous class, to generate all the synchronous stubs, for methods which match the naming convention.
Because I have found this custom tool so helpful, I have folded it into the Missing Bits product. You can search for this product on CodeProject to obtain a copy containing a version of this custom tool along with many other useful additions to Visual Studio.
Background and Prerequisites
This article is not a tutorial on asynchronous programming, merely an overview on utilising this particular custom tool. A basic understanding of Custom Tools would be greatly helpful; however, everything is provided in the zip file for Visual Studio 2005 registration.
Basic Architecture
This custom tool is designed to be applied to a code file containing a single class, wherein are one or more method signatures matching the required asynchronous code pattern. The custom tool then parses these methods, determining from their parameters and return types, what the synchronous method should look like.
Method Pattern
Both the beginner, and completion, async methods must conform to the following patterns so that the custom tool may identify, and interpret them.
The following example uses a basic read operation to demonstrate method signatures that will be recognised by the custom tool.
Example Begin Method
public IAsyncResult BeginRead(byte[] buffer,
int length, int offset, AsyncCallback callback, object state)
The method must return IAsyncResult
, and the last two arguments must be AsyncCallback
, and an object
for state.
Example End Method
public int EndRead(IAsyncResult result)
The method returns the same type as the synchronous version, and takes just the IAsyncResult
as the sole argument.
Code generated by the Custom Tool follows:
public virtual int Read( byte[] buffer, int length, int offset) {
System.IAsyncResult result = base.BeginRead(buffer, length, offset, null, null);
return base.EndRead(result);
}
Installation
The SynchronizerCustomTool assembly must be installed in the GAC, then run the reg file to install the required Registry keys. Then, to use the custom tool, set the 'Custom Tool' property of your C# code file to "SynchronizerCustomTool" - this will result in the generation of another C# code file containing the synchronized methods.
Credits
This code uses a C# parser library written by Debreuil Digital Works and actively maintained by Denis Erchof, and distributed under the BSD license.
History
- 2008.02.09: Initial publication.