Export (0) Print
Expand All

Get started creating provider-hosted apps for SharePoint

apps for SharePoint

Set up a development environment and create your first provider-hosted app for SharePoint.

Last modified: June 22, 2015

Applies to: apps for SharePoint | Office 365 | SharePoint Add-ins | SharePoint Server 2013

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

In this article
Set up your dev environment
Create the app project
Code your app
Next steps
Additional resources

Provider-hosted apps are one of the two major types of apps for SharePoint. For an overview of apps for SharePoint and the two different type, see Apps for SharePoint. Here's a summary of provider-hosted apps:

  • They include a web application, or service, or database that is hosted externally from the SharePoint farm or SharePoint Online subscription. They may also include SharePoint components. You can host the external components on any web-hosting stack, including the Linux, Apache, MySQL, and PHP (LAMP) stacks.

  • The custom business logic in the app has to run on either the external components or in JavaScript on custom SharePoint pages.

Step 1 Set up your dev environment Step 2 Create the app project Step 3 Code your app

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

Get the tools

Sign up for an Office 365 Developer Site

Note 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?

    Office 365 Midsize Business

    Office 365 Enterprise E1, E3, E4, or K1

    Office 365 Education A2, A3, or A4

    Office 365 Government G1, G3, G4, or K1

    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 two ways to get an Office 365 plan.

Tip Tip

Each of these links open in a new window or tab so that you can still see the following instructions.

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 .onmicrosoft.com; for example, contoso.onmicrosoft.com.

    After signup, you use the resulting credentials (in the format UserID@yourdomain.onmicrosoft.com) 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://yourdomain.sharepoint.com.

  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 land line telephone number, but not a VoIP (Voice over Internet Protocol) number.

Note 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 someone@example.com or someone@example.onmicrosoft.com."

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 Apps 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 Apps in Testing list on the page confirms that the website was made with 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 URL of the site; it's used when you create apps for SharePoint projects in Visual Studio.

Figure 3. Your Developer Site home page with the Apps in Testing list

