Building a Broadsoft XSI event consumer on .NET

I wrote about the specifics I encountered with the Broadsoft XSI API before, in this post. I didn’t mention the software I used to support the development of the application. This post will be about what I did to consume data produced by the XSI environment

Well, I basicly used a whole lot of google and stackoverflow. I’ll mention the most interesting things I learned here.

XSI-events are pieces of information, serialized into XML or JSON format. The XML has an XML Schema Definition which is not completely aligned with what the API expects, but you’ll be able to work with them just fine. Information transferred using the JavaScript Object Notation format is probably going to be easier and less bloated, but the XSDs offer a huge advantage over JSON when it comes to serialization. This advantage shows when you learn about xsd.exe, which is able to transform the Broadsoft XSI Schema to C# classes. You’ll be able to use these classes in your application. I used them and added code to conveniently handle serialization and deserialization of XML strings.

When you’ve got your persistent HTTP channel running and receiving events, you’ll need a tool like fiddler to review the requests and responses. I developed the application to a provider that offers both HTTP and HTTPS connections and I suggest using HTTP during development only, because it’s easier to inspect requests and responses. Fiddler maintains the order the requests were sent in and, as a bonus, it can simulate a slow connection too, so you can test the way your application will behave on a slow link. Try starting Fiddler, then start your application, wait a couple of minutes and stop Fiddler, the outcome may be surprising. You’ll have to make sure the application uses the proxy in order to use it; like the code below:

            HttpWebRequest web_request = (HttpWebRequest)WebRequest.Create(base_uri + @"com.broadsoft.async/com.broadsoft.xsi-events/v2.0/channel");

            web_request.KeepAlive = true;
            web_request.Method = WebRequestMethods.Http.Post;
            web_request.Credentials = credentials;
            web_request.AllowAutoRedirect = true;
            web_request.ContentType = @"application/xml; charset=UTF-8";
            web_request.Accept = @"application/xml";
            // http://msdn.microsoft.com/en-us/library/system.net.httpwebrequest.readwritetimeout(v=vs.90).aspx
            web_request.Timeout =
                web_request.ReadWriteTimeout = 60000;
            // PreAuthentication is added in an attempt to prevent the 401 exception
            web_request.PreAuthenticate = true;
            //web_request.Proxy = null;

You can use the Windows firewall to block access to the XSI provider and test how your application behaves.

The application we developed uses log4net to handle logging. Use a recent version of Visual Studio with NuGet to install the package and you’re almost there. We logged the XSI events received by the application with DEBUG priority, so we can easily reduce the number of log entries written to disk by configuring the minimum priority. We use XML Notepad 2007 to inspect events in attempts to reduce errors. XML Notepad does not even come close to what XMLSpy, but it’s good enough to review event messages. JSON Viewer is a good alternative when you decide to handle JSON encoded events.

Another thing of interest is the way the XSI API allows you to version lock the API interface. This makes sure your code works when the XSI provider decides to update their installation. Add an HTTP header field with appropriate value:

        protected override void ProcessWebRequest(HttpWebRequest req)
        {
            log.Debug(String.Format("Adding X-Broadworks-Protocol-Version {0} to webrequest headers",
                api_version));
            req.Headers.Add(@"X-BroadWorks-Protocol-Version", api_version);
        }

The exact value of appropriate depends on your provider. Here’s an overview.

Hope this helps and let me know when there’s something I can add.