Lync Development: Troubleshooting

Unless you’re the Chuck Norris (or the ScottGU) of the development world, you’re going to run into problems with your code.

There’s a lot of moving parts involved between your code that sends a message, and someone actually receiving that message. There’s the Lync infrastructure, the network layer, routing, permissions, firewalls, geographical separation, latency etc.

Basically, there’s a lot that can go wrong.

When something doesn’t work, you need to work out which layer of the onion has failed. It could be a bug in your code. But it could also be part of the infrastructure getting in your way, or a Lync policy stopping you – and you don’t want to spend hours looking for problems in your code that aren’t there. Life’s too short for that.

Scott Hanselman said: “The internet is not a black box“. This is 100% true for Lync development. You have to be able to open the box, sift through the contents, and work out what’s broken.

Here are some ways you can “lift the lid” to see what’s going on, following by some useful resources for when you’ve found the problem.

Client Logging

The Lync Client can log full details about the SIP messages it’s sending and receiving. If you’re using the client to send a message to a UCMA application and it’s not responding how you expect, or you’re seeing problems with specific users, the client logs might be able to tell you why.

To turn on client logging, goto Tools > Options > General, and check the checkbox. Lync 2013 client users can additionally set the logging level. Set the logging level to Full whilst you conduct your tests to make sure you see SIP message traffic. You might want to turn it off again afterwards to save space.

The log files themselves can be found at:

2013 Client : %userprofile%\\AppData\\Local\\Microsoft\\Office\\15.0\\Lync\\Tracing
2010 Client : %userprofile%\\Tracing

The important file to look at is the Lync-UccApi-#.UccApilog file for 2013 (or the Communicator-uccapi-#.uccapilog file for 2010). You can view this file in Notepad or your favourite text editor). You can also view the file in Snooper, if you have it installed (see later section on Lync Server Logging)

HTTP Tracing with Fiddler

If you’re doing any UCWA development (or even if you’re troubleshooting client connection issues or CWE loading problems) you need Fiddler. It will help you see the HTTP traffic that’s going to and from your machine, and it can decode HTTPS traffic to help you understand what’s happening.

Fiddler is free and you can download it directly from the Telerik website. 10 minutes spent understanding how to use Fiddler will be saved many times over in debugging HTTP connection problems.

Always try..catch End statements

This advice is primarily for UCMA development, but it’s also useful for Client development. Many of the actions in the SDKs are asynchronous, so they involve you calling Begin and then waiting for the End to be invoked. You should always make sure that you try..catch the end statement, and at the very least log any errors. The SDK will do its best to tell you about any errors it encountered in the exceptions raised from these End methods, and the error messages are usually helpful. Don’t miss the opportunity to find out what’s happening by ignoring exceptions raised here!

Lync Server Logging

When all else fails, sometimes you need to track the individual SIP Messages going to and from the server, and that’s where Server Logging comes in. Both Lync Server 2010 and 2013 let you attach a logger to the server and capture all the SIP traffic. You should exercise caution when doing this on a production system however, as the logs can get quite large quite quickly.

Setting up OCSLogger and looking the results with Snooper has been written about extensively already, so I won’t tread the same path. Jeff Schertz has a great article on setting up OCSLogger, which you should go read.

Fixing Problems

All the tools I’ve mentioned so far help you find the problem, but how do you go about fixing it?

Well, often finding is more than half the battle: once you get to them, the error messages produced by Lync are usually pretty informative and self-explanatory. Sometimes, however, you need a little help.

There’s two good resources I often use when I come up against errors I don’t understand:

StackOverflow has a healthy collection of problems others have previously come across and the answer it often in one of the answers. Look especially for the #Lync and #UCMA tagged questions.

MSDN Forums has a separate forum for each of the Lync Development disciplines, and MVP and Microsoft representatives are frequent visitors. You’ll often find someone happy to discuss your problem, but be prepared to give lots of detail, usually including SIP traffic logs. Choose the most appropriate forum from:

Microsoft Lync Client Development
Microsoft Lync Persistent Chat Server SDK
Microsoft Lync Server SDK and Office Communications Server SDK (for MSPL questions)
Microsoft Unified Communications Managed API SDK (for UCMA questions)