Writing SharePoint Apps can be tricky at times. Especially until you learn to know where to look when things are not working for you. Usually the first issue people strike is trying to launch their app and it not working.

Usually one of the first errors people strike is a common one that has an error that says “The parameter ‘token’ cannot be null or empty string”.

This is a signal that something went wrong launching the application and that some of the information that is passed to SharePoint during the app launch wasn’t passed correctly.  Usually due to an app setup issue.

The particular error above could be caused by a variety of issues, however the point of this post is to show you the first place I look when trying to debug it.  Hopefully this will help others find and fix their problem too.

First, to understand where to look when debugging its important to understand the process of what happens when you are launching a SharePoint App. The basic steps of the launch process are:

1. User clicks the app to launch it
2. SharePoint sends the user to the AppRedirect.aspx telling it what app to launch
3. AppRedirect.aspx builds a set of launch parameters including a context token and other parameters about the SharePoint site launching the app e.g. SPSiteUrl
4. AppRedirect.aspx renders a page with these parameters as a hidden HTML form on the page
5. Javascript runs that submits the form to the applications launch page, POSTing these form parameters along with some query string parameters
6. The App page is called and can get these parameters from the Request and use them as it needs. e.g. for using the CSOM to call back to SharePoint.

The error shown above is a snippet of boilerplate code from a provider hosted app code template in Visual Studio.  In order to construct the CSOM context the classes in TokenHelper.cs that are used need some of the information passed in the POST parameters from AppRedirect.aspx.  These are not on the query string as they are POST parameters, so this is usually where people get stuck debugging.  You need to use a tool like Fiddler to see the POST being made and take a look at it.

Below is what the launch sequence looks like in Fiddler (click on the image to get a bigger version):

1. AppRedirect.aspx is called and the launch parameters are constructed and the Form is submitted by the browser.
2. The app page is called, in this case Default.aspx
3. My app wants to make a call using the CSOM to SharePiont and as part of that needs an OAuth Access Token, so is reuqesting one from Azure Access Control Services (ACS) (topic for another post).
4. Finally the CSOM query is processed and the call to ProcessQuery is made.

In the browser you will recognize the AppRedirect.aspx page by the infamous “Working on it…” text 🙂

If you open #1 above in Fiddler in the raw response to the browser you will see the following:

This is the HTML Form with the launch parameters included. 

If the SPAppToken is empty … you have a launch problem 🙂

If your form is missing the SPAppToken then you will get the error message at the beginning of those post. It’s got the context token that you need in order to use the CSOM.

If it’s empty in the Form you likely have an error message in the SPErrorInfo giving your some more information about why is null/empty.

SPErrorInfo is your first place to start looking for why things are not working.

This should provide some insight and more pointers on where to look next.

E.g. “The Azure Access Control service is unavailable”.   This message says that SharePoint can’t construct the SPAppToken because it cant talk to ACS in order to do that.  This could be for a variety of reasons, such as network connectivity.

This post wasn’t written to solve every problem you have with launching an app.  It was posted to help those trying to debug their apps.  I thought it would be useful for those wanting tips on where to look to find some information when they are having issues launching their app.

I hope to helps!

-CJ