SharePoint Web パーツをアドイン パーツに置き換えるReplace SharePoint Web Parts with add-in parts

変換プロセスを使用し、SharePoint クライアント オブジェクト モデル (CSOM) を使用して、Web パーツをアドイン パーツに置換します。Use the transformation process to replace Web Parts with add-in parts by using the SharePoint client object model (CSOM).

適用対象: SharePoint 2013 | SharePoint アドイン | SharePoint OnlineApplies to: SharePoint 2013 | SharePoint Add-ins | SharePoint Online

変換プロセスを使用して、ページ上にある SharePoint Web パーツをアドイン パーツに置換できます。その際、CSOM を使用して特定の Web パーツを検索および削除し、新しいアドイン パーツを追加します。You can use the transformation process to replace SharePoint Web Parts with add-in parts on pages by using CSOM to find and remove specific Web Parts, and then adding the new add-in parts.

重要: ファーム ソリューションを SharePoint Online に移行することはできません。この記事で取り上げられている技法とコードを適用すると、ファーム ソリューションと同様の機能を提供する新しいソリューションを構築し、それを SharePoint Online に展開できます。こうした技法を適用すると アドイン パーツを使用するようにページが更新されるので、SharePoint Online に移行できます。この記事のコードを完全に作動するソリューションとするためには、さらにコードを追加することが必要です。たとえば、この記事では、Office 365 に対する認証を行う方法、必要な例外処理を実装する方法などについては取り上げていません。他のコード サンプルについては、Office 365 Developer Patterns and Practices プロジェクトを参照してください。Important: Farm solutions cannot be migrated to SharePoint Online. By applying the techniques and code described in this article, you can build a new solution with similar functionality that your farm solutions provide, which can then be deployed to SharePoint Online. After you apply these techniques, your pages will be updated to use add-in parts, which can then be migrated to SharePoint Online. The code in this article requires additional code to provide a fully working solution. For example, this article does not discuss how to authenticate to Office 365, how to implement required exception handling, and so on. For additional code samples, see the Office 365 Developer Patterns and Practices project.

はじめにBefore you begin

この記事に記されている手順を実行して Web パーツをアドイン パーツに置換する前に、以下を確認してください。Before performing the steps in this article to replace your Web Parts with add-in parts, make sure that you:

Web パーツをアドイン パーツに置換するReplace Web Parts with add-in parts

Web パーツを新しいアドイン パーツに置換するには次のようにします。To replace Web Parts with new add-in parts:

  1. 新しいアドイン パーツをエクスポートします。エクスポートされたアドイン パーツを使用して、アドイン パーツ定義を取得します。Export the new add-in part. Use the exported add-in part to get the add-in part definition.

  2. 置換対象の Web パーツが含まれるページすべてを検出し、それらの Web パーツを削除します。Find all pages with Web Parts to be replaced, and then remove the Web Parts.

  3. アドイン パーツ 定義を使用して、ページ上に新しいアドイン パーツを作成します。Create the new add-in part on the page by using the add-in part definition.

