Migrating SharePoint Site Content Using CSOM: A Step-by-Step Guide

Introduction

In the modern digital workspace, SharePoint Online serves as a central hub for collaboration and document management. As businesses scale, the need often arises to migrate content between sites, whether for site consolidation, restructuring, or moving content to a more suitable location. Automating this process using the Client-Side Object Model (CSOM) not only saves time but also minimizes errors, ensuring a smoother migration experience.

In this blog, we will walk through the steps required to read content from a source SharePoint site and migrate it to a target site, leveraging CSOM. By reusing existing containers (such as document libraries and lists) in the target site, we can avoid duplicating data and ensure that only relevant content is migrated.

Why Migrate Content Programmatically?

Manual content migration can be tedious, error-prone, and inefficient for large SharePoint environments. Using CSOM provides the following benefits:

• Automation: Significantly reduces manual effort and the potential for human error.
• Accuracy: Ensures that content is transferred accurately, with metadata preserved.
• Scalability: Efficiently handles large-scale migrations involving thousands of files and list items.
• Metadata Preservation: Maintains crucial information like timestamps, permissions, and other metadata during the migration process.

Key Requirements

Before we begin, ensure the following prerequisites are met:

1. Access to SharePoint Online: We need access to both the source and target sites.
2. Access Token: Authentication is required through an access token (e.g., via Azure AD).
3. CSOM Library: Install the Microsoft.SharePointOnline.CSOM NuGet package in our project.
4. Development Environment: A suitable IDE such as Visual Studio for development.

Step-by-Step Guide to Migrate Content Using CSOM

Step 1: Set Up the CSOM Environment

To get started with SharePoint Online content migration, we first need to set up our development environment and reference the necessary CSOM libraries.

1. Install the CSOM Package: Ensure that the Microsoft.SharePointOnline.CSOM package is installed in our project. This package contains the Client-Side Object Model (CSOM) libraries that allow us to interact with SharePoint Online.

2. Install via Package Manager: Open the Package Manager Console in Visual Studio and run the following command to install the required package:

Install-Package Microsoft.SharePointOnline.CSOM

Once the environment is set up, we can begin by authenticating to the SharePoint Online sites (both source and target) using our access token. The ClientContext object is used to interact programmatically with the SharePoint site.

var sourceContext = new ClientContext(sourceSiteUrl);
var targetContext = new ClientContext(targetSiteUrl);

Next, we will implement the authentication helper method to create a ClientContext with the access token. This will allow us to securely access the SharePoint sites.

Helper Method: Create ClientContext with Access Token

The following helper method allows us to authenticate and create the ClientContext object for SharePoint sites, using the access token:

// Helper: Create ClientContext with access token
internal static ClientContext CreateClientContextWithToken(string siteUrl, string accessToken)
{
    var ctx = new ClientContext(siteUrl);
    ctx.ExecutingWebRequest += (sender, e) =>
    {
        e.WebRequestExecutor.RequestHeaders["Authorization"] = "Bearer " + accessToken;
    };
    return ctx;
}

How to Use the Helper Method:

You can use the above helper method to create the ClientContext objects for both the source and target sites as follows:

var sourceContext = CreateClientContextWithToken(sourceSiteUrl, accessToken);
var targetContext = CreateClientContextWithToken(targetSiteUrl, accessToken);

This method ensures that all requests to SharePoint are authenticated with the provided access token, which is a secure and preferred way to interact with SharePoint Online.

Step 2: Retrieve Content from the Source Site

Load all lists and libraries from the source site:

var sourceWeb = sourceContext.Web;  
var sourceLists = sourceWeb.Lists;  
sourceContext.Load(sourceLists, lists => lists.Include(  
    list => list.Title,  
    list => list.BaseTemplate,  
    list => list.RootFolder  
));  
sourceContext.ExecuteQuery();

Step 3: Check for Existing Containers in the Target Site

Before migrating, ensure that matching containers (lists or libraries) already exist in the target site:

