Remplacer les composants WebPart SharePoint par des composants de complément dans les solutions de batterie de serveurs

Article
04/08/2023

Vous pouvez utiliser le processus de transformation pour remplacer des composants WebPart SharePoint par des composants de complément sur les pages en utilisant CSOM pour rechercher et supprimer des composants WebPart spécifiques et en ajoutant les nouveaux composants de complément.

Importante

Les solutions de batterie de serveurs ne peuvent pas être migrées vers SharePoint Online. En appliquant les techniques et le code décrits dans cet article, vous pouvez créer une nouvelle solution avec une fonctionnalité similaire offerte par votre solution de batterie de serveurs, laquelle peut ensuite être déployée sur SharePoint Online. Une fois ces techniques appliquées, vos pages seront mises à jour pour utiliser des composants de complément qui pourront être ensuite migrés vers SharePoint Online.

Le code dans cet article requiert un code supplémentaire pour offrir une solution totalement fonctionnelle. Par exemple, cet article ne traite pas de l’authentification à Office 365, de la manière d’implémenter la gestion des exceptions, etc. Pour plus d’exemples de code, reportez-vous à la rubrique Pratiques et modèles de développement Office 365.

Remarque

Le code dans cet article est fourni tel quel, sans garantie d’aucune sorte, expresse ou implicite, y compris mais sans s’y limiter, aucune garantie implicite d’adéquation à un usage particulier, à une qualité marchande ou une absence de contrefaçon.

Pour remplacer les composants WebPart par de nouveaux composants de complément :

Exportez le nouveau composant de complément pour obtenir la définition du composant de complément.
Créez le nouveau composant de complément dans la page à l’aide de la définition du composant de complément.
Recherchez toutes les pages contenant des composants WebPart à remplacer, puis supprimez les composants WebPart.

Avant de commencer

Avant d’effectuer les étapes décrites dans cet article pour remplacer vos composants WebPart par des composants de complément, vérifiez les éléments suivants :

Vous utilisez un environnement SharePoint configuré pour prendre en charge les compléments. SharePoint Online est configuré pour prendre en charge les compléments. Si vous utilisez SharePoint Server en local, consultez l’article Configurer un environnement pour les applications pour SharePoint Server.
Vous avez déployé votre nouveau composant de complément sur SharePoint.
Vous avez attribué vos autorisations FullControl sur le web. Pour en savoir plus, consultez l’article Autorisations des compléments dans SharePoint.

Exporter le nouveau composant de complément

Pour remplacer un composant WebPart par un composant de complément à l’aide de CSOM, vous devez obtenir la définition du composant de complément en exportant le composant de complément. Pour exporter le composant de complément en vue d’obtenir la définition du composant de complément :

Ouvrez votre site SharePoint, puis sélectionnez Paramètres ou l’icône d’engrenage, puis sélectionnez Modifier la page.
Sur le ruban, cliquez sur Insérer>Composant de complément.
Sélectionnez votre composant de complément, puis Ajouter.
Lorsque le composant de complément est ajouté à votre page, cliquez sur la flèche vers le bas dans le coin supérieur droit du composant de complément, puis sélectionnez Modifier le composant WebPart.
Dans Avancé, en Mode d’exportation, sélectionnez Exporter toutes les données, puis OK.
Lorsque vous revenez à la page de modification avec votre composant de complément affiché, sélectionnez la flèche vers le bas dans le coin supérieur droit du composant de complément, puis Exporter.
Cliquez sur Enregistrer.
Une fois le téléchargement terminé, sélectionnez Ouvrir le dossier.
Ouvrez le Bloc-notes, puis sélectionnez Fichier>Ouvrir.
Sélectionnez le fichier du composant de complément que vous avez téléchargé, puis Ouvrir pour afficher la définition du composant de complément.

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

Créer le nouveau composant de complément sur la page à l’aide de la définition du composant de complément

Pour utiliser la définition du composant de complément dans votre code CSOM :

Remplacez tous les guillemets doubles (") par une paire de guillemets doubles ("") dans la définition du composant de complément.
Affectez la définition du composant de complément à une chaîne qui sera utilisée dans votre code 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>";

Recherchez toutes les pages contenant des composants WebPart à remplacer, puis supprimez les composants WebPart.

Recherchez les composants WebPart à remplacer.

ReplaceWebPartsWithAppParts démarre le processus de recherche des composants WebPart à remplacer :

en obtenant certaines propriétés à partir du web pour trouver la bibliothèque Pages sur le site.
Dans la bibliothèque Pages, en obtenant les éléments de liste et le fichier associés aux éléments de liste.

Pour chaque élément de liste renvoyé par la bibliothèque Pages, en appelant 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);
         }
     }
 }

Recherchez les composants WebPart à remplacer par le nouveau composant de complément.

FindWebPartToReplace recherche les composants WebPart à remplacer par le nouveau composant de complément :

en définissant la page sur le fichier associé à l’élément de liste renvoyé par la bibliothèque Pages.
en utilisant LimitedWebPartManager pour trouver tous les composants WebPart sur une page spécifique. Le titre de chaque composant WebPart est également renvoyé dans l’expression lambda.

Pour chaque composant WebPart dans la propriété WebParts du gestionnaire de composants WebPart, en déterminant si le titre du composant WebPart et la variable oldWebPartTitle, qui est définie sur le titre du composant WebPart que vous remplacez, sont égaux. Si le titre du composant WebPart et la variable oldWebPartTitle sont égaux, appelez ReplaceWebPart ; sinon poursuivez avec l’itération suivante de la boucle 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);
     }
 }

Remplacer le nouveau composant WebPart

ReplaceWebPart remplace le nouveau composant WebPart :

en utilisant LimitedWebPartManager.ImportWebPart pour convertir la chaîne XML en appPartXml dans une Définition de composant WebPart.
en utilisant LimitedWebPartManager.AddWebPart pour ajouter un composant WebPart à une page dans une zone du composant WebPart spécifique. Veillez à transmettre zoneId à AddWebPart. Dans le cas contraire, une exception est levée lors de l’exécution de ExecuteQuery.

en utilisant WebPartDefinition.DeleteWebPart pour supprimer l’ancien composant WebPart de la 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();

   }

Partager via