MyRemoteSession

MyRemoteSession.psm1

Function New-MyRemoteSession {
    <#
    .SYNOPSIS
        Setup a PowerShell profile on a remote computer
    .DESCRIPTION
        By default this function will copy the local 'profile.ps1' file from $PSHOME to same location on the remote computer you choose
    .EXAMPLE
        PS C:\> New-MyRemoteSession -ComputerName "server01.local"
        Copies profile.ps1 from local $PSHOME folder path to remote $PSHOME folder path and sets the profilename to 'WithProfile'

    .EXAMPLE
        PS C:\> $splat = @{
            ComputerName = "server01.local"
            ProfileName = HelpDeskUser"
            SrcFolder = "C:\scripts\HelpDeskUser"
            DestFolder = "C:\scripts\HelpDeskUser"
            FileName = HelpDeskUser.ps1"
            RunAsCredential = $credential
        }
        PS C:\> New-MyRemoteSession @splat
        Copies HelpDeskUser.ps1 from local folder to remote destination folder which will be run upon startup.
        Creates the profilename to 'HelpDeskUser' which will be set to run under a different user context.

        WARNING: When RunAs is enabled in a Windows PowerShell session configuration, the Windows security model cannot enforce a security boundary between different
        user sessions that are created by using this endpoint. Verify that the Windows PowerShell runspace configuration is restricted to only the necessary set of
        cmdlets and capabilities.
    .NOTES
        Ref: https://docs.microsoft.com/en-us/previous-versions//dd819496(v=technet.10)?redirectedfrom=MSDN
    #>
    [CmdletBinding()]
    Param (
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.Credential()]
        $RunAsCredential,

        [Parameter(Mandatory)]
        [string]$ComputerName,

        [string]$ProfileName = "WithProfile",

        [string]$FileName = "profile.ps1",

        [string]$SrcFolder = $PSHOME,

        [string]$DstFolder = $PSHOME,

        [switch]$force
    )

    process {
        $Session = New-PSSession -ComputerName $ComputerName

        Copy-Item –Path (Join-Path $SrcFolder $FileName) –Destination $DstFolder –ToSession $session
        Invoke-Command -Session $session -ScriptBlock {
            if ( $($using:RunAsCredential).IsPresent ) {
                Register-PSSessionConfiguration -Name $using:ProfileName -StartupScript (Join-Path $using:SrcFolder $using:FileName) -RunAsCredential $using:RunAsCredential
            } else {
                Register-PSSessionConfiguration -Name $using:ProfileName -StartupScript (Join-Path $using:SrcFolder $using:FileName)
            }

            if ( $($using:force).IsPresent ) {
                Restart-Service -Name WinRM
            }
        }
        $session | Remove-PSSession
    }
}

Function Set-MyRemoteSession {
    <#
    .SYNOPSIS
        Update a pre-existing PSSessionConfiguration a remote computer
    .DESCRIPTION
        By default this function will copy the local 'profile.ps1' file from $PSHOME to same location on the remote computer you choose.
        Caution:
        This will currently overwrite any pre-existing file that may be already on the remote computer and will also restart WinRM.
    .EXAMPLE
        PS C:\> Set-MyRemoteSession -ComputerName "server01.local"
        Copies profile.ps1 from local $PSHOME folder path and overwrites the remote $PSHOME folder path and sets the profilename to 'WithProfile'
    .EXAMPLE
        PS C:\> $splat = @{
            ComputerName = "server01.local"
            ProfileName = HelpDeskUser"
            SrcFolder = "C:\scripts\HelpDeskUser"
            DestFolder = "C:\scripts\HelpDeskUser"
            FileName = HelpDeskUser.ps1"
            RunAsCredential = $credential
        }
        PS C:\> Set-MyRemoteSession @splat
        Copies HelpDeskUser.ps1 from local folder and overwrites matching file on remote destination folder which will be run upon startup.
        Unregisters and Re-Registers the profilename 'HelpDeskUser' which will be set to run under a different user context.

        WARNING: When RunAs is enabled in a Windows PowerShell session configuration, the Windows security model cannot enforce a security boundary between different
        user sessions that are created by using this endpoint. Verify that the Windows PowerShell runspace configuration is restricted to only the necessary set of
        cmdlets and capabilities.
    #>
    [CmdletBinding()]
    Param (
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.Credential()]
        $RunAsCredential,

        [Parameter(Mandatory)]
        [string]$ComputerName,

        [string]$ProfileName = "WithProfile",

        [string]$FileName = "profile.ps1",

        [string]$SrcFolder = $PSHOME,

        [string]$DstFolder = $PSHOME
    )

    $Session = New-PSSession -ComputerName $ComputerName

    Copy-Item –Path (Join-Path $SrcFolder $FileName) –Destination "$DstFolder" –ToSession $session -Force
    Invoke-Command -Session $session -ScriptBlock {
        Get-PSSessionConfiguration -Name $using:ProfileName | Unregister-PSSessionConfiguration

        if ( $($using:RunAsCredential).IsPresent ) {
            Register-PSSessionConfiguration -Name $using:ProfileName -StartupScript (Join-Path $using:SrcFolder $using:FileName) -RunAsCredential $using:RunAsCredential
        } else {
            Register-PSSessionConfiguration -Name $using:ProfileName -StartupScript (Join-Path $using:SrcFolder $using:FileName)
        }

        Restart-Service -Name WinRM
    }
    $session | Remove-PSSession
}

