Transformieren ausgewählter klassischer Seiten mit PnP PowerShell

Das Microsoft 365-Bewertungstool inventarisieren klassische Seiten, ändert sie jedoch nicht. Verwenden Sie die Bewertungsausgabe, um eine Seitenwelle zu genehmigen, und verwenden Sie PnP PowerShell ConvertTo-PnPPage , um die modernen Seiten zu erstellen.

Hinweis

PnP PowerShell ist eine Open Source-Lösung mit aktiver Community, die Support dafür bietet. Es gibt keine SLA für den Support des Open-Source-Tools durch Microsoft.

Seitentransformationsworkflow

  1. Wählen Sie eine repräsentative Seitenwelle aus der abgeschlossenen Bewertungsabdeckung aus.
  2. Beheben Sie blockierende Webparts, und wählen Sie ein direktes oder websiteübergreifendes Ziel aus.
  3. Bereiten Sie eine mandanteneigene PnP-PowerShell-Anwendung und die erforderlichen Berechtigungen vor.
  4. Transformieren Sie die repräsentative Welle mit quellenerhaltenden Standardwerten und Protokollierungen.
  5. Überprüfen Sie jede generierte Seite, bevor Sie die Welle erweitern.

Bevor Sie beginnen

Erfüllen Sie die folgenden Voraussetzungen:

  1. Führen Sie die Bewertung klassischer Seiten aus, und interpretieren Sie sie.
  2. Wählen Sie eine repräsentative Welle aus einer erfolgreichen Scanabdeckung aus.
  3. Installieren Sie PowerShell 7.4.0 oder höher und die aktuelle stabile PnP PowerShell-Version.
  4. Registrieren Sie eine mandanteneigene Microsoft Entra-Anwendung für interaktive PnP PowerShell.
  5. Vergewissern Sie sich, dass der angemeldete Benutzer Seiten in den Quell- und Zielwebs bearbeiten kann.

Seit dem 9. September 2024 erfordert die interaktive PnP-PowerShell-Authentifizierung Ihre eigene Anwendungsregistrierung und Client-ID.

Das Konto, das die Anwendung registriert, muss zum Erstellen von App-Registrierungen berechtigt sein. Die Mandantenzustimmungsrichtlinie bestimmt, ob ein Administrator die Zustimmung erteilen muss.

Berechtigungen

Verwenden Sie eine separate delegierte Anwendung von der schreibgeschützten Bewertungsanwendung.

Transformationsanforderung Delegierter SharePoint-Bereich
Lesen der Quelle und Erstellen, Speichern und Veröffentlichen der modernen Seite AllSites.Manage
Außerdem können Sie eindeutige Berechtigungen auf Elementebene kopieren. AllSites.FullControl

Die Websiteberechtigungen des angemeldeten Benutzers gelten ebenfalls. Der delegierte Bereich der Anwendung gewährt dem Benutzer keinen Zugriff auf eine Website, auf die er andernfalls nicht zugreifen konnte.

Fügen AllSites.ManageSie mit hinzu -SkipItemLevelPermissionCopyToClientSidePage , damit die generierte Seite Berechtigungen von ihrer Bibliothek erbt. Verwenden Sie AllSites.FullControl diese Option nur, wenn die eindeutigen Berechtigungen der Seite beibehalten werden müssen.

Weitere Informationen finden Sie unter Migrieren klassischer Seiten mit der geringstmöglichen Berechtigung.

Installieren oder Aktualisieren von PnP PowerShell

PnP PowerShell erfordert PowerShell 7.4.0 oder höher.

$PSVersionTable.PSVersion
Install-Module PnP.PowerShell -Scope CurrentUser

Wenn PnP PowerShell bereits installiert ist, führen Sie Update-Module PnP.PowerShell powerShell 7.4.0 oder höher aus.

Weitere Informationen finden Sie unter Installieren von PnP PowerShell.

Registrieren der interaktiven Transformationsanwendung

Der folgende Befehl erstellt eine öffentliche Clientanwendung für die interaktive Anmeldung:

Register-PnPEntraIDAppForInteractiveLogin `
  -ApplicationName "Classic Page Transformation" `
  -Tenant "<tenant>.onmicrosoft.com" `
  -SharePointDelegatePermissions AllSites.Manage `
  -SignInAudience AzureADMyOrg

Kopieren Sie die zurückgegebene Anwendungs-ID. Abhängig von der Mandantenzustimmungsrichtlinie muss ein Administrator möglicherweise vor der ersten Verbindung seine Zustimmung erteilen.

Diese öffentliche Clientregistrierung ist für delegierte interaktive Anmeldungen oder Geräteanmeldungen vorgesehen. Es stellt nicht die Anwendungsberechtigungen oder das Zertifikat bereit, die für die unbeaufsichtigte Authentifizierung erforderlich sind.

Informationen zur manuellen Registrierung und anderen Authentifizierungsmethoden finden Sie unter Registrieren einer Entra-ID-Anwendung für PnP PowerShell.

Geben Sie für GCC High, DoD oder Microsoft 365, betrieben von 21Vianet, den übereinstimmenden -AzureEnvironment Wert an, wenn Sie die Anwendung registrieren und eine Verbindung herstellen. Weitere Informationen finden Sie unter den Cmdlets Register-PnPEntraIDAppForInteractiveLogin und Connect-PnPOnline .

Zuordnen einer Bewertungszeile zu PnP PowerShell

Bewertungsfeld PnP PowerShell-Verwendung
SiteUrl + WebUrl Quell-URL für Connect-PnPOnline.
ListUrl, ListId, PageUrl Genaue SitePages Bibliotheks- und Quelldateiidentität.
PageType Muss oder WebPartPage für diesen Workflow seinWikiPage.
Layout Gruppierung und Validierung repräsentativer Muster.

Vor dem Transformieren einer Seite mit der ersten Welle ist Folgendes erforderlich:

  • Erfolgreiche Website- und Webabdeckung.
  • PageType gleich WikiPage oder WebPartPage.
  • Keine nicht aufgelösten, nicht zugeordneten Webparts.
  • WebPartCount größer als 0. Verarbeiten von nullteiligen Seiten außerhalb dieses automatisierten Beispiels nach manueller Überprüfung.
  • Eine Quellseite, die Berechtigungen von ihrer Bibliothek erbt.
  • Eine aufgezeichnete Inhalts- und Layoutbaseline für die Überprüfung.

Erstellen repräsentativer Seitengruppen

Mit dem folgenden Skript wird ein Kandidatenbestand erstellt. Seiten werden nicht transformiert.

Es gruppiert berechtigte Wiki- und Webpartseiten nach Seitentyp, Layout und geordneter Webpartsignatur. Die Signatur umfasst den Webparttyp, das Zuordnungsergebnis, den ausgeblendeten Zustand und den Zustand "Geschlossen".

$pages = Import-Csv .\classicpages.csv
$webParts = Import-Csv .\classicpagewebparts.csv
$partsByPage = @{}

function Get-PageKey {
  param($Row)

  '{0}|{1}|{2}|{3}' -f $Row.ScanId, $Row.SiteUrl, $Row.WebUrl, $Row.PageUrl
}

foreach ($part in $webParts) {
  $key = Get-PageKey $part
  if (-not $partsByPage.ContainsKey($key)) {
    $partsByPage[$key] = [Collections.Generic.List[object]]::new()
  }

  $partsByPage[$key].Add($part)
}

$candidates = foreach ($page in $pages) {
  $fileName = [IO.Path]::GetFileName($page.PageUrl)

  if ($page.PageType -notin @('WikiPage', 'WebPartPage') -or
      $page.HomePage -eq 'True' -or
      -not $page.ListUrl.EndsWith('/SitePages', [StringComparison]::OrdinalIgnoreCase) -or
      $page.WebPartCount -eq '0' -or
      $page.MappingPercentage -ne '100' -or
      -not [string]::IsNullOrWhiteSpace($page.UnmappedWebParts) -or
      $fileName.StartsWith('Migrated_', [StringComparison]::OrdinalIgnoreCase) -or
      $fileName.StartsWith('Previous_', [StringComparison]::OrdinalIgnoreCase)) {
    continue
  }

  $key = Get-PageKey $page
  if (-not $partsByPage.ContainsKey($key)) {
    throw "Web Part rows are missing for $($page.PageUrl)."
  }

  $signature = (
    $partsByPage[$key] |
      Sort-Object { [int]$_.WebPartIndex } |
      ForEach-Object {
        '{0}|Mappable={1}|Hidden={2}|Closed={3}' -f
          $_.WebPartTypeShort, $_.IsMappable, $_.Hidden, $_.IsClosed
      }
  ) -join ';'

  [pscustomobject]@{
    PatternKey = '{0}|{1}|{2}' -f $page.PageType, $page.Layout, $signature
    ScanId = $page.ScanId
    SiteUrl = $page.SiteUrl
    WebUrl = $page.WebUrl
    PageUrl = $page.PageUrl
    PageType = $page.PageType
    ListUrl = $page.ListUrl
    ListId = $page.ListId
    AssessmentTimeZoneId = [TimeZoneInfo]::Local.Id
    Layout = $page.Layout
    HomePage = $page.HomePage
    WebPartCount = [int]$page.WebPartCount
    MappingPercentage = $page.MappingPercentage
    UnmappedWebParts = $page.UnmappedWebParts
    ModifiedAt = $page.ModifiedAt
    WebPartSignature = $signature
    IncludePattern = 'True'
    Selected = 'False'
    ExpectedVisibleContent = ''
    ValidationOwner = ''
  }
}

$groups = $candidates | Group-Object PatternKey -AsHashTable -AsString

$candidateInventory = foreach ($candidate in $candidates) {
  $candidate | Select-Object *,
    @{ Name = 'PatternPageCount'; Expression = { $groups[$candidate.PatternKey].Count } }
}

$candidateInventory |
  Sort-Object PatternKey, PageUrl |
  Export-Csv .\representative-page-groups.csv -NoTypeInformation

Überprüfen Und representative-page-groups.csv wählen Sie mindestens eine Seite aus jeder PatternKey Seite aus, die die Migrationswelle enthalten wird. Wählen Sie zusätzliche Seiten aus, wenn Webparteigenschaften, verknüpfte Inhalte oder Geschäftsverhalten innerhalb eines Musters erheblich abweichen.

Legen Sie für Muster außerhalb der geplanten Migration fest IncludePattern=False . Legen Sie für jede ausgewählte Seite fest Selected=True , und füllen Sie ExpectedVisibleContent und aus ValidationOwner.

Führen Sie den Gruppierungsschritt auf demselben Computer aus, auf dem die Bewertungs-CSVs generiert wurden. AssessmentTimeZoneId zeichnet die Zeitzone auf, die zum Interpretieren des offsetfreien ModifiedAt Werts verwendet wird.

Speichern Sie nullteilige Seiten, Startseiten, Veröffentlichungsseiten und Seiten mit nicht aufgelösten Zuordnungen in separaten Überprüfungswarteschlangen. Seiten außerhalb der Standardbibliothek SitePages verbleiben ebenfalls im separat überprüften Single-Page-Pfad.

Grundlegendes zu den Standardwerten, die quellenerhaltend sind

Achtung

-TakeSourcePageName benennt die klassische Quellseite um und -Overwrite ersetzt eine vorhandene Zielseite. Verwenden Sie keine der beiden Optionen, bis die generierten Seiten genehmigt wurden und ein Rollbackplan vorhanden ist.

