Reemplazar elementos web de SharePoint por elementos de complemento en soluciones de granja de servidores

Artículo
04/08/2023

Puede usar el proceso de transformación para reemplazar elementos web de SharePoint por elementos de complemento en las páginas usando CSOM para buscar y eliminar elementos web específicos y agregando después los nuevos elementos del complemento.

Importante

Las soluciones de granja no se pueden migrar a SharePoint Online. Al aplicar las técnicas y el código descrito en este artículo, puede crear una nueva solución con funciones similares a las que proporcionan las soluciones de granja de servidores, que pueden implementar después en SharePoint Online. Después de aplicar estas técnicas, las páginas se actualizarán para usar elementos de complemento, que se pueden migrar después a SharePoint Online.

El código de este artículo requiere código adicional para ofrecer una solución que funcione completamente. Por ejemplo, en este artículo no se explica cómo autenticar Office 365, cómo implementar excepciones necesarias, etc. Para obtener ejemplos de código adicionales, consulte el Proyecto de patrones y prácticas para desarrolladores de Office 365.

Nota:

El código de este artículo se proporciona tal cual, sin garantía de ningún tipo, expresa o implícita, incluidas las garantías implícitas de aptitud para un propósito particular, comerciabilidad o ausencia de infracción.

Reemplazar elementos web por elementos de complemento:

Exporte el nuevo elemento de complemento para obtener su definición.
Cree el nuevo elemento de complemento en la página con la definición de este.
Busque todas las páginas con elementos web para sustituir y, a continuación, elimínelos.

Antes de empezar

Antes de realizar los pasos de este artículo para reemplazar los elementos web con elementos de complemento, asegúrese de que:

Su entorno de SharePoint está configurado para admitir complementos. SharePoint Online está configurado para admitir complementos. Si usa SharePoint Server local, consulte Configuración de un entorno para aplicaciones de SharePoint.
El nuevo elemento de complemento se ha implementado en SharePoint.
Ha asignado a los complementos permisos FullControl en la Web. Para obtener más información, consulte Permisos de complementos en SharePoint.

Exportar el nuevo elemento de complemento

Para usar CSOM para reemplazar un elemento web por un elemento de complemento, deberá obtener la definición del elemento de complemento mediante su exportación. Para exportar el nuevo elemento de complemento para obtener su definición:

Abra el sitio de SharePoint y elija Configuración, o el icono de engranaje, y después elija Editar página.
En la cinta de opciones, elija Insertar>Elemento de complemento.
Elija su elemento de complemento y, luego, seleccione Agregar.
Cuando la parte del complemento se haya agregado a la página, elija la flecha hacia abajo en la esquina superior derecha del elemento de complemento y, después, elija Editar elemento web.
En Opciones avanzadas, en el Modo exportar, elija Exportar todos los datosy, por último, Aceptar.
Cuando regrese a la página de edición, donde se mostrará el elemento de complemento, elija la flecha hacia abajo en la esquina superior derecha del elemento de complemento y, después, elija Exportar.
Seleccione Guardar.
Una vez completada la descarga, elija Abrir carpeta.
Abra el Bloc de notasy elija Archivo>Abrir.
Seleccione el archivo de elemento de complemento que descargó y, después, elija Abrir para ver la definición del elemento de complemento.

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

Crear el nuevo elemento de complemento en la página con la definición de este.

Para usar la definición del elemento de complemento en el código CSOM:

Reemplace todas las comillas dobles (") por un par de comillas dobles ("") en la definición del elemento de complemento.
Asigne la definición del elemento de complemento a una cadena que se usará en el 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>";

Buscar todas las páginas con elementos web para sustituir y, a continuación, eliminarlas.

Busque los elementos web para reemplazar

ReplaceWebPartsWithAppParts inicia el proceso de buscar los elementos web para sustituir. Para ello:

Obtiene algunas propiedades de la Web para encontrar la biblioteca de Páginas del sitio.
En la biblioteca de Páginas, obtiene los elementos de lista y el archivo asociados con los elementos de lista.

Por cada elemento de lista devuelto de la biblioteca de Páginas, llama a 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);
         }
     }
 }

Buscar elementos web para sustituirlos por un nuevo elemento de complemento

FindWebPartToReplace busca elementos web para reemplazar por el nuevo elemento de complemento. Para ello:

Configura la página del archivo asociado con el elemento de lista devuelto por la biblioteca de Páginas.
Usa LimitedWebPartManager para encontrar todos los elementos web en una página específica. El título de cada elemento web también se devuelve en la expresión lambda.

Por cada elemento web de la propiedad WebParts del Administrador de elementos web, determina si el título del elemento web y la variable oldWebPartTitle, que se establece con el título del elemento web que se va a reemplazar, son iguales. Si el título del elemento web y oldWebPartTitle son iguales, llame a ReplaceWebPart; en caso contrario, continúe con la siguiente iteración del bucle 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);
     }
 }

Reemplazar el nuevo elemento web

ReplaceWebPart reemplaza el nuevo elemento web. Para ello:

Usa LimitedWebPartManager.ImportWebPart para convertir la cadena XML en appPartXml en una WebPartDefinition.
Usa LimitedWebPartManager.AddWebPart para agregar un elemento web a una página en una zona específica de los elementos web. Asegúrese de que pasa el zoneId a AddWebPart; en caso contrario, se produce una excepción cuando al ejecutar ExecuteQuery.

Usa WebPartDefinition.DeleteWebPart para eliminar de la página el elemento web anterior.

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

   }

Compartir a través de