Step by Step Guide to Configure Environment for Creating your first SharePoint Hosted App

Article
1/17/2024

Introduction

One of the new features of SharePoint 2013 is the SharePoint App Model. Similar to the windows phone marketplace, we now have a SharePoint Store available where we can simply search for apps and download them on our SharePoint site. In SharePoint 2013, everything is an app, be it lists or libraries.

If you have a look at the below screenshot, you will see an option to “add an app” in the View All Site Content section.

Now, if you click on this “add an app” link, you get the below screen where you get available templates for your app like document library, custom list, picture library etc. that you can add as an app.

What are Apps?

Having known that everything in SharePoint is an app, let us first discuss what an app is actually.

As cited by MSDN “Apps for SharePoint are easy-to-use, lightweight web applications that integrate popular web standards and technologies to extend the capabilities of a SharePoint website.”

Apps are standalone bits of functionality that can be hosted locally, or in the cloud.

Below screenshot shows you the link to SharePoint Store from where you can search for apps and install them on your SharePoint site.

Clicking on the SharePoint Store link will navigate you to the online SharePoint Store as shown in the screen below. Here you can search for apps based upon different categories. You have paid as well as free apps available.

Apps do not run on the SharePoint Server rather they are executed within the client browser or an IIS server or in a cloud server such as Windows Azure.

