Migrating SharePoint 2016 and 2019 to Subscription Edition: the scripts

# INVENTORY.PS1: runs on the SharePoint 2016 or 2019 farm.
# Reads only. Produces the record that the new farm gets compared against.
$out = "C:\Migration\inventory"
New-Item -ItemType Directory -Path $out -Force | Out-Null

# Patch level of every SharePoint product in the farm. This is the documented
# way to see what is actually installed, server by server.
Get-SPProduct |
  Select-Object ProductName, @{n='Patches';e={ $_.PatchableUnitDisplayNames -join '; ' }} |
  Export-Csv "$out\products.csv" -NoTypeInformation -Encoding UTF8

# Web applications with their URLs and authentication. The new farm has to
# reproduce these URLs exactly, or every link inside the content breaks.
Get-SPWebApplication -IncludeCentralAdministration |
  Select-Object DisplayName, Url,
    @{n='Zones';e={ ($_.AlternateUrls | ForEach-Object { "$($_.UrlZone)=$($_.IncomingUrl)" }) -join ' | ' }},
    @{n='ClaimsMode';e={ $_.UseClaimsAuthentication }} |
  Export-Csv "$out\webapps.csv" -NoTypeInformation -Encoding UTF8

# Content databases, their sizes and how many site collections each holds.
# The counts are what tells you which mount will take twenty minutes and
# which will take six hours.
Get-SPContentDatabase |
  Select-Object Name, Server, WebApplication, CurrentSiteCount,
    @{n='SizeGB';e={ [math]::Round($_.DiskSizeRequired / 1GB, 2) }} |
  Export-Csv "$out\contentdbs.csv" -NoTypeInformation -Encoding UTF8

# Farm solutions. These have to be deployed to the new farm BEFORE the content
# databases are tested, and this list is what you deploy.
Get-SPSolution |
  Select-Object Name, Deployed, ContainsGlobalAssembly, ContainsWebApplicationResource,
    @{n='DeployedTo';e={ ($_.DeployedWebApplications | ForEach-Object { $_.Url }) -join ' | ' }} |
  Export-Csv "$out\solutions.csv" -NoTypeInformation -Encoding UTF8

# Service applications and their databases. Five of these can be upgraded.
# Everything else on this list is a rebuild, and it is better to know now.
Get-SPServiceApplication |
  Select-Object DisplayName, TypeName, Status |
  Export-Csv "$out\serviceapps.csv" -NoTypeInformation -Encoding UTF8

Get-SPDatabase |
  Select-Object Name, Type, Server,
    @{n='SizeGB';e={ [math]::Round($_.DiskSizeRequired / 1GB, 2) }} |
  Export-Csv "$out\databases.csv" -NoTypeInformation -Encoding UTF8

# Every site collection, with its template. The templates are what a missing
# feature shows up as later, so this is the list you check against.
Get-SPSite -Limit All |
  Select-Object Url, @{n='Template';e={ $_.RootWeb.WebTemplate + '#' + $_.RootWeb.Configuration }},
    ContentDatabase, Owner |
  Export-Csv "$out\sites.csv" -NoTypeInformation -Encoding UTF8

Write-Host "Inventory written to $out" -ForegroundColor Green

# CERTIFICATES. Subscription Edition deploys imported certificates to the
# Windows certificate store on every server in the farm automatically, and
# to any server that joins later.
$pfxPassword = Read-Host -AsSecureString -Prompt 'PFX password'
Import-SPCertificate -Path '\\fileserver\certs\sharepoint.contoso.com.pfx' `
                     -Password $pfxPassword -Exportable

# The whole chain has to be present, not just the leaf, or SSL connections fail.
Import-SPCertificate -Path '\\fileserver\certs\issuing-ca.p7b'

# Confirm what landed, and in which store.
Get-SPCertificate | Select-Object DisplayName, Store, NotAfter, Thumbprint

# Warn earlier than the default. The health rules then chase expiry for you.
Set-SPCertificateSettings -CertificateExpirationWarningThreshold 45

# WEB APPLICATIONS. The URL must match the old farm exactly: it is written
# into links, into search results and into anything anyone ever bookmarked.
$appPoolAccount = Get-SPManagedAccount 'CONTOSO\svc-sp-content'

# Windows claims. Classic mode was REMOVED for content web applications in
# Subscription Edition, so a farm that was still classic changes here, not later.
$ap = New-SPAuthenticationProvider

New-SPWebApplication -Name 'Contoso Intranet' `
    -ApplicationPool 'ContosoIntranetPool' `
    -ApplicationPoolAccount $appPoolAccount `
    -AuthenticationProvider $ap `
    -Port 443 -SecureSocketsLayer `
    -HostHeader 'sharepoint.contoso.com' `
    -Url 'https://sharepoint.contoso.com' `
    -Certificate 'sharepoint.contoso.com' `
    -UseServerNameIndication `
    -DatabaseName 'SP_Content_Placeholder'

