在场解决方案中使用外接程序部件替换 SharePoint Web 部件

项目
04/08/2023

可以根据转换过程，将页面上的 SharePoint Web 部件替换为外接程序部件，方法是使用 CSOM 查找和删除特定的 Web 部件，然后添加新的外接程序部件。

重要

不能将场解决方案迁移到 SharePoint Online。通过应用本文中介绍的方法和代码，你可以使用场解决方案提供的类似功能构建一个新的解决方案，然后可以将该解决方案部署到 SharePoint Online。应用这些技术后，页面将更新为使用外接程序部件，稍后可将其迁移到 SharePoint Online。

若要采用本文中的代码，还需要使用其他代码，才能生成完全正常的解决方案。例如，本文不讨论如何对 Office 365 进行身份验证、如何实现必需的异常处理，等等。有关其他代码示例，请参阅 Office 365 开发人员模式和做法项目。

注意

本文中的代码按原样提供，不提供任何明示或暗示的担保，包括对特定用途适用性、适销性或不侵权的默示担保。

要将 Web 部件替换为新的外接程序部件，请执行以下操作：

导出新的外接程序部件以获取外接程序部件定义。
使用外接程序部件定义在页面上创建新的外接程序部件。
查找具有要替换的 Web 部件的所有页面，然后删除 Web 部件。

准备工作

在执行本文中的步骤以将 Web 部件替换为外接程序部件之前，请确保：

使用配置为支持外接程序的 SharePoint 环境。SharePoint Online 配置为支持外接程序。如果你使用 SharePoint Server 本地部署，请参阅为 SharePoint Server 相关应用程序配置环境。
已将新的外接程序部件部署到 SharePoint。
已在 Web 上为你的外接程序分配 FullControl 权限。有关详细信息，请参阅 SharePoint 中的外接程序权限。

导出新的外接程序部件

要使用 CSOM 将 Web 部件替换为外接程序部件，则需要导出外接程序部件以获取外接程序部件定义。要导出外接程序部件以获取外接程序部件的定义，请执行以下操作：

打开你的 SharePoint 网站，选择“设置”或齿轮图标，然后选择“编辑页面”。
在功能区中选择“插入”>“外接程序部件”。
选择你的外接程序部件，然后选择“添加”。
将外接程序部件添加到你的页面后，在外接程序部件的右上角选择向下箭头，然后选择“编辑 Web 部件”。
在“高级”下的“导出模式”中，选择“导出所有数据”，然后选择“确定”。
返回到显示外接程序部件的编辑页面后，在外接程序部件的右上角选择向下箭头，然后选择“导出”。
选择“保存”。
下载完成后，选择“打开文件夹”。
打开“笔记本”，然后选择“文件”>“打开”。
选择下载的外接程序部件文件，再选择“打开”，查看外接程序部件定义。

<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 代码中使用外接程序部件定义，请执行以下操作：

在外接程序部件定义中，将所有双引号 (") 替换为一对双引号 ("")。
将外接程序部件定义分配到将在 CSOM 代码中使用的一个字符串。

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

查找要替换的 Web 部件

ReplaceWebPartsWithAppParts 通过以下方式开始查找要替换的 Web 部件：

从 Web 中获取一些属性以查找网站上的“页面”库。
在“页面”库中，获取列表项以及与列表项关联的文件。

对于从“页面”库返回的每个列表项，调用 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 部件

FindWebPartToReplace 通过以下方式查找应替换为新外接程序部件的 Web 部件：

将 page 设置为与从“页面”库返回的列表项关联的文件。
使用 LimitedWebPartManager 查找特定页面上的所有 Web 部件。每个 Web 部件的标题也会在 lambda 表达式中返回。

对于 Web 部件管理器的 WebParts 属性中的每个 Web 部件，确定 Web 部件的标题和 oldWebPartTitle 变量（设置为要替换的 Web 部件的标题）是否相同。如果 Web 部件标题与 oldWebPartTitle 相同，调用 ReplaceWebPart；否则，请继续执行 foreach 循环的下一次迭代。

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

ReplaceWebPart 通过以下方式替换新的 Web 部件：

使用 LimitedWebPartManager.ImportWebPart 将 appPartXml 中的 XML 字符串转换为 WebPartDefinition。
使用 LimitedWebPartManager.AddWebPart 将 Web 部件添加到特定 Web 部件区域中的某个页面。确保将 zoneId 传递到 AddWebPart，否则当运行 ExecuteQuery 时将抛出异常。

使用 WebPartDefinition.DeleteWebPart 从页面中删除旧 Web 部件。

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

   }

通过