プロバイダー ホスト型 SharePoint アドインの作成を始めるGet started creating provider-hosted SharePoint Add-ins

プロバイダー ホスト型アドインは、SharePoint アドインの主な 2 つの種類のうちの 1 つです。SharePoint アドインの概要と、その 2 つの種類については、「SharePoint アドイン」を参照してください。Provider-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 provider-hosted add-ins:

  • SharePoint ファームまたは SharePoint Online サブスクリプションの外部でホストされている Web アプリケーション、サービス、またはデータベースが含まれています。They include a web application, service, or database that is hosted externally from the SharePoint farm or SharePoint Online subscription. また、SharePoint コンポーネントが含まれていることもあります。They may also include SharePoint components. 外部コンポーネントは、LAMP (Linux、Apache、MySQL、PHP) スタックなど、任意の Web ホスティング スタックでホストできます。You can host the external components on any web-hosting stack, including the LAMP (Linux, Apache, MySQL, and PHP) stack.
  • アドイン内のカスタム ビジネス ロジックは、外部コンポーネントかカスタム SharePoint ページ上の JavaScript で実行する必要があります。The custom business logic in the add-in has to run on either the external components or in JavaScript on custom SharePoint pages.

この記事では、次の手順を実行します。In this article, you'll complete the following steps:

  • 開発環境のセットアップSet up your dev environment
  • アドイン プロジェクトの作成Create the add-in project
  • アドインのコーディングCode your add-in

開発環境のセットアップSet up your dev environment

SharePoint アドイン用に開発環境をセットアップする方法は多数あります。このセクションでは最も簡単な方法について説明します。There are many ways to set up a development environment for SharePoint Add-ins. This section explains the simplest way. "すべてオンプレミス" 環境に設定するなど、その他の方法については、「ツール」を参照してください。For alternatives, such as setting up an "all on-premises" environment, see Tools.

ツールを取得するGet the tools

前のバージョンの Visual Studio または他の Visual Studio ドキュメントを参照してください。Reference earlier versions of Visual Studio or other Visual Studio documentation.

Office 365 Developer サブスクリプションへのサインアップSign up for an Office 365 developer subscription

注意

既に Office 365 Developer サブスクリプションにアクセスできる可能性があります。You might already have access to an Office 365 developer subscription:

Office 365 プランを取得するには、次の手順を実行してください。To get an Office 365 plan:

開発者向けサイトを開くOpen your developer site

ページの左上にある [アドインのビルド] リンクを選択し、開発者向けサイトを開きます。Select 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 the following figure. このページの [テスト中アドイン] リストでは、SharePoint 開発者向けサイトのテンプレートで作成された Web サイトを確認できます。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.

注意

サイトの URL を書き留めておきます。これは、Visual Studio で SharePoint アドイン プロジェクトを作成するときに使用します。Make a note of the site's URL; it's used when you create SharePoint Add-in projects in Visual Studio.

開発者向けサイトのホーム ページと [テスト中アドイン] のリストYour developer site home page with the Add-ins in Testing list

開発者向けサイトのホームページを示すスクリーンショット。

