Switch from SharePoint 2010 solutions to apps for SharePoint

apps for SharePoint

This article provides guidance for the SharePoint 2010 developer to start developing apps in SharePoint 2013. You can use this guidance to identify and weigh considerations for developing apps that meet user needs.

This article is for SharePoint 2010 developers who want to understand app development for SharePoint 2013 and how to start developing apps. It assumes knowledge of what SharePoint is and some experience developing SharePoint 2010 extensions.

This article is not a deep exploration of developing apps in SharePoint 2013. It is meant to help you understand what is possible with apps for SharePoint, how you can assemble apps, and some considerations for developing them.

After reading this article, you, as a SharePoint 2010 solution developer, should have the information you need to decide which SharePoint 2013 options make the most sense for the app you have in mind.

SharePoint 2013 provides several options for developing apps, including standard web technologies such as JavaScript and OAuth. SharePoint also offers many hosting options and functionality to interact with SharePoint resources.

One of the most striking differences between SharePoint 2010 extensions and apps for SharePoint is that apps for SharePoint don’t use a server object model, nor do they use custom code that runs on the SharePoint server. All custom code components reside either in the expanded client object model or in cloud-hosted application servers.

The various SharePoint 2013 development models provide options to build apps that can be run in the cloud instead of in a SharePoint farm. These flexible development models, along with the integration of standard web technologies, make SharePoint development work more like other kinds of web development that you may already be doing.

An app for SharePoint can have SharePoint components, remote components, or both. The types of components and the locations where they are hosted (not necessarily where they run) determine whether they require any configuration and whether they require a trust system (implementation of trust levels).

Apps that don’t need a trust system

The two types of apps that don’t require a trust system are apps that use only SharePoint 2013 components, and apps that use no SharePoint 2013 components or features.

  • SharePoint-only apps contain only SharePoint components in an app web, so they do not require configuration of trust settings. It’s important to know the difference between host webs and app webs. The app web is an isolated SharePoint 2013 subsite; the app web parent site is known as the host web. Even though you do not need to configure trust settings, you still need to set permissions. (For more information, see App permissions later in this article.) The ability to install and run SharePoint-only apps depends on the users’ login credentials.

  • SharePoint-surfaced apps are business web apps that SharePoint makes available to users as a convenience. Users can start these apps from app tiles within SharePoint, but the apps don’t use SharePoint features. They may contain app parts and custom actions, but they don’t have SharePoint components or app webs, and they don’t access the host web. Trust and permissions are not applicable because these apps do not interact with SharePoint.

Apps that need a trust system

Apps that use a mix of SharePoint and remote components require that a trust system be in place.

  • Remote-only apps that have only components that are not from SharePoint are not really apps for SharePoint. They are mentioned here because they can gain access to SharePoint data through the Representational State Transfer (REST) API and therefore require use of a trust system. However, remote-only apps are not discussed further in this article.

  • Mixed apps for SharePoint contain SharePoint components and remote components, and they can be categorized by the following criteria:

    • Where the remote components are hosted.

    • Where components are installed, either in SharePoint Online or in an on-premises SharePoint farm. SharePoint components are always hosted in the same site collection as where the app is installed, so you can think of this criterion as "where the SharePoint components are hosted."

    • The trust system used for remote components to authorize to SharePoint.

For mixed apps, there are three potential ways you can set up how and where components are deployed:

  • All on-premises: The app is installed only in SharePoint on-premises instances. SharePoint and remote components are all on-premises. The trust system can be called high-trust, which means the trust broker is also on-premises. In other words, the SharePoint server farm could be disconnected from the Internet without affecting the way the app functions.

  • All-cloud: The app (and the app web) is installed only in SharePoint Online. Remote components are also in the cloud. The trust system is OAuth, and the trust broker is Microsoft Azure Active Directory Access Control. Nothing is on-premises.

    Some apps in this category are eligible for automatic provisioning in Office 365. An app can be automatically provisioned only if the database in the app is a Microsoft Azure SQL Database and the web applications or services can be hosted in Azure Web Sites.

  • Cross-hosted: The app is partly in the cloud and partly on-premises. At least one of the following elements is on-premises and at least one is in the cloud:

    • SharePoint components

    • Remote components

    • Trust broker, if any

Trust level refers to permissions that govern what actions an application can or cannot perform. Because not all apps require a fully trusted environment to operate, Microsoft offers you the ability to establish different levels of trust for the apps you develop for SharePoint 2013.

Using OAuth

Apps can use an authentication provider to act as a common authentication broker between SharePoint and the app. These apps use Microsoft Azure Active Directory Access Control service and they require users to have access to an Office 365site (usually through a subscription to Office 365).

When users start one of these apps, SharePoint requests a context token from Access Control and sends it to the app. The app then uses this context token to request an access token from Access Control. After the app receives the access token, the app uses this token to communicate with SharePoint.

SharePoint uses the OAuth authorization code flow (grant type) to delegate limited rights to apps to act on behalf of users. Granting rights means giving a user or group the right to access all secured objects within the web application, regardless of local permissions for the object. By defining a grant type, you can assign users access levels such as read, write, manage, and full control. For this approach to work, both SharePoint and the client app (the app for SharePoint) must trust and communicate with an authentication provider. SharePoint relies on Microsoft Azure Active Directory, which in turn must be aware of SharePoint and the client app to grant them the necessary code and tokens to work together.

Using server-to-server protocol (high-trust apps)

High-trust apps for SharePoint are built to be used on-premises and not in a cloud-hosted environment. High-trust is not the same as full trust—a high-trust app still must request app permissions. The app is considered high-trust because it is trusted to use any user identity that it needs. The app is responsible for creating the user portion of the access token.

In SharePoint 2013, the server-to-server security token service (STS) extends OAuth and provides access tokens for server-to-server authentication. This provision enables temporary tokens for gaining access to other app services such as Exchange 2013, Lync 2013, and other apps for SharePoint. A trust relationship is then established between these apps and services through a certificate. High-trust apps are unique because they have both the trust broker and the app on-premises, and use a certificate instead of a token to establish the trust relationship. The SharePoint server farm could be disconnected from the Internet without affecting the way the app functions.

Using the SharePoint cross-domain library

The cross-domain library is a client-side alternative provided by a JavaScript file (SP.RequestExecutor.js) that developers can refer to from a remote app. It is hosted on a SharePoint website, and it can interact with more than one domain in the remote app page through a proxy. Using the cross-domain library is a good choice in the following scenarios:

The SharePoint cross-domain library uses a hidden inline frame (IFrame) and a client-side proxy page that is hosted in SharePoint to enable client-side communication through JavaScript. It receives authorization cookies in the remote page and loads the proxy page successfully.

Figure 1. Functionality of the cross-domain library

The SharePoint cross-domain library uses an IFrame and a proxy page to make calls across domains.

Summary of approaches for setting trust level

The approach we recommend for setting trust level is based on the location of application components as shown in Table 1.

Table 1. Trust systems for mixed apps for SharePoint

SharePoint component location

Remote component location

Trust system

On-premises

On-premises

SharePoint server-to-server STS (OAuth) and certificate
-or-
OAuth + Microsoft Azure AD Access Control

On-premises

In-cloud

SharePoint server-to-server STS (OAuth) and certificate
-or-
OAuth + Microsoft Azure AD Access Control

In-cloud (SharePoint Online)

In-cloud

OAuth + Microsoft Azure AD Access Control

In-cloud (SharePoint Online)

On-premises and outside firewall

OAuth + Microsoft Azure AD Access Control
-or-
Cross-domain library

In-cloud (SharePoint Online)

On-premises and inside firewall

Cross-domain library

Apps for SharePoint are often classified based on the configuration effort needed to deploy the application. The SharePoint 2013 development model allows for the following deployment patterns:

  • SharePoint-hosted

  • Provider-hosted

  • Microsoft Azure auto-provisioned (autohosted)

Often, provider-hosted and autohosted are considered cloud-based deployment patterns. For more information, see Choose patterns for developing and hosting your app for SharePoint on MSDN.

SharePoint-hosted app deployment pattern

Apps hosted in SharePoint are the same as the SharePoint-only apps discussed earlier in this article. SharePoint-hosted apps include only declarative components such as HTML and JavaScript files, and they are installed in the customer's own SharePoint Online tenancy or in the customer’s on-premises SharePoint farm.

Hosting apps in SharePoint enables reuse of common SharePoint artifacts such as lists and Web Parts. When you follow this deployment pattern, you are limited to using only client-side scripting and you cannot use any server-side code.

SharePoint-hosted apps for SharePoint are installed on an isolated SharePoint 2013 subsite called the app web; the app web parent site is known as the host web.

Provider-hosted app deployment pattern

Apps hosted by the provider require configuration by the person deploying the app (the app’s provider). This configuration includes the trust system described earlier. These apps also include the SharePoint-surfaced apps and remote-only apps discussed earlier in this article, in addition to most of the mixed apps (including all on-premises apps, most of the all-cloud apps, and all cross-hosted apps, also discussed earlier). You can use provider-hosted apps in both on-premises environments and cloud environments.

Provider-hosted apps for SharePoint can include components that are deployed and hosted outside of the web app hosting environment, usually by the developer, but in some scenarios by the end user. This type of provider-hosted app for SharePoint interacts with a SharePoint 2013 site but also uses resources and services that reside on the remote site.

When you use provider-hosted apps that contain remote components and services, you must provide a packaging, installation, and configuration system for the remote components.

Within the category of provider-hosted apps for SharePoint, there are important architectural differences between apps for SharePoint that have remote components installed outside the on-premises firewall of the SharePoint farm where the app is installed, and apps for SharePoint that have remote components installed within the firewall. The different trust systems used are covered earlier in this article.

In addition, the remote components inside the firewall can use either the SharePoint client object model (CSOM) or SharePoint REST endpoints to interact with your SharePoint environment and content. For remote components that are outside the firewall app, you can use SharePoint REST endpoints because they can be supported from any development language.

Autohosted app deployment pattern

Autohosted apps for SharePoint are hosted on Azure Web Sites and are mentioned earlier as a special type of all-cloud app that has automatic provisioning. The biggest difference is that these apps are not provider-hosted, meaning you do not need to provide a packaging, installation, and configuration system.

Autohosted apps are installed in a host web within the customer's SharePoint Online tenancy, where components are installed automatically in a Azure Web Sites account. The Azure Web Sites infrastructure manages isolation of tenancies. When an autohosted app is deployed for SharePoint, all Microsoft Azure and Microsoft Azure SQL Database components are provisioned for you when the app for SharePoint is installed. Each installation of the app provisions its own website in Microsoft Azure Web Sites.

Autohostedapps for SharePoint interact with a SharePoint 2013 website, but they also use resources and services that reside on a remote site that is hosted by Azure Web Sites infrastructure.

Language and API considerations

The SharePoint 2013 development model supports three deployment patterns and two client APIs through two languages—meaning that there are twelve permutations of language, API, and deployment options. Some of these combinations must be used when cross-domain support is required, others are good choices if cross-domain support is not required, and two cannot be used. Table 2 shows these combinations.

Table 2. Possible combinations of deployment and APIs for apps for SharePoint

Language

API

Provider-hosted

Autohosted

SharePoint-hosted

Javascript

CSOM

Use when cross-domain support is required

Use when cross-domain support is required

Excellent choice

Javascript

REST

Use when cross-domain support is required

Use when cross-domain support is required

Excellent choice

C#

CSOM

Excellent choice

Excellent choice

Not possible

C#

REST

Good choice

Good choice

Not possible

Patterns for accessing data

When you develop apps for SharePoint you have three options for storing and retrieving data.

  • SharePoint data on the app web.

  • SharePoint data on the host web.

  • External data

The most significant high-level design consideration is whether the data you need to use is stored in SharePoint (on either the host web or the app web) or externally. Table 4 shows that the key differences between externally stored data and data stored in SharePoint relate to the resources that you need to use in order to get access.

Table 3. Comparison of access to data stored externally and in SharePoint

Data source

Data access

App component location

App components

Hosting options

Key resources

Examples

Security considerations

Use cases

External

CRUD

App web

Host web

App parts

Immersive apps

SharePoint-hosted

Provider-hosted

Autohosted

Web proxy

BCS (The BCS model is tied to the app itself and is not reusable.)

Remote event receivers

WCF service

REST

SharePoint 2013: Access an external list with REST

SharePoint 2013: Create an external content type that supports notifications

SharePoint 2013: Create multiple external lists with associations

SharePoint 2013: Create external lists based on app-scoped external content type

App-scoped external content types in SharePoint 2013

Data might be stored behind a firewall.

External data source may require additional authentication.

External data authentication requirements may determine your options.

Stock ticker

RSS reader

LOB app integration

Data across SharePoint farms

Dashboard reporting data from business intelligence solutions

SharePoint

CRUD

App web

Host web

App parts

Immersive apps

SharePoint-hosted

Provider-hosted

Autohosted

OAuth + Microsoft Azure AD Access Control
-or-
Cross-domain library

CSOM or JSOM

REST

SharePoint 2013: Perform basic data access operations by using CSOM in apps

SharePoint 2013: Perform basic data access operations by using REST in apps

How to: Access SharePoint 2013 data from apps using the cross-domain library

App and data share the same security model.

  • Integrate SharePoint list data into business processes:

    • Meeting schedule

    • Contract tracking

    • HR interview process

    • Custom list view app

  • Business application based on existing document library:

    • Training management

    • Project management

  • Site inventory dashboard

  • Site map

  • Interact with SharePoint search results

  • Interact with SharePoint user profile information (people directory)

You can use SharePoint data stored on both the app web and the host web. If your app has permission to use data at the tenant level, you can access host web data stored across site collections. Table 4 shows that the key differences between using data on the app web and the host web relate to the design and lifecycle management of your app.

Table 4. Comparison of access to data stored on the app web and the host web

Data source

App components

Hosting options

Known limitations

Design considerations

Implementation

App web

App parts

Immersive apps

SharePoint-hosted

Provider-hosted

Autohosted

The app and the data are tied together on the app web. Removing the app also removes the data associated with the app.

The app is the exclusive user of the data.

The app and the data share the same life cycle.

Communication happens at the browser level because you are always using code that runs on the client (JSOM or cross-domain library).

Create data either declaratively or imperatively.

Host web

App parts

Immersive apps

Remote event receivers

SharePoint-hosted

Provider-hosted

Autohosted

You must use the app uninstall event to remove any data, if necessary.

Provision lists and other SharePoint objects with code by using the app install event.

You need appropriate host web permissions to create data on the host web.

Use the host web URL to get client context.

Host web across site collections

App parts

Immersive apps

Remote event receivers

SharePoint-hosted

Provider-hosted

Autohosted

The cross-domain library is allowed to make calls across site collections if and only if the app is installed as a tenant-scoped app from the app catalog.

Option 1: Deploy a app for SharePoint app that has tenant-level permissions.

Option 2: Deploy a provider-hosted app that has tenant-level permissions and that gets the correct client context from the host web URL.

A tenant admin must install the app.

Use the host web URL to get client context.

Design considerations

You must choose the hosting model for an app on the basis of differences shown in Table 5.

Table 5. Comparison of hosting options for apps for SharePoint

SharePoint-hosted

Cloud (provider-hosted or autohosted)

App scope

SharePoint site

Site or tenancy

Architecture

Website

Multitenant app

Developer skill set

SharePoint + HTML or JavaScript

Full stack

User interface technologies

SharePoint + HTML or JavaScript

Any web stack

Server code

None

Any (none on SharePoint)

Storage

Lists and document libraries

Any

Key limitations

No server code

Hosting expertise required

Factors that affect hosting choice:

  • Cloud-hosted apps: This approach offers the flexibility to choose hosting and technology options. The use of cloud-hosted apps may require management of hosting, app permissions, and multitenancy.

  • SharePoint-hosted apps: We recommend this approach for smaller apps and storage of resources. Because all of the components in the apps are completely hosted in SharePoint on the premises or online, no server-side code is required. You get the benefit of multitenancy and isolation out of the box.

This section discusses additional considerations and information about apps for SharePoint that you can apply to your planning for app development.

App identity

Authenticated identities in SharePoint 2013 determine which authorization policy is used. The authenticated identities can be user identity only, user plus app identities, or app identity only.

  • User-only policy: The authorization policy applied in SharePoint 2010.

  • User + app policy: Authorization checks take into account both the user identity and the app identity.

  • App-only policy: Content database authorization checks take into account only the app identity. The content database is the repository of information required by the app.

App permissions

An app for SharePoint uses permission requests to specify the permissions that it needs to function correctly. Permission requests specify both the rights that an app needs and the scope at which it needs the rights. You request these permissions as part of the app definition.

App rights

You use app rights for SharePoint 2013 to specify the level of rights that allows users to perform actions against the app. SharePoint 2013 supports four levels of rights in the content database:

  • Read-only

  • Write

  • Manage

  • Full control

App scopes

An app for SharePoint uses app permission request scopes and permission requests to specify the level at which the app is intended to run, and the permission level that is assigned to the app. The app permission request scope indicates the location within the SharePoint 2013 hierarchy where a permission request will apply. (See Plan app permissions management in SharePoint 2013 and Manage permissions for a Web application for more information.) SharePoint 2013 supports the following permission request scopes:

  • SPSite: Defines the scope as a SharePoint site collection.

  • SPWeb: Defines the scope as a SharePoint website.

  • SPList: Defines the scope as a SharePoint list.

  • Tenancy: Defines the scope as a SharePoint tenancy.

Additionally, there are scopes for actions such as performing search queries, accessing taxonomy data, and editing user profiles.

Other solution types

With the flexibility that SharePoint 2013 offers for application development and deployment, you can incorporate many other types of solutions by using cloud-based apps for SharePoint. Mashups that use combinations of SharePoint elements also are possible. Table 6 shows some of these technologies mapped to the patterns for deploying your app for SharePoint. This table is not meant to be an exhaustive list, but rather an introduction to a world of possibilities.

Table 6. Compatibility of apps for SharePoint deployment options and other solution types

SharePoint-hosted

Provider-hosted

Autohosted

App for SharePoint

YES

YES

YES

Web Part

NO

YES

YES

ASP.NET web app

NO

YES

YES

HTML or JavaScript app

YES

NO

NO

LAMP web app

NO

YES

NO

Windows PowerShell script

NO

YES

YES

Event receiver

NO

YES

YES

App for Office

NO

YES

YES

This section provides code examples for each of the deployment models for apps for SharePoint. You can reuse these samples in developing your apps.

SharePoint-hosted app

A SharePoint-hosted app is the easiest type of app for SharePoint 2013 that you can create and deploy. Its contents are deployed to a single SharePoint site, and it contains only SharePoint components—so it does not require trust or permissions settings.

In the following code example, the app retrieves a count of the number of lists on the current SPWeb object and the current user. It also populates elements in the Default.aspx file with the information that it retrieves.

var ctx;
var web;
var user;

function sharePointReady() {
    ctx = new SP.ClientContext.get_current();

    $("#getListCount").click(function (event) {
        getWebProperties();
        event.preventDefault();
    });
    welcome();
}


function welcome() {
    web = ctx.get_web();
    user = web.get_currentUser();
    ctx.load(user);

    ctx.executeQueryAsync(onUserReqSuccess, onUserReqFail);
}

function onUserReqSuccess() {
    var welcomeText = document.getElementById("starter");
    var userWelcome = document.createElement("p");
    userWelcome.style.fontSize = "14pt";
    userWelcome.innerText = "Welcome " + user.get_loginName() + ".";
    welcomeText.appendChild(userWelcome);
}

function onUserReqFail(sender, args) {
    alert('Failed to find current user. ' + args.get_message());
}


function getWebProperties() {
    web = ctx.get_web();
    lists = this.web.get_lists();
    ctx.load(this.lists);
    ctx.executeQueryAsync(Function.createDelegate(this, this.onSuccess), Function.createDelegate(this, this.onFail));
}

function onSuccess(sender, args) {
    alert('Number of lists in web:' + this.lists.get_count());
}

