OnTime 2008 API C# Wrapper

OnTime 2008 is a Defect tracking and Agile Development Management system.  They have a great API exposed through SOAP web services.  But each time that you want to call a service, you have handle instantiating that service, and then every method must take (as  it's first parameter) the Security Token (guid) from the Web.Config on the server.

I wanted one interface that would simplify these calls so that I could simply say:

CSharp DataSet projects = ProjecandlerSoapClient.GetAllProjects(); // or Project p = new Project(); p.Name = "Some project"; ProjectHandlerSoapClient.AddProject(p);<span class=""> </span> VB Dim projects As DataSet = ProjecandlerSoapClient.GetAllProjects() ' or Dim p As Project = New Project() p.Name = "Some project" Dim class As ProjectHandlerSoapClient.AddProject(p)<span = "" </span>

So I wrote a wrapper for each of their Service.asmx files.  You can download the OnTime 2008 API Wrapper here.

All you have to do is to replace the text DefaultNamespace with the actual default namespace from the project that you add the OTW folder to. 

Behind the Scenes

My main objective here was that I didn't want to have to pass in a Guid to the first parameter of EVERY call to the API.  Instead, I wanted to set that Guid once and then simply call other methods that didn't include the SecurityToken parameter.  So GetAllProjects(Guid securityToken) was replaced with a static method GetAllProjects().

The model implements the Singleton Pattern to automatically instantiate one instance of each ServiceClass (when that service is first access) and to share the Guid centrally in a static class called OTW.  The class OTW has a static parameter called SecurityToken which automatically loads itself from the SecurityToken AppSettings (if provided), otherwise, it must be set through code before the first API is called as follows:

CSharp OTW.SecurityToken = new Guid("--- your security token here"); VB OTW.SecurityToken = New Guid("--- your security token here")

How the Wrapper Classes Work

The wrapper classes take advantage of the fact that the Web Service Reference class is a partial class.  The wrapper class simply adds a static singleton instance of the class (which is lazily loaded), and then a series of static methods (which operate on that singleton instance) which are identical to the underlying methods except that they don't have a SecurityToken parameter.  Instead, when passing the call to the underlying API, it simply passes the static OTW.SecurityToken in place of the 1st parameter.  So, as long as the SecurityToken has been configured in the App.Config, or is set through code before the API is executed, OTW.SecurityToken will have the correct value in it.  Now, if that security token ever changes, you don't have to change it in 100's of places, but rather just the one.  It also simplifies every call to the API by shrinking the number of parameters required by 1 in every case.

In order for this to work, you must follow these simple steps:

1. Add references to whichever wrappers you want to include (such as ProjectService).
2. This reference must have the same name as the asmx file.
3. Copy the OTW folder from the zip file into the root folder of your project
4. Include the OTW.cs file in your code
5. Include whichever wrapper files that you have setup Service References for (such as ProjectHandlerSoapClient).
6. Do a global search and replace to replace the text "DefaultNamespace"  with whatever the default namespace is for your project.  It is critical that the wrapper classes be in the same namespace as the web service reference classes automatically generated by VS 2008.

That's it.  Now, rather than ever having to instantiate any specific instances, you can simply reference the static methods of the SoapClient wrapper classes, and the wrappers will handle everything else.

Good luck and happy coding.

Article Courtesy of
EJ Alexandra