Export (0) Print
Expand All

How to: Convert an autohosted app for SharePoint to a provider-hosted app

Learn how to convert an autohosted app for SharePoint to a provider-hosted app.

Last modified: August 27, 2014

Applies to: SharePoint Foundation 2013 | SharePoint Online

In this article
Prerequisites for converting an autohosted app to a provider-hosted app
Converting the app
Other resources

Microsoft SharePoint 2013 introduced a new approach to extending SharePoint sites in addition to the previous approach of using solution-based customizations. This new extensibility model for SharePoint, called the app model, enables developers to create custom implementations that can be deployed to SharePoint environments regardless of whether they are running in an on-premises, SharePoint Online, or hybrid deployment.

Developers can build two different types of apps for SharePoint. The first type, a SharePoint-hosted app, primarily runs in the browser; and all the assets that support it such as HTML, CSS, images and JavaScript are stored and served by SharePoint. The other types of apps fall into the Cloud App model (CAM) and primarily run external to SharePoint on another server and communicate with SharePoint using the client-side object model (CSOM) and REST API. They establish an identity using the popular OAuth 2.0 protocol supported by SharePoint 2013.

Developers could implement apps using the app model in one of two ways, either as a provider-hosted app or an autohosted app. Autohosted apps were released as a preview program when SharePoint 2013 released, but in May, 2014 Microsoft announced that they would be closing the preview program and would no longer support creating autohosted apps. For the announcement, see Update on Autohosted Apps Preview Program.

This article explains how to convert and migrate an autohosted app to a provider-hosted app. However, it is important developers understand some specific differences between the two approaches because this knowledge greatly simplifies the conversion process.

Core concepts to know

Before you convert an autohosted app to a provider-hosted app, you should have a basic understanding of apps for SharePoint and the differences among SharePoint-hosted, provider-hosted, and autohosted apps for SharePoint. The articles listed in Table 1 should give you that understanding.

Table 1. Core concepts for converting an autohosted app to a provider-hosted app

Article title

Description

Overview of apps for SharePoint

Learn about the new app model in SharePoint 2013 that enables you to create apps, which are small, easy-to-use solutions for end users.

Important aspects of the app for SharePoint architecture and development landscape

Learn about aspects of the architecture of apps for SharePoint and the model for apps for SharePoint, including the app hosting options, user interface (UI) options, deployment system, security system, and lifecycle.

Choose patterns for developing and hosting your app for SharePoint

Learn about the various ways that you can host apps for SharePoint.

Host webs, app webs, and SharePoint components in SharePoint 2013

Learn about the distinction between host webs and app webs. Also find out which SharePoint 2013 components can be included in an app for SharePoint, which are deployed to the host web, which are deployed to the app web, and how the app web is deployed in an isolated domain.

Converting an autohosted app for SharePoint to a provider-hosted app involves modifying two or three components.

  • The SharePoint app itself

  • The remote web application or services

  • The Microsoft Azure SQL Database, if any, in the app

A SharePoint autohosted app deployed the Azure Web Site and Microsoft Azure SQL Database automatically when it was installed, however provider-hosted apps can have their remote web application and other services exist in any web platform. This article assumes that the remote components autohosted app are going to be remain as Azure services following the conversion to a provider-hosted app.

The following sections walk through the process of converting an autohosted app to a provider-hosted app. The example autohosted app that is used – Customer Manager - is simple, in order to focus on the conversion steps and not the actual app. It consists of three projects:

  • CustomersDb: A SQL database project that will generate the necessary *.dacpac. Note there is no schema defined in this project. It is simply used to create a database because the schema is created by the ASP.NET web application.

  • CustomerManagerAH: A SharePoint autohosted app that is configured to include the ASP.NET web application project and Azure SQL data-tier application in the resulting SharePoint app package.

  • CustomerManagerAHWeb: An ASP.NET MVC web application that uses the Entity Framework Code First with Migrations approach to create the database schema as well as read and write to the database.

The app is an ASP.NET MVC web application that can both show the customers from a table in an Microsoft Azure SQL Database as well as add new customers. This is an anonymous web application that will allow anyone to view or add customers. The Visual Studio solution for the autohosted app and associated projects can be downloaded from the following public repository: Autohosted-Migration-Code-Samples.

Converting a SharePoint 2013 autohosted app to a provider-hosted app involves multiple steps. Each is outlined in the following sections.

  1. Deploy the Microsoft Azure SQL Database

  2. Create the Azure Web Site to host the remote web application

  3. Register the app with your SharePoint site

  4. Update and deploy the Azure Web Site for the remote web application

  5. Update and deploy the SharePoint provider-hosted app

Deploy the Azure SQL Database

The first step in converting the autohosted app to a provider-hosted app is to deploy the Microsoft Azure SQL Database that the ASP.NET web application will rely on. There are many different ways to create a Microsoft Azure SQL Database, some of which are documented on the Microsoft Azure documentation site: How to Deploy a Database to Azure.

The approach outlined in the following steps uses the data-tier application deployment model because that is how the database is deployed in a SharePoint autohosted app. This involves generating a data-tier application package (*.dacpac) and using it to create the database.

Creating and Deploying the Azure SQL Database

First open the autohosted solution in Visual Studio. Right-click the database project CustomerDb and select Build. This will generate the CustomerDb.dacpac file in the [..]\bin\[debug | release] folder.

