So today I will deviate from my normal technical comments to take an opportunity to honor our US Military Veterans.

A few years back I met a good friend of mine after work and we did some fishing. He was usually ecstatic to get out on the boat and get his line wet. This day he was a short of weary and run down. After about 20 minutes of this I asked him what was up. He told me nobody had wished him a “Happy Veterans Day”, as he is a veteran of the USAF. He spent numerous years serving, took fire in Central America, left his wife in the middle of the night many times for deployments when he could not tell her where he was going or when he’d be back.

I worked with an officer in the US Army. He was a miserable guy. Very ornery, borderline rage monster some days. Many folks sort of dismissed him. As part of his career, he was deployed 9 times, 4 of them to war zones. He had been shot at, had lost a number of comrades and a number of troopers under his command. As a parting gift, his wife (also in the US Army was station) on the other side of the world. He rarely saw her for three years.

I worked with another outspoken gentleman. He was former US Army. He tended to annoy folks as he was very loud. He also had a rather unique temperament. I took some time to talk with him. He served 2 tours in Iraq. Both his trips ended with a mission ending injury from IEDs. His last one, he was hit in Iraq, and did not wake up till he was in Germany. His hearing was partially damaged from the explosion.

I also heard of an inactive member of the USMC who was a family member of a coworker. He was looked at as lazy. One of those guys who always had a hurt back, folks figured he was faking it. He was a bit quick on angering when he left the USMC he took some grief on his “mental issues”. Come to find out, his last tour in Iraq, he was in a convoy that was hit with an IED. His armored Humvee was lifted off the ground and rolled off the road with him and his comrades inside. His friend who was the gunner on the top of the vehicle was not so lucky. In shock, this guy went out on the road and began picking pieces of his friend up off the road.

I bring these stories to light because most of us have no idea whatsoever what our vets do and what they have sacrificed for us. We mumble “Happy Veterans Day” on Facebook, and a couple emails. We give grief to the vets on the other 364 days of the year if they don’t adjust back to civilian life quite right and we have no true respect for their sacrifice to this country. Many of them still bear scars internally, that will never heal. They did this for US. So on Veterans Day, my ask is this, LOUDLY thank our veterans for their service, shake their hands, let them know you mean it. On the other 364 days, try to consider some of these stories, try to imagine how many other stories like these and worse there are in this country and take some understanding and compassion and help these folks out. They have more than earned it.

HAPPY VETERANS DAY!!

SharePoint Distributed Cache Service ….DANGER WILL ROBINSON!!

 

This is a late night blog so sorry for the brevity and less cohesive thought pattern. I just needed to get this out there as much for my benefit as anyone elses.

So I have to admit. This service has always been a bit of a mystery to me. Simply put, it always worked. Never had to dig. Never had to care. Just a few commandlets and it was running and I went on my merry way. Well I had a recent case where I lost a host and had to dig when it would not come back.

What a scary experience. All these tools to use, the App Fabric cache tool, App fabric cache commandlets, SP commandlets, Services MMC, and multiple CA points to manage it. And then the warnings. If you use the wrong ones, you may need to rebuild your farm. Yes, rebuild the farm. Rebuild a 13 server farm. Can you say Holy crap!