Option First-Wave-Leitfaden
Standardbenennung Behalten Sie den Quellnamen bei, und erstellen Sie Migrated_<source-page>.aspx.
-TakeSourcePageName Verwenden Sie nicht zuerst. Die klassische Quelle wird mit einem Previous_ Präfix umbenannt.
-Overwrite Verwenden Sie nicht zuerst. Überprüfen Sie ein vorhandenes Ziel, anstatt es automatisch zu ersetzen.
-ReplaceHomePageWithDefault Verwenden Sie nicht in einer repräsentativen Welle.
-DontPublish Verwenden Sie für die erste Welle, damit die generierte Seite während der Überprüfung ein Entwurf bleibt.
-SkipItemLevelPermissionCopyToClientSidePage Verwenden Sie mit der AllSites.Manage Anwendung, es sei denn, eindeutige Berechtigungen müssen kopiert werden.

Rollback eines Entwurfs der ersten Welle

Der Batchworkflow benennt die klassische Quellseite nicht um oder überschreibt sie nicht. Wenn die Überprüfung eines generierten Entwurfs fehlschlägt:

  1. Halten Sie die klassische Quellseite in Betrieb.
  2. Behalten Sie TransformationStatus=Createdbei, legen Sie ValidationStatus=Failedfest, und füllen Sie ValidationNotes, ValidatedByund aus ValidatedAt.
  3. Behalten Sie TargetPageUrl und LogPath mit dem Fehlerhaften Validierungsbeweis bei.
  4. Den generierten Migrated_ Entwurf aus der Websiteseitenbibliothek wiederverwenden, wenn er nicht mehr zur Untersuchung benötigt wird und die Aufbewahrungsrichtlinie des organization das Entfernen zulässt.
  5. Korrigieren Sie die Kandidatenregel oder Korrektur, und wiederholen Sie eine repräsentative Seite, bevor Sie die Welle fortsetzen.

-Overwrite und -TakeSourcePageName befinden sich außerhalb des Batchworkflows. Bevor Sie eine der beiden Optionen in einem separaten Verfahren verwenden, behalten Sie die Seitenversionen und URLs bei, notieren Sie die aktuelle Homepageeinstellung, testen Sie den umgekehrten Umbenennungs- oder Wiederherstellungsprozess auf einer Nichtproduktionswebsite, und holen Sie eine explizite Genehmigung ein.

Transformieren einer ausgewählten Wiki- oder Webpartseite

Verwenden Sie das Skript für repräsentative Seiten mit einer Zeile, die als markiert ist Selected=True. Dadurch bleibt der einseitige Test auf demselben Validierungs-, Authentifizierungs- und Ergebnisvertrag wie eine größere Welle.

Die Batchskripts unterstützen Wiki- und Webpartseiten in der Standardbibliothek SitePages . Sie schließen Homepages, nullteilige Seiten, Seiten mit eindeutigen Berechtigungen und Seiten aus, die nach der Bewertung geändert wurden. Behandeln Sie diese Seiten über einen separat überprüften Pfad.

Transformieren aller repräsentativen Seiten

Speichern Sie die drei eingebetteten Dateien aus dem Seitenwellenskriptverweis im selben Ordner.

In representative-page-groups.csv:

  1. Legen Sie für jedes Transformationsmuster in der geplanten Migration fest IncludePattern=True .
  2. Legen Sie Selected=True in jedem enthaltenen Muster auf mindestens einer Seite fest.
  3. Füllen Sie ExpectedVisibleContent und ValidationOwner für jede ausgewählte Seite aus.

Zeigen Sie eine Vorschau der gesamten Welle an, ohne SharePoint-Seiten zu authentifizieren oder zu schreiben:

.\Convert-RepresentativePages.ps1 `
  -ManifestPath .\representative-page-groups.csv `
  -ClientId "<application-id>" `
  -AuthenticationMode Interactive `
  -WhatIf `
  -Force

Die CSV-Vorschaudatensätze PlannedAction und PlannedTargetPageUrl. Da -WhatIf sich nicht authentifiziert, TargetExists ist NotChecked.

Führen Sie einen authentifizierten schreibgeschützten Preflight aus, um die aktuelle Quelle, Startseite, Berechtigungen, Zeitstempel und Das Fehlen des Ziels zu überprüfen:

.\Convert-RepresentativePages.ps1 `
  -ManifestPath .\representative-page-groups.csv `
  -ClientId "<application-id>" `
  -AuthenticationMode Interactive `
  -PreflightOnly `
  -Confirm:$false `
  -Force

Jede Zeile muss vor der Livekonvertierung einen Bericht erstellen TransformationStatus=PreflightPassed .

Interaktive Ausführung mit Bestätigung mit hoher Auswirkung:

.\Convert-RepresentativePages.ps1 `
  -ManifestPath .\representative-page-groups.csv `
  -ClientId "<application-id>" `
  -AuthenticationMode Interactive `
  -Confirm

Das Skript schreibt jedes Ergebnis sofort in representative-page-results.csv. Generierte Seiten bleiben Entwürfe, und jede erstellte Zeile beginnt mit ValidationStatus=Pending.

Folgen Sie den Anweisungen zum Überprüfen von transformierten klassischen Seiten. Legen Sie ValidationStatus=Passed, ValidationNotes, ValidatedByund ValidatedAt erst fest, nachdem die Seite jedes Akzeptanzkriterium erfüllt hat.

Auf alle benutzerdefinierten Seiten erweitern

Erstellen Sie, approved-pages.csv indem Sie die zusätzlichen eingeschlossenen Zeilen kopieren, die der Benutzer aus dem ursprünglichen representative-page-groups.csvgenehmigt hat. Behalten Sie jedes generierte Feld bei, und füllen Sie ExpectedVisibleContent und ValidationOwneraus.

Führen Sie zuerst das Skript für die ausgewählte Seite mit -PreflightOnly -Confirm:$false -Force aus. Jede Zeile muss melden PreflightPassed.

Führen Sie das Erweiterungsskript aus:

.\Convert-SelectedPages.ps1 `
  -PagesPath .\approved-pages.csv `
  -RepresentativeManifestPath .\representative-page-groups.csv `
  -RepresentativeResultsPath .\representative-page-results.csv `
  -ClientId "<application-id>" `
  -AuthenticationMode Interactive `
  -Confirm

Das Skript kann nicht erweitert werden, wenn:

  • Das repräsentative Manifest und die Ergebnisse stimmen nicht überein.
  • Jede repräsentative Seite ist nicht Created und Passed.
  • Validierungshinweise, Validierungssteuerelemente oder Validierungszeitstempel fehlen.
  • Die PnP PowerShell-Version oder eine der drei Skriptdateien unterscheidet sich von der repräsentativen Ausführung.
  • Eine genehmigte Seite ist keine unveränderte eingeschlossene Zeile aus dem ursprünglichen Manifest.
  • Eine genehmigte Seite gehört zu einem Muster ohne einen bestandenen Vertreter.

Die erweiterte Welle erstellt auch Entwurfsseiten und schreibt selected-page-results.csv. Überprüfen Sie diese Seiten, bevor Sie sie veröffentlichen.

Optionen, die eine explizite Überprüfung erfordern

Verwenden Sie die generierte ConvertTo-PnPPage-Cmdlet-Referenz für den vollständigen Parametervertrag.

Die Batchskripts unterstützen keine benutzerdefinierten Webpartzuordnungen, Veröffentlichungsseiten oder websiteübergreifende Ziele. Behandeln Sie diese Szenarien über ein separat überprüftes einzelseitiges oder erweitertes Verfahren.

Überprüfen Sie diese Optionen nur außerhalb des Batchworkflows:

  • -CopyPageMetadata und -KeepPageCreationModificationInformation.
  • -UrlMappingFile, -UserMappingFileund -TermMappingFile.
  • -Overwrite und -TakeSourcePageName nach genehmigungs- und rollbackplanung.

Problembehandlung für moderne Seitenfunktionen

Die Seitenwellenskripts aktivieren keine SharePoint-Features. Dieser Problembehandlungspfad gilt nur für eine unterstützte klassische Teamwebsite. Aktivieren Sie das Feature nicht in einem klassischen Veröffentlichungsportal. Veröffentlichungsseiten an das separate websiteübergreifende Veröffentlichungsbacklog und -modell weiterleiten. Weitere Informationen finden Sie unter Unterstützte Anpassungen für moderne Seiten.

Stellen Sie eine Verbindung mit einem Konto her, das zum Verwalten des Webs autorisiert ist, und listen Sie die aktivierten Webfeatures auf:

$source = Connect-PnPOnline `
  -Url "https://<tenant>.sharepoint.com/sites/<site>" `
  -Interactive `
  -ClientId "<application-id>" `
  -ReturnConnection

$modernPageFeatureId = [guid]'B6917CB1-93A0-4B97-A84D-7CF49975D4EC'
$modernPageFeature = Get-PnPFeature `
  -Scope Web `
  -Connection $source |
  Where-Object DefinitionId -eq $modernPageFeatureId

if ($modernPageFeature) {
  Write-Host "Modern pages feature is active."
}
else {
  Write-Host "Modern pages feature is not active."
}

Die delegierte AllSites.Manage Anwendung, die von den Batchskripts verwendet wird, reicht nicht aus, um Webfeatures zu aktivieren. Wenn das Feature auf einer unterstützten klassischen Teamwebsite nicht aktiv ist, holen Sie die Genehmigung des Websitebesitzers ein, und stellen Sie eine Verbindung her mit:

  • Eine separate delegierte Anwendung mit SharePoint AllSites.FullControl.
  • Ein angemeldetes Konto mit Vollzugriff im Web.
$adminConnection = Connect-PnPOnline `
  -Url "https://<tenant>.sharepoint.com/sites/<site>" `
  -Interactive `
  -ClientId "<full-control-application-id>" `
  -ReturnConnection

Enable-PnPFeature `
  -Identity $modernPageFeatureId `
  -Scope Web `
  -Connection $adminConnection

