New-Module | Taking on PowerShell one cmdlet at a time | Weekly Blog

Share this post:

This is a part of an on-going blog series written by Adam Gordon. Each week, Adam will walk you through a PowerShell command, showing you when and how to use each one. This week, Adam covers New-Module.

When to use New-Module?

The New-Module cmdlet creates a dynamic module from a script block. The members of the dynamic module, such as functions and variables, are immediately available in the session and remain available until you close the session.

Like static modules, by default, the cmdlets and functions in a dynamic module are exported and the variables and aliases are not. However, you can use the Export-ModuleMember cmdlet and the parameters of New-Module to override the defaults.

You can also use the –AsCustomObject parameter of New-Module to return the dynamic module as a custom object. The members of the modules, such as functions, are implemented as script methods of the custom object instead of being imported into the session.

Dynamic modules exist only in memory, not on disk. Like all modules, the members of dynamic modules run in a private module scope that is a child of the global scope. Get-Module cannot get a dynamic module, but Get-Command can get the exported members.

To make a dynamic module available to Get-Module, pipe a New-Module command to Import-Module, or pipe the module object that New-Module returns to Import-Module. This action adds the dynamic module to the Get-Module list, but it does not save the module to disk or make it persistent.

What version of PowerShell am I using?

Get the PowerShell Version from your machine:

$PSVersionTable

This command shows you the PowerShell version information on your machine.

How to use New-Module?

Create a dynamic module and working with dynamic modules and Get-Module and Get-Command:

Line #1:  new-module -scriptblock {function Hello {“Hello!”}}

Line #2:  Get-Module

Line #3:  Get-Command Hello

Line # 1 in this example creates a new dynamic module with a function called Hello.

Line # 2 demonstrates that dynamic modules are not returned by the Get-Module cmdlet.

Line # 3 shows that the members that they export are returned by the Get-Command cmdlet.

 

Export a variable into the current session:

New-Module -ScriptBlock {$SayHelloHelp=”Type ‘SayHello’, a space, and a name.”; function SayHello ($name) { “Hello, $name” }; Export-ModuleMember -function SayHello -Variable SayHelloHelp}

$SayHelloHelp

This example uses the Export-ModuleMember cmdlet to export a variable into the current session. Without the Export-ModuleMember command, only the function is exported.

The output shows that both the variable and the function were exported into the session.

 

Make a dynamic module available to Get-Module:

New-Module -ScriptBlock {function Hello {“Hello!”}} -name GreetingModule | Import-Module

$Get-Module

Get-Command hello

This example demonstrates that you can make a dynamic module available to Get-Module by piping the dynamic module to Import-Module.

New-Module creates a module object that is piped to the Import-Module cmdlet.

The –Name parameter of New-Module assigns a friendly name to the module. Because Import-Module does not return any objects by default, there is no output from this command.

Get-Module shows that the GreetingModule has been imported into the current session.

The Get-Command cmdlet shows the Hello function that the dynamic module exports.

 

Generate a custom object that has exported functions:

$m = New-Module -ScriptBlock {
function Hello ($name) {“Hello, $name”}
function Goodbye ($name) {“Goodbye, $name”}
} -AsCustomObject

$m

$m | Get-Member

This example shows how to use the –AsCustomObject parameter of New-Module to generate a custom object that has script methods that represent the exported functions.

The New-Module cmdlet creates a dynamic module with two functions, Hello and Goodbye.

The –AsCustomObject parameter creates a custom object instead of the PSModuleInfo object that New-Module generates by default. This custom object is saved in the $m variable.

The $m variable appears to have no assigned value.

Piping $m to the Get-Member cmdlet displays the properties and methods of the custom object.

The output shows that the object has script methods that represent the Hello and Goodbye functions. Finally, you see the that I call these script methods and display the results.

 

Get the results of the script block:

New-Module -ScriptBlock {function SayHello {“Hello, World!”}; SayHello} -ReturnResult

This example uses the –ReturnResult parameter to request the results of running the script block instead of requesting a module object.

The script block in the new module defines the SayHello function and then calls the function.

Learn last week’s command: Import-Module.

Need PowerShell training? Check out ITProTV’s PowerShell online IT training courses.