Easy Dynamics Blog

Designing and Developing SharePoint-Hosted Add-Ins (Part 1)

Posted by Pranav Kothare on Apr 20, 2016 10:00:00 AM

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:

  1. Setup and Introduction (this post)
  2. Designing the add-in
  3. Developing the add-in (part 1)
  4. Developing the add-in (part 2)
  5. Office Store Licensing and Conclusion


Any add-in after it has been successfully provisionedsite contents page in SharePoint by Pranav Kothare at Easy Dynamics, 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

Immersive Page

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.

Add-In Part

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.blog subscription CTA

UI Commands

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:

  1. Reusability of SharePoint components
  2. Easy to setup and deploy, with very little overhead

The limitations are as follows:

  1. You can only use JavaScript and HTML in your SharePoint-hosted add-in. You cannot deploy any server side code. This is obviously to curb the harmful effects of poorly written code. Imagine if Microsoft provided the ability to deploy server side code to their SharePoint Online environment, it would be bring their entire SharePoint cloud infrastructure to a standstill very quickly, to say the least! In the past, full trust farm solutions were deployed by organizations hosting a SharePoint environment on-premise to fulfill a business need. These organizations would often reach out to Microsoft for support as the stability of their farms started to deteriorate. This in turn raised the question: Why was the farm becoming unstable? More often than not it was determined that the solutions deployed to the organization’s SharePoint farm had a highly negative impact due to poor code quality. For this reason, SharePoint-hosted add-ins do not permit server side code. This has been mitigated to a very high degree with the new JavaScript Object Model made available in SharePoint 2013.


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

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

  2. For the purposes of this article, I will be using the Visual Studio 2015 Community Edition
    Office Dev Tools that can be downloaded here.

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

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

The Wrap-Up

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:

Subscribe to Blog at Easy Dynamics for Fixes and How-To's

Topics: SharePoint, Office 365, UI, HTML, SharePoint Online, Visual Studio, Office Dev Tools

Easy Dynamics: The SharePoint Experts

We are a leading SharePoint Services and Solutions shop located in Washington, DC. 

Thanks for coming to our blog! Here you will find relevant news and information about the technologies we use and other things we find interesting. Want to know more about who we work with? Or our first commercially available product, EasyBox

You can find links to all of these things and more right from this page. Enjoy reading!

Recent Posts

Subscribe to Email Updates