So recently I had the painful job of porting one of our web services, which previously executed on the SharePoint Web Front Ends (WFEs), to a SharePoint 2010/2013 service application. Going off my experience I would recommend the following 3 things before embarking on such an endeavour.
- Make sure you understand SharePoint’s general architecture very well and deeply – if all your experience is with WFE architecture like site collections, sites, lists, content types etc. this isn’t going to cut it, you need to go deeper
- The guts of the service you’re writing should be already done. If it’s simple then I would be questioning whether you really need to do a service application. If it’s as complex as the service I have, the last thing you need is to be battling the complexity of the service itself AS WELL AS the complexity of the service application framework.
- Plenty of sleep because this stuff is boring – especially if your service was as complex with as many methods as mine because it’s pretty mind numbing stuff.
As a result of doing this though, I felt like I learnt quite a bit in terms of the principles for the process to troubleshoot deployment of service applications. The principles I share in this post aren’t necessarily applicable to all OOTB or custom service applications, but generally speaking I think it could be helpful so thought I’d put it out there.
So I don’t like to talks in terms of “steps”. I’ve always felt that detailing a process is open to misinterpretation because I’ll get lazy people thinking they don’t need to learn anything to fix their issue and just mindlessly follow the steps.
- Understand every component of the service application framework and how they relate to each other
- Don’t jump straight to code / debuggers – if you really need to see what may be happening behind the scenes, use Powershell
- Run through the deployment / retraction process of the service application you’re working with to make sure you haven’t missed any steps
- Understand what each part of the deployment process is doing and look for indications that each step worked correctly
Understanding the SharePoint 2010/2013 Service Application Framework
This really should go without saying, especially if you’re deploying or building a service application. This is though, people don’t. It’s the same reason we have to write “contents are hot” on disposable coffee cups and “do not operate machinery after taking” on medication packets. I’m not going to bother going into the parts of the framework here as there are already heaps of articles that explain it better than I could. Here are some of them –
The one point I will make is to understand and be able to distinguish the following three types of components –
- Components to support the deployment of the Service Application
- Components for the Service Application itself that runs on SharePoint Application Servers
- Components that the WFEs will use to communicate with the Service Application web services
It’s really important to understand these three types of components as depending on the error you receive it will help you determine where you’re having problems. For instance if your services aren’t listed on the “Manage services on server” page then you know it’s likely that the installation components haven’t worked properly. This COULD be a very different issue to the service being stuck in the “Starting” state on the “Manage services on server” page which indicates that more likely there’s a problem with the service itself like missing files, problematic code etc.
Don’t Jump to Code / Debuggers – PowerShell is your friend!!!
So I have provided mentoring to quite a few developers new to SharePoint and I always find they have an affinity to looking at code and using the VS debugger to solve problems. I’ll admit, when I was a junior developer I used to do the same – it was a safe environment where you had total control. Problem is more often than not you’re having problems in production where there is no debugger available and you don’t have this luxury.
That’s why I advise all my developers to use PowerShell even when they’re trying to resolve these kinds of issues in development. Using these scenarios as an opportunity to improve your PowerShell skills is hugely valuable in improving your ability to solve problems in production environments.
The method I have found most valuable when using PowerShell to help me with debugging my service application, was to use it to instantiate the “client” objects that my WFE code uses to communicate with the Service Application web service itself. This was extremely helpful as I got to see whether the problem was with my WFE code, web service interface, or service application itself.
Run Through the Deployment / Retraction Process Multiple Times
Again this should be done without saying. Doing this provides a number of benefits –
- Sometimes all that is the problem is the need for an IIS Reset, a service to be restarted, and application proxy to be recreated, files to be redeployed etc.
- You learn the deployment process very well and hopefully may even begin to think about where your issue could be occurring
- You’re going to need to understand the deployment process well to be able to act on the next principle
Although this is the third last principle, in terms of process it’s the first thing you should be doing when you have an issue.
Understand the Steps of the Deployment Process
Again, another “no sh*t Sherlock” moment. Thing is though, people still drink scalding hot coffee and drive a car after taking two Valium. When I use the word “understand” I mean “deeply understand” and the reason I say this is because if you do, you can use your PowerShell skills to check if required components have been deployed properly.
So often I have seen people waste hours / days because of a misspelt assembly reference in a web service declaration file, the service application wasn’t actually started, configuration information hadn’t been set where it needed to be, files were deployed the wrong location or not at all blah blah blah etc. The list goes on for how many stupid things can trip a person up. These kinds of problems inevitably lead an inexperienced developer to chase the rabbit down the hole and have an unsettling adventure in “Developer Wonderland” – don’t become Alice!!!!