Choose patterns for developing and hosting your SharePoint Add-in
Learn about the different ways that you can host the components of SharePoint Add-ins.
Note The name "apps for SharePoint" is changing to "SharePoint Add-ins". During the transition, the documentation and the UI of some SharePoint products and Visual Studio tools might still use the term "apps for SharePoint". For details, see New name for apps for Office and SharePoint.
The SharePoint add-in model introduces a wide range of hosting and development patterns. Some of these patterns can be used in combination with each other. For example, your add-ins can mix SharePoint-hosted and remotely hosted components. The most useful way to determine which patterns you'll want to use is to start with your own requirements, technologies, and goals and match them with the options and possibilities that are enabled by SharePoint Add-ins.
What to think about when choosing your development pattern
SharePoint Add-ins widen the range of possible programming languages and technology stacks that you can use when you work with SharePoint resources and services. The precise range of options depends on both the type of add-in and the hosting pattern that you choose. It's also possible to mix patterns.
Start with the simplest option: SharePoint-hosted add-ins, or add-ins where all components are hosted on either an on-premises or Office 365 SharePoint farm. SharePoint-hosted add-ins are installed on a SharePoint website, called the host web. They have their resources hosted on an isolated subsite of a host web, called the add-in web. It's important to know the difference between host webs and add-in webs. Figure 1 illustrates the basic architecture of a SharePoint-hosted add-in.
Figure 1. SharePoint-hosted add-in architecture
You can combine a SharePoint-hosted add-in with add-ins that have remotely hosted components, but any add-in or portion of an add-in that runs on an add-in web has the following set of requirements for three key components: where the add-in is hosted, how the add-in gets authorization, and what language it can use.
|Component||SharePoint-hosted add-in requirement|
|Where the add-in components are hosted||In the isolated add-in domain of your SharePoint farm|
|How the add-in gets authorized||The privileges of the signed-in user|
This pattern is the easiest to deploy, and you can use the Create a basic SharePoint-hosted add-in by using Napa Office 365 Development Tools. You'll want to consider the following before deciding to create a SharePoint-hosted add-in.
|Get these benefits||But consider this|
|Relatively easy to create and deploy, so they are good for small team productivity add-ins and business process automation, with lower complexity business rules.||Your add-in has only the authorization privileges of the signed-in user.|
Provider-hosted SharePoint Add-ins include components that are deployed and hosted outside the SharePoint farm. They are installed to the host web, but their remote components are hosted on another server that should not be a server in the SharePoint farm . Figure 2 illustrates the basic architecture of a provider-hosted add-in.
Figure 2. Provider-hosted add-in architecture
The following table shows how the requirements for hosting location, add-in authorization, and languages are much less fixed for provider-hosted add-ins than they are for SharePoint-hosted add-ins.
|Component||Provider-hosted add-in requirement|
|Where the add-in components are hosted||Any web server or hosting service|
|What language the add-in can use||Any language supported by your web server or hosting service|
A provider-hosted add-in interacts with a SharePoint site but also uses resources and services that are located on the remote site. You'll want to consider the following before deciding to create a provider-hosted add-in.
|Get these benefits||But consider this|
|Host the add-in on Microsoft Azure or any remote web platform, including non-Microsoft platforms.||You are responsible for creating the installation, upgrade, and uninstallation logic of the remote components.|
|Gain authorization to SharePoint data using one of the three authorization systems.||You need to decide between OAuth and the cross-domain library to authorize your add-in's access to SharePoint.|
Match your hosting pattern with your development goals
In addition to considering the technical advantages and constraints of each option, you'll also need to think about your development goals when deciding on a hosting pattern. You can use the following table to help sort out which hosting pattern best fits your needs.
|Your requirements||Recommended Hosting pattern||Example|
|Work with and provision new SharePoint entities exclusively||SharePoint-hosted||An add-in that includes a people picker control and that stores information about SharePoint users in a SharePoint list|
|Use existing SharePoint entities and interact with external (non-SharePoint) web services||Provider-hosted||An add-in that gets customer addresses from an existing SharePoint list in the host web and uses a mapping service in a web application to display their locations|
|Provision new SharePoint entities and interact with external web services||Combined SharePoint-hosted and provider-hosted||A mapping add-in that provisions a SharePoint list on the appweb so that it can store latitude and longitude coordinates for addresses that are supplied by the user or pulled from an existing SharePoint list|
What to think about when choosing your hosting pattern for provider-hosted add-ins
SharePoint-hosted add-ins have a fixed hosting pattern, since they are hosted on the add-in web. Provider-hosted add-ins provide more flexibility for hosting the various components of your add-in, so if you choose to create one, you'll need to match your goals and requirements to the appropriate hosting pattern.
OAuth or the cross-domain library
The cross-domain library lets you interact with more than one domain from the remote components of your add-in through a proxy. If client-side code and the permissions of a user who is signed in to SharePoint are sufficient, the cross-domain library is a good option. The cross-domain library is also convenient whenever you are making remote calls through a firewall.
Secure data access and client object models for SharePoint Add-ins and Three authorization systems for SharePoint Add-ins explain the choice between OAuth and the cross-domain library more thoroughly.
OAuth with on-premises SharePoint farms
If you are using an on-premises deployment of SharePoint, you can use OAuth, but you will have to choose between creating high-trust add-ins and using an Office 365 tenancy. Office 365 uses Microsoft Azure Access Control Service (ACS) as the trust broker, and if you do not have access to an Office 365 tenancy, you'll need to use Create high-trust SharePoint Add-ins, which uses certificates to establish trust between your add-in and SharePoint. You can add high trust add-ins to the add-in catalog of your SharePoint farm, but you can't sell them in the Office Store. If you do have access to an Office 365 tenancy, you can link it to your on-premises installation of SharePoint and use ACS as the trust broker for add-ins that are installed to your on-premises SharePoint.
The following table lists all of the possible patterns for hosting both the SharePoint components and the remote components of your add-in, along with the trust brokers that are available to you if you're using OAuth. Note that you'll need access to an Office 365 tenant in order to use ACS to establish trust between SharePoint and a SharePoint Add-in that is installed to an on-premises installation of SharePoint.
|SharePoint component location||Remote component location||Trust broker|
|On premises||In cloud||ACS, certificate|
|On premises||On premises||ACS, certificate|
|Office 365 SharePoint site||In cloud||ACS|
|Office 365 SharePoint site||On premises||ACS|
Combine provider hosting and SharePoint hosting
Figure 4. SharePoint add-in server-to-server communication when you use OAuth and Windows Azure
Here are some things to think about when you're considering a combination of provider hosting and SharePoint hosting.
|Get these benefits||But consider this|
|All the benefits of the two approaches.||More complex architecture requires careful planning around server-to-server communication and cross-site scripting restrictions.|
Provider-hosted add-ins in Azure Web Roles
You can host a provider-hosted SharePoint Add-in on a Microsoft Azure web role instead of a web application (whether the web application is on-premises or a Azure Web Site). An Azure web role is, essentially, a website that's based on Internet Information Services (IIS) and hosted on Azure. You can take advantage of the hosting services and scalability of Azure web roles. You can also enhance the performance and usability of your SharePoint Add-in, especially if the add-in is heavily used or demand for it changes over time. If the SharePoint Add-in ever requires more server resources, Azure can dynamically allocate them to the add-in.
See the following links for more information about Azure web roles.
As a prerequisite, you will need the Microsoft Azure SDK for .NET (VS 2012) 1.8.1, which you can install by using the Web Platform Installer.
The way that you use create the project in vsnv depends on whether you start with a SharePoint Add-in project and then add the Azure web role project, or you start with the Azure project and then add the SharePoint project.
Add a cloud service to an existing add-in
If you already have a provider-hosted SharePoint Add-in that you want to host on Azure, choose the web application project in the solution for the SharePoint Add-in. On the menu bar, choose Project, Add Microsoft Azure Cloud Service Project. A Azure project, called NameOfTheWebAppProject.Azure, is added to the solution for your SharePoint Add-in. A web role for the web project is also added to the project for the Azure cloud service. The Office Developer Tools for Visual Studio 2012 sets the necessary project properties so that the web role can work with the SharePoint Add-in.
Add an add-in to an existing web role
If you already have a web role in an Azure cloud service that you want to use as a host for a provider-hosted SharePoint Add-in, open the Azure cloud project in Visual Studio, and then, in Solution Explorer, choose the web role project. On the menu bar, choose Project, Add Add-in for SharePoint Project. A project for a provider-hosted SharePoint Add-in is created, called NameOfTheWebAppProject.Azure, and added to the solution. Visual Studio references the Azure web role as the web project host for the SharePoint Add-in.
For more information, see the following resources: