Замена веб-частей SharePoint частями надстроек в решениях фермы

Статья
04/08/2023

Процесс преобразования можно использовать для замены веб-частей SharePoint частями надстроек на страницах с помощью CSOM для поиска и удаления определенных веб-частей, а затем добавления новых частей надстройки.

Важно!

Решения фермы нельзя перенести в SharePoint Online. Применив методы и код, описанные в этой статье, вы можете создать новое решение с функциями, аналогичными функциями, предоставляемыми решениями фермы, которое затем можно развернуть в SharePoint Online. После применения этих методов страницы будут обновлены для использования частей надстроек, которые затем можно перенести в SharePoint Online.

Код, приведенный в этой статье, требует дополнительного кода, чтобы обеспечить полностью работающее решение. Например, в этой статье не рассматривается проверка подлинности для Office 365, реализация необходимой обработки исключений и т. д. Дополнительные примеры кода см. в проекте шаблоны и методики разработчика Office 365.

Примечание.

Код, приведенный в этой статье, предоставляется "как есть" без какой-либо явной или подразумеваемой гарантии, включая подразумеваемые гарантии пригодности для какой-либо цели, для продажи или гарантии отсутствия нарушения прав иных правообладателей.

Чтобы заменить веб-части новыми частями надстройки, выполните следующие действия:

Экспортируйте новую часть надстройки, чтобы получить определение части надстройки.
Создайте новую часть надстройки на странице с помощью определения части надстройки.
Найдите все страницы с веб-частями для замены, а затем удалите веб-части.

Подготовка к работе

Перед выполнением действий, описанных в этой статье, чтобы заменить веб-части частями надстройки, убедитесь, что:

Вы используете среду SharePoint, настроенную для поддержки надстроек. SharePoint Online настроен для поддержки надстроек. Если вы используете SharePoint Server в локальной среде, см . статью Настройка среды для приложений для SharePoint Server.
Вы развернули новую часть надстройки в SharePoint.
Вы назначили надстройкам разрешения FullControl в Интернете. Дополнительные сведения см. в статье Разрешения для надстроек в SharePoint.

Экспорт новой части надстройки

Чтобы использовать CSOM для замены веб-части надстройкой, необходимо получить определение части надстройки путем экспорта части надстройки. Чтобы экспортировать часть надстройки, чтобы получить ее определение, выполните следующие действия:

Откройте сайт SharePoint, выберите Параметры или значок шестеренки, а затем выберите Изменить страницу.
На ленте выберите ВСТАВИТЬ>часть надстройки.
Выберите часть надстройки и нажмите кнопку Добавить.
Когда часть надстройки будет добавлена на страницу, щелкните стрелку вниз в правом верхнем углу части надстройки, а затем выберите Изменить веб-часть.
В разделе Дополнительно в режиме экспорта выберите Экспорт всех данных, а затем нажмите кнопку ОК.
Когда вы вернеесь на страницу редактирования с отображаемой частью надстройки, щелкните стрелку вниз в правом верхнем углу части надстройки и нажмите кнопку Экспорт.
Выберите Сохранить.
После завершения загрузки выберите Открыть папку.
Откройте Блокнот, а затем выберите Открыть файл>.
Выберите скачанный файл части надстройки, а затем нажмите кнопку Открыть , чтобы просмотреть определение части надстройки.

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

Поиск всех страниц с веб-частями для замены, а затем удаление веб-частей

Поиск веб-частей для замены

ReplaceWebPartsWithAppParts запускает процесс поиска веб-частей для замены:

Получение некоторых свойств из Интернета для поиска библиотеки Pages на сайте.
В библиотеке Pages овладейте элементами списка и файлом, связанным с элементами списка.

Для каждого элемента списка, возвращаемого из библиотеки Pages , вызывается метод 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 находит веб-части, которые должны быть заменены новой частью надстройки:

Настройка страницы для файла, связанного с элементом списка, возвращенным из библиотеки Pages .
Использование LimitedWebPartManager для поиска всех веб-частей на определенной странице. Заголовок каждой веб-части также возвращается в лямбда-выражении.

Для каждой веб-части в свойстве WebParts диспетчера веб-частей определите, равны ли заголовок веб-части и переменная oldWebPartTitle , которая имеет заголовок заменяемой веб-части. Если заголовок веб-части и 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);
     }
 }

Замена новой веб-части

ReplaceWebPart заменяет новую веб-часть следующими:

Использование LimitedWebPartManager.ImportWebPart для преобразования XML-строки в appPartXml в WebPartDefinition.
Использование LimitedWebPartManager.AddWebPart для добавления веб-части на страницу в определенной зоне веб-части. Убедитесь, что вы передаете zoneIdв AddWebPart, в противном случае при выполнении ExecuteQuery возникнет исключение.

С помощью WebPartDefinition.DeleteWebPart удалите старую веб-часть со страницы.

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

   }

Поделиться через