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

SharePoint Hosted Add-in

Provider Hosted Add-in

Add-in Part

Custom Actions

REST

JSOM

REST

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

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.

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

Turn on Microsoft SharePoint foundation subscription settings service

Turn on Microsoft SharePoint foundation subscription settings service

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

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_Prefix – Add-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.

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_Prefix – Add-in_ID . Add-in_Base_Domain / Domain_Relative_URL_of_Host_Web / Add-in_Name

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

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>

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

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.

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.

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

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 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.

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

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

1. Add-in Installed

2. Add-in Uninstalling

3. Add-in Upgrading

• Update Host Web Components

• Update Add-in Web components

• Update Remote components

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

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.

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 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.

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

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

Text Editor

Any Client Side Development Editor

Web Matrix

Light Switch

Any Web Development Editor