There is a lot of documentation out on the Internet that showcases development of add-ins with code samples. In this 5 part series, I want to do the same but also shed some light on the development process from end to end. Before we go any further, I would like you to pay careful attention to a part of the title: SharePoint-hosted. Note that I will not be tackling provider-hosted add-ins in this series. Provider-hosted add-ins are a great platform for development, but there are some intricacies that can be best understood after learning how SharePoint-hosted add-ins work.
In this article I will first tackle the anatomy of a SharePoint-hosted add-in, then enumerate the benefits and limitations of it, and finally dive into setting up the development environment.
Before we dive into this post, here is how the series will progress:
- Setup and Introduction (this post)
- Designing the add-in
- Developing the add-in (part 1)
- Developing the add-in (part 2)
- Office Store Licensing and Conclusion
Any add-in after it has been successfully provisioned, can be installed to a SharePoint website by going to the Site Contents page and adding it.
Just to clarify add-ins were formerly known as apps.
When a SharePoint-hosted add-in is installed, it is provisioned on a separate website called the add-in web. By that principle, the website where you installed the add-in from is called the host web. The URL for the host web is usually something like: https://www.fabrikam.com/sites/operations. The add-in web once installed, assumes the URL: http://add-in-bdf2016ea7dacb.fabrikamadd-ins.com/sites/operations/myaddin.
This URL can be decomposed as follows:
- prefix is any string set by the farm administrator in Central Administration. The default is default. In this example the administrator has changed this to add-in.
- id is a hexadecimal number generated internally when the add-in is installed.
- add-indomain is any string set by the farm administrator in Central Administration or with SharePoint Management Shell. This should not be set to a subdomain of the SharePoint web application or the purpose of add-in isolation is largely defeated. In this example, the administrator has removed the www and added add-ins to the company name. So fabrikamadd-ins.com is the add-in domain.
- hostwebrelativeurl is the relative URL of the parent host web, in this case sites/operations.
- name is the value of the Name attribute of the App element in the appmanifest.xml file (discussed later).
For SharePoint Online, the prefix used is usually the name of the tenant and the add-in domain is sharepoint.com. The hostwebrelativeurl is dependent on which site you install the add-in to and the name remains the name of the app you have specified during development.
The components that can deployed in a SharePoint-hosted add-in are as follows:
- Immersive full page
- Add-in parts (iframe dropped on a page)
- UI commands
The full page experience is what end users see when they browse to the add-in web. Once opened, you as the developer/designer have full control on how you would like to tailor that experience.
Sometimes users would like to leverage the functionality of your add-in within the confines of the host web. In this case, you as the developer/designer can create an add-in part which can be dropped on a page (much like a traditional web part) in the host web. The add-in part itself is an iframe that requests a page from the add-in web and displays it within the borders of the iframe on the host web page.
UI commands can be defined as menu actions on a list item/document in the add-in or host web. They can also be defined as actions on the ribbon in the host web. These commands can hint at providing some functionality to the end user regarding the context of the item.
Benefits and Limitations
There are many advantages to using a SharePoint-hosted add-in over a provider-hosted add-in, but there are a few caveats with that too. A good SharePoint-hosted add-in is one that can leverage the existing features/items of SharePoint and provide a cohesive solution to a business problem without necessarily having to reference external components (or at least encapsulate these components directly into the solution). SharePoint-hosted apps offer the following benefits:
- Reusability of SharePoint components
- Easy to setup and deploy, with very little overhead
The limitations are as follows:
- The add-in has the privileges of the signed on user. This can be detrimental if the scope of the user’s permissions are not considered. You as the developer/designer must consider the actions of users with different kinds of permissions, in order to provide a clean and seamless and experience.
Setting up the Development Environment
In order to start developing against SharePoint 2013/Online there are only a few things you need to setup:
- Visual Studio (preferably 2015 but it doesn’t matter which version as long as it meets the minimum requirements). The community version is free and can be downloaded here.
- For the purposes of this article, I will be using the Visual Studio 2015 Community Edition
Office Dev Tools that can be downloaded here.
- A SharePoint on-premise farm configured for deploying add-ins or a SharePoint Online development environment which comes with an Office 365 developer subscription. Instructions on setting up an Office 365 developer subscription can be found here.
- For setting up an on-premise environment you will need to follow the instructions listed here. Again for the purposes of this article, I will be using a SharePoint Online development environment.
We have finally reached the end of part 1 and we can move on to designing our add-in. In the next post, we will take a step back and use design tools to come up with an interactive user interface that meets our needs. After that, we can dive into development and begin to realize our solution. Feel free to drop me a line if you have any questions or comments about this topic.
What other benefits and limitations of a SharePoint-hosted add-in have you discovered? Share your wisdom with us in a comment below!
Found this blog post useful? Make yourself comfortable and check out our blog home page to explore other technologies we use on a daily basis and the fixes we've solved in our day to day work. To make your life easier,subscribe to our blog to get instant updates sent straight to your inbox: