Substituir web parts do SharePoint por partes de suplemento em soluções de farm

Artigo
04/08/2023

Você pode usar o processo de transformação para substituir web parts do SharePoint por partes de suplemento nas páginas usando o CSOM para localizar e remover web parts específicas e, em seguida, adicionar as novas partes de suplemento.

Importante

As soluções farm não podem ser migradas para o SharePoint Online. Aplicando as técnicas e o código descritos neste artigo, você pode criar uma nova solução com funcionalidades semelhantes que suas soluções de farm fornecem, que podem ser implantadas no SharePoint Online. Depois de aplicar essas técnicas, suas páginas serão atualizadas para usar partes de suplemento, que podem ser migradas para o SharePoint Online.

O código neste artigo requer código adicional para fornecer uma solução totalmente funcional. Por exemplo, este artigo não discute como autenticar a Office 365, como implementar o tratamento de exceção necessário e assim por diante. Para obter exemplos de código adicionais, consulte o projeto padrões e práticas do desenvolvedor Office 365.

Observação

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.

Para substituir web parts por novas partes de suplemento:

Exporte a nova parte do suplemento para obter a definição da parte de suplemento.
Crie a nova parte de suplemento na página usando a definição da parte de suplemento.
Localize todas as páginas com web parts a serem substituídas e remova as Web Parts.

Antes de começar

Antes de executar as etapas neste artigo para substituir suas web parts por partes de suplemento, verifique se:

Você está usando um ambiente do SharePoint configurado para dar suporte a suplementos. O SharePoint Online está configurado para dar suporte a suplementos. Se você estiver usando o SharePoint Server local, consulte Configurar um ambiente para aplicativos para o SharePoint Server.
Você implantou sua nova parte de suplemento no SharePoint.
Você atribuiu suas permissões fullcontrol de suplementos na Web. Para saber mais, confira Permissões de suplementos no SharePoint.

Exportar a nova parte de suplemento

Para usar o CSOM para substituir uma Web Part por uma parte de suplemento, você precisa obter a definição de parte do suplemento exportando a parte de suplemento. Para exportar a parte de suplemento para obter a definição da parte de suplemento:

Abra seu site do SharePoint e escolha Configurações ou o ícone de engrenagem e escolha Editar página.
Na faixa de opções, escolha Insert>Add-in Part.
Escolha sua parte de suplemento e escolha Adicionar.
Quando a parte de suplemento for adicionada à sua página, escolha a seta para baixo no canto superior direito da parte de suplemento e escolha Editar Web Part.
Em Avançado, no Modo de Exportação, escolha Exportar todos os dados e escolha OK.
Quando você retornar à página de edição com a parte de suplemento exibida, escolha a seta para baixo no canto superior direito da parte de suplemento e escolha Exportar.
Escolha Salvar.
Depois que o download for concluído, escolha Abrir pasta.
Abra o Bloco de Notas e, em seguida, escolha Abrir arquivo>.
Escolha o arquivo de parte de suplemento que você baixou e escolha Abrir para exibir a definição da parte de suplemento.

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

Criar a nova parte de suplemento na página usando a definição de parte do suplemento

Para usar a definição de parte de suplemento em seu código CSOM:

Substitua todas as aspas duplas (") por um par de aspas duplas ("") na definição da parte de suplemento.
Atribua a definição de parte de suplemento a uma cadeia de caracteres que será usada em seu código 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>";

Encontre todas as páginas com web parts a serem substituídas e remova as Web Parts

Localizar as Web Parts a serem substituídas

ReplaceWebPartsWithAppParts inicia o processo de localização das web parts a serem substituídas por:

Obtendo algumas propriedades da Web para localizar a biblioteca De páginas no site.
Na biblioteca Páginas , obter os itens de lista e o arquivo associados aos itens de lista.

Para cada item de lista retornado da biblioteca Páginas , chamando 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);
         }
     }
 }

Localizar web parts a serem substituídos por uma nova parte de suplemento

FindWebPartToReplace localiza web parts que devem ser substituídas pela nova parte de suplemento por:

Página de configuração para o arquivo associado ao item de lista retornado da biblioteca De páginas.
Usando LimitedWebPartManager para localizar todas as Web Parts em uma página específica. O título de cada web part também é retornado na expressão lambda.

Para cada Web Part na propriedade WebParts do web part manager, determinar se o título da Web Part e a variável oldWebPartTitle , que é definida como o título da Web Part que você está substituindo, são iguais. Se o título da Web Part e o oldWebPartTitle forem iguais, chame ReplaceWebPart; caso contrário, continue com a próxima iteração do loop 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);
     }
 }

Substituir a nova Web Part

ReplaceWebPart substitui a nova Web Part por:

Usando LimitedWebPartManager.ImportWebPart para converter a cadeia de caracteres XML no appPartXml em um WebPartDefinition.
Usando LimitedWebPartManager.AddWebPart para adicionar uma Web Part a uma página em uma zona de Web Part específica. Verifique se você passa a zoneId para AddWebPart, caso contrário, uma exceção será gerada quando ExecuteQuery for executada.

Usando WebPartDefinition.DeleteWebPart para excluir a Web Part antiga da página.

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

   }

Partilhar via