The next step is to create a new Microsoft Azure SQL Database. Login to the Azure Management Portal (https://manage.windowsazure.com) and once the dashboard loads, select the SQL DATABASES link in the margin:

Fig 3: Azure SQL Database dashboard in the Azure Management Portal

Azure SQL DB listing

Click the SERVERS link in the top navigation and then click the ADD button in the footer as shown in the following figure:

Fig 4: Azure SQL Database dashboard in the Azure Management Portal

Azure SQL DB Add button

In the CREATE SERVER dialog that appears, select the Azure SUBSCRIPTION, the LOGIN NAME and PASSWORD for the user who will have rights to the server and select the same REGION used when creating the Azure Web Site previously. Make a note of the login name and password as those will be needed in a later step.

Fig. 5: Creating an Azure SQL Database in the Azure Management Portal

Azure SQL New DB dialog

Once the form is filled out, click the check icon in the lower right to create the database. While the server is now created, the only resource that can access it are other Azure services. Make a note of the name of the Microsoft Azure SQL Database because this will be needed in a later step.

In order to connect to the Microsoft Azure SQL Database and deploy the database, a firewall rule must be created that allows traffic from the computer that will deploy the database. Otherwise connections to the Microsoft Azure SQL Database will be refused with errors similar to the one in figure 6:

Fig 6: Error Connecting to an Azure SQL Database

Connect to server error

To create a firewall rule, within the Azure Management Portal, select the Microsoft Azure SQL Database previously created and then click the CONFIGURE link in the top navigation. Under the Allowed IP Addresses section, your IP address is currently shown as shown in figure 7 below. Click ADD TO THE ALLOWED IP ADDRESSES to add a firewall rule. Doing so will allow connections to the Microsoft Azure SQL Database and deployment of the database. Make sure to click the Save button in the footer.

Fig. 7: Creating a firewall rule for an Azure SQL Database in the Azure Management Portal

Azure SQL create firewall rule

The next step is to deploy the database. This can be done from Visual Studio using the Azure SDK v2.3. Install it from this Download Center page. Within Visual Studio, open the SQL Server Object Explorer tool window, right-click the SQL Server node and select Add SQL Server:

Fig. 8: Adding an Azure SQL Database in Server Explorer

Connect to SQL Azure from Visual Studio

In the Connect to Server dialog, enter the Server Name, set the Authentication to SQL Server Authentication and enter the same Login and Password defined when creating the Microsoft Azure SQL Database. The server name should be the fully qualified name of the server which is [server-name].database.windows.net, as shown in the following figure:

Fig. 9: Connecting to an Azure SQL Database in Visual Studio

SQL login to server dialog

After connecting to the Microsoft Azure SQL Database, expand the node for the newly added server, right-click on the Databases node and select Publish Data-tier Application to bring up the publishing wizard.

In the section Source Data-tier Application (.dacpac), use the Browse button to find the *.dacpac file generated from when the database project was built in a previous step and ensure the Database Name is set to CustomerDb, then click Publish to publish the CustomerDb in the Microsoft Azure SQL Database.

Fig. 10: Publishing a Data-tier Application to an Azure SQL Database using Visual Studio

Publish DACPAC dialog

Refresh the Visual Studio SQL Server Object Explorer tool window to see the CustomerDb listed under the Databases node.

Note Note

Depending on how the database was created for the autohosted app, some extra work might be necessary to deploy it to Azure. Refer to the following articles in MSDN for additional guidance:

Post-deployment actions

Once the Microsoft Azure SQL Database has been created, make a copy of the connection string used to establish a connection to the database. This can be obtained two ways. One way is to login to the Azure Management Portal (https://manage.windowsazure.com) and navigate to the Microsoft Azure SQL Database created in the last step: CustomerDb. On the DASHBOARD page for the database, click the link Show Connection Strings to see a list of connection strings. Make a copy of the ADO.NET connection string for later use.

Fig. 11: Obtaining Azure SQL Database Connection Strings from the Azure Management Portal

Azure SQL connection strings dialog

The other way to get the connection string is from within Visual Studio, provided the Azure SDK v2.3 is installed. Within the SQL Server Object Explorer tool window in Visual Studio, select the database CustomerDb. Once the database is selected, look at the Properties tool window to see connection string. This is the same value found in the Azure Management Portal above.

Fig. 12: Obtaining Azure SQL Database Connection Strings from Visual Studio via the Azure SDK

Obtain SQL connection string in Visual Studio

Create an Azure Web Site

The next step is to create a new Azure Web Site where the remote web application will reside for the provider-hosted app. This has to be done first because the URL of the remote web application is needed before registering the app. However, the registration of the app in SharePoint should precede the deployment of the files for the ASP.NET web application because there are two outputs from the registration process (the Client ID and Client Secret) that are needed prior to the deployment of the ASP.NET web application files.

To create a new Azure Web Site, first login to the Azure Management Portal (https://manage.windowsazure.com). When the dashboard loads, click the WEB SITES navigation link in the left-hand margin, and then the NEW button in the footer as shown in figure 13:

Fig. 13: Azure Web Site dashboard in the Azure Management Portal

Azure Web Sites dashboard

Next, in the new web site wizard, select COMPUTE, WEB SITE, QUICK CREATE and then specify a URL and WEB HOSTING PLAN. Finally specify the REGION where the web site should be created. Make sure to remember the region selected because the same region should be used for the Microsoft Azure SQL Database created later. In addition, if a web hosting plan does not already exist or a new one is desired, select the option Create new web hosting plan. The following figure shows an example:

Fig. 14: Creating an Azure Web Site in the Azure Management Portal

Create Azure Web Site dialog

After creating the Azure Web Site, make a note of the URL that is used for the site. In the figures above, the site created is http://spahapptoph.azurewebsites.net.

Register a new app

All apps for SharePoint created using the app model must be registered with the hosting SharePoint farm or tenancy in order to establish a trust between SharePoint and the remote web application. This involves registering a new app principal with SharePoint specifying the following values:

  • Client ID - the app ID

  • Client Secret - the app password

  • Title - the name of the app

  • App Domain – the top-level domain of the remote web application

When an autohosted app is installed in SharePoint Online, Office 365 creates the app principal automatically. It knows the URL of the remote web application because it creates the site automatically. It also takes the client ID and client secret and adds them to the remote web application’s web.config. The web.config is where a class provided by Microsoft (in the TokenHelper.cs or .vb file) will look for them when validating requests and authenticating with SharePoint.

However, in a provider-hosted app, the developer has to manually register the app and manually update the web.config in the ASP.NET web project.

To register a new app, browse to the app registration page of the SharePoint website’s where the app will be installed. This page is found at http://[SharePoint-site-url]/_layouts/15/appregnew.aspx. On the app registration page, set the App Type to An app running on a web server and click the two Generate buttons to create a new Client Id and Client Secret. Enter the name of the app in the Title field and the URL of the target Azure Web Site created it the previous step in the App Domain field. Finally, click the Create button. Figure 15 shows an example.

Fig. 15: Completed app registration form for a new provider-hosted app

SharePoint app registration form

After the app has been registered, SharePoint will display a summary of the information that was used in the form to create the registration. It is very important that this information is copied for safekeeping, specifically the Client Id and Client Secret, because these are needed in a later step.

Remote web application / Azure Web Site configuration changes

The next step is to reconfigure the remote web application so that it can be deployed as a provider-hosted app instead of an autohosted app. There are multiple ways to deploy an ASP.NET site to an Azure Web Site including deploying it straight from Visual Studio, automatically from source control like Visual Studio Online, or from GitHub, or even by using the tried and true FTP option. In this article Visual Studio is used. However before the web application can be deployed, it first needs a few updates in order to work with the provider-hosted app.

Update the remote web application project

The big change that needs to occur in the ASP.NET MVC web application is within the web.config file. Within this file there are three settings found within the <appSettings> node. These are the ClientId, ClientSecret, and SqlAzureConnectionString. The first two are used by the Microsoft-provided class, in TokenHelper.cs or .vb, to facilitate authenticating and communicating with SharePoint from the remote web application. The latter, SqlAzureConnectionString, is used by the app to connect to the Microsoft Azure SQL Database.

In a SharePoint autohosted app, Office 365 fills in the values for these settings when the Azure Web Site and Microsoft Azure SQL Database are created when the app is installed. However in a provider-hosted app these must be manually set before the app is deployed.

One option is to paste in the values for the three settings from the steps above, but the disadvantage with this approach is that if they ever need to be changed, the web.config will need to be manually updated and redeployed to the Azure Web Site.

Another option is to simply clear these settings (leave the settings keys in place, just set the value="" attribute to an empty string) and instead define them in the Azure Web Site settings through the Azure Management Portal. This approach means that the settings can be changed without updating the codebase.

To do this, login to the Azure Management Portal (https://manage.windowsazure.com) and navigate to the Azure Web Site created in the previous steps. On the Azure Web Site dashboard page, click CONFIGURE in the top navigation menu and then scroll down to the app settings section. Add three new app settings using the same same setting names from the web.config file. Use the values obtained in the previous steps as shown in the following figure:

Fig. 16: Adding the Azure Web Site app settings using the Azure Management Portal

Adding settings to Azure Web Site

Make sure the Microsoft Azure SQL Database connection string is correct and valid because, when the connection string is exposed through the Azure Management Portal and Visual Studio, the password attribute is replaced with a mask. The masked password in the connection string should be changed to use the correct password defined when creating the login for the Microsoft Azure SQL Database.

Deploying the Remote web application to the Azure Web Site

Now the ASP.NET MVC web application files need to be deployed to the Azure Web Site as the remote web application. Within Visual Studio, right-click the web project and select Publish. This will launch the Publish Web wizard dialog. In this dialog select the option Windows Azure Web Sites and click Publish.

Fig. 17: Visual Studio’s Publish Web Dialog

Publish web site dialog in Visual Studio

In the next step, select the name of the Azure Web Site that was created in a previous step as shown in the following figure, click OK, and ensure the URL of the site is HTTPS.

Fig. 18: Publishing the ASP.NET web application to an existing Azure Web Site

Select existing web site dialog

In the last step, click the button Validate Connection to ensure the settings and connection is in good working order and finally click Publish. This will trigger Visual Studio to deploy the ASP.NET web application to the Azure Web Site.

After deploying the website, Visual Studio will launch the default debugging browser and navigate to the Azure Web Site. However the site will render with an error. This is because the ASP.NET MVC controllers are decorated with an attribute (specifically the SharePointContextFilter) that expects SharePoint to send certain values to the controller in the header of an HTTP POST request, but by default the browser launched an HTTP GET request, so this error is expected.

Note Note

Refer to the Azure documentation for additional options for deploying ASP.NET web applications to an Azure Web Site: How to Deploy a Microsoft Azure Web Site.

Post-deployment actions

The next step is to copy the URL of the site.

Custom Domains and SSL Certificates for Azure Web Sites

All Azure Web Sites use the following naming convention: http[s]://[site-name].azurewebsites.net. Microsoft has already added a wildcard SSL certificate to all web sites under the *.azurewebsites.net domain, but customers are free to associate a custom domain with their Azure Web Site as well as use their own SSL certificates for these custom domains.

For information on using custom domains, refer to the Azure documentation: Configure a Custom Domain Name for a Microsoft Azure Web Site. For information on adding a custom SSL certificate for your custom domain name, refer to the Azure documentation: Enable HTTPS for a Microsoft Azure Web Site.

Reconfiguring the SharePoint App Project

The last step is to reconfigure the SharePoint app project. The Visual Studio project for the SharePoint app has the app type configured to autohosted. First change this from autohosted to provider-hosted by opening the AppManifest.xml file in the SharePoint app project and change the Hosting Type option from Autohosted to Provider-hosted:

Fig. 19: Updating the AppManifest.xml of the SharePoint app

App manifest designer in Visual Studio

In addition, set the Start Page of the app to point to the URL of the remote web application’s start page which is the URL of the Azure Web Site. Make sure to include the query string value {StandardTokens}, if it isn't already there. This ensures that SharePoint adds the core query string tokens to the URL when it opens the remote web application.

Next, remove the reference in the SharePoint app project to the ASP.NET MVC web application by selecting the SharePoint app project in Visual Studio Solution Explorer and within the Properties tool window, set the Web Project property to (None), as shown in figure 20:

Fig. 20: Removing the remote web application from the SharePoint app package

Web project properties in Visual Studio

The last step requires a manual update to the AppManifest.xml file because some settings are not exposed within the designer. Do this by saving any existing changes to the AppManifest.xml file, and then right-click the same file in Solution Explorer and select View Code.

Fig. 21: Opening the AppManifest.xml file in the code view

App manifest context menu in Visual Studio

Within the code view of the AppManifest.xml file, remove the two references to the ASP.NET MVC web application project and the SQL data-tier application project as they are not needed within a SharePoint provider-hosted app.

Next, create a new GUID and replace the existing GUID in the ProductId attribute. This will tell SharePoint this is a new app, not an update to an existing app.

Important note Important

If the existing ProductId was used SharePoint would return the error "The provided app differs from another app with the same version and product ID" when the converted app is installed.

Then find the <RemoteWebApplication> element and update the ClientId attribute to be the same GUID that was obtained when registering the app with SharePoint and that was used in the Azure Web Site’s web.config app settings.

Fig. 22: Setting the ClientId for a SharePoint provider-hosted app

Client ID attribute in app manifest

After saving all changes to the AppManifest.xml file, the app is now ready for testing as a SharePoint provider-hosted app. Deploy the app to a SharePoint farm or SharePoint Online site to verify the conversion steps were performed correctly.

For more information on the SharePoint app model, SharePoint-hosted apps or the app model, follow the Office Developer Blog for news and updates on development tools, scripts and utilities to assist in creating SharePoint apps and migrating from autohosted apps to provider-hosted apps.

Show:
© 2015 Microsoft