# Server Name Indication is what lets several web applications share port 443
# with their own certificates. Without it they all share one certificate.

# Right: every binding setting stated, even the ones that are not changing.
Set-SPWebApplication -Identity 'https://sharepoint.contoso.com' -Zone Default `
    -Port 443 -SecureSocketsLayer `
    -HostHeader 'sharepoint.contoso.com' `
    -Url 'https://sharepoint.contoso.com' `
    -Certificate 'sharepoint.contoso.com' `
    -UseServerNameIndication

# SOLUTIONS. Driven from solutions.csv, produced by the inventory.
$wsps = Import-Csv 'C:\Migration\inventory\solutions.csv'

foreach ($w in $wsps) {
    $path = Join-Path 'C:\Migration\wsp' $w.Name
    if (-not (Test-Path $path)) {
        Write-Warning "MISSING: $($w.Name). Find the package, or the sites that use it will not upgrade cleanly"
        continue
    }

    $solution = Add-SPSolution -LiteralPath $path

    # GACDeployment is required when the package contains a global assembly.
    # The inventory recorded that per solution, so it is not a guess.
    $gac = [bool]::Parse($w.ContainsGlobalAssembly)

    if ($w.ContainsWebApplicationResource -eq 'True') {
        Install-SPSolution -Identity $solution -AllWebApplications `
                           -GACDeployment:$gac -Force
    } else {
        Install-SPSolution -Identity $solution -GACDeployment:$gac -Force
    }
}

# Deployment is asynchronous: it runs on a timer job. Wait for it, or the
# next phase tests against a farm that is still deploying.
do {
    Start-Sleep -Seconds 15
    $pending = Get-SPSolution | Where-Object { $_.JobExists }
    Write-Host "Waiting for $($pending.Count) solution job(s)..."
} while ($pending)

Get-SPSolution | Select-Object Name, Deployed, DeploymentState | Format-Table -AutoSize

-- ON THE OLD FARM'S SQL INSTANCE.
-- Read-only, not offline: people keep reading during the copy window.
ALTER DATABASE [WSS_Content_Intranet] SET READ_ONLY WITH ROLLBACK IMMEDIATE;

-- COPY_ONLY leaves the existing backup chain intact. Without it, this backup
-- becomes part of the chain and the scheduled restore plan quietly changes.
-- CHECKSUM makes the restore refuse a backup that was damaged in transit.
BACKUP DATABASE [WSS_Content_Intranet]
    TO DISK = N'\\fileserver\migration\WSS_Content_Intranet.bak'
    WITH COPY_ONLY, COMPRESSION, CHECKSUM, STATS = 5;

-- ON THE SUBSCRIPTION EDITION FARM'S SQL INSTANCE.
RESTORE DATABASE [WSS_Content_Intranet]
    FROM DISK = N'\\fileserver\migration\WSS_Content_Intranet.bak'
    WITH MOVE 'WSS_Content_Intranet'     TO N'E:\SQLData\WSS_Content_Intranet.mdf',
         MOVE 'WSS_Content_Intranet_log' TO N'F:\SQLLogs\WSS_Content_Intranet_log.ldf',
         REPLACE, STATS = 5;