Screenshot that shows the Developer site homepage.

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

  2. In Visual Studio, choose File > New > Project.

  3. In the New Project dialog box, expand the Visual C# node, expand the Office/SharePoint node, and then choose Apps > App for SharePoint.

  4. Name the project SampleApp, and then choose OK

  5. In the first Specify the App for SharePoint Settings dialog box, do the following:

    • Provide the full URL of the SharePoint site that you want to use to debug your app. This is the URL of the Developer Site. Use HTTPS, not HTTP in the URL. (At some point during this procedure, or shortly after it completes, you will be prompted to login to this site. The timing of the prompt varies. Use the administrator credentials. (in the *.onmicrosoft.com domain) that you created when you signed up for your Developer Site; for example MyName@contoso.onmicrosoft.com.

    • Under How do you want to host your app for SharePoint, choose Provider-hosted.

    • Choose Next.

  6. On the Specify the target SharePoint version page, choose SharePoint Online, and then choose Next.

  7. Under Which type of web application project do you want to create?, choose ASP.NET Web Forms Application. Choose Next.

  8. Under How do you want your app to authenticate?, choose Use Windows Azure Access Control Service (for SharePoint cloud apps), and then choose Next.

  9. In the wizard, choose Finish.

    Much of the configuration is done when the solution opens. Two projects are created in the Visual Studio solution - one for the app for SharePoint and the other for the ASP.NET web application.

  1. Open the AppManifest.xml file. On the Permissions tab, specify the Site Collection scope and the Read permission level.

  2. Add the following HTML and ASP.NET controls inside the <body> tag of the Pages/Default.aspx file of your web application. This sample uses the UpdatePanel control to enable partial page rendering.

    <form id="form1" runat="server">
        <div>
            <asp:ScriptManager ID="ScriptManager1" runat="server"
                EnablePartialRendering="true" />
          <asp:UpdatePanel ID="PopulateData" runat="server" UpdateMode="Conditional">
            <ContentTemplate>   
       
            <table border="1" cellpadding="10">
             <tr><th><asp:LinkButton ID="CSOM" runat="server" Text="Populate Data" 
                                   OnClick="CSOM_Click" /></th>
                 </tr>
    
             <tr><td>
            <h2>SharePoint Site</h2>
            <asp:Label runat="server" ID="WebTitleLabel"/>
            <h2>Current User:</h2>
            <asp:Label runat="server" ID="CurrentUserLabel" />
            <h2>Site Users</h2>
            <asp:ListView ID="UserList" runat="server">     
                <ItemTemplate ><asp:Label ID="UserItem" runat="server" 
                                                  Text="<%# Container.DataItem.ToString()  %>"></asp:Label>
                <br /></ItemTemplate>
            </asp:ListView>
            <h2>Site Lists</h2>
            <asp:ListView ID="ListList" runat="server">
                <ItemTemplate ><asp:Label ID="ListItem" runat="server" 
                                                  Text="<%# Container.DataItem.ToString()  %>"></asp:Label>
                  <br /></ItemTemplate>
            </asp:ListView>
            </td>
                  
            </tr>
            </table>
            </ContentTemplate>
          </asp:UpdatePanel>
        </div>
        </form>
    
  3. Add the following declarations to the Default.aspx.cs file of your web application.

    using Microsoft.SharePoint.Client;
    using Microsoft.IdentityModel.S2S.Tokens;
    using System.Net;
    using System.IO;
    using System.Xml;
    
  4. In the Default.aspx.cs file of your web application, add these variables inside the Page class.

    SharePointContextToken contextToken;
    string accessToken;
    Uri sharepointUrl;
    string siteName;
    string currentUser;
    List<string> listOfUsers = new List<string>();
    List<string> listOfLists = new List<string>();
    
  5. Add the RetrieveWithCSOM inside the Page class. This method uses the SharePoint CSOM to retrieve information about your site and display it on the page.

    // This method retrieves information about the host web by using the CSOM.
    private void RetrieveWithCSOM(string accessToken)
    {
    
        if (IsPostBack)
        {
            sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);
        }            
    
        ClientContext clientContext =
                        TokenHelper.GetClientContextWithAccessToken(
                            sharepointUrl.ToString(), accessToken);
    
        // Load the properties for the web object.
        Web web = clientContext.Web;
        clientContext.Load(web);
        clientContext.ExecuteQuery();
    
        // Get the site name.
        siteName = web.Title;
    
        // Get the current user.
        clientContext.Load(web.CurrentUser);
        clientContext.ExecuteQuery();
        currentUser = clientContext.Web.CurrentUser.LoginName;
    
        // Load the lists from the Web object.
        ListCollection lists = web.Lists;
        clientContext.Load<ListCollection>(lists);
        clientContext.ExecuteQuery();
    
        // Load the current users from the Web object.
        UserCollection users = web.SiteUsers;
        clientContext.Load<UserCollection>(users);
        clientContext.ExecuteQuery();
    
        foreach (User siteUser in users)
        {
            listOfUsers.Add(siteUser.LoginName);
        }
    
    
        foreach (List list in lists)
        {
            listOfLists.Add(list.Title);
        }
    }
    
  6. Add the CSOM_Click method inside the Page class. This method triggers the event that occurs when the user clicks the Populate Data link.

    protected void CSOM_Click(object sender, EventArgs e)
    {
        string commandAccessToken = ((LinkButton)sender).CommandArgument;
        RetrieveWithCSOM(commandAccessToken);
        WebTitleLabel.Text = siteName;
        CurrentUserLabel.Text = currentUser;
        UserList.DataSource = listOfUsers;
        UserList.DataBind();
        ListList.DataSource = listOfLists;
        ListList.DataBind();    
     }
    
  7. Replace the existing Page_Load method with this one. The Page_Load method uses methods in the TokenHelper.cs file to retrieve the context from the Request object and get an access token from Microsoft Azure Access Control Service (ACS).

    // The Page_load method fetches the context token and the access token. 
    // The access token is used by all of the data retrieval methods.
    protected void Page_Load(object sender, EventArgs e)
    {
         string contextTokenString = TokenHelper.GetContextTokenFromRequest(Request);
    
        if (contextTokenString != null)
        {
            contextToken =
                TokenHelper.ReadAndValidateContextToken(contextTokenString, 
                                                                                              Request.Url.Authority);
    
            sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);
            accessToken =
                        TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority)
                         .AccessToken;
            CSOM.CommandArgument = accessToken;
        }
        else if (!IsPostBack)
        {
            Response.Write("Could not find a context token.");
            return;
        }
    }
    
  8. The Default.aspx.cs file should look like this when you’re done.

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Web;
    using System.Web.UI;
    using System.Web.UI.WebControls;
    
    using Microsoft.SharePoint.Client;
    using Microsoft.IdentityModel.S2S.Tokens;
    using System.Net;
    using System.IO;
    using System.Xml;
    
    namespace SampleAppWeb
    {
        public partial class Default : System.Web.UI.Page
        {
            SharePointContextToken contextToken;
            string accessToken;
            Uri sharepointUrl;
            string siteName;
            string currentUser;
            List<string> listOfUsers = new List<string>();
            List<string> listOfLists = new List<string>();
            protected void Page_PreInit(object sender, EventArgs e)
            {
                Uri redirectUrl;
                switch (SharePointContextProvider.CheckRedirectionStatus(Context, out redirectUrl))
                {
                    case RedirectionStatus.Ok:
                        return;
                    case RedirectionStatus.ShouldRedirect:
                        Response.Redirect(redirectUrl.AbsoluteUri, endResponse: true);
                        break;
                    case RedirectionStatus.CanNotRedirect:
                        Response.Write("An error occurred while processing your request.");
                        Response.End();
                        break;
                }
            }
    
            protected void CSOM_Click(object sender, EventArgs e)
            {
                string commandAccessToken = ((LinkButton)sender).CommandArgument;
                RetrieveWithCSOM(commandAccessToken);
                WebTitleLabel.Text = siteName;
                CurrentUserLabel.Text = currentUser;
                UserList.DataSource = listOfUsers;
                UserList.DataBind();
                ListList.DataSource = listOfLists;
                ListList.DataBind();
            }
    
            // This method retrieves information about the host web by using the CSOM.
            private void RetrieveWithCSOM(string accessToken)
            {
    
                if (IsPostBack)
                {
                    sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);
                }
    
    
                ClientContext clientContext =
                        TokenHelper.GetClientContextWithAccessToken(
                            sharepointUrl.ToString(), accessToken);
    
    
                // Load the properties for the web object.
                Web web = clientContext.Web;
                clientContext.Load(web);
                clientContext.ExecuteQuery();
    
                // Get the site name.
                siteName = web.Title;
    
                // Get the current user.
                clientContext.Load(web.CurrentUser);
                clientContext.ExecuteQuery();
                currentUser = clientContext.Web.CurrentUser.LoginName;
    
                // Load the lists from the Web object.
                ListCollection lists = web.Lists;
                clientContext.Load<ListCollection>(lists);
                clientContext.ExecuteQuery();
    
                // Load the current users from the Web object.
                UserCollection users = web.SiteUsers;
                clientContext.Load<UserCollection>(users);
                clientContext.ExecuteQuery();
    
                foreach (User siteUser in users)
                {
                    listOfUsers.Add(siteUser.LoginName);
                }
    
                foreach (List list in lists)
                {
                    listOfLists.Add(list.Title);
                }
            }
    
            protected void Page_Load(object sender, EventArgs e)
            {
                string contextTokenString = 
                     TokenHelper.GetContextTokenFromRequest(Request);
    
                if (contextTokenString != null)
                {
                    contextToken =
                        TokenHelper.ReadAndValidateContextToken(contextTokenString, 
                                                                                                      Request.Url.Authority);
    
                    sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);
                    accessToken =
                        TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority)
                                              .AccessToken;
                    CSOM.CommandArgument = accessToken;
                }
                else if (!IsPostBack)
                {
                    Response.Write("Could not find a context token.");
                    return;
                }
            }
        }
    }
    
  9. Use the F5 key to deploy and run your app. If you see a Security Alert window that asks you to trust the self-signed Localhost certificate, choose Yes.

    Choose Trust It on the consent page to grant permissions to the app, and then choose the name of your app in the Apps list on the Site Contents page. When you launch the app, you'll see a page that has the table shown in Figure 1. Choose Populate Data to see summary information about your SharePoint 2013 site.

    Figure 1. Launch page of the basic provider-hosted app sample

    Basic self-hosted app launch page

See Deploying and installing apps for SharePoint: methods and options to learn how to publish your app to a SharePoint 2013 site.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2015 Microsoft