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 options, deployment system, security system, and lifecycle. This article supplements the information in the article Apps for SharePoint.
Last modified: March 09, 2015
Applies to: apps for SharePoint | Office 365 | SharePoint Add-ins | SharePoint Foundation 2013 | SharePoint Server 2013
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".
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 app for SharePoint.
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.
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 apps in SharePoint 2013.
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 apps in SharePoint 2013. For more information about the chrome control, see How to: Use the client chrome control in apps for SharePoint.
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 and the package of an app for SharePoint.
SharePoint 2013 introduces a new app permissions and security system.
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 App 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 apps in SharePoint 2013.
If your app for SharePoint requires the presence of some SharePoint Feature or service, you must register this dependency in the app manifest file. For more information about how to do this, see Register app dependencies in SharePoint 2013.
The lifecycle for an app for SharePoint includes publishing, installing, upgrading, and uninstalling. For more information about these subjects, see Publish apps for SharePoint, Deploying and installing apps for SharePoint: methods and options and App for SharePoint 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 apps for SharePoint.
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 apps for SharePoint and Data access options for apps in SharePoint 2013.
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.
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.