-- A restored copy inherits the read-only state, and a read-only database
-- cannot be attached. This is the step people forget, and Mount fails on it.
ALTER DATABASE [WSS_Content_Intranet] SET READ_WRITE WITH ROLLBACK IMMEDIATE;

# SERVICE APPLICATIONS. Order matters: MMS and UPA before Search.
$applicationPool = Get-SPServiceApplicationPool -Identity 'SharePoint Web Services default'

# --- Secure Store -------------------------------------------------------
# The passphrase is from the OLD farm. Without it the stored credentials are
# unreadable, and no amount of restoring gets them back.
$sss  = New-SPSecureStoreServiceApplication -Name 'Secure Store' `
            -ApplicationPool $applicationPool `
            -DatabaseName 'Secure_Store_Service_DB' -AuditingEnabled
$sssp = New-SPSecureStoreServiceApplicationProxy -Name 'Secure Store Proxy' `
            -ServiceApplication $sss -DefaultProxyGroup

$oldPassphrase = Read-Host -Prompt 'Secure Store passphrase from the old farm'
Update-SPSecureStoreApplicationServerKey -Passphrase $oldPassphrase `
            -ServiceApplicationProxy $sssp

# --- Business Data Connectivity ----------------------------------------
# The only one that creates its own proxy and puts it in the default group.
New-SPBusinessDataCatalogServiceApplication -Name 'BDC Service' `
    -ApplicationPool $applicationPool -DatabaseName 'BDC_Service_DB'

# --- Managed Metadata ---------------------------------------------------
$mms = New-SPMetadataServiceApplication -Name 'Managed Metadata Service' `
           -ApplicationPool $applicationPool `
           -DatabaseName 'Managed_Metadata_Service_DB'
New-SPMetadataServiceApplicationProxy -Name 'Managed Metadata Proxy' `
    -ServiceApplication $mms -DefaultProxyGroup

# --- User Profile -------------------------------------------------------
# After Managed Metadata, and before any My Site is touched. The Sync
# database is NEW: only Profile and Social come across.
New-SPProfileServiceApplication -Name 'User Profile Service Application' `
    -ApplicationPool $applicationPool `
    -ProfileDBName 'UPA_ProfileDB' `
    -SocialDBName  'UPA_SocialDB' `
    -ProfileSyncDBName 'UPA_SyncDB'

$upa = Get-SPServiceApplication | Where-Object { $_.TypeName -eq 'User Profile Service Application' }
New-SPProfileServiceApplicationProxy -Name 'User Profile Proxy' -ServiceApplication $upa

$upaProxy = Get-SPServiceApplicationProxy |
            Where-Object { $_.TypeName -eq 'User Profile Service Application Proxy' }
Add-SPServiceApplicationProxyGroupMember -member $upaProxy -identity ''

# --- Search, part one: ON THE OLD FARM ---------------------------------
# The Search Administration database is copied later than the others, because
# Search has to be paused first. While it is paused the old index stops
# updating, so results on the old farm get staler during the window.
$ssaOld = Get-SPEnterpriseSearchServiceApplication 'Search Service Application'
Suspend-SPEnterpriseSearchServiceApplication -Identity $ssaOld
# Now set the Search Admin DB read-only, back it up and restore it, as in phase 3.

# --- Search, part two: ON THE SUBSCRIPTION EDITION FARM ----------------
# The Search service instance cannot be started from Central Administration
# until a Search service application exists, so PowerShell it is.
$searchInst = Get-SPEnterpriseSearchServiceInstance -local
Start-SPServiceInstance $searchInst

