Migrate to SharePoint using PowerShell

This article is about the new PowerShell cmdlets based on the SharePoint Migration Tool (SPMT) migration engine. They can be used to move files from SharePoint 2010 and SharePoint 2013 on-premises document libraries and list items, and file shares to Microsoft 365. For information on all current PowerShell cmdlets relating to SharePoint migration, see the Microsoft SharePoint Migration Tool cmdlet reference.

The PowerShell cmdlets provide the same functionalities as the SharePoint Migration Tool.

System requirements

Recommended requirements for best performance

Minimum requirements (expect slow performance)

Workaround for long path issue

When using SPMT PowerShell, you might encounter scan failures on source files with paths longer than 260 characters. To resolve this issue, you can modify the system registry to enable PowerShell to read long path files.

Open Register Editor, navigate to "Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework", add a new key "AppContext". Then add 2 String values under the key.

• Value Name: Switch.System.IO.BlockLongPaths Value Data: false

• Value Name: Switch.System.IO.UseLegacyPathHandling Value Data: false

Before you begin

1. Provision your Microsoft 365 with either your existing active directory or one of the other options for adding accounts to Microsoft 365. For more information, see Microsoft 365 integration with on-premises environments and Add users to Microsoft 365 Apps for business.

2. Open the folder: $env:UserProfile\Documents\WindowsPowerShell\Modules\Microsoft.SharePoint.MigrationTool.PowerShell. Make sure you have DLLs inside of it. If you're using OneDrive, you need to copy the WindowsPowershell Folder into $env:UserProfile\OneDrive - Microsoft\Documents.

3. From this location, run the following PowerShell command:

   Import-Module Microsoft.SharePoint.MigrationTool.PowerShell
   

Create and initialize a migration session

• Register-SPMTMigration

This cmdlet creates and then initializes a migration session. The initialization configures migration settings at the session level. If no specific setting parameters are defined, default settings are used. After a session is registered, you can add a task to the session and start migration.

Add a migration task

• Add-SPMTTask

Use this cmdlet to add a new migration task to the registered migration session. Currently there are three different types of tasks allowed: File share task, SharePoint task, and JSON defined task. Note: Duplicate tasks aren't allowed.

Remove a task

• Remove-SPMTTask

Use this cmdlet to remove an existing migration task from the registered migration.

Start your migration

• Start-SPMTMigration

This cmdlet starts the registered SPMT migration.

Return the object of current session

• Get-SPMTMigration

Returns the object of the current session. This cmdlet includes the status of current tasks and current session level settings. Current task status includes:

S - Count of scanned files

• Count of migrated files
  • Any migration error messages

Stop your current migration

• Stop-SPMTMigration

This cmdlet cancels the current migration.

Show your migration status details in the console

• Show-SPMTMigration

If you start the migration in NoShow mode, running the Show-SPMTMigration cmdlet displays the task ID, data source location, target location, and migration status in the console. Selecting Ctrl+C returns the display to NoShow mode.

Remove the migration session

• Unregister-SPMTMigration

Use this cmdlet to delete the migration session.

Sample Scenarios

Example 1: The IT admin adds a SharePoint on-premises task and starts migration in the background.

#Define SharePoint 2013 data source#
$SourceSiteUrl = "http://YourOnPremSite/"
$OnPremUserName = "Yourcomputer\administrator"
$OnPremPassword = ConvertTo-SecureString -String "OnPremPassword" -AsPlainText -Force
$SPCredential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $OnPremUserName, $OnPremPassword
$SourceListName = "SourceListName"

#Define SharePoint target#
$SPOUrl = "https://contoso.sharepoint.com"
$UserName = "[email protected]"
$PassWord = ConvertTo-SecureString -String "YourSPOPassword" -AsPlainText -Force
$SPOCredential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $UserName, $PassWord
$TargetListName = "TargetListName"

#Define File Share data source#
$FileshareSource = "YourFileShareDataSource"