Function Enter-MyRemoteSession {
    <#
    .SYNOPSIS
        Establishes a remote PSSession which auto-runs a pre-configured profile script on the remote computer
    .DESCRIPTION
        Establishes a remote PSSession which auto-runs a pre-configured profile script on the remote computer
        Note:
        If a matching profile is not found, the remote session will be denied.
    .EXAMPLE
        PS C:\> Enter-MyRemoteSession -ComputerName "server01.local"
        Creates a remote PSSession which launches the default 'WithProfile' PSSessionConfiguration
    .EXAMPLE
        PS C:\> Enter-MyRemoteSession -ComputerName "server01.local" -ProfileName "HelpDeskUser"
        Creates a remote PSSession which launches the default 'HelpDeskUser' PSSessionConfiguration
    #>
    [CmdletBinding()]
    Param (
        [Parameter(Mandatory)]
        [string]$ComputerName,

        [string]$ProfileName = "WithProfile"
    )

    process {
        Enter-PSSession -ComputerName $ComputerName -ConfigurationName $ProfileName
    }
}


Function Remove-MyRemoteSession {
    <#
    .SYNOPSIS
        Remove a pre-existing PSSessionConfiguration a remote computer
    .DESCRIPTION
        Remove a pre-configured PSSessionConfiguration on the remote computer as no module would be complete without a way to clean-up.
    .EXAMPLE
        PS C:\> Remove-MyRemoteSession -ComputerName "server01.local"
        By default, this will attempt to remove 'WithProfile' PSSessionConfiguration from the remote computer specified
    .EXAMPLE
        PS C:\> Remove-MyRemoteSession -ComputerName "server01.local" -ProfileName "HelpDeskUser"
        This will attempt to remove the 'HelpDeskUser' PSSessionConfiguration from the remote computer specified
    .NOTES
        As part of the clean-up, the WinRM service will also be automatically restarted on the remote computer
    #>
    [CmdletBinding()]
    Param (
        [Parameter(Mandatory)]
        [string]$ComputerName,

        [string]$ProfileName = "WithProfile",

        [switch]$force
    )

    process {
        $Session = New-PSSession -ComputerName $ComputerName

        Invoke-Command -Session $session -ScriptBlock {
            Get-PSSessionConfiguration -Name $using:ProfileName | Unregister-PSSessionConfiguration

            if ( $($using:force).IsPresent ) {
                Restart-Service -Name WinRM
            }
        }
        $session | Remove-PSSession
    }
}

Function Restart-MyRemoteSession {
    <#
    .SYNOPSIS
        Remove a pre-existing PSSessionConfiguration a remote computer
    .DESCRIPTION
        Remove a pre-configured PSSessionConfiguration on the remote computer as no module would be complete without a way to clean-up.
    .EXAMPLE
        PS C:\> Remove-MyRemoteSession -ComputerName "server01.local"
        By default, this will attempt to remove 'WithProfile' PSSessionConfiguration from the remote computer specified
    .EXAMPLE
        PS C:\> Remove-MyRemoteSession -ComputerName "server01.local" -ProfileName "HelpDeskUser"
        This will attempt to remove the 'HelpDeskUser' PSSessionConfiguration from the remote computer specified
    .NOTES
        As part of the clean-up, the WinRM service will also be automatically restarted on the remote computer
    #>
    [CmdletBinding()]
    Param (
        [Parameter(Mandatory)]
        [string]$ComputerName
    )

    process {
        $Session = New-PSSession -ComputerName $ComputerName

        Invoke-Command -Session $session -ScriptBlock {
            Restart-Service -Name WinRM
        }
        $session | Remove-PSSession
    }
}