SharePoint Web パーツをファーム ソリューションのアドイン パーツに置き換えるReplace SharePoint web parts with add-in parts in farm solutions

変換プロセスを使用して、ページ上にある 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 に移行できません。Farm solutions cannot be migrated to SharePoint Online. この記事で取り上げられている技法とコードを適用すると、ファーム ソリューションと同様の機能を提供する新しいソリューションを構築して、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. これらの技法を適用すると、その後、アドイン パーツを使用するようにページが更新され、それを 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. たとえば、この記事では、Office 365 に対する認証を実行する方法や、必要な例外処理を実装する方法などについては取り上げていません。For example, this article does not discuss how to authenticate to Office 365, how to implement required exception handling, and so on. 追加のコード サンプルについては、「Office 365 Developer Patterns and Practices プロジェクト」を参照してください。For additional code samples, see the Office 365 Developer Patterns and Practices project.

注意

この記事で提供されるコードは、明示または黙示のいかなる種類の保証なしに現状のまま提供されるものであり、特定目的への適合性、商品性、権利侵害の不存在についての暗黙的な保証は一切ありません。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.

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

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

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

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

はじめにBefore you begin

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

  • 使用している SharePoint 環境が アドイン をサポートするように構成済みであること。SharePoint Online がアドインをサポートするように構成されていること。オンプレミスの SharePoint Server を使用している場合には、「SharePoint Server 用アプリの環境を構成する」をご覧ください。You are using a SharePoint environment that is configured to support add-ins. SharePoint Online is configured to support add-ins. If you are using SharePoint Server on-premises, see Configure an environment for apps for SharePoint Server.

  • 新しいアドイン パーツが SharePoint に既に展開されていること。You have deployed your new add-in part to SharePoint.

  • Web に対する FullControl アクセス許可がアドインに割り当てられていること。You have assigned your add-ins FullControl permissions on the Web. 詳細については、「SharePoint 2013 でのアドインのアクセス許可」を参照してください。For more information, see Add-in permissions in SharePoint.

新しいアドイン パーツをエクスポートするExport the new add-in part

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, and 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.

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

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

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>";

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

置換する Web パーツを検出するFind the web parts to replace

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

  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);
             }
         }
     }
    

新しいアドイン パーツに置換される Web パーツを検出するFind web parts to be replaced with new add-in part

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 パーツを検出します。Using LimitedWebPartManager to find all web parts on a specific page. また、各 Web パーツのタイトルもラムダ式に返されます。The title of each web part is also returned in the lambda expression.

  3. Web パーツ マネージャーの WebParts プロパティにあるそれぞれの Web パーツについて、Web パーツのタイトルと、(置換前の Web パーツのタイトルに設定されている) oldWebPartTitle 変数が等しいかどうか判別します。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. Web パーツ タイトルと oldWebPartTitle が等しい場合は、ReplaceWebPart を呼び出します。等しくない場合は、foreach ループの次の反復を続行します。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);
         }
     }
    

新しい Web パーツに置換するReplace the new web part

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 パーツを追加します。Using LimitedWebPartManager.AddWebPart to add a web part to a page in a specific web part zone. 必ず zoneIdAddWebPart に渡してください。そうでないと、ExecuteQuery の実行時に例外がスローされます。Ensure that 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