#Import SPMT Migration Module#
Import-Module Microsoft.SharePoint.MigrationTool.PowerShell

#Register the SPMT session with SharePoint credentials#
Register-SPMTMigration -SPOCredential $SPOCredential -Force

#Add two tasks into the session. One is SharePoint migration task, and another is File Share migration task.#
Add-SPMTTask -SharePointSourceCredential $SPCredential -SharePointSourceSiteUrl $SourceSiteUrl  -TargetSiteUrl $SPOUrl -MigrateAll
Add-SPMTTask -FileShareSource $FileshareSource -TargetSiteUrl $SPOUrl -TargetList $TargetListName

#Start Migration in the console. #
Start-SPMTMigration

Example 2: The IT admin wants to bring the migration from the background "NoShow mode" to the foreground, and run below the cmdlet so the migration progress is shown in the console.

Show-SPMTMigration

Example 3: The IT Admin wants to do a bulk migration by loading a .csv file. The sample file in this example is SPMT.csv.

Load CSV;
$csvItems = import-csv "C:\spmt.csv" -Header c1,c2,c3,c4,c5,c6
ForEach ($item in $csvItems)
{
    Write-Host $item.c1
    Add-SPMTTask -FileShareSource $item.c1 -TargetSiteUrl $item.c4 -TargetList $item.c5 -TargetListRelativePath $item.c6
}

Two migration tasks are defined in the file of spmt.csv.

D:\MigrationTest\Files\Average_1M\c,,,https://SPOSite.sharepoint.com,Documents,Test
C:\work\Powershell\negative,,,https://SPOSite.sharepoint.com/,Documents,DocLibrary_SubfolderName

Code snippets for bulk migration by loading one JSON file:

#Load JSON:
$jsonItems = Get-Content -Raw -Path  "C:\spmt.json" | ConvertFrom-Json
ForEach ($taskItem in $jsonItems.Tasks)
{
    $jsonString = ConvertTo-Json $taskItem -Depth 100
    Add-SPMTTask -JsonDefinition $jsonString -SharePointSourceCredential $onpremCredential
}

Three migration tasks are defined in the file of spmt.json.

{
   "Tasks":[
      {
         "SourcePath":"http://On-prem/sites/test",
         "TargetPath":"https://YourSPO.sharepoint.com",
         "Items":{
            "Lists":[
               {
                  "SourceList":"list-01",
                  "TargetList":"list-01"
               }
            ],
            "SubSites":[

            ]
         }
      },
      {
         "SourcePath":"http://On-prem/sites/test",
         "TargetPath":"https://YourSPO.sharepoint.com",
         "Items":{
            "Lists":[
               {
                  "SourceList":"list-02",
                  "TargetList":"list-02"
               }
            ],
            "SubSites":[

            ]
         }
      },
      {
         "SourcePath":"http://On-prem/sites/test",
         "TargetPath":"https://YourSPO.sharepoint.com",
         "Items":{
            "Lists":[
               {
                  "SourceList":"doclib-01",
                  "TargetList":"doclib-01"
               }
            ],
            "SubSites":[

            ]
         }
      }
   ]
}

Example 4: Display migration progress

These samples show how to display the progress of your migration project. Get-SPMTMigration returns the object of current session It includes current tasks status and current session level settings.

The status of current tasks includes:

• A count of scanned files.
• A count of filtered out files.
• A count of migrated files.
• A count of failed files.
• The migration progress of the current task (0 ~ 100).
• The current task status.
• Migration error messages, if there are any.

# Start migration in the background
Start-SPMTMigration -NoShow

# Get the object of current migration
$session = Get-SPMTMigration

# Query migration status every 5 seconds until migration is finished
while ($session.Status -ne "Finished")
{
Write-Host $session.Status

    # Query migration progress of each tasks
    Foreach ($taskStatus in $session.StatusOfTasks)
    {
        $taskStatus.MigratingProgressPercentage
}

    Start-Sleep -Seconds 5
}