PowerShell: How to create or associate a HubSite

There are two ways to make a site a “HubSite”. The first is to go to the administration console in your tenant and create it. It’s easy but impossible to automate the process hence the second option—a PowerShell script. Here’s how to make a SharePoint site a HubSite in PowerShell and a detailed explanation of the script.

Please notice that the site should have been created already. If not, it won’t work since we need to provide the “HubSite” we want to convert into the script.

Let’s take a look at the script and common mistakes.

The script

The script may look long, but I wanted to add some error handling in case something goes wrong.

Write-Host "Script starting..."

Write-Host "Installing Modules..."

if (Get-Module -ListAvailable -Name "PnP.PowerShell") {
    Write-Host "Module exists"
} 
else {
    Install-Module -Name PnP.PowerShell
    Write-Error "Module already installed, so no action needed."
}

try {
    Import-Module PnP.PowerShell
}
catch {
    Write-Error "Module import failed, probably because it's already loaded. No action needed."
}


try {
    #Set variables (need to use the tenant administratoin site since we're checking the structure of the platform)
    $SiteURL = "https://manueltgomes-admin.sharepoint.com/"

    #Connect to PnP Online
    Connect-PnPOnline -Url $SiteURL -Interactive -ErrorAction Stop
}
catch {
    Write-Error "Problem connecting to the admin site with the following error:"
    Write-Error $_
    Exit 1
}

try {
    # Now we register the site as a HubSite
    Register-PnPHubSite -Site "https://manueltgomes.sharepoint.com/sites/country"
}
catch {
    Write-Host "Error connecting to site $url with the following error:" -ForegroundColor Yellow
    Write-Error $_
    Exit 1 
}

Write-Host "Process completed"

So what are we doing here?

1. Load and install the modules in case they don’t exist.
2. Connect to the administration website.
3. Set the website as a “HubSite”.

To connect to the administration, we’re using the Interactive action since it’s the one that, in my view, balances security and convenience. It launches a new window in your browser where you log in using the usual Microsoft 365 login screen. After the correct authentication, you should see this:

The script will continue to run, and we’ll define the website as a “HubSite”.

Notice that we have two different URLs. One with “manueltgomes.sharepoint.com” and another with “manueltgomes-admin.sharepoint.com”. This is not a mistake, and it’s necessary to do it. Connecting to the “admin” version of your tenant indicates to the authentication mechanism that you have additional permissions to do these operations. SharePoint checks if you indeed have these permissions and proceeds.

You must replace the “manueltgomes” in the script by your tenant site. You can easily understand what it is by going to any SharePoint site. The part before “sharepoint.com” is your tenant, so please ensure that you change it in the script; otherwise, it won’t work.

If all goes well, you should see something like this.

If, for some reason, there’s an error, please check the next section for the most common mistakes.

Common Mistakes or Error messages

Here are some of the most common errors.

Assembly with the same name is already loaded

Assembly with the same name is already loaded

This means the module was already loaded, so there’s no need to load it again. If you run across this issue, check if you’re importing the same module twice or running in an environment where the module was already loaded. Since the module is loaded, you can continue since you wanted to load it anyway.

File not found

File not found

The “file not found” error is common in actions like Register-PnPHubSite and means the site doesn’t exist. If you try opening the URL, you’ll get the following in your browser:

The solution is to create the site and rerun the script.

This site is already a HubSite.

This site is already a HubSite.

No action is needed. Probably the script or the instruction was run twice, but since the website is ready as an “HubSite”, there’s nothing else that we need to do.

Final thoughts

The script is relatively easy to run but be careful when running it to upgrade the URLs to the ones in your domain. I left mine (manueltgomes.sharepoint.com) as an example, but if you run the script as is, it won’t work.

Photo by Matt Ridley on Unsplash