Windows Azure auto-provisioned apps for SharePoint 2013

I suppose you all heard about the “App” concept in SharePoint 2013? If not, you have a nice overview about this new concept on msdn. An app for SharePoint is a great way to surface a remote web application in SharePoint. In this post, I want to tell you a little bit more about Windows Azure auto-provisioned apps for SharePoint 2013.

Imagine this: Wouldn’t it be cool if you can deploy whatever custom web application with whatever server-code behind it, directly to your Office 365 instance? Well, using the Windows Azure auto-provisioned apps you can. First question you can ask yourself, what’s Windows Azure doing in this story and how does it link to your Office 365? Well, to get this working internally each Office 365 gets automatically an Azure account associated. That’s nice, and really powerful. Because you now have both Azure and Office 365 together, you don’t have any reasons or whatever to stick with your on-premise installation.

An auto-provisioned app contains at least one Windows Azure Web Site that can be launched from a SharePoint 2013 Preview host web, and may also include SharePoint components on an app web and a SQL Server database (based on SSDT and .dacpac packages).

Let’s take a look what the development and deployment process looks like:

1. The developer builds a SharePoint application into in .APP file
2. Deploy to SharePoint
3. SharePoint installs the application for you
4. SharePoint provisions all Azure components
5. SharePoint provisions the SQL Azure database and initializes everything included in the .dacpac (Data-tier Application Component Package)

So in general, you create an application, publish it to SharePoint, and SharePoint will do everything for you. So creating an Azure Website, manage your database on SQL Azure and initialize everything.

Let’s try it out. First you have to create a new SharePoint project in Visual Studio 2012. Open Visual Studio and click ‘File –  New Project‘. In the ‘new project‘ window, select ‘Visual C# – Office/SharePoint – Apps‘ and select the ‘App for SharePoint 2013‘ template. Give your project a name and click ‘Ok‘

Note: If you have never created a SharePoint/Office 2013 app before, you will not find the Project Template in Visual Studio 2012. You need to install the Microsoft Office Developer Tools for Visual Studio 2012. You can download this here. It will start WebMatrix and download all the required components you need.

On the next screen, enter the name of the application, and the URL of your development site. I used my SharePoint Online subscription for this. Be sure to use a ‘Development Site‘, otherwise you will get an error when you try to test your application. (been there, done that!). If you don’t have a development site, create a new one and use the ‘Development’ template when creating. That will do the trick. Ok, in the current window, also be sure to select  and choose “Autohosted”.

When you click ‘Finish’, your project will be created. Basically, it will create a solution with 2 projects. The first project contains an AppManifest file, and the second project is a simple ASP.NET application.

The AppManiFest file is the definition of your SharePoint application. It contains a title, a name, which (tile) icon it uses, what the start page is, which permission requests it need to run (for example accessing  User Profile information),… The ASP.NET application itself is really basic, but one thing to notice is the file ‘TokenHelper.cs‘. This is a file who is responsible for the OAuth 2.0 authentication of your application with SharePoint. This helper class is used in Default.aspx. It includes sample code about how to handle OAuth 2.0 authentication and how to perform callbacks to SharePoint using CSOM.

In this example, we won’t change anything and just continue and get our application up and running. All you have to do is click on ‘Debug‘, or just press ‘F5‘.

In the output console of Visual Studio, you will see that the SharePoint application will be uploaded to SharePoint, and that SharePoint will do the necessary things to install it. Note that your App is NOT provisioned on Azure yet. If the installation was successful, your browser will be opened and will ask you to do a login and it will now ask you: “Do you trust your application”? Click ‘Trust it‘

You will now have your application listed as an item in the ‘Site Contents‘.  Click on your application and you will get a certificate error. If you look good to the URL of your application you will see ‘http://localhost:xxxx’. What SharePoint did was an installation, and during the installation, the application URL was set to your localhost environment. Indeed, if you look on that taskbar of your machine, Visual Studio started an IISExpress with the same port as the one SharePoint redirects you to. Just ignore the certification error and continue.

What you see now is not quite much. What this example basically does is using the ‘SPHostUrl‘ parameter that is added to the URL when SharePoint opens your application. Using this parameter, the application will get an access token (using OAuth 2.0) and use this token to get a client context object. This object can load the title of the SharePoint site you’re using. Because your app is hosted locally using IISExpress, you can easily debug it.

Ok, let’s assume that our application is ready to be deployed. We can use Visual Studio to deploy our application. Right-click on your project containing the AppManifest file and select ‘Deploy‘. It will now execute the same process as before (as you can see in the Visual Studio Output window). When your application is installed, trust it, and click on the Application icon to open it.

As you can see now, the URL is not on localhost anymore, but it got a unique o365apps.net URL. So our application has been deployed to Windows Azure, awesome!

Of course, we’re still in development. But let’s say that everything is good, tests are written and the application is ready to go live, how can you do this? Well, we first need to create an ‘APP’ package of our application. In Visual Studio, right-click on your project containing the AppManifest file and select ‘Publish‘. You will get this dialog:

Click finish, and the output folder of your .APP file should open. In fact, an APP file is nothing more that a zip file (you can open it with 7Zip for example), containing all your artifacts. A bit like the WSP files.

Ok, so we have our APP file. Now we should ‘upload‘ it to our SharePoint farm, and make it possible for users to select this application on their site. The place where App’s can be managed is called the “App Catalog“. This app catalog is a separate Site Collection, and can be created using the SharePoint Administration Center. There you can click on ‘Apps – App Catalog‘. If you haven’t created one yet, it will create one for your, and otherwise, you will be redirected to the App Catalog itself.

Adding an App to the catalog is really simple. On your App Catalog site, click on ‘Apps for SharePoint‘ (on the left side). You will see an overview of all installed apps, including an indication of the licenses you still have available. To add your App, click ‘New Item‘

It will open a new dialog where you can select your .App file and give it a version comment. Click ‘OK‘ to continue. The next dialog gives you an overview of everything related to your application. Complete this as you want, and click ‘Save‘

Now you have your new Application available in the App Catalog. To use it, just go to a site where you want to use the application. On this site, go to ‘Site Contents‘ on the left side, and click on ‘Add an App‘. Look what you see there, the application we’ve just uploaded:

Click the App, trust it, and your application will be provisioned by SharePoint. When this process is ready, your application is installed on your site, and you’re ready to use it. Click on the App, and you should see:

The text displayed is the name of my site, which is ‘Ideation’, and you also see a unique ID in the URL = a unique Windows Azure website. (Note the ‘Website’ part of the name).

So that’s it. We have our SharePoint app up and running on Windows Azure. Great! One thing that’s really important to know: each ‘installation’ of our App will provision a new Windows Azure Website. So this will be a part of your billing/account, don’t forget that.

To finish this post, I’ll give you 2 reasons to use this approach:

1. When you deploy an autohosted app for SharePoint, all Windows Azure and SQL Azure components are provisioned for you when the app for SharePoint is installed.
2. The Windows Azure Web Sites infrastructure handles load balancing, multi-tenancy, and other important maintenance tasks for you.

Thanks for reading!