This is the first post in a series of blog posts on the SharePoint app model. Here is the outline of this series.
Get the custom code out of SharePoint
The server-side code you write for a SharePoint solution runs inside the SharePoint environment. For example, managed code deployed in a farm solution runs inside the main SharePoint worker process (w3wp.exe). Managed code deployed using a sandboxed solution runs inside the SharePoint sandbox worker process (SPUCWorkerProcess.exe). However, The SharePoint app model mandates that code from an app cannot run inside any process that is launched or managed by SharePoint.
There are a few simple reasons why Microsoft wants to get rid of custom code that runs inside the SharePoint environment. The first reason has to do with increasing the stability of SharePoint farms. The one is pretty obvious. Getting rid of any type of custom code running inside the SharePoint environment results in lower risk, fewer problems and greater stability for the hosting farm.
The second reason has to do with a company’s ability to upgrade to newer versions of SharePoint. The underlying problem is that SharePoint solutions which contain code that programs against the SharePoint server-side object model have been notorious at creating migration problems when a company is upgrading from one version of SharePoint to the next. More to the point, Microsoft has witnessed many of their biggest SharePoint customers postponing the upgrade of their production farm for months and sometimes years until they have had time to update and test all their SharePoint solutions on the new version of SharePoint. Since this problem negatively affects SharePoint sales revenue, you can bet it was pretty high on the fix-it priority list when Microsoft began to design SharePoint 2013.
Your custom code has to run somewhere
When you develop a SharePoint app you obviously need to write custom code to implement your business logic. It is also clear that app's code must run some place other than the Web servers in the hosting SharePoint farm. The SharePoint app model gives you two places to run your custom code. First, a SharePoint app can contain client-side code which runs inside the browser on the user's machine. Secondly, a SharePoint app can contain server-side code that runs in an external website that is implemented and deployed as part of the app itself.
There are many different ways in which you can design and implement a SharePoint app. For example, you could create SharePoint app that contains only client-side resources such as web pages and client-side JavaScript code which are served up by the SharePoint host. This type of app is known as a SharePoint-hosted app because it doesn't require its own external website. If it's late at night when there's nobody around and your feeling a bit naughty, you could even write a SharePoint-hosted app that uses Silverlight code instead of JavaScript code to implement its client-side business logic.
Now imagine you want to create a second SharePoint app in which you want to write server-side code in a language such as C#. This type of SharePoint app will require its own external website so that your server-side code has a place to execute outside the SharePoint environment. In the new SharePoint 2013 terminology, a SharePoint app with its own external website is known as a Cloud-hosted app. The following diagram shows the key architectural difference between a SharePoint-hosted app and a cloud-hosted app.
From this diagram you can see that both SharePoint-hosted apps and cloud-hosted apps have a start page that represents the app's primary entry point. With a SharePoint-hosted app, the app's start page is served up by the SharePoint host. However, with a cloud-hosted app the start page is served up from the external website. Therefore, SharePoint must track the external URL for each cloud-hosted app that has been installed so that it can redirect users to the app's start page. The SharePoint infrastructure creates a client-side JavaScript component known as a launcher which is used to actually redirect the user from the SharePoint host over to the external app.
When you decide to develop a cloud-hosted SharePoint app, you must take on the responsibility hosting the app's external website. However, this responsibility of creating and deploying an external website along with a SharePoint app also comes with a degree of flexibility. You can implement the external website for a SharePoint app using any existing Web-based development platform.
For example, the external website for a cloud-hosted SharePoint app could be implemented using a non-Microsoft platform such as Java, LAMP or PHP. However, the easiest and the most common approach for SharePoint developers will be to design and implement the external website for cloud-hosted apps using Visual Studio 2012 and the ASP.NET Framework.
Let's look at an example. Imagine you would like to develop a cloud-hosted SharePoint app. Visual Studio 2012 and the new SharePoint Tools provide you with a new project template for SharePoint apps development that quickly create the starting point you need for creating a cloud-hosted SharePoint app. This starting point is a Visual Studio solution which contains two separate projects as shown in the following screenshot.
The first Visual Studio project in this example is named MyCloudHostedApp. This is the SharePoint app project that creates the distributable installation file named MyCloudHostedApp.app that gets installed inside a SharePoint host. As you can see from the screenshot, this project contains an important XML file named AppManifest.xml which tracks the app’s metadata that is used by SharePoint when the app is installed. The project also contains an image file named AppIcon.png that is used to add a custom icon to the page in SharePoint with the launcher that the user clicks on to navigate to the start page of the app.
The second project named MyCloudHostedAppWeb is used to develop the ASP.NET Web Application that will serve as an implementation of the cloud-hosted app’s external website. Note that Visual Studio uses the naming convention of adding “Web” to the end of the name of the first project to create the name for the second project. Therefore, the project for the SharePoint app is named MyCloudHostedApp and the project for the external website is named MyCloudHostedAppWeb. You will also find that a SharePoint app project such as MyCloudHostedApp has a project property named Web Project which can be used to reference the external website project which allows Visual Studio to recognize these two projects are used together to develop single cloud-hosted app.
From the screenshot above, you can see that the MyCloudHostedAppWeb project contains a page named default.aspx which is located inside a folder named Pages. This page will be used as the app’s start page. Now let's examine the AppManifest.xml file in the SharePoint app project to see how the app's metadata is configured to use default.aspx as its start page.
Note that the app manifest contains a top-level App element with an inner Properties element. Within the Properties element are two required elements named Title and StartPage. The Title element contains human-readable text that is displayed along with the launcher. The StartPage element contains the URL that SharePoint uses in the launcher to redirect the user to the start page in the external website. When an app is deployed into production, the StartPage element will contain the full path to the start page on the Internet.
https://appserver.wintip.com/MyCloudHostedAppWeb/Pages/Default.aspx
When you are developing a cloud-hosted app, Visual Studio provides a convenient dynamic token named ~remoteAppUrl which eliminates your need to hardcode the path to the external website during the development phase. For example, Visual Studio created the StartPage element with the following value.
~remoteAppUrl/Pages/Default.aspx?{StandardTokens}
The reason this works is that the SharePoint app project named MyCloudHostedApp has a Web Project property which associates it with the external website project named MyCloudHostedAppWeb. Whenever you deploy or debug your solution, Visual Studio will perform a substitution to replace ~remoteAppUrl with the current URL of the Web Project. Note that the ~remoteAppUrl token will always be replaced by Visual Studio before the app manifest is installed into a SharePoint host. Therefore, SharePoint really sees a value for the StartPage element that looks like this.
https://localhost:44300/Pages/Default.aspx?{StandardTokens}
Note that the value of the StartPage element in this example contains a second dynamic token named {StandardTokens}. This token is different that the ~remoteAppUrl token because it is not replaced by Visual Studio. Instead, this dynamic token remains inside the app manifest after it has been installed into a SharePoint host. It is the SharePoint infrastructure and not Visual Studio that performs the substitution on this token. Whenever SharePoint uses this StartPage element to create the URL for a launcher, it replaces {StandardTokens} with a standard set of query string parameters used in SharePoint app development such as SPHostUrl and SPLangauge.
default.aspx?SPHostUrl=http%3A%2F%2Fwingtipserver&SPLanguage=en%2DUS
When you implement the code behind the start page of a SharePoint app, you can generally expect that the page is passed these two query string parameters named SPHostUrl and SPLanguage which you can use to determine the language in use and the URL back to the site in the SharePoint host. In quite a few scenarios, SharePoint will add additional query string parameters beyond these two.
What’s nice about developing a cloud-hosted app using this type of Visual Studio solution is that you can develop and debug both projects at the same time within a single session of Visual Studio 2012. This approach will be appealing to experienced .NET developers because it allows them to write the app’s server-side code using C# or VB.NET using the latest and greatest version of the .NET Framework (version 4.5). You can also leverage the libraries of the .NET Framework and benefit from essential Visual Studio support for debugging and IntelliSense. Moreover, the code runs outside of the SharePoint environment so you avoid many of the frustrating limitations and idiosyncratic SharePoint-isms that SharePoint developers have had to deal with over the years. Compare this to writing C# code for a sandboxed solution that has to deal with frustrating limitations of the SharePoint 2010 sandbox. Now that's a good reason to get excited about developing SharePoint apps.
Using an ASP.NET application to implement the external website also provides flexibility in deployment. When deploying a cloud-hosted SharePoint app within a private network, you can host the external website on a local Web server running within the same LAN as the hosting SharePoint farm. For other scenarios that require scaling and/or accessibility from anywhere on the Internet, you can deploy the ASP.NET application in the cloud using Windows Azure Services.
A tale of three app hosting models
When you create your first SharePoint app in Visual Studio 2012, you will not see a specific option to create a cloud-hosted app. Instead, Visual Studio gives you three options for selecting the app's hosting model. The three options you get are Autohosted, Provider-hosted and SharePoint-hosted as shown in the following screenshot.
At a high-level, Autohosted apps and Provider-hosted apps are just two different variations of a cloud-hosted app. Everything I have explained in this blog post about cloud-hosted apps applies equally well to both Autohosted apps and Provider-hosted apps. So then you ask, "what's the difference between the two?" I will first explain what an Provider-hosted app is and then I will finish by discussing the value of an Autohosted app. However, I will keep this discussion at a fairly high level and wait until later in the series to drill down into more detail.
When you decide to create a Provider-hosted app, then you will ultimately be responsible for deploying the external website and making it accessible on the Internet or on a private network. As I mentioned earlier, you have the option of deploying this external website on a local Web server or up in the cloud using Windows Azure services. What is important to see is that the external website must be deployed and made accessible to the users who will access it before you begin to install the SharePoint app that relies on this external website.
The Autohosted app can provide a better strategy for deploying the external website associated with a cloud-hosted app. The main idea is that an Autohosted app calls upon infrastructure built into Office 365 that can automatically deploy the external website when the app is installed. Note that this approach will only work in the Office 365 environment and cannot be used in scenarios in which SharePoint apps are installed within an on-prem farm.
The automated deployment model provided by Autohosted apps relies on a special implementation which integrates Windows Azure Services together with the Office 365 environment. Inside the installation file for an Autohosted app, there is extra metadata and all the ASP.NET application source files required to spin up a Web Site in Windows Azure Services in order to deploy the external website. An Autohosted app can even go one step further by allowing you to automate the creation of a SQL Azure database as part of the app installation process. There are a ton of details you need to know to make it all work, but here I just wanted to explain things at a high level so you can understand that both Provider-hosted apps and Autohosted apps are really just cloud-hosted apps that mainly differ in how their external website gets deployed.
Conclusion
So now you understand one of the key points of the SharePoint app model. Custom code never runs inside SharePoint. It runs somewhere else. You have the option of writing both client-side code and server-side code. A SharePoint-hosted app is easier to create, implement and deploy. However, it does not provide the opportunity to add server-side code. A cloud-hosted app will yield more power because you can write as much server-side code as you would like using a managed language such as C# and your code is not limited by all those frustrating limitations and issues created by running code inside the SharePoint environment. In my next post, I will dive into the details about how the SharePoint infrastructure is able to isolate SharePoint apps with respect to request processing and storing app-specific content within a SharePoint content database.