Part 2: Intro to Provider Hosted Apps – Develop, Package, and Deploy

The purpose of this blog series is to consolidate and provide a simple flow on how to setup Provider Hosted App Infrastructure and understand the basics around Packaging and Deploying provider hosted apps. I assume you have setup the infrastructure for Provider Hosted Apps. If not, start Part 1 of my blog series here before continuing this blog.  Part 2 covers how to create a simple provider hosted app in Visual Studio 2013 and how to package and deploy the solution to both the remote server (hosting the remote web application) and SharePoint 2013 (drop the app in the app catalog). This blog will not cover how to deploy your app to a developer site in order to debug within Visual Studio 2013.   This is fairly basic and plenty of documentation exists which guides one through this.  This blog is is for a 100% on premise SharePoint 2013 provider hosted app environment. Also, some of the steps below I grabbed from various spots on MSDN and I’ll provide references to MSDN links which provide useful details.

Before going through the steps, I’ll provide a quick intro into my basic setup:

Domain: Contoso.local (all boxes are Windows 2012 member servers joined to the domain)

Remote Web (will host provider hosted apps) – Windows 2012 running IIS 8.0

  • Default Web Site responds to http://remoteweb (used host header and set up SSL)
  • Each app will reside under the default web site as a Virtual Directory
  • Default Web Site set to Windows Authentication

SharePoint: SharePoint 2013 running latest cumulative update (Single Server Farm)


Create a simple app in Visual Studio 2013

The first step is to create a simple provider hosted app. I’m not going to do anything fancy with app development and simply going to leverage the OOB default.aspx page that’s produced and add a paragraph. The app will not call back into SharePoint in this case and instead will redirect a user that clicks on the app to the default.aspx page on the remote web server. To reiterate, the purpose of this blog as mentioned in part 1 of this blog series isn’t to show you how to do x and y with apps but rather show you the basics for setup, packaging, and deploying Provider Hosted Apps.

1. Start Visual Studio 2013 and choose File, New Project.
2. In the New Project wizard, expand the Visual C# or Visual Basic node, and then expand the Office/SharePoint node.
3. Choose Apps, and then choose to create an App for SharePoint 2013 project.
4. Name the project whatever you want. In my case: RemoteSampleApp.
5. Ensure you point the URL to the developer site you created in SharePoint 2013
6. Save the project in a location you choose, and then choose OK.
7. Select the Provider-hosted option, and then choose the Next button.


Note: The site inputted above should point to the developer site


8. If prompted to specify the type of web project, select ASP.NET Web Forms Application for the continuing example in this topic, and then choose the Next button



9. For the Configure authentication settings page perform the following steps:

a. Click the Browse button next to the Certificate location box and navigate to the location of the self-signed certificate (.pfx file) that you created (C:\Certs). The value of this field should be the full path C:\Certs\remotewebapps.pfx. (Note: this is my cert created from part 1 (previous blog) here)

b. Type the password for this certificate in the Password box. In this case, it is “password”.

c. Type the issuer ID (8cb8c3db-5bfd-4a7a-8b18-189000065ad0) in the Issuer ID box. (Note this is the issuer id (random guid) associated to the sptrustedsecuritytokenissuer I created from part 1 (previous blog) here)

Note: It should look like the following:



d. Click finish and the default.aspx page automatically opens so added a paragraph to the page and saved it.




11. This step is just for observation purposes) Click on the AppManifest.xml for the app looks like the following:


Note: the Start page contains the virtual directory, path, and page name that will be deployed on the remote web.



12. Save Project and Build the Solution




Register App in SharePoint Farm

The next step is the app must be registered in the SharePoint farm where it will be deployed. We also require the App ID generated for Visual Studio 2013 when we build the app package.

1. Access any site and append /_layouts/15/appregnew.aspx

For Example:



2. Click Generate buttons for both App Id and App Secret fields.
3. The App Domain is the domain name set on the remote web application server’s IIS Site that will be hosting this app.
4. The redirect URI isn’t required in my case so click create button which produces the following:



5. Copy the output as it’s needed during the packaging phase.



Publish the App Web (remote Web)

Publishing the App Web builds a package that includes files and a script. These files are copied to the remote web server and deployed. First, in Visual Studio 2013 you’ll have two different projects created. One is for the app which produces an app file and that file is uploaded to the app catalog and made available to SharePoint Sites. The second project is for the remote web and is a simple web application. In my case, RussMaxSecProvHostedApp is the app project and RussMaxSecProvHostedAppWeb is the remote web project. These steps apply to the remoteweb.



1. Right click the “RussMaxSecProvHostedAppWeb” and hit publish.

2. Created a New Profile and set the connection like the following:


Note: In my case, I want all of my provided hosted apps living under the default web site as a virtual directory. So I specified the site name as “Default Web Site/RussMaxSecProvHostedApp


3. Click next and choose Release



4. Choose Next



5. Click Publish and Success!



6. Checking the directory I have the package



7. Copy this directory + output to the IIS Server hosting this remote web.



Deploy and Test Remote Web

