Export (0) Print
Expand All

Important aspects of the SharePoint Add-in architecture and development landscape

SharePoint Add-ins

Learn about aspects of the architecture of apps for SharePoint and the model for apps for SharePoint, including the app hosting options, user interface options, deployment system, security system, and lifecycle. This article supplements the information in the article SharePoint Add-ins.

Last modified: July 22, 2015

Applies to: apps for SharePoint | Office 365 | SharePoint Add-ins | SharePoint Foundation 2013 | SharePoint Server 2013

Note 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 2013 app model provides the following ways to host the components of an app for SharePoint:

  • Provider-hosted: Apps that include at least one remote component and may also include SharePoint components. The non-SharePoint components are deployed by your logic on your hardware or cloud account, or deployed on the customer’s hardware or cloud account using installation programs and instructions that you provide.

  • SharePoint-hosted: Apps that include only SharePoint components and logic that runs on the client.

For more detailed information about hosting options and some guidance for how to choose between them, see Choose patterns for developing and hosting your SharePoint Add-in.

The website to which an app for SharePoint is installed is called the host web. However, the significant parts of the app for SharePoint, whether they are SharePoint components or external components, are not deployed to the host web. External parts are deployed to external servers or cloud accounts. SharePoint components are deployed to a special website with its own domain. This is called the app web. Only a limited set of UI elements that give users access to the app's other components are deployed to the host web. These UI components in the host web are deployed as part of a host web Feature — a Feature that is loose in the app package instead of inside a .wsp file. The components that are deployed to the app web are always in Features that are inside a .wsp file. Both kinds of Features must have Web scope. No other scope is possible for Features in apps for SharePoint.

As a general rule, any SharePoint component that does not include custom code that runs on the SharePoint servers can be included in an app for SharePoint (and be deployed to the app web). There are, however, some exceptions and some nuances to how and where the components are deployed. For more information about these nuances and about host webs, the isolated app webs, and Features in apps, see Host webs, app webs, and SharePoint components in SharePoint 2013.

When an app for SharePoint is installed on a website, the app is listed on the Site Contents page of the host web. Users can start the app from that page. When opened in this way, the app runs in full-screen mode.

Another way that an app for SharePoint can be surfaced is through an app part, a type of Web Part that is represented by the ClientWebPart class. This kind of Web Part is essentially a wrapper for an IFrame that would host a page of the app. In the simplest case, the only significant property of the Web Part is a URL that points to the page. But Web Parts can have custom properties that users can set in a Tool Part. Such properties could be used, for example, to set context information such as the user's ZIP Code or Postal Code. To include such an app part in your app, you create a host web Feature in the app and add declarative Web Part markup. Like any other Web Part, it appears in the SharePoint 2013 UI from which users add Web Parts. You can have more than one app part deployed with your app if you need even more variability. For example, a weather app can have an app part that shows current weather and a second app part that shows a weekly forecast. The two parts can have different sizes and functionality.

Note Note

You can also deploy app parts to the app web. To implement this, the markup for the Web Part would be part of a Feature inside a .wsp file in the app package, not in the host web Feature.

We recommend that you try to give your apps a SharePoint appearance to the extent possible, although that is not mandatory and may not always be the best choice. For more information about the user experience guidelines, see UX design for SharePoint Add-ins.

There is, for example, a special master page called app.master. This page is optimized for use by the pages of apps. The app.master page is part of a new site definition that is included in SharePoint 2013.

Another tool you can use to help your apps maintain a consistent look and feel with SharePoint is the chrome control that ships with SharePoint 2013. This control enables you to add the SharePoint navigation header area to your app pages, including pages hosted externally. For more information about UX design in apps for SharePoint, see UX design for SharePoint Add-ins. For more information about the chrome control, see Use the client chrome control in SharePoint Add-ins.

An app for SharePoint package is a file that has an ".app" extension and that complies with the Open Packaging Conventions (OPC). (You can open the file by adding ".zip" as an extra extension on the filename and then opening it in Windows Explorer.) It contains an app manifest that specifies certain properties of the app and instructions to the SharePoint installation infrastructure. For more information about the app manifest and package, see Explore the app manifest structure and the package of a SharePoint Add-in.

SharePoint 2013 introduces a new app permissions and security system.

App permissions

Apps for SharePoint have permissions just as users and groups do. This enables an app to have a set of permissions that are different from the permissions of the user who is executing the app.

You must request, in the app manifest file, the permissions that an app needs to run. The user who adds the app must grant these requests, and the user can only grant permissions that he or she has as a user. The grant must be for all the requested permissions or none of them to simplify the management of permissions for users and developers. (The app principal always has full control rights to the app web, so it only needs to request permissions to SharePoint resources in the host web or other locations outside the app web.)

For more information about app permissions, see Add-in permissions in SharePoint 2013.

Selective delegation and authorization

Neither users who are launching an app, nor resource owners who are granting an app permission to access a resource, need to provide the app their credentials or password. Instead, SharePoint 2013 enables users and resource owners to grant only the specific permissions that the app requests. What makes this possible is the use by SharePoint 2013 of the transaction protocol OAuth 2.0. For more information about OAuth in SharePoint 2013, see Context Token OAuth flow for SharePoint Add-ins 2013.

