How to import custom PowerShell module into the remote session?

Question

I'm developing a custom PowerShell module, which I'd like to use in context of a remote session to a different computer. The following code (which obviously doesn't work) explains what I'm trying to achieve:

import-module .\MyCustomModule.psm1
$session = new-pssession -computerName server01
invoke-command -session $session -scriptblock { 
  <# use function defined in MyCustomModule here #> 
}

The first question is whether it is at all possible to achieve this scenario? I mean I would only like my custom module to be physically present on my machine, not on remote server.

I have found this thread, but I didn't manage it to work - it doesn't allow creating a session from remote machine back to the local one. Probably, I faced with the configuration limitations mentioned somewhere in the comments to that thread... Besides, the author mentioned the performance implications which is critical for my solution...

If that's possible, then how?

The version of PowerShell is currently not a constraint - if the solution is only available in PS 3.0 - I can live with this.

Answer 1

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