All about SharePoint Add Ins. The must have reference guide for SharePoint Add In development

Senthil Kumaresan
 
SharePoint Consultant
January 19, 2016
 
Rate this article
 
Views
15105

There has been a lot of information on the internet about Add-ins for SharePoint and the information has been complex to understand for developers who migrate from the traditional .Net based Farm/Sandbox solutions to Add-ins for SharePoint. So I thought of creating a simple table that covers most of the high level information related to the add-ins (SharePoint Hosted and Provider Hosted) for SharePoint.

Before we dive into reviewing the table, below is a simple explanation about the 2 different add-in Models that can be deployed to a SharePoint On-Premise farm or O365 SharePoint Online tenant.

1. A SharePoint hosted Add-in runs only in the client from the browser.

2. A Provider hosted Add-in runs from the client browser and includes at least one remote component that runs on a cloud or internal server.

Add-in Model

SharePoint Hosted Add-in

Provider Hosted Add-in

EnvironmentSharePoint On-PremiseOffice365SharePoint On-PremiseOffice365
Add-in Types that can be builtSingle Page Add-in

Add-in Part

Custom Actions

Single Page Add-in
Web Technologies used to develop an Add-inHTML, JavaScript, ODataHTML, JavaScript, OData, C#, Asp.Net., PHP or any web technologies
SharePoint Data Access Api and InterfacesJSOM

REST

.Net Client Side Managed Code

JSOM

REST

Add-In Project StructureAdd-In Project Component which gets deployed to Add-in WebAdd-in Project which gets to deployed to Add-in Web

Web Project which gets deployed remotely from a SharePoint instance and developed using ASP.Net, PHP or any web technologies.

Add-in Code StoreAdd-in Code and components are stored in SharePoint Content Database as they primarily run JavaScript on pagesAdd-In Components

SharePoint Content Database

Remote Components

· Azure Web Server with Azure Control Services (ACS) trust for exchanging access tokens.

· Dedicated Web Server with .Net language based Remote Components to SharePoint Server trust using Self Signed Certificate.

· Dedicated Web Server with Non-.Net language based Remote Components to SharePoint Server trust using Azure Control Services.

Add-in Components

SharePoint Content Database

Remote Components

· Azure Web Server with Azure Control Services (ACS) trust to O365.

· Dedicated Web Server (.Net/Non-.Net) with ACS trust to O365

Dependent Service ApplicationsTurn on App Management Service Application

Turn on Microsoft SharePoint foundation subscription settings service

Available by defaultTurn on App Management Service Application

Turn on Microsoft SharePoint foundation subscription settings service

Available by default
Add-in Deployment ScopeHow do you want to distribute an add-in to users in your organizations farm depends upon the deployment scope.

Web Scope -> Deployed to all webs and available for users to add the add-in to their site when needed from the Add-in Catalog

Tenancy Scope -> Batch installed to all webs in tenancy by a tenant admin from the Add-in Catalog

Add-in Deployment StructureWhen an Add-in is installed by web scope on the Site (Host Web), a sub site (Add-in Web) is created under the Site and the code is deployed to sub site (Add-in Web) under the site (Host Web).

When an Add-in is batch installed in a tenancy scope it only creates one Add-in web in the App Catalog

The sub site(Add-in Web) created will have a different domain name which will be unique compared to any other Add-in web in the farm. The domain name is constructed with the Pre-configured AppPrefix, App Base Domain value set in the farm’s App Management Service Application.

Ex. https:// Add-in_PrefixAdd-in_ID. Add-in_Base_Domain / Domain_Relative_URL_of_Host_Web / Add-in_Name

Single Page App code will be deployed to Add-in Web.

App Part UI Components will be deployed to Host web

Custom Actions UI Components will be deployed to Host Web

A Single Page Add-in runs the code from an Add-in Web and gets access to the List/Libraries in Parent Site(Host Web) via permissions defined in AppManifest.xml part of the App project.

1. When an Add-in is installed by web scope on the Site (Host Web), a sub site (Add-in Web) is created under the Site and the code is deployed to sub site (Add-in Web) under the site (Host Web).

2. When an Add-in is batch installed in a tenancy scope it only creates one Add-in web in the App Catalog

3. Add-in code runs completely off the SharePoint server.

4. Remote Component of Add-in can be run from an IIS server in the Cloud servers like Windows Azure which is completely off the SharePoint Server.

5. There is also an optional way of deploying App Code to Add-in Web when we have SharePoint components like List/Libraries to be provisioned.

6. The sub site(Add-in Web) created will have a different domain name which will be unique compared to any other Add-in web in the farm. The domain name is constructed with the Pre-configured AppPrefix, App Base Domain in the farm’s App Management Service application.

Ex. https:// Add-in_PrefixAdd-in_ID . Add-in_Base_Domain / Domain_Relative_URL_of_Host_Web / Add-in_Name

Add-in PermissionsAn Add-in is an entity like a user or a group for SharePoint and will need permissions to access resource in SharePoint.

By default the add-in has Full control permission for the Add-in Web and no permissions on the Host web.

To access resources in Host Web, an AppManifest.xml file which is part of the Add-in project is used by developer to define permissions required on the SharePoint resources (List/Library) available in the HostWeb.

User who adds the add-in to SharePoint site must grant permissions to all the permission requests defined by the developer.

Ex. <AppPermissionRequests AllowAppOnlyPolicy="false">

<AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="FullControl" />

</AppPermissionRequests>

The Scope of permissions can be applied to a Tenant, Site Collection, Website and List. When add-in gets permission on a scope, then the add-in will get the same permission right on all children objects of the scope.

The Rights is not same as user rights defined in SharePoint. It has different levels of rights. Please follow the link to know more.

After an Add-in is installed with developer defined permissions, an admin can further modify the permissions of an add-in on the web site by using the below URL

http://<SharePointWebSite>/_layouts/15/AppInv.aspx

Authorization policies for Add-in to access SharePoint resources1. App Policy + User Policy (Uses authorization information from AppManifest.xml and the permissions the users has on the SharePoint resources)

App only policy cannot be used in SharePoint hosted add-in as they only use JavaScript and runs in the context of user.

The policy is defined by the developer in the AppManifest.xml when configuring permission request for accessing resources in HostWeb.

Ex. <AppPermissionRequests AllowAppOnlyPolicy="false">

<AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="FullControl" />

</AppPermissionRequests>

1. App only Policy(Uses authorization information defined in appmanifest.xml)

2. App Policy + User Policy(Uses authorization information from AppManifest.xml and the permissions the users has on the SharePoint resources)

Provider Hosted Add-in remote component’s authorization to SharePoint ResourcesNot ApplicableNot ApplicableHigh Trust Add-ins:

For Remote component of an Add-in to access SharePoint Resources on behalf of an Add-in or User that runs in remote server hosted in company’s’ intranet you need to create a trust between the Remote Component and SharePoint. To have SharePoint Trust calls from the remote component, A Digital Certificate trust between servers running SharePoint On-Premise and the Remote Web App in the company’s intranet has to be created. Add-ins that work with the Certificate based trust are called High Trust Add-ins

Low-Trust Add-ins:

Only For Add-ins that have its remote components hosted in a cloud environment like Azure.

OAuth protocol is used for authorizing requests for Remote code to access SharePoint resources.

OAuth Trust to be created between On Premise SharePoint Farm and Azure Server by using Azure ACS if remote components run on Azure or any Cloud Servers. These Add-ins that use OAuth for authorizing remote code to access SharePoint resources are called Low Trust Add-ins

JavaScript Cross Domain Library:

– This is used when you use a remote component that uses only JavaScript/JSOM.

– Only Works on HTML5 supported Browsers

– Uses an In-built proxy page under the Layouts folder to support cross domain calls.

Low Trust Add-in:

OAuth protocol is used for authorizing requests from Remote Server to O365. OAuth is implemented using Azure Control Services.

Office365 has Preconfigured Trust with Azure Control Services to use OAuth for authorizing app to use content in O365 Sites.

A remote app has to use Azure Control Services to get authorized by the O365.

JavaScript Cross Domain Library:

– This is used when you use a JavaScript only remote component

– Only Works on HTML5 supported Browsers

– Uses an In-built proxy page under the Layouts folder to support cross domain calls.

Access SharePoint Data from Add-in/Remote ComponentSingle Page add-in code runs from a Sub-site (Add-in Web) and will have a different domain name from its Parent Site (Host Web). Since the code runs in from the Add-in web, In order to access objects of HostWeb from the Add-in Web you will have to use a special library called JavaScript Cross Domain Library (SPRequestExecutor.js) to overcome Same-Origin Policy enforced in browsers.

JavaScript Cross Domain Library:

– Only Works on HTML5 supported Browsers

– Uses an In-built proxy page under the Layouts folder to support cross domain calls.

-Call Rest interface or use JSOM

Use JavaScript Cross Domain library to access data from Host web/Add-in Web or other SharePoint site when your remote component running on remote server uses only Javascript/JSOM.

You cannot use JavaScript Cross Domain Library if you are using .Net Managed CSOM in remote components.

Remote Pages which uses .Net Managed CSOM to access content is add-in web and host web can utilize the TokenHelper.cs class to request access token from either S2S(High Trust) or ACS(Low Trust) for authenticating the code executing in the remote component. A Special Configuration has to be done as explained in the link

Use Remote Event Receivers:

Host Web’s List, List item and Add-in events can trigger a call to remote Web Service components from where you can access back SharePoint resources via .Net CSOM. JavaScript cannot be used in the remote web services.

Use OAuth with Azure Control Services when

  • Non-.Net Language used for Remote Components.
  • Azure Hosting environment used for Remote Components
  • Add-in needs to use App-only Policy.
  • Add-in needs to act on behalf of a user other than the one who is logged on.
  • Add-in needs to perform operations even when the user is not logged on.

 

Use JavaScript Cross Domain Library when you use JavaScript/JSOM on Remote Pages to access content is add-in web and host web.

 

Use OAuth with Azure Control Services when

  • Add-in needs to use App-only Policy.
  • Add-in needs to act on behalf of a user other than the one who is logged on.
  • Add-in needs to perform operations even when the user is not logged on.
Access External Data from Add-in Component hosted in SharePointUse SharePoint Web Proxy

To Access external data from your Add-in Code, you can use the SharePoint web proxy class (SP.WebProxy.invoke) available in JSOM and .Net Managed Code.

Your external data might be from a different domain and to overcome the cross domain issue, you will have to use the SharePoint web proxy so the call to the external remote service happens at the server level.

When you use the web proxy method, you issue the initial request to SharePoint via the web proxy class and in turn, SharePoint requests the data to the specified endpoint and forwards the response back to your page.

For more info check the link

Use SharePoint Web Proxy

To Access external data from your Add-in Code, you can use the SharePoint web proxy class (SP.WebProxy.invoke) available in JSOM and .Net Managed Code.

Your external data might be from a different domain and to overcome the cross domain issue, you will have to use the SharePoint web proxy so the call to the external remote service happens at the server level.

When you use the web proxy method, you issue the initial request to SharePoint via the web proxy class and in turn, SharePoint requests the data to the specified endpoint and forwards the response back to your page.

For more info check the link

Use Cross Domain Library with Custom Proxy page in Remote Application

From an Add-in Component page if you want to access data from the Remote app then you will have to create a similar proxy page and host it part of your remote app Component. To create a custom proxy page in your remote component check the link.

Use External Content Types

Use external content types when you want to access external data like SAP using Business Connectivity Services that support OData format

Add-in Event ReceiversNAThe Add-in Event Receivers are triggered when an add-in is installed, Uninstalled or upgraded. This is similar to a Remote Event Receiever with some minor differences. The trigger will call a Remote Web Service and in turn you can code other operations from the trusted remote component.

1. Add-in Installed

2. Add-in Uninstalling

3. Add-in Upgrading

  • Update Host Web Components
  • Update Add-in Web components
  • Update Remote components
Registering Add-in DependenciesIf your Add-in for SharePoint requires the presence of some SharePoint Feature or service, you must register this dependency in the add-in manifest file.

This helps to block installation if the required dependencies are not available in the site or activated them

Ex. <AppPrerequisites>

<AppPrerequisite Type=”Capability” ID=”{CDD8F991-B459-4512-8048-03D5A03FF27E}” MinimumVersion=”15.0.0.0” />

</ AppPrerequisites>

There are 3 types of Prerequisite

1. Feature -> Feature that need to be activated on the Add-in Web. ID is the feature Guid

2. Capability -> Set of Features and Services that is required to be available on the Add-in Web. ID is a list of services available in SharePoint. Refer Link

Publishing Add-insAn add-in can be published any of below two places.

1. Office Store

You would need to sign up for a seller account in order to publish the add-in to the office store. Since this will be publicly available, any SharePoint farm admin can install the add-in from the office store.

2. Organizations Add-in Catalog

Upload the add-in package and publish it in the Add-in Catalog to have the add-in available to all users within your SharePoint Farm.

Registering Remote components of Add-ins on SharePointNot ApplicableNot ApplicableFor an external app code to communicate with SharePoint, it needs to be registered with SharePoint.

To Register an external app with SharePoint, you need to create an app identity. Create an app identity by generating Client ID and Client Secret. Use the steps below to create the app identity based on the 2 app hosting options:

  • For App Catalog
    • To create the app identity, navigate to http://<AnySiteUrlinFarmorO365Tenancy>/_layouts/15/AppRegNew.aspx on the O365 tenancy or On-Premise farm. The Client Secret in the app identity has an expiration and it expires in 1 year. It needs to be renewed.
  • For Office Store
    • Use Seller Dashboard to create an account and generate the Client ID and Client Secret. The Client Secret expiration in the app identity can be configurable to a maximum of 3 years.

    After generating the ClientID and Client Secret from AppRegNew.aspx or Seller Dashboard update it in the Web.config of the remote web project and AppManifest.xml of your Provider hosted add-in project.

    Ex. 1. AppManifest.Xm in Add-in:

    <AppPrincipal>

    <RemoteWebApplication ClientId="2becf626-7fe1-4ba9-b839-ce3502e4e0b0" />

    </AppPrincipal>

    2. Web.Config in Remote Component:

    <appSettings>

    <add key="ClientId" value="<ClientId value>" />

    <add key="ClientSecret" value="<ClientSecret value>" />

    </appSettings>

    To lookup Add-in registration information, you can use the link http://<AnySiteUrlinFarmorO365Tenancy>/_layouts/15/AppInv.aspx link

Add-in StaplingAdd-in stapling is a process of enabling an add-in to be available to a subset of sites by an Administrator from the Organization’s Add-in Catalog.

Add-in can be stapled to one of the below items

  • Site Collection – Add-in will be available in all sites of the site collection to which it is stapled.
  • Managed Path – Add-in will be available in all sites under all site collections created under the managed path selected.
  • Site Template – Add-in will be available in all sites created with the stapled site template.

Upload and Install an Add-in to AppCatalog site. From the Site Contents of the App Catalog site deploy the app to criteria based on Site Collection, Managed Paths and Site Templates.

This centralized deployment also share the same centralized add-in resources (Add-in Web and Remote Web) available for the Add-in in the Add-in Catalog site. Essentially, the add-in will be deployed, but not installed in the sites. All sites will leverage the Add-in Web and Remote Web from the instance installed in the App Catalog.

The Add-in deployed by this method cannot be removed by Site Admin/Site Collection Admins. Only an Add-in Catalog administrator can remove/disable the add-in.

Add-in Event Receivers will work only when the add-in is installed in Add-in Catalog site.

LicensingLicensing Framework for Add-ins are applicable only to add-ins deployed to the Office Store. There are 3 Payment Categories for users to obtain license

1. Free

2. Paid(With/Without Trial Period)

3. Subscription Based(With/Without Trial Period)

Scope of the License can be applied to

1. Per User

2. Per Site

Monitoring Add-insFarm administrators can monitor add-in for errors and usage details of the add-in.

The primary items of monitoring framework are

  • No. of times the add-in was installed
  • Server resource consumption history
  • Runtime and Installation errors occurred for each instance of add-in installed by users.

The information provided by the monitoring framework helps administrators to decide if additional server resources need to be added or if the add-in is being used effectively.

Monitoring Add-in Depends on 2 Timer Jobs:

  • ECM analytics timer job name: Usage Analytics timer job for Search Service
  • Usage DB timer job name: Microsoft SharePoint Foundation Usage Data Import
Development ToolsVisual Studio

Text Editor

Any Client Side Development Editor

Visual Studio

Web Matrix

Light Switch

Any Web Development Editor

Author Info

Senthil Kumaresan
 
SharePoint Consultant
 
Rate this article
 
SharePoint Architect – Consulting on SharePoint Infrastructure, IT Governance and Apps Development. ...read more
 

Leave a comment