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.

Note

These PowerShell cmdlets are currently not available for users of Office 365 operated by 21Vianet in China.

System requirements

Description Recommendation
CPU 64-bit Quad core processor or better
RAM 16 GB
Local Storage Hard disk: 150 GB free space
Operating system Windows Server 2016 Standard or Datacenter
Windows Server 2012 R2
Windows 10 client
.NET Framework 4.6.2
Microsoft Visual C++ 2015 Redistributable Required for OneNote migration

Important

PowerShell 5.0x and .NET Framework 4.6.2 or higher are required to support the migration of file paths of up to 400 characters.

Minimum requirements (expect slow performance)

Description Minimum requirement
CPU 64-bit 1.4 GHz 2-core processor or better
RAM 8 GB
Local Storage Hard disk: 150 GB free space
Network card High-speed Internet connection
Operating system Windows Server 2008 R2
Windows 7
Windows 8 or 8.1
.NET Framework 4.6.2
Microsoft Visual C++ 2015 Redistributable Required for OneNote migration.
PowerShell PowerShell 5.x required to support migration of file paths of up to 400 characters. PowerShell 6.0 or higher isn't supported.

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. See Microsoft 365 integration with on-premises environments and Add users to Microsoft 365 Apps for business for more information.

  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 may need to copy the WindowsPowershell Folder into OneDrive / 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 will be 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

Return the object of current session

  • Get-SPMTMigration
    Return the object of the current session. This cmdlet includes the status of current tasks and current session level settings. Current task status includes:
    • Count of scanned files
    • Count of migrated files
    • Any migration error messages

Stop your 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 will display the task ID, data source location, target location and migration status in the console. Pressing Ctrl+C will return to NoShow mode.

Remove the migration session

Sample Scenarios

Example 1: 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 = "admin@contoso.onmicrosoft.com"
$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: 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: 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
}