After the Beating … Office Application Development (1 of 3)

Posted: November 13, 2013 in Office 2013 Apps, Uncategorized

     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/
Advertisements
Comments
  1. Holger says:

    Thanks for sharing this !!! I was breaking my head, couse I did not get the SP.js in my word-app. So I have to think about a new way, thanks for pointing to some possibilities.

    Did you wrote 2/3 and 3/3 too? (could not find it)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s