CSOM を使用して Web パーツをアドイン パーツに置換するには、アドイン パーツをエクスポートしてアドイン パーツ定義を取得する必要があります。アドイン パーツの定義を取得するためにアドイン パーツをエクスポートするには、次のようにします。To use CSOM to replace a Web Part with an add-in part, you need to get the add-in part definition by exporting the add-in part. To export the add-in part to get the add-in part's definition:

  1. SharePoint サイトを開き、[ 設定] を選択するか、ギア アイコンを選択し、[ ページの編集] を選択します。Open your SharePoint site and choose Settings, or the gear icon, and then choose Edit page.

  2. リボンで、[ 挿入] > [ アドイン パーツ] と選択します。On the ribbon, choose INSERT > Add-in Part.

  3. ご使用のアドイン パーツを選択し、[ 追加] を選択します。Choose your add-in part, and then choose Add.

  4. アドイン パーツがページに追加されたら、アドイン パーツの右上隅にある下矢印を選択し、[ Web パーツの編集] を選択します。When the add-in part is added to your page, choose the down arrow in the top-right corner of the add-in part, and then choose Edit Web Part.

  5. [ 詳細] の [ エクスポート モード] で [ すべてのデータをエクスポート]、[ OK] の順に選択します。In Advanced, in Export Mode choose Export all data, and then choose OK.

  6. ご使用のアドイン パーツが表示された編集ページに戻り、アドイン パーツの右上隅にある下矢印を選択して、[ エクスポート] を選択します。When you return to the edit page with your add-in part displayed, choose the down arrow in the top-right corner of the add-in part, and then choose Export.

  7. [ 保存] を選択します。Choose Save.

  8. ダウンロードの完了後、[ フォルダーを開く] を選択します。After the download completes, choose Open folder.

  9. [ メモ帳] を開き、[ ファイル] > [ 開く] と選択します。Open Notepad, then choose File > Open.

  10. ダウンロードしたアドイン パーツ ファイルを選択し、[開く] を選択してアドイン パーツ定義を表示します。Choose the add-in part file that you downloaded, and then choose Open to view the add-in part definition.

注意

この記事で提供されるコードは、明示または黙示のいかなる種類の保証なしに現状のまま提供されるものであり、特定目的への適合性、商品性、権利侵害の不存在についての暗黙的な保証は一切ありません。The code in this article is provided as-is, without warranty of any kind, either express or implied, including any implied warranties of fitness for a particular purpose, merchantability, or non-infringement.

<webParts>
  <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
    <metaData>
      <type name="Microsoft.SharePoint.WebPartPages.ClientWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" />
      <importErrorMessage>Cannot import this Web Part.</importErrorMessage>
    </metaData>
    <data>
      <properties>
        <property name="TitleIconImageUrl" type="string" />
        <property name="Direction" type="direction">NotSet</property>
        <property name="ExportMode" type="exportmode">All</property>
        <property name="HelpUrl" type="string" />
        <property name="Hidden" type="bool">False</property>
        <property name="Description" type="string">WelcomeAppPart Description</property>
        <property name="FeatureId" type="System.Guid, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089">0b846986-3474-4f1a-93cf-b7817ef057f9</property>
        <property name="CatalogIconImageUrl" type="string" />
        <property name="Title" type="string">WelcomeAppPart</property>
        <property name="AllowHide" type="bool">True</property>
        <property name="ProductWebId" type="System.Guid, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089">741c5404-f43e-4f01-acfb-fcd100fc7d24</property>
        <property name="AllowZoneChange" type="bool">True</property>
        <property name="TitleUrl" type="string" />
        <property name="ChromeType" type="chrometype">Default</property>
        <property name="AllowConnect" type="bool">True</property>
        <property name="Width" type="unit" />
        <property name="Height" type="unit" />
        <property name="WebPartName" type="string">WelcomeAppPart</property>
        <property name="HelpMode" type="helpmode">Navigate</property>
        <property name="AllowEdit" type="bool">True</property>
        <property name="AllowMinimize" type="bool">True</property>
        <property name="ProductId" type="System.Guid, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089">0b846986-3474-4f1a-93cf-b7817ef057f8</property>
        <property name="AllowClose" type="bool">True</property>
        <property name="ChromeState" type="chromestate">Normal</property>
      </properties>
    </data>
  </webPart>
</webParts>

CSOM コードでアドイン パーツ定義を使用するには、次のようにします。To use the add-in part definition in your CSOM code:

  • アドイン パーツ定義にあるすべての二重引用符 (") を二重引用符のペア ("") に置き換えます。Replace all double quotes (") with a pair of double quotes ("") in the add-in part definition.

  • アドイン パーツ定義を、CSOM コードで使用する文字列に割り当てます。Assign the add-in part definition to a string that will be used in your CSOM code.