var targetWeb = targetContext.Web;  
var targetLists = targetWeb.Lists;  
targetContext.Load(targetLists, lists => lists.Include(list => list.Title));  
targetContext.ExecuteQuery();

Step 4: Migrate Content to the Target Site

If a matching container exists in the target site, migrate its content without creating duplicates.

Migrate Document Libraries:

foreach (var sourceList in sourceLists)  
{  
    if (sourceList.BaseTemplate == (int)ListTemplateType.DocumentLibrary)  
    {  
        var targetList = targetLists.FirstOrDefault(l => l.Title == sourceList.Title);  
        if (targetList != null)  
        {  
            MigrateDocumentLibrary(sourceList, targetList);  
        }  
    }  
}

Migrate Other Lists:

foreach (var sourceList in sourceLists)  
{  
    if (sourceList.BaseTemplate != (int)ListTemplateType.DocumentLibrary)  
    {  
        var targetList = targetLists.FirstOrDefault(l => l.Title == sourceList.Title);  
        if (targetList != null)  
        {  
            MigrateListItems(sourceList, targetList);  
        }  
    }  
}

Step 5: Implement Content Migration Methods

Migrate Document Libraries

Recursively copy files and folders from the source to the target:

private void MigrateDocumentLibrary(List sourceLib, List targetLib)  
{  
    var sourceRoot = sourceLib.RootFolder;  
    var targetRoot = targetLib.RootFolder;  
    sourceContext.Load(sourceRoot, f => f.Files, f => f.Folders);  
    targetContext.Load(targetRoot);  
    sourceContext.ExecuteQuery();  
    targetContext.ExecuteQuery();  

    MigrateFolderContents(sourceRoot, targetRoot);  
}

Migrate List Items

Copy list items while skipping system fields:

private void MigrateListItems(List sourceList, List targetList)  
{  
    var query = CamlQuery.CreateAllItemsQuery();  
    var sourceItems = sourceList.GetItems(query);  
    sourceContext.Load(sourceItems);  
    sourceContext.ExecuteQuery();  

    foreach (var sourceItem in sourceItems)  
    {  
        var itemInfo = new ListItemCreationInformation();  
        var targetItem = targetList.AddItem(itemInfo);  

        foreach (var field in sourceItem.FieldValues)  
        {  
            if (field.Key != "ID" && field.Key != "GUID")  
            {  
                targetItem[field.Key] = field.Value;  
            }  
        }  

        targetItem.Update();  
        targetContext.ExecuteQuery();  
    }  
}

Step 6: Handle Folders in the Target Site

Create missing folders dynamically in the target site:

private Folder GetOrCreateFolder(Folder parentFolder, string folderName)  
{  
    try  
    {  
        var targetFolder = parentFolder.Folders.GetByUrl(folderName);  
        targetContext.Load(targetFolder);  
        targetContext.ExecuteQuery();  
        return targetFolder;  
    }  
    catch (ServerException)  
    {  
        var newFolder = parentFolder.Folders.Add(folderName);  
        targetContext.Load(newFolder);  
        targetContext.ExecuteQuery();  
        return newFolder;  
    }  
}

Step 7: Test and Validate

Before completing the migration, ensure that:

• All files, folders, and list items are successfully migrated.
• Permissions and metadata are preserved.
• No data loss or duplication occurs.

Benefits of Using CSOM for Content Migration

By automating the migration with CSOM, we:

• Eliminate manual effort: Save time and reduce errors.
• Scale efficiently: Migrate large datasets effortlessly.
• Customize workflows: Tailor our migration to specific needs.
• Reuse code: Apply the migration logic across future projects.

Conclusion

Migrating content in SharePoint from one site to another is a crucial task that can be made efficient with CSOM. By automating the process and reusing containers in the target site, we can preserve data integrity while ensuring a smooth transition. Whether consolidating sites or optimizing collaboration, this approach empowers us to manage SharePoint environments with ease.

Happy coding! 🚀