Apps comes in variety of flavors depending upon how they are hosted. You can have cloud based apps or you can have a SharePoint hosted apps. In cloud hosted apps, we have the option to create Provider Hosted Apps. The cloud hosted model also had an option to implement Autohosted apps. But Autohosted apps were released as a part of preview program when SharePoint 2013 was released, but in May 2014 Microsoft announced that they would be closing the preview program and would no longer support creating Autohosted apps. (Announcement: http://blogs.office.com/2014/05/16/update-on-autohosted-apps-preview-program/)

[

](resources/6862.5.jpg)

[Source of the above image is http://msdn.microsoft.com/en-us/library/office/fp179930(v=office.15).aspx]

If you want to know more about what are apps and why apps and what are these different hosting options in details, MSDN is an excellent source for the same. You can refer these links for more details.

http://msdn.microsoft.com/en-us/library/office/fp179930(v=office.15).aspx

http://msdn.microsoft.com/en-us/library/office/fp179887(v=office.15).aspx

Scope

Let us now define the scope of this article. In this article we will talk about how to configure development environment for an on-premise implementation of a SharePoint Hosted App. We will also create our first basic SharePoint Hosted Apps and talk about few possible errors usually encountered by developers while implementing their very first app. There are huge amount of reference available over MSDN to create and configure the apps but the purpose of this article is to help developers not only configure the environment but also pose before them the common challenges that they might face during their very first implementation and help them resolve those errors.

Configuring an on-premise development environment for Apps for SharePoint

Setting up the environment for development of On-premise SharePoint hosted apps is a tedious task as you need to lot of things as when compared with a pre-configured Office 365 environment.

In this article since we are focusing on developers so we will make an assumption that you do not have DNS in the box. If DNS is available then that is simply awesome. To configure using DNS there are ample reference material available on MSDN. See reference section for further details.

Let us get started now.

Create an Isolated App Domain

If you want to create and deploy SharePoint Hosted apps you must create an isolated app domain where your apps for SharePoint will run. Apps have their own isolated URL’s which are different from the site URL where the app is deployed and used.

Whenever we deploy a SharePoint hosted app on a site, an app web gets created beneath that site. You might think that like any normal subsite, app web would also live as a subsite in the site but that is not the case.

Say for example we installed an app named “MyFirstApp” at

http://intranet.contoso.com/sites/SiteCollectionA

You might expect that the URL of the app web will look like

http://intranet.contoso.com/sites/SiteCollectionA/MyFirstApp

But this is not the case. The URL of the App web will be something like this.

http://app-c95e49d1e88566.contosoapps.com/sites/SiteCollectionA/MyFirstApp

Each app web is created with a unique URL. The difference in URL between each provides a layer of isolation. The URL of the app web has the following structure.

[

](resources/2313.6.jpg)

You need to create an app domain in the DNS for the apps. This is very important. However there are scenarios where the developers don’t have domain controller in their box to do the same. The other option to get around with this is to make a host file entry. Since the configuration using DNS is widely available so in this document we will make use of the host file entry approach to make an app domain for the SharePoint Hosted App environment.

In the above screenshot, we have created an entry in the host file for the app domain as apps.practice.com

Start the Required Services

Once you have created the app domain, the next step is to start the required services for app development. Confirm that the SharePoint Administration (spadmin) and SharePoint Timer (sptimer) services are running.

To verify this, click Start, point to Administrative Tools, and then click Services. In the Services list, verify that the SharePoint Administration and SharePoint Timer services are running.

You can start these services from services.msc control or using command prompt like below

net start spadminv4

net start sptimerv4

For apps to work, you need to have the App Management and Subscriptions Settings Service Applications configured. Before creating these service applications verify that the following services are running in the Manage Services on Server page.

App Management Service
Microsoft SharePoint Foundation Subscription Settings service

You can verify the same from the Services on Server page in central admin.

Alternatively you can make use of PowerShell to start these services.

Create Service Applications

You need to create the following service applications.

App Management Service Application
Subscription Settings Service Application

App Management Service Application is responsible for tracking of app licenses and app permissions. This service application can be created using PowerShell or using Central Admin.

Subscription Settings Service Application is responsible for generating the app URL. It also maintains tenant subscriptions in multi-tenant deployment. This service application cannot be created from Central Admin and can only be provisioned using PowerShell.

Before creating these service applications ensure that you have the following memberships

securityadmin fixed server role on the SQL Server instance.
db_owner fixed database role on all databases that are to be updated.
Administrators group on the server on which you are running the Windows PowerShell cmdlets

Open SharePoint 2013 Management Shell and run the following commands. You can create a .ps1 file and run the script file itself instead of running every single command on the Management Shell console.

Navigate to central admin and browse to Manage Service Applications page. You will see the newly created service applications.

Configure App URL’s

Create the app domain prefix and the tenant name to use for apps in your environment. The app URL will point to your app domain and a prefix that determines how each app is named.

To configure App URL’s using Central Admin, follow the below mentioned steps.

In Central Admin, click on Apps.
In Apps page, click on Configure App URLs.

Sometimes on clicking this link the page does not open and instead the following error is thrown on the page.

Though the services are up and running still this issue might come. A simple iisreset can fix this issue for you.

In the App domain box, type the app domain that was created earlier for hosting apps. In our case we have used app.practice.com.
In the App Prefix box, type a name to use for the URL prefix for the apps.
Click OK.

In case you want to set the above values using PowerShell, follow the below steps.

Create your isolated app domain by running the SharePoint Management Shell as an administrator and typing the following command.

Set-SPAppDomain "your app domain"

Set-SPAppSiteSubscriptionName -Name "app" -Confirm:$false

There are some other settings required besides this which we will not talk right away. Let us start with the actual app creation and while doing that let us see what all issues comes up when you are creating your first app and then fix those issues which we missed out in the above configuration steps. We could have included those steps in the configuration only but for our learning let’s face them and then fix them so that we get the significance of those steps.

Creating Your First App

Open Visual Studio 2012 instance and select App for SharePoint 2013 template to create the project.

In the below screen, you can see that we have selected SharePoint-hosted as the hosting platform for our app.

Once you click Finish the following project structure gets created.

You can see there is some default modules created for you for Scripts, Images, and Pages etc.

As you can see in the above screenshot, we have an App.js file and Default.aspx file. Here App.js file is our main JavaScript file where the entire logic is there and default.aspx is the landing page of the app where we will reference the App.js file.

If you look at the App.js file, by default some logic is written there. What it is doing is that it is fetching the current logged in user’s name and displaying that. Let us keep things simple and not add any business logic here and try deploying this app right away and see what happens.

Right click on the project name and deploy. You might encounter your very first error over here.

SharePoint will not allow you to install nor uninstall apps using the farm account (System Account). If you try to deploy your app using Visual Studio F5 you will get one of the following errors if you do it using System Account:

Error occurred in deployment step ‘Install app for SharePoint’: The System Account cannot perform this action.

Digging into reflector shows this check. In the below screenshot you can see there is a method implemented stating DemandUserIsNotSystemAccount.

Now try to log in into the machine using some other account and try to install the app. You might receive the following error.

"Error occurred in deployment step "Installed app for SharePoint": The local SharePoint server is not available. Check that the server is running and connected to the SharePoint Farm"

To resolve the above error login using system account and open the SQL server management studio and assign the db_owner permissions to the account which you are using to deploy the app for below databases. This is really very important step since you are not using the System Account for deploying apps. This step should be a part of the configuration of the environment for the SharePoint hosted apps.

SharePoint_Config
SharePoint_Admin_ [GUID]
Current web application content database that needs to host the app
App management service application database
Subscription Settings service application database

Other probable errors that you might face initially while doing your first app deployment are as follows

The pointer to resolve the above issue is to check if your App Management Service Application is created in the central admin as well as it is also associated with your web application.

There is a possibility that you have created the service application but have not yet associated that with your web application.

Other probable error that you might encounter is

Error occurred in deployment step 'Install app for SharePoint': The requested service, AppMng.svc' could not be activated. See the server's diagnostic trace logs for more information

The cause for getting the above error is free memory is less to start this service. So you need to free some memory.

“Memory gates checking failed because the free memory is less than 5% of total memory. As a result, the service will not be available for incoming requests. To resolve this, either reduce the load on the machine or adjust the value of minFreeMemoryPercentageToActivateService on the serviceHostingEnvironment config element.”

You can resolve this issue by restarting the SPSearchHostController service in services.msc console as this consumes lot of memory, which will free some memory for you. You can also try to reboot your server or close unnecessary applications to free some memory.

You may encounter the following error

@"Error 1

CorrelationId: f9b593e6-5170-4e7c-97f3-075a24f9e460

ErrorDetail: The content database on the server is temporarily unavailable.

ErrorType: Transient

ErrorTypeName: Intermittent

ExceptionMessage: Microsoft.SharePoint.SPException: Settings or services required to complete this request are not currently available. Try this operation again later. If the problem persists, contact your administrator.

at Microsoft.SharePoint.SPSubscriptionSettingsServiceApplicationProxy.ProcessCommonExceptions(Exception ex, SPServiceLoadBalancerContext context)

at Microsoft.SharePoint.SPSubscriptionSettingsServiceApplicationProxy.ExecuteOnChannel(CodeBlock codeBlock)

at Microsoft.SharePoint.SPSubscriptionSettingsServiceApplicationProxy.GetSubscriptionMetadata(Guid subscriptionId)

at Microsoft.SharePoint.SPSiteSubscriptionSettings.EnsureSubscriptionMetadata()

at Microsoft.SharePoint.Utilities.SPUtility.IsValidAppInstallationConfiguration(SPSite site)

at Microsoft.SharePoint.Utilities.SPUtility.CanInstallAppsInSite(SPSite site)

at Microsoft.SharePoint.Packaging.SPUserCodeSolutionDeploymentGroup.Deploy()

at Microsoft.SharePoint.Administration.SPAppTask.DeployOperation()

at Microsoft.SharePoint.Lifecycle.MonitoredTaskExecution.DoTask()

Source: AppWeb

SourceName: App Web Deployment

This error can come either due to missing service application. Besides App Management and Subscription Settings service application, you have to install Managed Metadata Service Application.

Another possible cause of the above error is missing app prefix in your Apps section in the central admin. So verify if the app prefix is specified there or not.

Now if you try to deploy your app, you will be able to successfully deploy it.

If you notice above, the URL where the app was installed is

http://app-c95e49d1e88566.app.practice.com:5555/sites/XXXX/SharePointTestApp/

app: App prefix (tenant)
**
c95e49d1e88566: App ID

app.practice.com: App domain

sites/XXXX: Host Web

SharePointTestApp: App Name
**

In case you are prompted for password again and again on click of the app then you need to disable loopback.

As you can see in the above screenshot, when you click on the app, you are navigated to the default landing page of the app inside the app web and you can see “Hello Geetanjali Arora” on the page.

Remember we talked initially that this is going to be a very simple app with no business logic. Just a simple app to display logged in user’s username inside an app.

Share via