アドイン プロジェクトの作成Create the add-in project

  1. [管理者として実行] オプションを使用して Visual Studio を開始します。Start Visual Studio by using the Run as administrator option.

  2. Visual Studio で、[ファイル] > [新規作成] > [新しいプロジェクト] を選択します。In Visual Studio, select File > New > New Project.

  3. [新しいプロジェクト] ダイアログ ボックスで、[Visual C#] ノードを展開し、[Office/SharePoint] ノードを展開して、[アドイン] > [SharePoint アドイン] を選択します。In the New Project dialog box, expand the Visual C# node, expand the Office/SharePoint node, and then select Add-ins > SharePoint Add-in.

  4. プロジェクトに「SampleAddIn」という名前を付けて、[OK] を選択します。Name the project SampleAddIn, and then select OK.

  5. [SharePoint アドインの設定を指定する] ダイアログ ボックスで、次の操作を実行します。In the Specify the SharePoint Add-in Settings dialog box, do the following:

    • アドインのデバッグに使用する SharePoint サイトの完全 URL を入力します。Provide the full URL of the SharePoint site that you want to use to debug your add-in. これは、開発者向けサイトの URL になります。This is the URL of the developer site. URL には、HTTP ではなく HTTPS を使用してください。Use HTTPS, not HTTP in the URL. このプロセスの間またはプロセスの完了直後に、このサイトへのサインインを求めるダイアログが表示されることがあります。At some point during this procedure, or shortly after it completes, you will be prompted to sign in to this site. このダイアログが表示されるタイミングはさまざまです。The timing of the prompt varies. 開発者向けサイトのサインアップ時に作成した管理者の資格情報 (*.onmicrosoft.com ドメイン内) を使用してください (例: MyName@contoso.onmicrosoft.com)。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.

    • [SharePoint アドインをホストする方法] で、[プロバイダー向けのホスト型] を選択します。Under How do you want to host your SharePoint Add-in, select Provider-hosted.

    • [次へ] を選択します。Select Next.

  6. [ターゲットの SharePoint バージョンを指定します] ページで、[SharePoint Online] を選択してから [次へ] をクリックします。On the Specify the target SharePoint version page, select SharePoint Online, and then select Next.

  7. [作成する Web アプリケーション プロジェクトのタイプ] で、[ ASP.NET Web フォーム アプリケーション] を選択してから [次へ] をクリックします。Under Which type of web application project do you want to create?, select ASP.NET Web Forms Application, and then select Next.

  8. [アドインの認証方法] で、[Windows Azure アクセス制御サービスを使用する] を選択します。Under How do you want your add-in to authenticate?, select Use Windows Azure Access Control Service.

  9. ウィザードで、[完了] を選択します。In the wizard, select Finish.

    構成の大半は、ソリューションを開いたときに実行されます。Much of the configuration is done when the solution opens. Visual Studio ソリューション内に 2 つのプロジェクトが作成されます。1 つは SharePoint アドインのプロジェクトで、もう 1 つは ASP.NET Web アプリケーションのプロジェクトです。Two projects are created in the Visual Studio solution: one for the SharePoint Add-in and the other for the ASP.NET web application.

アドインのコーディングCode your add-in

  1. AppManifest.xml ファイルを開きます。[権限] タブで [サイト コレクション] スコープと [読み取り] アクセス許可レベルを指定します。Open the AppManifest.xml file. On the Permissions tab, specify the Site Collection scope and the Read permission level.

  2. Web アプリケーションの Pages/Default.aspx ファイルの <body> タグ内にあるすべてのマークアップを削除してから、次に示す HTML と ASP.NET コントロールを <body> の内側に追加します。Delete any markup inside the <body> tag of the Pages/Default.aspx file of your web application, and then add the following HTML and ASP.NET controls inside the <body>. このサンプルでは、UpdatePanel コントロールを使用して、部分ページ レンダリングを可能にしています。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. 次の宣言を Web アプリの Default.aspx.cs ファイルに追加します。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. Web アプリケーションの Default.aspx.cs ファイルで、Page クラス内に次の変数を追加します。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. Page クラス内に RetrieveWithCSOM メソッドを追加します。Add the RetrieveWithCSOM method inside the Page class. このメソッドは、SharePoint CSOM を使用してサイトに関する情報を取得して、ページ上に表示します。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. Page クラス内に CSOM_Click メソッドを追加します。Add the CSOM_Click method inside the Page class. このメソッドは、ユーザーが [Populate Data (データの読み込み)] リンクをクリックしたときに発生するイベントをトリガーします。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. 既存の Page_Load メソッドを次のメソッドに置き換えます。Replace the existing Page_Load method with this one. この Page_Load メソッドは、TokenHelper.cs ファイル内のメソッドを使用して、Request オブジェクトからコンテキストを取得し、Microsoft Azure Access Control Service (ACS) からアクセストークンを取得します。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;
    
             // For simplicity, this sample assigns the access token to the button's CommandArgument property. 
             // In a production add-in, this would not be secure. The access token should be cached on the server-side.
            CSOM.CommandArgument = accessToken;
        }
        else if (!IsPostBack)
        {
            Response.Write("Could not find a context token.");
            return;
        }
    }
    
  8. 作業が完了すると、Default.aspx.cs ファイルは次のようになります。The Default.aspx.cs file should look like this when you're finished.

      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 SampleAddInWeb
      {
          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. F5 キーを使用して、アドインを展開して実行します。Use the F5 key to deploy and run your add-in. 自己署名 Localhost 証明書を信頼するかどうかを尋ねる [セキュリティの警告] ウィンドウが表示されたら、[はい] を選択します。If you see a Security Alert window that asks you to trust the self-signed Localhost certificate, select Yes.

  10. 同意ページで [信頼する] を選択して、アドインにアクセス許可を付与します。Select Trust It on the consent page to grant permissions to the add-in. Visual Studio は、IIS Express に Web アプリケーションをインストールしてから、テスト用 SharePoint サイトにアドインをインストールして起動します。Visual Studio will install the web application to IIS Express and then install the add-in to your test SharePoint site and launch it. 次のスクリーンショットに示す表を含むページが表示されます。You'll see a page that has the table shown in the following screen shot. SharePoint サイトの要約情報を確認するには、[Populate Data (データの読み込み)] をクリックします。To see summary information about your SharePoint site, select Populate Data.

基本的なセルフホステッド アプリ起動ページ

次の手順Next steps

アドインを作成するには、次の手順を順序どおりに行ってください。To create your add-ins, walk through the following steps in this order:

  1. プロバイダー向けのホスト型アドインに SharePoint の外観を付けるGive your provider-hosted add-in the SharePoint look-and-feel
  2. プロバイダー ホスト型アドインにカスタム ボタンを含めるInclude a custom button in the provider-hosted add-in
  3. SharePoint オブジェクト モデルの概要を簡単に説明するGet a quick overview of the SharePoint object model
  4. プロバイダー ホスト型アドインに SharePoint の書き込み操作を追加するAdd SharePoint write operations to the provider-hosted add-in
  5. プロバイダー ホスト型アドインにアドインの一部を含めるInclude an add-in part in the provider-hosted add-in
  6. プロバイダー ホスト型アドインでアドイン イベントを処理するHandle add-in events in the provider-hosted add-in
  7. プロバイダー向けのホスト型アドインに最初の実行ロジックを追加するAdd first-run logic to the provider-hosted add-in
  8. プログラムを使用してプロバイダー向けのホスト型アドインにカスタム ボタンを展開するProgrammatically deploy a custom button in the provider-hosted add-in
  9. プロバイダー向けのホスト型アドインでリスト アイテム イベントを処理するHandle list item events in the provider-hosted add-in