Private/Connect-SiteServer.ps1

<#
.Synopsis
Created on: 28/10/2023
Updated on: 16/11/2026
Created by: Ben Whitmore
Filename: Connect-SiteServer.ps1
 
.Description
Function to connect to a ConfigMgr site server. The caller's location is saved in
$global:Win32AppMigrationTool_OriginalLocation (if not already set) so Get-ScriptEnd can restore it.
 
.PARAMETER LogId
The component (script name) passed as LogID to the 'Write-Log' function.
This parameter is built from the line number of the call from the function up the
 
.PARAMETER SiteCode
The Site Code of the ConfigMgr Site. If not provided, the function will attempt to retrieve it from the provider machine
 
.PARAMETER ProviderMachineName
Server name that has an SMS Provider site system role
#>

function Connect-SiteServer {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $false, ValuefromPipeline = $false, HelpMessage = "The component (script name) passed as LogID to the 'Write-Log' function")]
        [string]$LogId = $($MyInvocation.MyCommand).Name,
        [Parameter(Mandatory = $false, ValueFromPipeline = $false, Position = 0, HelpMessage = 'The Site Code of the ConfigMgr Site')]
        [ValidatePattern('(?##The Site Code must be only 3 alphanumeric characters##)^[a-zA-Z0-9]{3}$')]
        [String]$SiteCode,
        [Parameter(Mandatory = $true, ValueFromPipeline = $false, Position = 1, HelpMessage = "Server name that has an SMS Provider site system role")]
        [String]$ProviderMachineName
    )

    begin {
        Write-LogAndHost -Message "Function: Connect-SiteServer was called" -LogId $LogId -ForegroundColor Cyan
        Write-LogAndHost -Message ("Importing Module: 'ConfigurationManager' and connecting to Provider '{0}'..." -f $ProviderMachineName) -LogId $LogId -ForegroundColor Cyan
    }
    
    process {
        $attempt = 0
        $maxAttempts = 3
        $siteCodeRetrieved = $false

        # Attempt to retrieve the Site Code from the provider machine
        while (-not $siteCodeRetrieved -and $attempt -lt $maxAttempts) {

            if (-not $SiteCode) {
                try {

                    # Get the Site Code from the provider machine. There can be several providers, take the first
                    $retrieved = Get-CimInstance -Namespace 'root\SMS' -ClassName 'SMS_ProviderLocation' -ComputerName $ProviderMachineName -ErrorAction Stop |
                        Select-Object -First 1 -ExpandProperty SiteCode

                    if ($retrieved) {
                        $SiteCode = $retrieved
                        Write-LogAndHost -Message ("Retrieved Site Code: {0}" -f $SiteCode) -LogId $LogId -ForegroundColor Green
                        $siteCodeRetrieved = $true
                    }
                    else {
                        Write-LogAndHost -Message ("No SMS_ProviderLocation instance was returned by '{0}'" -f $ProviderMachineName) -LogId $LogId -Severity 3
                    }
                }
                catch {
                    Write-LogAndHost -Message "Failed to retrieve Site Code from provider machine: $($_.Exception.Message)" -LogId $LogId -Severity 3
                }
            }
            else {
                $siteCodeRetrieved = $true
            }

            # If the Site Code was not retrieved, prompt the user to enter it
            if (-not $siteCodeRetrieved) {
                # Read into a separate variable: $SiteCode has [ValidatePattern], so assigning invalid input to it throws
                $enteredSiteCode = Read-Host -Prompt "Please enter the Site Code (3 alphanumeric characters)"

                if ($enteredSiteCode -match '^[a-zA-Z0-9]{3}$') {
                    $SiteCode = $enteredSiteCode
                    $siteCodeRetrieved = $true
                }
                else {
                    Write-LogAndHost -Message ("Invalid Site Code entered: {0}" -f $enteredSiteCode) -LogId $LogId -Severity 3
                }
            }

            $attempt++
        }

        # If the Site Code was not retrieved after the maximum attempts, throw an error
        if (-not $siteCodeRetrieved) {
            $message = "Failed to retrieve or enter a valid Site Code after {0} attempts" -f $maxAttempts
            Write-LogAndHost -Message $message -LogId $LogId -Severity 3
            throw $message
        }

        # Import the ConfigurationManager module
        try {
            if (-not (Get-Module ConfigurationManager)) {
                if ($env:SMS_ADMIN_UI_PATH) {
                    Import-Module "$($env:SMS_ADMIN_UI_PATH)\..\ConfigurationManager.psd1" -Verbose:$false -ErrorAction Stop
                }
                else {
                    Import-Module ConfigurationManager -Verbose:$false -ErrorAction Stop
                }
            }
        }
        catch {
            $message = "Failed to import the ConfigurationManager module: $($_.Exception.Message)"
            Write-LogAndHost -Message $message -LogId $LogId -Severity 3
            throw $message
        }

        # Connect to the site
        try {

            # Save the caller's location so it can be restored by Get-ScriptEnd
            if (-not $global:Win32AppMigrationTool_OriginalLocation) {
                $global:Win32AppMigrationTool_OriginalLocation = (Get-Location).Path
            }

            # Create the site drive if it does not exist (first import of the module on this computer)
            if (-not (Get-PSDrive -Name $SiteCode -PSProvider CMSite -ErrorAction SilentlyContinue)) {
                New-PSDrive -Name $SiteCode -PSProvider CMSite -Root $ProviderMachineName -Scope Global | Out-Null
            }

            Set-Location -Path "$SiteCode`:" -ErrorAction Stop
            Write-LogAndHost -Message ("Connected to site: {0}" -f $SiteCode) -LogId $LogId -ForegroundColor Green
        }
        catch {
            $message = "Failed to connect to site '{0}': {1}" -f $SiteCode, $_.Exception.Message
            Write-LogAndHost -Message $message -LogId $LogId -Severity 3
            throw $message
        }
    }
}