# Restore, not New: this is what upgrades the admin database instead of
# creating an empty one. It keeps the search schema, the result sources and
# the query rules. It does NOT keep the index.
Restore-SPEnterpriseSearchServiceApplication `
    -Name 'Search Service Application' `
    -applicationpool $applicationPool `
    -databasename 'Search_Service_Application_DB' `
    -databaseserver 'SQLSE01' `
    -AdminSearchServiceInstance $searchInst

$ssa  = Get-SPEnterpriseSearchServiceApplication
New-SPEnterpriseSearchServiceApplicationProxy -Name 'Search Proxy' -SearchApplication $ssa
$ssap = Get-SPEnterpriseSearchServiceApplicationProxy
Add-SPServiceApplicationProxyGroupMember -member $ssap -identity ''

$pg = Get-SPServiceApplicationProxyGroup -Identity ''
$pg.Proxies | Select-Object DisplayName, TypeName | Format-Table -AutoSize

# TEST THEN MOUNT. Driven from the inventory, one database at a time.
$dbs    = Import-Csv 'C:\Migration\inventory\contentdbs.csv'
$webApp = 'https://sharepoint.contoso.com'
$report = 'C:\Migration\reports'
New-Item -ItemType Directory -Path $report -Force | Out-Null

foreach ($db in $dbs) {

    Write-Host "`n=== $($db.Name) ===" -ForegroundColor Cyan

    # -ExtendedCheck catches a claims/classic mismatch, which Subscription
    # Edition cannot resolve later: classic mode is gone for content web apps.
    $issues = Test-SPContentDatabase -Name $db.Name -WebApplication $webApp -ExtendedCheck

    $issues | Export-Clixml "$report\$($db.Name).test.xml"
    $issues | Format-List | Out-File "$report\$($db.Name).test.txt" -Encoding UTF8

    # UpgradeBlocking is the property that separates "fix this now" from
    # "write this down". Read the file either way: a non-blocking missing
    # web part is still a broken page for whoever put it there.
    $blocking = $issues | Where-Object { $_.UpgradeBlocking }

    if ($blocking) {
        Write-Host "BLOCKED: $($blocking.Count) blocking issue(s). Not mounting." -ForegroundColor Red
        $blocking | Format-List Category, Message, Remedy
        continue
    }

    if ($issues) {
        Write-Host "$($issues.Count) non-blocking issue(s), logged. Mounting." -ForegroundColor Yellow
    }

    # Mount-SPContentDatabase, not Central Administration: attaching a database
    # through the Central Administration pages is not supported for upgrading.
    # Site collections upgrade automatically as part of this, which is the
    # default and the recommended behaviour.
    Mount-SPContentDatabase -Name $db.Name -WebApplication $webApp -Verbose

    Write-Host "MOUNTED: $($db.Name)" -ForegroundColor Green
}

Mount-SPContentDatabase -Name 'WSS_Content_Archive' -WebApplication $webApp -SkipSiteUpgrade

# 1. Every site collection accounted for, against the inventory.
$before = Import-Csv 'C:\Migration\inventory\sites.csv'
$after  = Get-SPSite -Limit All | Select-Object -ExpandProperty Url
$missing = $before.Url | Where-Object { $_ -notin $after }
if ($missing) { $missing | ForEach-Object { Write-Warning "MISSING SITE: $_" } }
else { Write-Host "All $($before.Count) site collections present." -ForegroundColor Green }

# 2. Site collection upgrade status, per site. The logs from Mount-based
# upgrades live inside the Upgrade*.log files, not in separate SiteUpgrade
# files, which is where people go looking and find nothing.
Get-SPSite -Limit All | ForEach-Object {
    $info = Get-SPSiteUpgradeSessionInfo -Site $_.Url -ErrorAction SilentlyContinue
    [pscustomobject]@{
        Url       = $_.Url
        Status    = $info.Status
        Errors    = $info.ErrorCount
        Warnings  = $info.WarningCount
    }
} | Where-Object { $_.Errors -gt 0 -or $_.Status -ne 'Completed' } | Format-Table -AutoSize

# 3. The index is EMPTY. The topology in the new farm is new, so a full crawl
#    over the whole corpus is mandatory, and only once every content database
#    is mounted. Starting it earlier just means crawling twice.
$ssa = Get-SPEnterpriseSearchServiceApplication
Get-SPEnterpriseSearchCrawlContentSource -SearchApplication $ssa |
  ForEach-Object { $_.StartFullCrawl() }

# 4. Which feature release ring this farm should be on. Standard is the
#    default; Early gets new experiences sooner. Record the decision.
Get-SPFeatureReleasePreference