function onFail(sender, args) {
    alert('failed to get list. Error:' + args.get_message());

Provider-hosted app and autohosted app

A provider-hostedapp for SharePoint consists of both an app for SharePoint that is deployed directly to a SharePoint 2013 site and a separately deployed web app. Because the app contains SharePoint components and other types of components, it requires additional trust settings such as Microsoft Azure Active Directory Access Control for low-trust apps and certificates for high-trust apps.

An autohosted app for SharePoint contains at least one website deployed from Azure Web Sites that can be started from a SharePoint 2013 host web, and it also may include SharePoint components in an app web and a SQL Server database. Autohosted apps are a kind of provider-hosted app in which the web app and database are hosted on in Azure Web Sites, so in these apps, Microsoft Azure Active Directory Access Control acts as the trust broker.

The following code example uses methods in the TokenHelper.cs file to retrieve context from the Request object and obtain an access token from Microsoft Azure Active Directory Access Control. The RetrieveWithCSOM method uses the SharePoint CSOM to retrieve information about your site and display it on the page.

public partial class Default : System.Web.UI.Page
    {
        SharePointContextToken contextToken;
        string accessToken;
        Uri sharepointUrl;
        string siteName;
        string currentUser;
        List<string> listOfUsers = new List<string>();
        List<string> listOfLists = new List<string>();

        // The Page_load method fetches the context token and the access token. 
        // The access token is used by all of the data retrieval methods.
        protected void Page_Load(object sender, EventArgs e)
        {

     
            TokenHelper.TrustAllCertificates();
            string contextTokenString = TokenHelper.GetContextTokenFromRequest(Request);

            if (contextTokenString != null)
            {
                contextToken =
                    TokenHelper.ReadAndValidateContextToken(contextTokenString, Request.Url.Authority);

                sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);
                accessToken =
                    TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority).AccessToken;
                CSOM.CommandArgument = accessToken;

            }
            else if (!IsPostBack)
            {
                Response.Write("Could not find a context token.");
                return;
            }
        }

        // This method retrieves information about the host web by using the CSOM.
        private void RetrieveWithCSOM(string accessToken)
        {

            if (IsPostBack)
            {
                sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);
            }
            

            ClientContext clientContext =
                    TokenHelper.GetClientContextWithAccessToken(
                        sharepointUrl.ToString(), accessToken);


            // Load the properties for the web object.
            Web web = clientContext.Web;
            clientContext.Load(web);
            clientContext.ExecuteQuery();

            // Get the site name.
            siteName = web.Title;

            // Get the current user.
            clientContext.Load(web.CurrentUser);
            clientContext.ExecuteQuery();
            currentUser = clientContext.Web.CurrentUser.LoginName;

            // Load the lists from the Web object.
            ListCollection lists = web.Lists;
            clientContext.Load<ListCollection>(lists);
            clientContext.ExecuteQuery();

            // Load the current users from the Web object.
            UserCollection users = web.SiteUsers;
            clientContext.Load<UserCollection>(users);
            clientContext.ExecuteQuery();

            foreach (User siteUser in users)
            {
                listOfUsers.Add(siteUser.LoginName);
            }


            foreach (List list in lists)
            {
                listOfLists.Add(list.Title);
            }
        }


        protected void CSOM_Click(object sender, EventArgs e)
        {
            string commandAccessToken = ((LinkButton)sender).CommandArgument;
            RetrieveWithCSOM(commandAccessToken);
            WebTitleLabel.Text = siteName;
            CurrentUserLabel.Text = currentUser;
            UserList.DataSource = listOfUsers;
            UserList.DataBind();
            ListList.DataSource = listOfLists;
            ListList.DataBind();
    
        }

    }

SharePoint 2013 provides a strong development platform for building solutions and apps. With the development approach and app framework in SharePoint 2013, you can create apps that surface SharePoint components and remote components. By supporting standards-based technologies such as HTML5, JavaScript, and OAuth, SharePoint 2013 offers a unified development experience.

As a developer, you can make intelligent architecture and coding choices that address different requirements and needs, from among the many options that the SharePoint 2013 platform provides for app hosting models, app patterns, and app design approaches.

Show:
© 2014 Microsoft