private const string appPartXml = @"<webParts>
  <webPart xmlns=""http://schemas.microsoft.com/WebPart/v3"">
    <metaData>
      <type name=""Microsoft.SharePoint.WebPartPages.ClientWebPart, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c"" />
      <importErrorMessage>Cannot import this Web Part.</importErrorMessage>
    </metaData>
    <data>
      <properties>
        <property name=""TitleIconImageUrl"" type=""string"" />
        <property name=""Direction"" type=""direction"">NotSet</property>
        <property name=""ExportMode"" type=""exportmode"">All</property>
        <property name=""HelpUrl"" type=""string"" />
        <property name=""Hidden"" type=""bool"">False</property>
        <property name=""Description"" type=""string"">WelcomeAppPart Description</property>
        <property name=""FeatureId"" type=""System.Guid, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"">0b846986-3474-4f1a-93cf-b7817ef057f9</property>
        <property name=""CatalogIconImageUrl"" type=""string"" />
        <property name=""Title"" type=""string"">WelcomeAppPart Title</property>
        <property name=""AllowHide"" type=""bool"">True</property>
        <property name=""ProductWebId"" type=""System.Guid, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"">717c00a1-08ea-41a5-a2b7-4c8f9c1ce770</property>
        <property name=""AllowZoneChange"" type=""bool"">True</property>
        <property name=""TitleUrl"" type=""string"" />
        <property name=""ChromeType"" type=""chrometype"">Default</property>
        <property name=""AllowConnect"" type=""bool"">True</property>
        <property name=""Width"" type=""unit"" />
        <property name=""Height"" type=""unit"" />
        <property name=""WebPartName"" type=""string"">WelcomeAppPart</property>
        <property name=""HelpMode"" type=""helpmode"">Navigate</property>
        <property name=""AllowEdit"" type=""bool"">True</property>
        <property name=""AllowMinimize"" type=""bool"">True</property>
        <property name=""ProductId"" type=""System.Guid, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"">0b846986-3474-4f1a-93cf-b7817ef057f8</property>
        <property name=""AllowClose"" type=""bool"">True</property>
        <property name=""ChromeState"" type=""chromestate"">Normal</property>
      </properties>
    </data>
  </webPart>
</webParts>";

ReplaceWebPartsWithAppParts は、次のようにして、置換対象の Web パーツの検出プロセスを開始します。ReplaceWebPartsWithAppParts starts the process of finding the Web Parts to be replaced by:

  1. Web からいくつかのプロパティを取得して、サイト上の Pages ライブラリを見つけます。Getting some properties from the Web to find the Pages library on the site.

  2. Pages ライブラリで、リスト項目と、そのリスト項目に関連付けられているファイルを取得します。In the Pages library, getting the list items and the file associated with the list item.

  3. Pages ライブラリから戻されるそれぞれのリスト項目に関して、 FindWebPartToReplace を呼び出します。For each list item returned from the Pages library, calling FindWebPartToReplace.

protected void ReplaceWebPartsWithAppParts(object sender, EventArgs e)
{
    var spContext = SharePointContextProvider.Current.GetSharePointContext(Context);
    using (var clientContext = spContext.CreateUserClientContextForSPHost())
    {
        Web web = clientContext.Web;
        // Get properties from the Web.
        clientContext.Load(web,
                            w => w.ServerRelativeUrl,
                            w => w.AllProperties);
        clientContext.ExecuteQuery();
        // Read the Pages library name from the Web properties.
        var pagesListName = web.AllProperties["__pageslistname"] as string;

        var list = web.Lists.GetByTitle(pagesListName);
        var items = list.GetItems(CamlQuery.CreateAllItemsQuery());
        // Get the file associated with each list item.
        clientContext.Load(items,
                            i => i.Include(
                                    item => item.File));
        clientContext.ExecuteQuery();

        // Iterate through all pages in the Pages list.
        foreach (var item in items)
        {
            FindWebPartForReplacement(item, clientContext, web);
        }
    }
}

FindWebPartToReplace は、次のようにして新しいアドイン パーツに置換する必要がある Web パーツを検出します。FindWebPartToReplace finds Web Parts that should be replaced with the new add-in part by:

  1. page を、 Pages ライブラリから戻されるリスト項目と関連付けられているファイルに設定します。Setting page to the file associated with the list item returned from the Pages library.

  2. LimitedWebPartManager を使用して、特定のページ上のすべての Web パーツを検出します。各 Web パーツのタイトルも、ラムダ式で戻ります。Using LimitedWebPartManager to find all Web Parts on a specific page. The title of each Web Part is also returned in the lambda expression.

  3. Web パーツ マネージャーの WebParts プロパティにあるそれぞれの Web パーツに関して、Web パーツのタイトルと oldWebPartTitle 変数 (置換前の Web パーツのタイトルに設定されています) が等しいかどうか判別します。Web パーツ タイトルと oldWebPartTitle が等しい場合には、 ReplaceWebPart を呼び出します。等しくない場合には、 foreach ループの次の反復を続行します。For each Web Part in the Web Part manager's WebParts property, determining whether the Web Part's title and the oldWebPartTitle variable, which is set to the title of the Web Part you are replacing, are equal. If the Web Part title and oldWebPartTitle are equal, call ReplaceWebPart; otherwise continue with the next iteration of the foreach loop.

private static void FindWebPartToReplace(ListItem item, ClientContext clientContext, Web web)
{
    File page = item.File;
    // Requires Full Control permissions on the Web.
    LimitedWebPartManager webPartManager = page.GetLimitedWebPartManager(PersonalizationScope.Shared);
    clientContext.Load(webPartManager,
                        wpm => wpm.WebParts,
                        wpm => wpm.WebParts.Include(
                                            wp => wp.WebPart.Title));
    clientContext.ExecuteQuery();

    foreach (var oldWebPartDefinition in webPartManager.WebParts)
    {
        var oldWebPart = oldWebPartDefinition.WebPart;
        // Modify the Web Part if we find an old Web Part with the same title.
        if (oldWebPart.Title != oldWebPartTitle) continue;

        ReplaceWebPart(web, item, webPartManager, oldWebPartDefinition, clientContext, page);
    }
}

ReplaceWebPart は、次のようにして、新しい Web パーツを置換します。ReplaceWebPart replaces the new Web Part by:

  1. LimitedWebPartManager.ImportWebPart を使用して、 appPartXml 内の XML 文字列を WebPartDefinition に変換します。Using LimitedWebPartManager.ImportWebPart to convert the XML string in appPartXml into a WebPartDefinition.

  2. LimitedWebPartManager.AddWebPart を使用して、Web パーツを、特定の Web パーツ領域のページに追加します。 zoneIdAddWebPart に渡してください。そうしないと、 ExecuteQuery の実行時に例外がスローされます。Using LimitedWebPartManager.AddWebPart to add a Web Part to a page in a specific Web Part zone. Ensure you pass the zoneId to AddWebPart, otherwise an exception will be thrown when ExecuteQuery runs.

  3. WebPartDefinition.DeleteWebPart を使用して、ページから古い Web パーツを削除します。Using WebPartDefinition.DeleteWebPart to delete the old Web Part from the page.

private static void ReplaceWebPart(Web web, ListItem item, LimitedWebPartManager webPartManager,
      WebPartDefinition oldWebPartDefinition, ClientContext clientContext, File page)
  {

      // Create a Web Part definition using the XML string.
      var definition = webPartManager.ImportWebPart(appPartXml);
      webPartManager.AddWebPart(definition.WebPart, "RightColumn", 0);

      // Delete the old Web Part from the page.
      oldWebPartDefinition.DeleteWebPart();
      clientContext.Load(page,
                          p => p.CheckOutType,
                          p => p.Level);

      clientContext.ExecuteQuery();

  }

関連項目See also