Building your first Provider-Hosted App for SharePoint using Windows Azure – Part 1

Article
02/17/2013

If you’ve been tracking on this blog, you’ve seen me write a few posts about SharePoint and Windows Azure. For those of you that have explored SharePoint 2013, you’ll also know that Windows Azure is natively supported with this new release. There are two primary ways in which Windows Azure is natively supported within the new concept of “Apps” in SharePoint 2013: Autohosted Apps and Provider-Hosted Apps. These are two variants of what are called Cloud-Hosted Apps.

Within Autohosted Apps, SharePoint has its “own” Azure environment where you can build and deploy your Cloud-Hosted App, and using this model is quick, agile and enables you to natively tap into the ability to deploy Cloud-Hosted Apps to SharePoint without too much fuss. Provider-Hosted Apps are a slightly different beast. As the name implies, the Cloud services are not automatically hosted for you. You are the “provider” so you need to build, deploy and host your Cloud app in your own domain; though, SharePoint provides plumbing (e.g. APIs, Authentication services, etc.) to enable the connection between a Cloud-hosted App that is deployed to your own domain. Also, it’s worth noting that just because a Provider-hosted app is a type of Cloud-hosted app, it doesn’t mean that the domain to which you deploy could not be an on-premises Web server. So, think of the “hosted domain” part as flexible; you can deploy on-premises, or you can deploy to the Cloud.

For more information on Provider-Hosted Apps, see the following MSDN article: https://msdn.microsoft.com/en-us/library/fp179887.aspx.

In this blog, I wanted to walk you through how to create a deploy a simple Provider-Hosted App. This will be Part 1. (In Part 2, we’ll cover more about the glue that binds your Provider-Hosted App to SharePoint.)

So, let’s get started.

Setting up your Development Environment

If you’re just starting out with building Provider-Hosted Apps in the Cloud, then you’ll first want to check out this blog post: https://blogs.msdn.com/b/steve_fox/archive/2013/02/03/setting-up-your-development-environment-for-o365-amp-azure-development.aspx. I’ve documented the fundamentals to setting up your own development environment, inclusive of the Windows Azure part.

Key takeaway here is that while you’re getting started, you can use the new Windows Azure Web Sites service to create a simple Web site that’s free and that’s hosted in Windows Azure. This gives you a chance to try before you buy.

Creating a New Azure Web Site

Assuming you’ve got your development environment set up, you can now go ahead and create a new Azure Web Site. To do this:

Navigate to www.microsoft.com/windowsazure
Click the PORTAL link in the upper right-hand corner of the page
Sign in using your LiveID
Click the Web Sites link along the left-hand side of the page
Click the New button at the bottom of the page
Click QUICK CREATE, provide a valid URL, select a REGION (which is the data center in which your Azure app will be deployed) – see image below
Click CREATE WEB SITE

The provision process should take less than a minute to create, and when it does you’ll be able to click the new link in your portal and navigate to your newly created site. Now don’t be surprised when you see a default page with some graphics on it; this is just a starter page that you can customize. The important thing is that you’ve got a live Web site up and running, and it’s hosted in your own Windows Azure domain—see image below. An interesting note is that Windows Azure Web Sites are HTTPS compliant by default, so the site below can be accessed via https://mycrazycool.azurewebsites.net or https://mycrazycool.azurewebsites.net. Further, the trusted root certs used in Azure are conversant with Office 365/SharePoint, so you don’t have to go off and create a whole new trusted cert to get HTTPS working for you.

With your Web site now created, the question is what’s next? Well, let’s assume you want to customize your new Azure Web site a little—maybe even has some limited interaction with SharePoint. You’ve created and deployed a Web site, but how do you customize it?

Customizing your Azure Web Site

The Azure Web site you created has a Dashboard view, where you can see a number of key metrics. Towards the bottom right, you can see a set of commands under the quick glance category. One of the these commands is the Download publish profile link, which surprisingly downloads the publish profile for your Azure Web site. This publish profile is in essence an XML file that contains information about your subscription, methods of deployment, deployment URL, and so on. You can open the file in Notepad if you’re curious and want to explore it.

Save the publish profile to a convenient folder, because you’ll need it in the next step.

To customize your site, we’re going to open up Visual Studio and create a new Provider-Hosted Application, which contains a simple ASP.NET Web app by default.

Open Visual Studio 2012 (as Administrator)
Click New Project
Select Office/SharePoint, Apps, App for SharePoint 2013, and provide a name (e.g. GetSPInfoApp)
Click OK

When prompted by the New app for SharePoint dialog, add the O365 SharePoint site you’re using, and select Provider-hosted in the drop-down list as per the image below.

You’re now prompted to either use a client secret or a certificate. Select the “Use a client secret” option and click Finish.

Visual Studio creates the project structure (with two projects, one for the SharePoint App and the other for the ASP.NET App we’ll deploy to Azure) for you and by default creates an ASP.NET app with some code-spit in place. On first pass, let’s keep things really simple. Add some text on the Default.aspx page as per the snippet below.

…

<html xmlns="https://www.w3.org/1999/xhtml">
<head runat="server">
<title></title>
</head>
<body>
<form id="form1" runat="server">
<div>
<h2>Simple Azure Test Page.</h2>
</div>
</form>
</body>
</html>

If you were to deploy your app now, you’d get an error similar to the below.

And this is because you have OAuth code specific to SharePoint (see below) that raises an error if loaded only in the context of Azure. This code uses a class called the TokenHelper class, which manages the app and event authentication. So, comment this out for now; you can return to it later.

…

protected void Page_Load(object sender, EventArgs e)
{

var contextToken = TokenHelper.GetContextTokenFromRequest(Page.Request);
var hostWeb = Page.Request["SPHostUrl"];

using (var clientContext = TokenHelper.GetClientContextWithContextToken(hostWeb, contextToken, Request.Url.Authority))
{
clientContext.Load(clientContext.Web, web => web.Title);
clientContext.ExecuteQuery();
Response.Write(clientContext.Web.Title);
}
}

…

Now let’s deploy the Web app to Azure by right-clicking the Web project and selecting Publish. Here is where you’ll import your Azure publish profile by clicking the Import button, browsing to your publish profile and then clicking OK. You should see something similar to the below after this point, so click Publish to publish the simple web site to Azure.

When your Web app finishes deploying, you should see something similar to the below.

At this point, you have a working app that’s been deployed to Azure, but you need to deploy this as a Provider-hosted app to SharePoint. And you’ve already got the project structure in place, so what’s next?

Deploying Provider-Hosted App to SharePoint

If you remember, you opted to use the client secret to configure your Provider-hosted app. This is a key that both the SharePoint app and the app deployed to Azure need to be aware of, so we need to first get a client secret and then add it to the appropriate spots in our project to ensure our Provider-hosted app will work properly. To do this:

Navigate to your SharePoint Online site (where you’ll be deploying your app)
Navigate to /_layouts/15/appregnew.aspx">https://<your site>/_layouts/15/appregnew.aspx
Click Generate for the ID and for the Secret
Add a Title for your Provider-hosted App
Add the domain (this is the Azure domain)
Add the Redirect URI (again, using the Azure URI)
Click Create

Now copy the App Id into your AppManifest.xml file in your Visual Studio project. To do this, right-click the AppManifest.xml file and select View Code. Add the App Id into the ClientId property as per the bolded snippet below. Also, you can amend the StartPage property to point to your Azure Web site.

<?xml version="1.0" encoding="utf-8" ?>
…
<Properties>
<Title>GetSPInfoApp</Title>
<StartPage> https://mycrazycool.azurewebsites.net/Pages/Default.aspx?{StandardTokens} </StartPage>
</Properties>

In the Web.config file for your Web app, you’ll also need to add both the App Id and App Secret (also called the ClientID and ClientSecret) as per below.

…

…

Before we deploy, we need to ensure we’ve set the permissions on the App so it can interact with SharePoint. Right-click AppManifest.xml and select View Designer. In the Permissions tab, select Web as the Scope and FullControl as the Permission.

Hit F6 to build.

At this point, you can either publish (which packages up the files for manual deployment) or you can hit F5 to debug.

To publish the Provider-hosted app, right-click the App project and select Publish. Add a name for your profile. Click Next.

Add your Azure web site, the Client ID and the Client Secret to your app.

Click Next, and inspect the summary dialog to ensure all of the information is accurate. Click Finish to complete the process, and you’ll see all of your packaged files.

To debug, simply hit F5. Click Yes if prompted to accept and install a certificate, and then when prompted click Trust It to trust your new Provider-hosted App.

When you trust the app, it will then load for you as per the below image.

If you explore the URL, you’ll see that it points off to your Azure web site, but loads that into your SharePoint site as a Provider-hosted App.

https://mycrazycool.azurewebsites.net/Pages/Default.aspx?SPHostUrl=https%3A%2F%2Fmydemosite%2Esharepoint%2Ecom%2Fsites%2Fspc&SPLanguage=en%2DUS&SPClientTag=0&SPProductNumber=15%2E0%2E4454%2E1011

This was the first step. In Part 2, I’ll swap out some of the simple code-behind, and we’ll see how we can interact with SharePoint remotely from Azure.

Happy Coding!

Steve

Building your first Provider-Hosted App for SharePoint using Windows Azure – Part 1

Additional resources