Ersetzen von SharePoint-Webparts durch Add-In-Webparts in Farm-Lösungen

Artikel
04/08/2023

Mit dem Transformationsprozesses können Sie SharePoint-Webparts durch Add-In-Webparts auf Seiten ersetzen, indem Sie CSOM verwenden, um bestimmte Webparts zu suchen und zu entfernen und dann neue Add-In-Webparts hinzuzufügen.

Wichtig

Farm-Lösungen können nicht zu SharePoint Online migriert werden. Durch Anwenden der Techniken und des Codes, die in diesem Artikel beschrieben sind, können Sie eine neue Lösung mit ähnlichen Funktionen wie die Ihrer Farm-Lösungen erstellen, die dann auf SharePoint Online bereitgestellt werden kann. Nachdem Sie diese Techniken angewendet haben, werden Ihre Seiten aktualisiert, um Add-in-Webparts zu verwenden, die dann zu SharePoint Online migriert werden können.

Der Code in diesem Artikel erfordert zusätzlichen Code für die Bereitstellung einer vollständig funktionierenden Lösung. Beispielsweise wird in diesem Artikel nicht erläutert, wie Sie sich bei Office 365 authentifizieren, wie die erforderliche Ausnahmenbehandlung implementiert wird und so weiter. Weitere Codebeispiele, finden Sie unter Office 365 Developer Patterns and Practices Project.

Hinweis

Der Code in diesem Artikel wird wie besehen und ohne jegliche Garantie zur Verfügung gestellt, gleich ob ausdrücklich oder konkludent, einschließlich jedweder stillschweigenden Gewährleistung der Eignung für einen bestimmten Zweck, Marktgängigkeit oder Nichtverletzung von Rechten.

So ersetzen Sie Webparts durch neue Add-In-Webparts:

Exportieren Sie das neue Add-In-Webpart, um die Definition für das Add-In-Webpart zu erhalten.
Erstellen Sie das neue Add-In-Webpart auf der Seite, indem Sie die Definition für das Add-In-Webpart verwenden.
Suchen Sie alle Seiten mit Webparts, die ersetzt werden sollen, und entfernen Sie dann die Webparts.

Bevor Sie beginnen

Ersetzen Sie vor dem Durchführen der Schritte in diesem Artikel Ihre Webparts durch Add-In-Webparts:

Sie verwenden eine SharePoint-Umgebung, die so konfiguriert ist, dass Add-Ins unterstützt werden SharePoint Online unterstützt Add-Ins ebenfalls. Wenn Sie SharePoint Server lokal verwenden, informieren Sie sich unter Konfigurieren einer Umgebung für Apps für SharePoint Server.
Sie haben das neue Add-In-Webpart in SharePoint bereitgestellt.
Sie haben Ihren Add-Ins FullControl-Berechtigungen für das Web zugewiesen. Weitere Informationen finden Sie unter Add-In-Berechtigungen in SharePoint.

Exportieren des neuen Add-In-Webpart

Wenn Sie CSOM verwenden, um ein Webpart durch ein Add-In-Webpart zu ersetzen, müssen Sie die Definition für das Add-In-Webpart abrufen, indem Sie das Add-In-Webpart exportieren. So exportieren Sie das Add-In-Webpart, um die Definition für das Add-In-Webpart zu erhalten:

Öffnen Sie Ihre SharePoint-Site und wählen Sie Einstellungen oder das Zahnradsymbol, und wählen Sie dann die Seite „Bearbeiten“.
Wählen Sie im Menüband EINFÜGEN>Add-In-Webpart.
Wählen Sie Ihr Add-In-Webpart und dann Hinzufügen.
Wenn das Add-In-Webpart zu Ihrer Seite hinzugefügt wird, wählen Sie den Nach-unten-Pfeil oben rechts im Add-In-Webpart, und wählen Sie dann Webpart bearbeiten.
Wählen Sie bei Erweitert, unter Exportmodus die Option Alle Daten exportieren und dann OK.
Wenn Sie zur Bearbeitungsseite zurückkehren und das Add-In-Webpart angezeigt wird, wählen Sie den Nach-unten-Pfeil oben rechts im Add-In-Webpart, und wählen Sie dann Exportieren.
Wählen Sie Speichern aus.
Nachdem der Download abgeschlossen ist, wählen Sie Ordner öffnen.
Öffnen Sie den Editor, und wählen Sie dann Datei>Öffnen.
Wählen Sie die Add-In-Webpart-Datei, die Sie heruntergeladen haben, und wählen Sie dann Öffnen, um die Definition für das Add-In-Webpart anzuzeigen.

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

Erstellen des neuen Add-In-Webpart auf der Seite, indem Sie die Definition für das Add-In-Webpart verwenden

So verwenden Sie die Definition für das Add-In-Webpart in Ihrem CSOM-Code:

Ersetzen Sie alle doppelten Anführungszeichen (") durch ein Paar doppelte Anführungszeichen (" ") in der Definition für das Add-In-Webpart.
Weisen Sie die Definition für das Add-In-Webpart einer Zeichenfolge zu, die in Ihrem CSOM-Code verwendet wird.

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

Suchen aller Seiten mit Webparts, die ersetzt werden sollen, und Entfernen der Webparts

Suchen der Webparts, die ersetzt werden sollen

ReplaceWebPartsWithAppParts startet die Suche der Webparts, die wie folgt ersetzt werden sollen:

durch Abrufen einiger Eigenschaften aus dem Web für die Suche der Bibliothek Seiten auf der Site.
durch Abrufen der Listenelemente und der mit den Listenelementen verknüpften Datei in der Bibliothek Seiten.

durch Abrufen von FindWebPartToReplace für jedes Listenelement, das aus der Bibliothek Seiten zurückgegeben wird.

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

Suchen von Webparts, die durch das neue Add-In-Webpart ersetzt werden

FindWebPartToReplace sucht Webparts, die wie folgt durch das neue Add-In-Webpart ersetzt werden sollen:

durch Festlegen der Seite auf die Datei, die mit dem Listenartikel verknüpft ist, der von der Bibliothek Seiten zurückgegeben wird.
durch Verwenden von LimitedWebPartManager zur Suche aller Webparts auf einer bestimmten Seite. Der Titel jedes Webpart wird auch im Lambda-Ausdruck zurückgegeben.

durch Festlegen, ob der Titel des Webpart und die Variable oldWebPartTitle, die auf den Titel des Webparts festgelegt ist, das Sie ersetzen, gleich sind (für jedes Webpart in der Eigenschaft WebParts des Webpart-Managers). Wenn der Titel des Webpart und oldWebPartTitle gleich sind, rufen Sie ReplaceWebPart auf; fahren Sie andernfalls mit der nächsten Iteration der Schleife foreach fort.

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

Ersetzen des neuen Webpart

ReplaceWebPart ersetzt das neue Webpart wie folgt:

durch das Verwenden von LimitedWebPartManager.ImportWebPart zum Konvertieren der XML-Zeichenfolge in appPartXml in eine WebPartDefinition.
durch Verwenden von LimitedWebPartManager.AddWebPart zum Hinzufügen eines Webpart zu einer Seite in einer speziellen Webpart-Zone. Stellen Sie sicher, dass Sie zoneId an AddWebPart übergeben; andernfalls wird eine Ausnahme ausgelöst, wenn ExecuteQuery ausgeführt wird.

durch Verwenden von WebPartDefinition.DeleteWebPart zum Löschen des alten Webpart von dieser Seite.

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

   }

Freigeben über