At this point, the app/remote web package has been copied to the remote web server.

1. Start Command Prompt and navigate to the directory containing the package files

2. Run the following command: yourproviderhostedappwebname.deploy.cmd /y

Note: In my case it’s: russmaxsecprovhostedappweb.deploy.cmd



Note 2: It finished successfully and refreshing IIS gives me the new site:



3. Test by manually attempted to browse to the site.


And Page renders:


Note: I had to remove the inherits element from default.aspx page because of a server side error. In my case, I removed: Inherits=”RussMaxSecProvHostedAppWeb.Default”



Publish the App

At this point, the remotewebapp project has been packaged and deployed to the remoteweb. The final step includes publishing the app, deploying to the desired SharePoint 2013 app catalog, and finally installing the app to a team site and test.

1. Within Visual Studio 2013, right click the “RussMaxSecProvHostedApp” and hit publish.



2. Click Edit and fill out the fields.


Note: The client ID is the App ID which came from the appregnew page. The Issuer ID is assigned to the associated SPTrustedSecurityTokenIssuer object. I assume you know what this ID is and please leverage Part 1 of the blog series for more details.


3. Hit OK and then click Package the App


Important: You must point at your site + virtual directory. In my case, the RussMaxSecProvHostedApp will be created under the Default Web Site.


4. Click Finish and it builds the app package automatically:


Note: It automatically opens windows explorer to the app.



5. Copy this file over to a server that can access the app catalog.



Add App to App Catalog

For an app to be consumed, it must be added to an app catalog.

1. Navigate to the app catalog and select Apps for SharePoint
2. Select New App and upload the .app file produced from the last set of steps

In my case, it looks like the following after upload:


Note: I added RussMaxSecProvHostedApp so I have two apps available now.



Install App to a site

1. Access a team site and selected site contents and clicked Add App.

Note: I see it here



2. Click on it and click Trust It


Note: If it errors on this step and you’re logged in as the system account, try again using a non-system account.


3. After install, test by clicking on the app.

For Example:  Clicked on the following (Before):


And the redirect works!








Russ Maxwell, MSFT

Comments (16)

  1. Ligesh says:

    I added the App Installed event to the above project, the deployment threw error. Any idea?

  2. Shilpa says:

    Awasome post. Simple and have covered all points nicely.. Thanks 🙂

  3. Ganesh Jat says:

    Nice post, simple explanation Thanks

  4. Bikash says:

    Hi Russ, Nice Post.

    Q: Can you please provide some pointers on the best way to publish remote web and app to Dev,QA and Prod environment ?

    – AppId and AppSecret would be different for different environment

    – Issuer ID and Certs would be different in different environment

  5. Jinad Padiyath says:

    Simple and Nice post. Covered all aspects of apps including production deployment also. Thanks.

  6. Varun Gupta says:

    This is one of the best blog I have read for deploying provider hosted app.

  7. Tomas says:

    Great article.

  8. Fab says:

    Very usefull article. All is clear.

    Except one part:   "Note: I had to remove the inherits element from default.aspx page because of a server side error. In my case, I removed: Inherits="RussMaxSecProvHostedAppWeb.Default""

    Why we have to do this and how can we use C# code to custom aspx page if we can't inherits from C# class?


  9. Wes says:

    I did not have to remove the Inherits tag from my page.  Just make sure that for provider hosted apps on Premises (high trust), that you are not receiving an unauthorized error, or any error for that matter within your code behind page.  Obviously we want to use CSOM within our code behind page to do something with our apps.  Not sure what error this blogger was receiving.

  10. VenuGopal says:

    Nice explanation of How to deploy provider hosted apps .

  11. taps says:

    great post however, my application is looking for pages in SharePoint pages list did i miss a step?

  12. Thiru says:

    Great post.

    i followed all the steps, when i click on the app it works, but when iam trying to add the app to app part on a page it shows only the title,does not render the contents. I also added the client webpart, any idea guys

    really struck at this point.

    thanks very much

  13. Stan says:

    Hi Russ,

    Nice post. Having gone through other hundreds of articles, this was really simple. It would be great if you could do a post on provisioning web, site column,content type, list and Remote Event Receiver for premises scenario using provider hosted apps.

  14. Kalyan says:

    Hi Russ,

    Excellent post, But I am stuck at deployment step,

    I've published the Remote Web App and copied it to my Dev server,

    But it giving me the below error when I tried to create site in IIS…


    Really stuck at this point please help..

  15. Arie says:

    I am still confused by the remote web/sharepoint add-in set up. Should i not be getting my pages in sharepoint with the c# code running on the remote web?

    In step 3 of publish you point to the remote web. Souldn't that be the sharepoint app? How do i know what page the add-in will run on in sharepoint? in my setup i got redirected to the remote web when starting the add-in.

    And i had to to through some setting up of sharepoint including creating a add-in domain on the sharepoint box. How does that fit in with this tutorial?

  16. YahiyaIqbal says:

    Awesome Post. I loved it!!!! you had put everything togeather other than Code