Cross-domain access

An app for SharePoint that includes a remote web application that uses JavaScript for its data access logic can use a JavaScript cross domain library to get authorized access to SharePoint data within the tenancy where the app is installed. For more information, see Access SharePoint 2013 data from add-ins using the cross-domain library.

The lifecycle for an app for SharePoint includes publishing, installing, upgrading, and uninstalling. For more information about these subjects, see Publish SharePoint Add-ins, Deploying and installing SharePoint Add-ins: methods and options and SharePoint Add-ins update process. Note also that there is a mechanism by which tenant administrators can batch install an app for SharePoint to multiple websites. For more information, see Tenancies and deployment scopes for SharePoint Add-ins.

Apps for SharePoint can create and access any kind of data, including structured data, documents, and multimedia files. This data can be stored in SharePoint or in an external location. For more information, see Data storage options in SharePoint Add-ins and Data access options for SharePoint Add-ins.

Site collection administrators and tenant administrators can monitor apps and change the resources allocated to them. In addition, Microsoft personnel for the app store can flag apps and disable them.

For more information about managing apps, see Install and manage apps for SharePoint on TechNet.

Monitoring apps

SharePoint 2013 provides health monitoring of apps and makes this information available in the UI to website owners, tenant administrators, and farm administrators. Most documentation for the monitoring system is on TechNet; for example Monitor apps for SharePoint. This section is just a quick introduction to explain how apps that you sell are monitored.

Some kinds of data are reported per-app and other kinds are reported per–app-instance. The primary items that the monitoring framework reports are as follows:

  • Use of the app, such as the number of times it has been installed (creating a new instance).

  • Server resource consumption of each app instance.

  • Installation, upgrade, and run-time errors of each app instance.

  • An overall health indicator for each app instance of green, yellow, and red.

If the app includes Azure Web Site components, the monitoring framework also polls Microsoft Azure hourly for its error data and reports critical errors and storage quota data in the SharePoint 2013 UI. Microsoft Azure SQL Database errors are not reported.

The information that is provided by the monitoring framework enables administrators to determine whether their app purchase budget is being wisely spent, whether they have to deploy more resources to apps, and whether they have to disable an app that is not working correctly.

If your app for SharePoint depends on a SharePoint capability that is not available and cannot be made available on the app web, then it will not work properly and your customers will complain. You can ensure that your app is not installed where the requisite services and Features are not available by registering the dependencies of the app in app manifest. The installation infrastructure for apps for SharePoint will check for these prerequisites and it will block installation of you app if any of them is not available.

For services, such as Excel, Access, or Visio services, the infrastructure will verify that the service is installed and licensed.

For Features, such as a Task list, the infrastructure will verify that the Feature is deployed and either:

-- activated at the Farm, WebApplication, or Site (site collection) scope


-- activatible, with Web scope, on the app web that is created when the app is installed.

Note Note

The app installation infrastructure will automatically activate such Features on the app web when it is created.

The following sections provide the details you need to register your prerequisites.

Implicitly register dependencies with permission requests

When your app needs access to SharePoint components outside of the app web, it must request permission for these resources in the AppPermissionRequests section of the app manifest. These permission requests also serve as prerequisite registrations because SharePoint will infer from the permissions that your app requests that it the app needs certain SharePoint capabilities to be available. In many situations, SharePoint can infer all the capabilities that your app needs and the remaining sections of this topic are not needed. However, redundant dependency registrations are not harmful.

Explicitly register dependencies with AppPrerequisites

When your app has a dependency that is not implied by its permission requests, you register each dependency with an AppPrerequisite element in the app manifest. There are three attributes in this element; Type, ID, and (optionally) MinimumVersion.

There are three possible prerequisite values for Type; Feature, Capablility, and AutoProvisioning. A Feature prerequisite is simply a SharePoint Feature that must be deployed and activated on the app web or a broader scope that includes the app web. A capability is a set of related Features and services that must be available on the app web. (AutoProvisioning is discussed in the next section.)

The optional MinimumVersion specifies the lowest version of the Feature or capability that your app requires. The attribute values are of the form n.n.n.n; for example

The ID specifies which Feature or capability is required. If Type is Feature, the ID is the bracketed, hyphenated GUID of the Feature; for example {151D22D9-95A8-4904-A0A3-22E4DB85D1E0}. If Type is Capability, the ID is the GUID of the capability. The capabilities are listed below. To get the find the GUID of a capability see AppPrerequisite element (AppPrerequisiteCollection complexType) (SharePoint App Manifest).

  • Access Services 2010

  • Access Services

  • Managed Metadata Web Service

  • PowerPoint Services

  • Secure Store Services

  • Machine Translation Service

  • User Profile Service

  • Visio Graphics Service

  • Work Management Service

  • Duet

  • Workflow

  • Search

  • EDU

The following is an example of raw AppPrerequisites markup that registers the Workflow capability. If you are using Visual Studio, you edit the app manifest in a designer tool.

  <AppPrerequisite Type=”Capability” ID=”{CDD8F991-B459-4512-8048-03D5A03FF27E}” MinimumVersion=”” />
</ AppPrerequisites>
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
© 2015 Microsoft