I found a lot of blogs on fixing it, a lot of MSDN and Technet articles on App Fabric cache architecture then I got a virtual and began dissecting it. I looked here (http://almondlabs.com/blog/manage-the-distributed-cache/ ) got some great pointers. I looked here http://www.microsoft.com/en-us/download/details.aspx?id=35557 and got some good reference material. I found lots of Commandlets on configuring the cluster and manhandling it. Pushing in providers (which they tell you your choices are XML or SQL), and found plenty of hacks. In many areas the lines between SharePoint 2013 and App Fabric blurred and people were unknowingly straying into dangerous areas without realizing it. Then the clouds parted around 2200 after 3 cups of coffee. The answer came to me when I looked at the HKEY_LOCAL_MACHINE -> SOFTWARE\Microsoft\AppFabric\V1.0\Providers\AppFabricCaching registry key. The provider listed was a third…SPDistributedCacheClusterProvider.

The fog lifted

                So for those who want to better understand it. In VERY simple terms. An app fabric cluster is a set of cache hosts tied together through a central point which is a SQL Server DB or a XML file on a file share. Similar to SharePoint and its reliability on a Config Db to help keep all the servers in line. In the case of SharePoint 2013, that cluster is managed through the SharePoint configuration database and the set of Distributed Cache Service instances in the farm. The SharePoint Distributed Cache Service sits on top of it. It manages it. It maintains the App Fabric cluster underneath, and keeps everything in line. This is why you only run SP commandlets to add/remove, etc. It is also why if you use alternate tools like the App Fabric cluster tool you can kill your farm. A SharePoint farms greatest weakness has always been its config DB. It is the 1 point where you can kill the farm. Using another tool risks putting the cache cluster in App Fabric out of sync with the Configuration database in SharePoint. Once that happens, well anything goes. You might be able to recover it, you might never get another DC service ever running on your farm again.

If you want to manage this service then, stick to those commandlets. Stick to the guidance on the Microsoft documents at http://www.microsoft.com/en-us/download/details.aspx?id=35557 for maintaining it. Be VERY careful on any mods outside those commandlets. The farm is literally at stake here. It is a very dangerous game and from the blog posts I have seen out there, a lot of folks are hacking in fixes.

Another great article I found which just about laid it out for me was here(I am dense and did not get the simple truth of it right away when I read this): http://social.technet.microsoft.com/wiki/contents/articles/20348.sharepoint-2013-appfabric-and-distributed-cache-service.aspx

 

Office Web Applications 2013 Installation and Configuration

 

I recently had the chance to do a full 2 server implementation of Office Web Applications (OWA, OWS, WAC, whatever you want to call it). I pulled from this article (http://technet.microsoft.com/en-us/library/jj219455(v=office.15).aspx ) which at the time of this writing, will get you just close enough to think you stand a chance but will leave you with a full on semi functional farm (if that), with a case of amnesia when it comes to certificate on the IIS site.

BTW, I am going with WAC. All the updates, patches, installs use it and it just makes it easier to identify them. Besides nobody outside of MS seems to have any clue what it means so it is a little more fun to torture folks.

Installation….wait lets talk SSL

First things first, let’s install the thing. Wait, before you do that, we need to talk certificates as in SSL. If you are thinking about not using them, stop thinking it. WAC lies outside your SharePoint, Outlook, Lync implementation. It is being sent your documents, your corporate IP, your HR forms, your engineering specs, etc etc. You do not want those transmitted HTTP unencrypted over the wire. Whether you are completely inside your firewall or external SSL is not optional. If you think it is, ask your users if they would mind you posting all their documents in SharePoint, Exchange, and Lync on the office walls. This takes your installation out of easy mode but it has to happen this way so deal with it. Sorry for the rant but it is way past time for IT professionals to take security seriously.

So now to your cert. You will need to request one. A lot of places have you do a self-signed one. In a word, NO. Get yourself a cert from either your Domain CA or form whomever you purchase them from. Have your internal and external references to your WAC farm tied to it (the ones SP, exchange, Lync will bind to), AND have it reference your WAC servers by FQDN (i.e. server1.contoso.com, server2.contoso.com). Make sure it has a certificate name AND a friendly name. This will require some lead time in most cases so I include it first.

Get the certificate and have it installed on every server in the WAC implementation.

Installation

Now we can install. First Prerequisites:

Install the following software prerequisites:

    • Windows Server 2008 R2 Service Pack 1
    • .NET Framework 4.5
    • Windows PowerShell 3.0 (Part of the Windows Management Framework 3.0 installation)
    • Platform update for Windows 7 SP1 and Windows Server 2008 R2 SP1 (KB2670838)Open the Windows PowerShell prompt as an administrator and run these commands to install the required roles and services.If not prompted, restart the server. A lot of the MS guidance does not list this as mandatory. You just added a ton of stuff to your server, restart it. Lastly, install one of the fun undocumented pre-requisites:
    • Import-Module ServerManager Then, run this command: Add-WindowsFeature Web-Server,Web-WebServer,Web-Common-Http,Web-Static-Content,Web-App-Dev,Web-Asp-Net,Web-Net-Ext,Web-ISAPI-Ext,Web-ISAPI-Filter,Web-Includes,Web-Security,Web-Windows-Auth,Web-Filtering,Web-Stat-Compression,Web-Dyn-Compression,Web-Mgmt-Console,Ink-Handwriting,IH-Ink-Support

Assuming you have Windows 2008 R2 server: Update for Windows Server 2008 R2 x64 Edition (KB2592525). This guy ay give you a challenge in installing it. If it does try this guys solution: http://ucbeacon.blogspot.com/2013/03/kb2592525-installation-failed-this.html

 

Now we will follow the technet link I mentioned word for word in the bits install:

 

Complete these steps on any servers that will run Office Web Apps Server.

Download Office Web Apps Server from the Microsoft Download Center.

Do one of the following:

For Windows Server 2012 or Windows Server 2012 R2, open the .img file directly and run Setup.exe.

For Windows Server 2008 R2 SP1, use a program that can mount or extract .img files, then run Setup.exe.

On the Read the Microsoft Software License Terms page, select I accept the terms of this agreement and click Continue.

On the Choose a file location page, select the folder where you want the Office Web Apps Server files to be installed (for example, C:\Program Files\Microsoft Office Web Apps) and select Install Now. If the folder you specified doesn’t exist, Setup creates it for you.

When Setup finishes installing Office Web Apps Server, choose Close.

Download and install Office Web Apps Server SP1 (Recommended for Windows Server 2012 and Windows Server 2008 R2 SP1. Required for Windows Server 2012 R2.)

Note:
If you are applying Office Web Apps Server SP1 at a later time, follow the directions in Apply software updates to Office Web Apps Server.

Check for the most current Office Web Apps Server updates by reviewing the list on the TechNet Update center for Office, Office servers, and related products.

Note:
If you did not install Office Web Apps Server SP1, apply KB2810007.

Step 3: Install language packs for Office Web Apps Server

 

Office Web Apps Server 2013 Language Packs let users view web-based Office files in multiple languages, whether they’re opened from SharePoint 2013 document libraries, Outlook Web Access (as attachment previews), and Lync 2013 (as PowerPoint broadcasts). Learn more about how the language packs work in Planning language packs for Office Web Apps Server.

To install the language packs, follow these steps.

Download the Office Web Apps Server Language Packs from the Microsoft Download Center.

Run WebAppsServerLP_en-us_x64.exe.

In the Office Web Apps Server Language Pack 2013 Wizard, on the Read the Microsoft Software License Terms page, select I accept the terms of this agreement and select Continue.

When Setup finishes installing Office Web Apps Server, choose Close.

Important:
To install language packs after the Office Web Apps Server farm is created, you must remove a server from the farm, install the language pack on it, and then add the server back to the farm.

For a language pack to work correctly, you’ll need to install it on all servers in the farm.

 

So lastly, Look for and push in any additional updates that are out there for the product at the time you are reading this. It is monumentally easier to install now rather than later.

 

Configure WAC

 

Now that the installs are done, it is time to configure. So this is where I advise read this carefully:

 

You will be using the New-OfficeWebAppsFarm commandlet. Before I mentioned you will be using SSL and you will have your own cert. This is one of those areas the current technet is wrong. Despite the wording that CertificateName is optional, that is not true. I should say, it is not true if you do not want your servers throwing out the SSL bindings to the WAC sites on 80 and 809 and if you do not want your users screaming about 404 errors instead of previews or viewing docs. Also, if you want to avoid manually adding the certificate to each web app on each WAC server on every reboot, and major farm PowerShell command, you will include this value.

 

The call goes like this:

Copy

New-OfficeWebAppsFarm -InternalUrl “https://server.contoso.com” -ExternalUrl “https://wacweb01.contoso.com” –EditingEnabled –CertificateName “certname”

 

So I left of the SSL Offloading command. Why? Again, documents..plain text..bad. Even if it is JUST from your load balancer to the server. Even if you get a compelling argument about how much more efficient it is on the NLB. How it is designed for it. Bad. You are most likely running virtualized, beef up your WAC boxes or add more but SSL on the WAC box.

 

Test your farm creation by hitting your machines discovery URL (HTTP and HTTPS) from another server/workstation. This url is your internal URL parameter + “hosting/Discovery”. In the example call I provided this would be https://server.contoso.com/hosting/discovery . If this gives you a 404, or does anything but give you a shiny pile of XML, then your farm is either not sucessfully created or you have a networking issue. Do not add any additional servers or attempt to link SharePoint, Exchange, or Lync to it until you resolve this.

 

Add additional Servers

 

So now you are ready to add additional servers to the WAC farm. You will use the New-OfficeWebAppsMachine commandlet. You will run this on the machine you are adding to the farm, not the ones that are already in the farm. The new server will reach out to the server specified in the “MachineToJoin” parameter. That’s right. You are not specifying the machine that is joining the farm (you do that by executing the command ON the machine you are trying to join to the farm). You are specifying the machine that your are going to join to. For this reason MachineToJoin much be your FQDN for that machine. As an example:

 

New-OfficeWebAppsMachine -MachineToJoin “server1.contoso.com”

 

You should get a confirmation that the server was added successfully. You can double check this by using the Get-OfficeWebAppsFarm commandlet if your servers are not all listed in the farm, then you have an issue.

 

Troubleshooting

 

So I could (and probably will) write an entire post on troubleshooting. So this is just a quick heads up. Get Fiddler. It is the best way to trace HTTP errors within your farm. I would not leave it on a production server long term but for troubleshooting, use it.

 

WAC ULS logs. My least favorite feature of this app. The logs are “hidden” in c:\programData\Microsoft\OfficeWebApps\Data\Logs\ULS. This is a hidden folder. You will need to either type in that location manually or set your explorer to show hidden files and folders. (Many thanks to: http://blogs.msdn.com/b/zwsong/archive/2013/04/16/where-would-you-find-uls-logs-on-office-web-apps-owa-2013-server.aspx for the ULS location).

 

Note: While in that folder set you may notice a few xml files. This is where WAC keeps a lot of it configuration information (it does not have a SQL box like SharePoint to use). There are numerous posts that send you into these files to edit them. Don’t. Best case, WAC will overwrite them. Worst case, you will mess up your WAC configuration and get to tear it down and do it all over again.

 

Event Viewer is you next best friend. Check Setup, Security, and Application logs for issues. I found WAC loves to send some very scary message there. It once loaded mine with Kerberos SPN errors when I misspelled the server name in the New-OfficeWebAppMachine command. Don’t freak on the error, just carefully analyze them. A WAC farm is really a pretty simple beast once you get to know it.

 

Wrapping it up

 

So that’s it. Hopefully, this gave you some useful information. I tried to include the things I wish I knew going into it. The certificate name feature and the cert settings were my favorite sticking point. Good luck and please feel free to post any additional pointers in the comments section. WAC is an awesome capability.

SharePoint and Kerberos for the common man

 

So your company decided it wants an enterprise class SharePoint 2013 farm. Oh and they have seen the awesome capability with PerformancePoint and PowerView, and SSRS. So you will be including the fancy Business intelligence add in. Awesome. Oh and they want ad-hoc reporting, and the DBAs and stake holders who own your data warehouse are not too keen on the idea of a random service account being used to access the data.

Sooner or later you will come to the point that you realize you will need to delegate the end users identity to the data store. In short, you will need to utilize use Kerberos Constrained Delegation (KCD). KCD is great, and at the same time utterly unforgiving. I am not diving into the specific settings. There are plenty of guides for those. This is a guide to KCD for those of us who don’t quite get the technical AD guides to it, and for those who need to troubleshoot it.

So first, when it comes to the basics, what do you need to know? You can go to this guide: http://technet.microsoft.com/en-us/library/ee806870(v=office.15).aspx which provides completely accurate guidance. However, for those who know jack about setting up Kerberos, and have no interest in becomes domain admins, what do you need to know? In short 2 things. 1 The SPNs (Service Principal Names), and 2 the service account Delegations.

SPN Delegation Basics

Here is the basic thing to keep in mind, the SPN is the TARGET of your delegation. The delegation itself is run from a source identity to a target (SPN). A SPN has x components. A Service Name, a machine/host name:<optionally a port> and an account name under which the service is being run. In the case of ECS, you set an SPN that would look like this: setSPN –s MSSQLSVC/Servername:1433 Contoso\svcSQLService. Now that the target is set you can set the delegation. This would be set in the AD tool by selecting properties on the account and then selecting the delegation tab…but wait. Your ECS account does have a delegation tab?

Dummy SPNs

              So when looking at guidance on SPNs for SharePoint you see a few on accounts such as your ECS service account that have service names like “SP/Excel”. So what is THIS for? Primarily, this is a “Dummy” SPN. And once you add it to the Excel Service account, the delegation tab we were missing in the last section will show up. You can now set your delegation

Duplicate SPNs

              So MANY domains have duplicate SPNs. You can add them to a domain. What’s the REAL harm? So remember the SPNs were your delegation target? In the previous example I set the SPN for delegating to the SQL server through port 1433 to account svcSQLService. Assume I also set one for : setSPN –s MSSQLSVC/Servername:1433 Contoso\svcSomeOtherAcct? Well, now I have 2 delegation targets for MSSQLSVC/ServerName:1433. When I set my delegation, it MAY set to the duplicate. If it does, my delegation will fail. This type of failure can be tough to locate. A good way us non-AD Admins can find it, running setspn commands. SetSPN –x will list duplicates, but depending on your list it could be HUGE. You could run a SetSPN –l Contoso\ServiceAcctName for all your service account and you may find it. Lastly, assuming you don’t have rights to actually add SPNs, you can run your own setspn –s MSSQLSVC/Servername:1433 Contoso\YOURACCOUNT. By default setspn will then list out all duplicates SPNs on that servicename/server.

Don’t get sloppy

You have to realize what an SPN/Delegation chain is. You are granting an account the right to delegate a person’s identity to another server/service. You need to think about that. In a standard ASP.Net application, if I were to delegate your identity to another web server, I could take actions on your behalf. If I were delegating a high rights service account used across an enterprise, I could wreak havoc. You should not add any delegation that you do not explicitly need. You should always use constrained delegation to enforce that delegation only be permitted by specific accounts to specific accounts on specific service types and ports. It is easy to throw SPNs out there “Just in case” and delegations “just in case” or because it is a totally time consuming frustrating experience of requesting tickets and service requests to have your AD team add additional ones later on that you were unsure of.

 

Other SharePoint SPN/Delegation troubleshooting

So how else can you look and figure out is your SPNs/Delegation point are causing issues with your services and where? In a full farm, there are multiple points. So brace yourself, these steps will have you looking through very large ULS logs. I will give you some pointers to hopefully cut down on that hunt.

Look on your SQL log. If you see NT Authority\Anonymous logging attempts, then your delegation is failing. If you look in your security log (through event viewer) on a server attempting delegation and see something like:

Error Code: 0×7  KDC_ERR_S_PRINCIPAL_UNKNOWN

Extended Error: 0xc0000035 KLIN(0)

Client Realm:

Client Name:

Server Realm: Domain.ACME.com

Server Name: MSSQLSvc/ServerName.Domain.ACME.com:1433

Target Name: MSSQLSvc/ServerName.Domain.ACME.com:1433@Domain.ACME.com

Well you are really lucky. You now know your delegation is failing and you know specifically which SPN is to blame. In the sample above, you have an SPN on MSSQLSVC/ServerName:1433 that is at fault. You now can look for duplicates or an improper service account name which most likely caused this.

If you are still seeing nothing though, quit delaying…it is time for the ULS logs.

So first when doing these steps coordinate. Run them all in sequence, and make sure you and your tester are the only ones on the farm at the time. If not, you will get a very large log and a lot of noise entries. First identify the server(s)/connections you need to validate. It would be good to navigate to within 1 click of the action/page/workbook you need to test. Keep a SP PowerShell window open on a remote session into the server(s) you wish to test.

  1. Execute new-splogfile (this will create a brand new log file for us to look at)
  2. set-sploglevel –traceseverity verboseex (your logs are now growing at a very fast rate)
  3. Run your test/data refresh/etc
  4. Re-execute New-splogfile to create a new log file and stop the growth of the one you will be analyzing
  5. Execute Clear-sploglevel to clear the high log level
  6. Collect logs

 

You will need to crack open your logs around the time your requests were being made. Some key things to look for:

  1. SPTokenCache.ReadTokenXml: Successfully read token XML ‘domain\<user name>’.
    1. This should be the domain\username that you logged into SP for to test. If you see this, then your C2WTS is successfully translating your windows claim into a Windows token. This is one less place you need to worry about in your search for your failure.
  2. PF_CHECK_ERROR returned ‘hresult error’ 0x80040e4d ; Stack Trace:NA
    1. This is a solid confirmation that you are missing a delegation point. Review your delegations on this server and you will likely find one missing, OR you have a duplicate SPN. In some cases, I have seen where a delegation set up with a duplicate SPN that has been deleted later will cause an issue. Sometimes resetting delegations will fix this.
  3. Lastly search for your data connections/connection string, as well as xlsx name (if ECS is what you are troubleshooting), or rdl filename (IS SSRS is what you are troubleshooting).

My PowerPivot Service App has fallen and it can’t get up

This was a rather fun “issue” I ran into on a client farm. I found very little documentation on this so it took me a few minutes to sort through it. Maybe it can help you out.

So I had a great PowerShell script that setup a large farm (13 servers). Had the full BI stack attached to SharePoint. Everything seems good until I started clicking on links in Central Administration, particularly on my PowerPivot Service Application. When I clicked on it, I got a 404. I thought that was weird. All the posts I saw in this issue told me to recreate it. I did this repeatedly and it did not work. It always gave me a 404.

So then I started to look a little more at the architecture for this site and the PowerPivot service itself. For those who have done this configuration there are some “special” things about it. Like for instance, it installs a group of WSPs in your farm to get all the pieces working. I thought, hmmm, that usually means features. I would have bet they were all hidden. But on a whim I went into the Site Settings page on the Central Administration site, opened up the Manage site features page. About ¾ of the way down the list there is a feature called “PowerPivot Administrative Feature” and it is not activated. So I activate this feature. No more 404 but I still get an error. So now I recreate the PowerPivot Service App again. This time is comes up and I am back in business.

So for those seeing this issue, go ahead and give this a try. My particular environment is very heavily GPO’d and I suspect the initial roll out of the corporate GPOs broke the initial service and blocked that feature. Either way though, something to consider.

So we had an application which attempted to parse through OOXML in a word doc locate all bindings and content controls and grab all their metadata (found in the WebExtensions/Bindings elements). We had a problem with the IDs which should bind these two sections inconsistently matching. Some docs they all would, some docs they never would, most docs only some would. The ones that would not match would typically be negative numbers.

So after Binging the problem, and beating ourselves to death over it we found the post at: http://stackoverflow.com/questions/2693542/open-xml-document-contentcontrols-problem-with-signed-ids . This one saved our lives.

The problem is that in the WebExtensions/Binding, the ID is stored as a 64 bit integer. In the sdt tag binding, it is a 32 bit representation of that same ID. We followed the code samples set at the link provided above and we now have a 100% match on all IDs.

     I felt compelled to write this series after I downloaded the sample office apps from MSDN (all of them) and descended into the 7th level of hell trying to get it to work. The goal was to create an office apps to implement a Word task pane app to allow insertions of bindings, pushing bindings/tags to a SPS 2013 List, and access the SPS taxonomy to allow for tagging of bindings within a Word document. Seems simple enough. I had a pile of samples, a mess of MSDN and TechNet links, I was ready to go or so I thought.

There is actually a good deal of documentation on the Apps for Office, some good MSDN samples, and some great videos. You can certainly go through these and get a pretty good base level of knowledge on Apps for Office. When you take it to a complex solution though, you quickly find some serious gaps which hopefully will be plugged and render this post pointless. This is especially true when your intention is to self-host your apps and use a local app catalog for the manifest. This series is about the gaps I encountered which hopefully will help someone else out.

As I state throughout this series, I am really in the midst of ramping into this area and even through the course of the project the documentation has been changing. So please chime in if you have any additional info to share or questions.

Clarification on terminology

               So before I go too far, I want to clarify a couple things on the terms I use. There are 2 parts to a deployment. First, you are pushing your manifest to a catalog. Second, you are deploying the actual app functionality somewhere. When I refer to deployment in this series, I am referring to the deployment of the functionality not the manifest. I will specifically call out the manifest deployment when that is what I am referring to.

Hope you like client side code

If not, you are probably going to have a bad day. Office apps first and foremost are client side focused. They utilized JavaScript, and JQuery, pulling in libraries from the Office.js, JQuery.js, and Microsoft Ajax just to start with. If you do not understand these technologies and the concepts around coding them, you need to. There are some very subtle (and not so subtle) paradigm shifts you need to be in the know on. A good example, cross site calls. When server side, you can have your server side app call services and references all across your enterprise and possibly even the web. On the client, this is called cross site scripting, and is viewed as a security violation and will be blocked in most cases. This is for good reason. Imagine JavaScript you would write on your website just to make a simple call to a SPS farms web service API to get some info for the current user. Well that would be a client side call, made from the browser, using that individual user’s security context, from that user’s box. It would not be a stretch to write code to go all over the internal sites, maybe some real bad external ones, pulling down inappropriate information, modifying documents in SPS, etc. and it would all look like the end user did it.

Additionally, client side code is blocked from doing most modifications to the local machine. It runs in its own special little area, and is tightly controlled from what it can do to protect people from malicious code. This plays a large role in the architecture you decide to use for your application and how you code it.

Not just client side code

So the good news for server side coders, as I mentioned, the office app is a web site. So that means, you can code it as an ASP.Net site, and enjoy all the wonders of server side code as well. The solution we wrote did in fact use a god deal of C# code to make some calls and save some information. Also, for the types of calls we needed to make, a server side web service call to SharePoint was needed. So you do not need to have server code but you can have it if there is a need. Another good reason may be to run confidential business logic. That way, you are not exposing it through client side code.

Understand the model

               There are some key things to understand. An office task pane app, is running within a task pane in the word client. It is essentially a little browser winder of its own. It is given SOME access to the document through the Office.js that is inherited. That is a key concept. The app accessed the DOCUMENT not the Word client. Bearing in mind that the Word client is running on the OS under the security context of the end user, there is a serious potential security risk in allowing a Word task pane app to manipulate the Word client. If you open the door for that, you run the risk of allowing a task pane app to make malicious calls to the local OS and file system. For this reason a lot of things you would like to do that involve changing Word state, are going to be blocked. Get to know the JavaScript API for Office Task pane apps to better understand it. As you can see, the calls focus on the document not the Word client application.

In the sample I was building, another key was your app catalog is in SharePoint, your app is not. Meaning the SharePoint SP.js library and its supporting libraries are not there for you to use. If you want to work with SPS, you will need to make some web service calls. As I noted before, these likely will involve cross site scripting. So now you need to work around that. For our solution, we knew we would need to make a series of calls to the asmx and svc APIs in SPS 2013, on multiple applications. For some of these calls we could use a JSON call to bypass the cross site scripting issue, and there are plenty of good examples of that in the MSDN coding samples but not all of them. What we decided to do was use the example in the MSDN Sample code and build a controlled class which could make the server side calls for us. In this model, the Office app JavaScript makes a service call back to itself, and then the server side calls out to the SharePoint farm web services and returns data back to the client. It allowed for a good deal of flexibility for our service calls and opened the door for hitting SPS to modify anything we wanted to, and retrieve data. This ended up being pretty easy

There is a way around the missing Sp.Js and SharePoint context. I found a solution in MSDN that had a task pane app embedded in a SharePoint app. This gave me the ability to simplify the deployment, to get access to the SP.Js and all its references, to capture SPS Context info on the client side and do some real easy coding. However, it does deploy to an App tenant in SPS 2013, and there are implications to that. Additionally, when you do this, it is only going to allow client side code. This may not matter, but bear it in mind.

Plan your deployment

               While coming up with the design know how you intend to deploy this app. Will it be hosted in SPS? Will it be part of an SPS App? Will it be on an IIS server? Azure? This decision can have a very big impact on what is possible. As an example, if I am deploying to a SharePoint App, or to a SharePoint site, I am deploying typically client side code only. Meaning no compiled dlls, but my code will have access to SP context on the client and Sp.js. If I am going to IIS Server, I will be able to code whatever I want on the backend/server side, I will not have direct access to SP context or SP.Js (assuming I care for this app).

For each deployment model I will also need to consider security and user context unique to that situation as well as infrastructure considerations, firewall rules, etc.

Watch your JavaScript and CSS References

               One extremely common newbie mistake (and of course one I made repeatedly) was not being mindful of my JavaScript and CSS references. In the Home.html file generated by VS when creating an office app they link to the online ones (for JQuery and Office) and local references for the css and some other JavaScript used for the app. They have commented out lines to use a local version of these files. When running on a development virtual, that may or may not have access to the web, your first time you will undoubtedly not realize this and your apps will fail when trying to run and import these files. When using the local files and relative links, you will probably run into an issue along your testing where it cannot find them because of where your app is running. This is an extremely common mistake so when you work with an office app and are moving through development, and testing and code stops working despite not being changed, this is the first place I would look.

Testing can be painful

               So while in VS 2012 or 2013, I can run this in debug mode, it all pops up in a word doc and everything is great. However, take away you VS debug ability and you are in trouble. Office task pane apps do not allow for “Alert” functions or many other functions you would commonly use to pop up state information while walking JavaScript to see what is wrong. But hey, why would I care? I got VS debugging. So a couple reasons. First VS debugging is about the perfect scenario. VS.Net is tied directly to the local IIS and it kicks off Word and inserts the app for you. In the real world, when you go to test and deploy the app, all these tools are not there. Your Office app is running elsewhere. Your manifest is in an app catalog on yet another server, and Word is running on yet another client machine. So now you have 3 separate servers running code, oh and the example I was building called out to yet another SPS farm. Your office app is running in a task pane and is secured by IE security settings, plus ones specific to Office Apps in Word, plus any additional GPOS in your Org. You are needing to ensure open and secure communication between Word, the Office app, and any other systems you are needing to hit. You need to consider the identity each communication channel is using. A lot of those failure are silent in your word application. For example, a security setting/GPO that blocks the JavaScript from loading and/or executing when calling a remote system can create silent failure which is tough to debug. An authentication issue may be silent. Tools like fiddler can help some but very often you need to really be methodical and not assume anything. IMO, the tools have not really caught up to this technology to make the testing as easy as it should be. To be honest, I am still developing my methodology on adequately testing and debugging these systems.

References:

  1. Apps for Office Training videos – http://msdn.microsoft.com/en-US/office/dn448488
  2. Apps for Office Samples – http://code.msdn.microsoft.com/office/Apps-for-Office-code-d04762b7
  3. Apps for Office Task Pane App JavaScript API – (http://msdn.microsoft.com/library/office/fp123523(v=office.15)#FundamentalsTaskContentApp_JavaScriptSupport)
  4. How to: Create an app for SharePoint that contains a document template and a task pane app – http://msdn.microsoft.com/library/office/fp179815.aspx
  5. Fiddler – http://fiddler2.com/