Führen Sie das authentifizierte Preflight erneut aus, nachdem Sie das Feature aktiviert haben.

Unbeaufsichtigte Authentifizierung und andere Seitentypen

Die zuvor erstellte delegierte öffentliche Clientanwendung kann nicht für die reine Zertifikatauthentifizierung wiederverwendet werden, es sei denn, sie ist separat für den reinen App-Zugriff konfiguriert.

Vor der unbeaufsichtigten Ausführung:

  1. Erstellen Sie eine separate Reine-App-Registrierung und ein separates Zertifikat, indem Sie Registrieren einer Entra-ID-Anwendung für den reinen App-Zugriff folgen.
  2. Konfigurieren Sie SharePoint-Anwendungsberechtigungen oder Websitezuweisungen für jede Quellwebsite, indem Sie bestimmen, welche PnP-PowerShell-Berechtigungen erforderlich sind.
  3. Erteilen Sie die erforderliche Administratorzustimmung.
  4. Führen Sie das Batchskript mit -PreflightOnly -Confirm:$false und dem Zertifikatauthentifizierungsmodus aus.
  5. Entfernen Sie -PreflightOnly nur, nachdem das authentifizierte Preflight in einem Testmandanten bestanden wurde.

Wichtig

Die Zertifikatparameterpfade sind pester-getestet, aber die Ausführung des Livemandanten der Phase 2 hat die delegierte interaktive Authentifizierung überprüft. Überprüfen Sie das ausgewählte Nur-App-Berechtigungsprofil in Ihrem Mandanten, bevor Sie unbeaufsichtigte Schreibvorgänge ausführen.

Veröffentlichungsseiten, Blogseiten, Seiten außerhalb SitePages, Startseiten, benutzerdefinierte Webpartzuordnungen und SharePoint Server-Quellen werden von den Batchskripts nicht unterstützt. Verwenden Sie diese erweiterten Verweise:

Nächste Schritte

  1. Überprüfen Sie jede transformierte Seite.
  2. Wird nur ausgeführt Convert-SelectedPages.ps1 , nachdem jede repräsentative Seite die Überprüfung bestanden hat.

Referenz

  • Last updated on