How to import custom PowerShell module into the remote session?

There were some great comments to the question, and I've spent some time investigating various ways to approach the problem.

To begin with, what I've initially asked for is not possible. I mean, if you go the module way, then the module should be physically present on a target machine to be able to Import-Module into remote session.

To abstract my question further, I'm trying to create a reusable PowerShell-based framework for the product deployments. It's going to be a push-manner deployments, meaning that we encourage people to run some scripts on a local machine to deploy to some remote server. As far as I investigated the area, there are two possible ways which are friendly to the common sense.

Modules approach

The process to follow:

• place each logically different piece of functionality into the PowerShell module (*.psm1)
• distribute the module to the remote machine and extend the PSModulePath variable to include the new modules location
• on a client machine, create a new session to the remote server, and use Invoke-Command -Session $s -ScriptBlock {...}
• in the script block start from Import-Module CustomModule - it will search the CustomModule on a remote machine and obviously will find it

Advantages

The following are the reasons to love this approach for:

• the consequence of the traditional module role - facilitate the creation of reusable libraries
• according to the great book Windows PowerShell in Action, "modules can be used to create domain-specific applications". As far as I understand, it can be achieved by combining the module nesting and mixing script / binary modules to expose the intuitive interface specific to a certain domain. Basically, this is the one I value most for the goal of PowerShell-based deployment framework

Disadvantages

The following is important to take into consideration:

• You have to find a way to deliver the custom modules to the remote machine. I have played with NuGet, and I'm not sure it suits well for the task, but there are other options as well, for instance, MSI installer or plain xcopy from the shared folder. Besides, the delivery mechanism should support upgrade / downgrade and (preferably) multi-instance installations, but that's more related to my task than to the problem in general

Scripts approach

The process to follow:

• place each logically different piece of functionality in a separate PowerShell script (*.ps1)
• on a client machine, create a new session to the remote server, and use Invoke-Command -Session $s -FilePath .\myscript.ps1 to load the functions defined in a script to the remote session
• use another Invoke-Command -Session $s -ScriptBlock {...} and refer to your custom functions - they will be there in a session

Advantages

The following are good points of this approach:

• it is simple - you don't have to know about module peculiarities. Just write plain PowerShell scripts and that's it
• you don't have to deliver anything to the remote machine - this makes the solution even simpler and less error-prone in maintenance

Disadvantages

Sure, it's not ideal:

• there's less control over the solution: for instance, if you "import" a set of functions to the session, all of them are "imported" and visible to the user, so no "encapsulation", etc. I'm sure many solutions can live with this, so don't decide based on this point only
• the functionality in each file has to be self-contained - any dot-sourcing or module import from there will search the remote machine, not the local one

Finally, I should say that remote machine still needs to be prepared for the remoting. This is what I mean:

• execution policy should be changed to something, because it is restricted by default: Set-ExecutionPolicy Unrestricted
• PowerShell remoting should be enabled: Enable-PSRemoting
• the account the script runs as should be added to the local administrators of the remote server
• if you plan to access file shares in the remote session, make sure you are aware about multi-hop authentication and take proper actions
• make sure your antivirus is your friend and doesn't send you to the PowerShell hell

I don't believe this is supported right of the box without any "hacks". The smart move would probably be to put the module on a public location like a fileserver and import it on the server when you need it. Ex:

$session = new-pssession -computerName server01
invoke-command -session $session -scriptblock {
    #Set executionpolicy to bypass warnings IN THIS SESSION ONLY
    Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
    #Import module from public location
    Import-Module \\fileserver\folders\modulelocation...


    <# use function defined in MyCustomModule here #> 
}

Here's another approach: Recreate the module in a remote session, without copying any files.

I've made no attempt to cope with dependencies between modules, but this seems to work ok for simple self contained modules. It relies on the module being available in the local session, as this makes determining exports easier, but with a bit of extra work it would also work with a module file.

function Import-ModuleRemotely([string] $moduleName,[System.Management.Automation.Runspaces.PSSession] $session)
{
    $localModule = get-module $moduleName;
    if (! $localModule) 
    { 
        write-warning "No local module by that name exists"; 
        return; 
    }
    function Exports([string] $paramName, $dictionary) 
    { 
        if ($dictionary.Keys.Count -gt 0)
        {
            $keys = $dictionary.Keys -join ",";
            return " -$paramName $keys"
        }
    }
    $fns = Exports "Function" $localModule.ExportedFunctions;
    $aliases = Exports "Alias" $localModule.ExportedAliases;
    $cmdlets = Exports "Cmdlet" $localModule.ExportedCmdlets;
    $vars = Exports "Variable" $localModule.ExportedVariables;
    $exports = "Export-ModuleMember $fns $aliases $cmdlets $vars;";

    $moduleString= @"
if (get-module $moduleName)
{
    remove-module $moduleName;
}
New-Module -name $moduleName {
$($localModule.Definition)
$exports;
}  | import-module
"@
    $script = [ScriptBlock]::Create($moduleString);
    invoke-command -session $session -scriptblock $script;
}