Get started creating SharePoint-hosted SharePoint Add-ins

Set up a development environment and create your first SharePoint-hosted SharePoint Add-in.

Note The name "apps for SharePoint" is changing to "SharePoint Add-ins". During the transition, the documentation and the UI of some SharePoint products and Visual Studio tools might still use the term "apps for SharePoint". For details, see New name for apps for Office and SharePoint.

SharePoint-hosted add-ins are one of the two major types of SharePoint Add-ins. For an overview of SharePoint Add-ins and the two different types, see SharePoint Add-ins. Here's a summary of SharePoint-hosted add-ins:

Set up your dev environment

There are many ways to set up a development environment for SharePoint Add-ins. This section explains the simplest way. For alternatives, see Additional Resources.

Get the tools

Sign up for an Office 365 Developer Site

Note You might already have access to an Office 365 Developer Site. Are you an MSDN subscriber? Visual Studio Ultimate and Visual Studio Premium with MSDN subscribers receive an Office 365 Developer Subscription as a benefit. Redeem your benefit today. Do you have one of the following Office 365 subscription plans? If so, an administrator of the Office 365 subscription can create a Developer Site by using the Office 365 admin center. For more info, see Create a developer site on an existing Office 365 subscription.

There are three ways to get an Office 365 plan.

Tip Open these links in another window or tab in order to keep the following instructions handy.

Figure 1. Office 365 Developer Site domain name

Page 2 of Sign up form for Office 365 account

  1. The first page (not shown) of the signup form is self-explanatory; supply the requested information and then choose Next.

  2. On the second page, shown in Figure 1, specify a user ID for the administrator of the subscription.

  3. Create a subdomain of; for example,

    After signup, you use the resulting credentials (in the format UserID@ to sign in to your Office 365 portal site where you administer your account. Your SharePoint Online Developer Site is set up at your new domain: http://

  4. Choose Next and fill out the final page of the form. If you choose to provide a telephone number to get a confirmation code, you can provide a mobile or landline number, but not a VoIP (Voice over Internet Protocol) number.

Note If you're logged on to another Microsoft account when you try to sign up for a developer account, you might see this message: "Sorry, that user ID you entered didn't work. It looks like it's not valid. Be sure you enter the user ID that your organization assigned to you. Your user ID usually looks like or ."If you see that message, log out of the Microsoft account you were using and try again. If you still get the message, clear your browser cache or switch to InPrivate Browsing and then fill out the form.

After you finish the signup process, your browser opens the Office 365 installation page. Choose the Admin icon to open the admin center page.

Figure 2. Office 365 admin center page

Screenshot that shows the Office 365 admin center.

  1. Wait for your Developer Site to finish setting up. After provisioning is complete, refresh the admin center page in your browser.

  2. Then, choose the Build Add-ins link in the upper left corner of the page to open your Developer Site. You should see a site that looks like the one in Figure 3. The Add-ins in Testing list on the page confirms that the website was made with the SharePoint Developer Site template. If you see a regular team site instead, wait a few minutes and then restart your site.

  3. Make a note of the site's URL; it's used when you create SharePoint Add-ins projects in Visual Studio.

Figure 3. Your Developer Site home page with the Add-ins in Testing list

Screenshot that shows the Developer site homepage.

Create the add-in project

  1. Start Visual Studio using the Run as administrator option.

  2. Choose File > New > New Project.

  3. In the New Project dialog box, expand the Visual C# node, expand the Office/SharePoint node, and then choose Add-ins > Add-in for SharePoint.

  4. Name the project EmployeeOrientation, and then choose OK.

  5. In the first Specify the Add-in for SharePoint Settings dialog box, provide the full URL of the SharePoint site that you want to use to debug your add-in. This is the URL of the Developer Site. (Use HTTPS, not HTTP in the URL.) Under How do you want to host your SharePoint Add-in, choose SharePoint-hosted. Choose Finish.

  6. You may be prompted to login to your Developer Site. If so, use your subscription administrator's credentials.

  7. After the project is created, open the file /Pages/Default.aspx from the root of the project. Among other things, this generated file loads one or both of two scripts that are hosted on SharePoint: sp.runtime.js and sp.js. The markup for loading these files is in the Content control near the top of the file that has the ID PlaceHolderAdditionalPageHead. The markup varies depending on the version of Microsoft Office Developer Tools for Visual Studio that you are using. This series of tutorials requires that both files be loaded and that they be loaded with ordinary HTML <script> tags, not <SharePoint:ScriptLink> tags. Ensure that the following lines are in the PlaceHolderAdditionalPageHead control, just above the line <meta name="WebPartPageExpansion" content="full" />:

  <script type="text/javascript" src="/_layouts/15/sp.runtime.js"></script> 
  <script type="text/javascript" src="/_layouts/15/sp.js"></script> 

Then search the file for any other markup that also loads one or the other of these files and remove the redundant markup. Save and close the file.

Code your add-in

For your first SharePoint-hosted SharePoint Add-in, we'll include the classic SharePoint extension: a custom list and list instance.

  1. In Solution Explorer, open the AppManifest.xml file.

  2. When the manifest designer opens, add a space between the words in the Title field so that it readsEmployee Orientation. (Do not change the Name field.)

  3. Save and close the file.

  4. Right-click the project in Solution Explorer and choose Add > New Folder. Name the folder Lists.

  5. Right-click the new folder and choose Add > New Item. The Add New Item dialog opens to the Office/SharePoint node.

  6. Choose List. Give it the name NewEmployeeOrientation, and then choose Add.

  7. On the Choose List Settings page of the SharePoint Customization Wizard, leave the list display name at the default NewEmployeeOrientation, choose the Create a customizable list template and a list instance of it option button, and choose Default (Custom List) on the drop-down list. Then choose Finish.

  8. The wizard creates a NewEmployeeOrientation list template with a child list instance named NewEmployeeOrientationInstance. A list designer may open. It is used in a later step.

  9. Expand the NewEmployeeOrientationInstance node in Solution Explorer, if it isn't already, so that you can clearly distinguish the elements.xml file that is a child of the list instance from the elements.xml file that is a child of the list template .

    Lists node in Solution Explorer

List folder with child NewEmployeeOrientation template, which itself has three children; a NewEmployeeOrientationInstance, an elements.xml file, and a schema.xml file. The instance itself has a child named elements.xml.

  1. Open the elements.xml child of the NewEmployeeOrientation list template.

  2. Add spaces to the DisplayName attribute (not the Name attribute) to make it friendlier:"New Employee Orientation".

  3. Set the Description attribute to"Orientation information about new employees."

  4. Leave all other attributes at their default, save the file and close it.

  5. If the list designer is not open, choose the NewEmployeeOrientation node in Solution Explorer.

  6. Open the List tab of the designer. This tab is used to set certain values for the list instance , not the list template , but it has some default values that it inherited from the template.

  7. Change the values on this tab to the following:

    • Title: New Employees in Seattle

    • List URL: Lists/NewEmployeesInSeattle

    • Description: The new employees in Seattle.

    Leave the check boxes at their default status, save the file, and close the designer.

  8. The list instance may have its old name in Solution Explorer. If so, open the shortcut menu for NewEmployeeOrientationInstance, choose Rename, and change the name to NewEmployeesInSeattle.

  9. Open the schema.xml file.

  10. In the View element whose BaseViewID value is "0", replace the existing ViewFields element with the following markup. (Use exactly this GUID for the FieldRef named Title.)

    Line breaks may come at odd places in this autogenerated schema.xml file. Be sure you have found the matching begin and end tags for the ViewFields element. Add line breaks to improve readability.

  <FieldRef Name="Title" ID="{fa564e0f-0c70-4ab9-b863-0177e6ddd247}" DisplayName="Employee" />
  1. Still in the schema.xml file, in the View element whose BaseViewID value is "1", replace the existing ViewFields element with the following markup. (Use exactly this GUID for the FieldRef named LinkTitle.)
  <FieldRef Name="LinkTitle" ID="{82642ec8-ef9b-478f-acf9-31f7d45fbc31}" DisplayName="Employee" />
  1. Save and close the schema.xml file.

  2. Open the elements.xml file that is a child of the list instance NewEmployeesInSeattle (not the elements.xml that is a child of the list template NewEmployeeOrientation).

  3. In this file, populate the list with some initial data. You do this by adding the following Data element markup as a child element of the ListInstance element.

      <Field Name="Title">Tom Higginbotham</Field>
      <Field Name="Title">Satomi Hayakawa</Field>
      <Field Name="Title">Cassi Hicks</Field>
      <Field Name="Title">Lertchai Treetawatchaiwong</Field>
  1. Save and close the file.

  2. In Solution Explorer, double-click Feature1 to open the Feature designer. In the designer, set the Title toNew Employee Orientation Components and set the Description toLists and other components for getting employees oriented to the company. Save the file, and close the designer.

  3. If the Feature1 in Solution Explorer has not been automatically renamed, open its shortcut menu, choose Rename, and rename it NewEmployeeOrientationComponents.

  4. Open the Default.aspx file.

  5. Find the ASP.NET Content element with the ID PlaceHolderPageTitleInTitleArea. Replace the default string "Page Title" with "New Employees by Location".

  6. Find the ASP.NET Content element with the ID PlaceHolderMain. Replace its contents with the following markup. The _spPageContextInfo is a JavaScript object that SharePoint automatically includes in the page. It's webAbsoluteUrl property returns the URL of the add-in web.

    <p><asp:HyperLink runat="server" 
    NavigateUrl="JavaScript:window.location = _spPageContextInfo.webAbsoluteUrl + '/Lists/NewEmployeesInSeattle/AllItems.aspx';" 
    Text="New Employees in Seattle" /></p>

Run the add-in and test the list

  1. Use the F5 key to deploy and run your add-in. Visual Studio makes a temporary installation of the add-in on your test SharePoint site and immediately runs the add-in. (To find out how end users run an installed SharePoint Add-in, see Next Steps.)

  2. When the add-in's default page opens, choose the New Employees in Seattle link to open the custom list instance.

    Default page and list view page

The add-in's default page is shown with its title New Employees by Location. There is a link labeled New Employees in Seattle. An arrow from this link points to the list view page for the list. It is titled New Employees in Seattle, with the list below.

  1. Add and delete items from the list.

  2. To end the debugging session, close the browser window or stop debugging in Visual Studio. Each time that you press F5, Visual Studio will retract the previous version of the add-in and install the latest one.

  3. You will work with this add-in and Visual Studio solution in other articles, and it's a good practice to retract the add-in one last time when you are done working with it for a while. Right-click the project in Solution Explorer and choose Retract.

So far, there isn't much orientation information in the list. We'll add some in later articles in this series. But first, take a brief break from coding to learn about deploying SharePoint Add-ins in Deploy and install a SharePoint-hosted SharePoint Add-in.