SharePoint Online: Develop Hosted Add-in using Visual Studio 2015
Here we will discuss What is an Add-in? What are few advantages of SharePoint add-in as well as we will see a demo to develop a SharePoint hosted add-in using Visual Studio 2015 for SharePoint Online Office 365? We will also discuss how we can package a SharePoint hosted add-in and deploy it to an add-in catalog site.
What is a SharePoint Add-in?
Previously, Microsoft named it Apps but later they renamed it to Add-in. Check out more here. So you should not confuse with Word apps with the add-in or vice versa.
"SharePoint Add-ins are self-contained extensions of SharePoint websites that you create, and that run without custom code on the SharePoint server. A SharePoint Add-in is a self-contained pieces of functionality that extends the capabilities of SharePoint websites to solve a well-defined business problem.
- Add-ins don't have custom code that runs on the SharePoint servers. All custom logic moves to cloud or to an on-premise server that is outside the SharePoint farm.
- Business logic in a SharePoint Add-in can access SharePoint data through one of the several client APIs included in SharePoint.
- Almost all major types of SharePoint components can be part of a SharePoint Add-in, including pages, lists, workflows, custom content types, list templates, Web Parts, and more.
- The SharePoint websites where SharePoint Add-ins are installed, and from which users launch them, are called host webs. The SharePoint components, however, are generally in a special child web of the host web called the add-in web.
- All SharePoint Add-ins that users install get a tile on the Site Contents page of the SharePoint website. You can click on the tile to launch the add-in." [MSDN]
- Microsoft designed Add-ins in such a way that it works both in Office 365 environment as well as within on-premise environment.
You can also check an article on Limitation of SharePoint Solutions and Advantages of SharePoint Add-ins
Types of Add-in?
There are two types of SharePoint Add-ins:
SharePoint-hosted add-in
There is no server side code in case of the SharePoint-hosted add-in.
"All business logic in a SharePoint-hosted add-in uses JavaScript either directly on a custom page or in a JavaScript file that is referenced from a custom page.
Custom pages in a SharePoint-hosted add-in are generally ASP.NET pages (ASPX) and they can declaratively reference ASP.NET and in-the-box SharePoint controls, but there can be no code behind. However, you can customize the SharePoint controls using a client-side rendering option and custom JavaScript.
The JavaScript in SharePoint-hosted add-ins can access data and resources that are outside of the add-in web by using either of two techniques for safely working around the browser's same origin policy: a special JavaScript cross-domain library or a specific JavaScript WebProxy class. Using these techniques a SharePoint-hosted add-in can work with data on the host web, its parent subscription.
Provider-hosted Add-in
*Any SharePoint component that can be in a SharePoint-hosted add-in can also be in a provider-hosted add-in. But provider-hosted add-ins are distinguished from SharePoint-hosted add-ins because they include at least one remote component; such as a web application, service, or database that is hosted externally from the SharePoint farm or SharePoint Online subscription. This could be a server in the same corporate network as a SharePoint farm or a cloud service. The external components can be hosted on any web hosting stack, including the Linux, Apache, MySQL, PHP (LAMP) stack. *
When the remote components are implemented with .NET, the managed code SharePoint Client-Side Object Model (CSOM) library is available.
For remote components that are not based on .NET, there is a set of REST/OData APIs that can be used to access SharePoint data. These can also be used from a .NET client if you prefer working with an OData interface.
An add-in can fit into a SharePoint website in below three ways:
- As a full page experience
- Inside a webpage within a control known as Add-in part
- As a UI commands in ribbons and menus." [MSDN]
Configure On-premise environment before developing an add-in
This is required if you want to develop or add an add-in to your on-premise environment. Here's an article on how we can configure the on-premise environment for add-in in SharePoint 2016. Microsoft has already released SharePoint 2016, if you have not tried yet, you can install it now.
Demo SharePoint Hosted Add-in for SharePoint Online
Here we will create a simple SharePoint hosted add-in.
Open Visual Studio 2015 and then File -> New Project and then expand Templates and then Office/SharePoint -> Office Add-ins. From there choose SharePoint Add-in like below. Give a name for the project and click OK.
https://www.enjoysharepoint.com/wp-content/uploads/2018/07/sharepoint-hosted-add-in-demo.png
Then we need to provide a SharePoint developer site for debugging the add-in. If you have not created a developer site, then you can create a developer site from Office 365 SharePoint Online admin center. You can follow this article. Microsoft provides the developer site to build, test and deploy add-in in SharePoint Online, SharePoint 2013 and also in SharePoint 2016.
Here we have given the developer site URL as well as the SharePoint-hosted for How do you want to host your SharePoint Add-in? like below:
In the next screen, it will ask you to give the credentials to connect to the SharePoint site like below. Provide the credentials for it.
Then it will automatically choose the SharePoint version to target the add-in like below:
Once you click Finish button, it will take some time and will create the project where you can see various folders in it. It contains folders like Features, Package, Content, Images, Scripts. The solution explorer looks like below:
Here the folders have specific propose like You can add .css files to Contents folder, images to the Images folder, any JS files to the Scripts folder and any pages to the Pages folder.
Another important file is the AppManifest.xml file. This file is very important.
"Every SharePoint app requires an XML file called AppManifest.xml, which is known as the app manifest. The app manifest contains essential metadata for the app that is read and tracked by the SharePoint host environment when an app is installed.
The app manifest contains a top-level <App> element that requires a set of attributes such as Name, ProductID, and Version. Within the <App> element there is an inner <Properties> element that contains important child elements such as <Title> and <StartPage>. The <Title> element contains human-readable text that is displayed to the user in the app launcher. The <StartPage> element contains the URL that the SharePoint host environment uses in the app launcher to redirect the user to the app’s start page." [microsoftpresstore.com]
Visual Studio provides to changes things in UI like below:
As we know in SharePoint hosted add-in we can write only JavaScript code. By default, all JavaScript code has been added in the App.js file which resides in the Scripts folder. So if you want to write any JavaScript code then you can write inside the App.js file. You can also add your own js file and give a reference in the page where you required.
In the default.aspx page, you can see all the required files has been referenced. And then in the PlaceHolderMain one <p> tag has been added. In the app.js file by default, it is retrieving the current username and showing in the <p> tag.
The default App.js code looks like below:
'use strict';
ExecuteOrDelayUntilScriptLoaded(initializePage, "sp.js");
function initializePage()
{
var context = SP.ClientContext.get_current();
var user = context.get_web().get_currentUser();
// This code runs when the DOM is ready and creates a context object which is needed to use the SharePoint object model
$(document).ready(function () {
getUserName();
});
// This function prepares, loads, and then executes a SharePoint query to get the current users information
function getUserName() {
context.load(user);
context.executeQueryAsync(onGetUserNameSuccess, onGetUserNameFail);
}
// This function is executed if the above call is successful
// It replaces the contents of the 'message' element with the user name
function onGetUserNameSuccess() {
$('#message').text('Hello ' + user.get_title());
}
// This function is executed if the above call fails
function onGetUserNameFail(sender, args) {
alert('Failed to get user name. Error:' + args.get_message());
}
}
Here we are not doing anything, simply we will deploy the SharePoint Add-in.
To deploy an add-in, right- click on the Add-in project and then click on Deploy like below:
It will take some time to deploy the add-in. Once it is deployed successfully, open the developer site and then go to the Site Contents page where you can see the add-in as below:
Once you will click on the add-in, the add-in will open and you can see like below:
Add-in Deployment:
You distribute SharePoint Add-ins in add-in packages that always include at least the add-in manifest.
There are two ways we can distribute the add-in package.
- - Add-in Catalog site: This is a dedicated SharePoint site collection in SharePoint Online or on-premise where we can upload the add-in package and people can start using within the organization.
- - Office Store: Here we can upload it to the Microsoft Office store. Microsoft handles the marketing process for you, from discovery to purchase to updates.
Upload add-in to Add-in Catalog site:
An add-in catalog site contains a special type of document library that is used to upload and store app package files. Along with storing the add-in package file, this document library also tracks various types of metadata for each app.
If you have not created an add-in catalog site then you can follow below article to create an add-in catalog site from Office 365 SharePoint add-in center.
https://www.enjoysharepoint.com/sharepoint-2013-online-app-catalog-site/
First, we need to create the .app file while we can upload to add-in catalog site. For this right-click on the Project -> Publish…
Then click on Package the add-in like below, which will generate the .app file.
This will package the app and the .app file will be available on <ProjectName>\bin\Debug\app.publish\version number>. This .app file we need to upload to the add-in catalog site.
Since the .app file is ready, open the App Catalog site and then open the Apps for SharePoint document library. We have to upload the .app package this library. You can use the Upload button or you can even drag and drop the file to the document library. Once you uploaded it should appear like below:
After this, you can open any SharePoint site and then go to site contents page and then click Add an app. You should be able to see the add-in as below:
From here you can add the add-in to the SharePoint site. Click the add-in to add it to the site. It will ask Do you trust OurDemoSharePointAddIn? Click Trust it like below:
It will take some time to add it to the site.
Once it is added you can see the add-in like below:
