Demystifying the Lync Server 2010 SDK
I’ve been using the Lync Server SDK (formerly the OCS SDK) for a few years now and have always thought that it is a very powerful little SDK that often gets over shadowed by its much bigger brother, UCMA. Both SDKs serve different purposes, the Lync Server SDK is focused on dealing with traffic at a SIP level (injecting headers, redirecting calls, viewing SIP Signal data, etc) while UCMA is focused on the creation and management of endpoints (both user and application). My biggest gripe on the Lync SDK is the lack of publicly available information on its usage and lack of tutorials on the subject. In this article I am going to walkthrough what you need to do to get your Lync application up and running.
Install the SDK
Alright it’s a gimme, go grab the SDK and install it, you’re going to need the latest version as it contains the ApplicationConfigHelper registration classes. The SDK now goes into a Lync SDK folder and on closer examination of the ServerAgent.dll you’ll see the version is now 4.0.7577.0 versus the previous 3.5.6907.0.
Security Credentials
This has been a pain point for many users; you get your application installed, go run it and are hit with the "Unauthorized Application Exception". Here’s the deal – the user running your application must have authentication privileges to run your app. It’s that simple, so if your app runs as a user (which it must) it needs these permissions, if you are running this in your own development environment, you need these permissions.
In Active Directory, take your domain user (no local users here), and add them to the RTCUniversalServerAdmins and RTCUniversalUserAdmins group. Next go to the local RTCServerApplications group on your Lync installation. Once you have made these changes, logout from that session on your Lync server. If you don’t do this step your app will not work (I’m guessing because Active Directory will have not pushed down the changes? I don’t know really, I’m not an AD expert). Once you’ve done this, the Exception should now be gone.
WMI Out, Powershell In
In OCS 2007 R2, you went through WMI classes to register your application as a Front-End Script. In Lync, you register your application via the built-in Lync Powershell Module cmdlets as a Server Application. To register your application you will use the New-CsServerApplication cmdlet in the following fashion;
New-CsServerApplication -Uri http://www.microsoft.com/LC/SDK/MyApp -Identity "Registrar:StandardFE.MyLync.com/MyApp" -Critical $False -Enabled $True
The Identity parameter replaces the previous "Name" property of your application in OCS 2007 R2 and requests that you assign it to a pool. URI is a unique identifier for your application (nothing different from OCS 2007 R2 here). If you don’t set "Enabled" to true you will need to do so later via Powershell or the Lync Control Panel. When your app is not enabled it will not receive any SIP events. Lastly, the Critical parameter, if you are going to set your application to Critical make sure it is rock solid. When Lync initializes if it sees an application marked as critical it will fail to start if it cannot start your application. When you’re just developing your application for the first time, set Critical to false, save yourself the pain and headaches. Powershell is the only mechanism by which you can register your application; you can do minimal management via the Lync Control Panel (enable/disable, changing critical), all core functions are via Powershell.
For a complete listing of all the Lync Powershell cmdlets check out this site - http://blogs.technet.com/b/csps/. It is an awesome resource.
The ApplicationConfigurationHelper
So at this stage, you’ve pretty much done the same things you did with OCS 2007 R2. In Lync they introduced the new ApplicationConfigurationHelper class to assist with registration and allow you to better handle change events from Lync against your application. I must confess I have only been working with this class for a few months, but the purpose is not entirely clear to me as all the events I need to detect changes in my application are handled from events directly wired to the Server Agent. However, to get my pre-existing OCS 2007 R2 application working I had to instantiate this class and subscribe to the event in order to start handling SIP events.
You use the ApplicationConfigurationHelper class in the following manner;
ApplicationConfigHelper ach = new ApplicationConfigHelper();
ach.RegisterChangeNotification(“MyApp”, new ApplicationConfigChangedEventHandler(OnApplicationChanged));
ach.GetApplicationConfiguration(“MyApp”);
And the wiring of the event itself;
private void OnApplicationChanged(object sender, ApplicationConfigChangedEventArgs ace)
{
}
Going through the above 8 lines of code is probably an article in of itself. Suffice to say, when I did this everything came alive in my application.
Backwards Compatibility
In the SDK help file it clearly states that any pre-existing application will need to be compiled against the 4.0 version of the SDK to work on Lync. Sadly, once compiled you cannot run this application against OCS 2007 R2. It is not backwards compatible. I’m working through this issue myself now to see how I can get my application to gracefully co-exist between both environments with little disruption.
My next objective will be creating a demo app that handles some if not all of the above and give you some basic information as to what you might be doing wrong in getting your application up and running. Like I said, it’s a great, powerful SDK, but its lack of documentation can be extremely frustrating, don’t give up.