powershellscripts.com

Tutorials  PowerShell Cmdlet Help for New-Module



NAME
New-Module

SYNOPSIS
Creates a new dynamic module that exists only in memory.

SYNTAX
New-Module [-Name] [-ScriptBlock] [-ArgumentList ] [-AsCustomObject] [-Cmdlet ing[]>] [-Function ] [-ReturnResult] []

New-Module [-ScriptBlock] [-ArgumentList ] [-AsCustomObject] [-Cmdlet ] [-Functio
n ] [-ReturnResult] []


DESCRIPTION
The New-Module cmdlet creates a dynamic module from a script block. The members of the dynamic module, such as func
tions 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 a
liases are not. However, you can use the Export-ModuleMember cmdlet and the parameters of New-Module to override th
e defaults.

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

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


PARAMETERS
-ArgumentList
Specifies arguments (parameter values) that are passed to the script block.

Required? false
Position? named
Default value None
Accept pipeline input? false
Accept wildcard characters? false

-AsCustomObject []
Returns a custom object with members that represent the module members.

When you use the AsCustomObject parameter, New-Module creates the dynamic module, imports the module members in
to the current session, and then returns a PSCustomObject object instead of a PSModuleInfo object. You can save
the custom object in a variable and use dot notation to invoke the members.

If the module has multiple members with the same name, such as a function and a variable that are both named "A
," only one member with each name is accessible from the custom object.

Required? false
Position? named
Default value None
Accept pipeline input? false
Accept wildcard characters? false

-Cmdlet
Exports only the specified cmdlets from the module into the current session. Enter a comma-separated list of cm
dlets. Wildcard characters are permitted. By default, all cmdlets in the module are exported.

You cannot define cmdlets in a script block, but a dynamic module can include cmdlets if it imports the cmdlets
from a binary module.

Required? false
Position? named
Default value None
Accept pipeline input? false
Accept wildcard characters? true

-Function
Exports only the specified functions from the module into the current session. Enter a comma-separated list of
functions. Wildcard characters are permitted. By default, all functions defined in a module are exported.

Required? false
Position? named
Default value None
Accept pipeline input? false
Accept wildcard characters? true

-Name
Specifies a name for the new module. You can also pipe a module name to New-Module.

The default value is an autogenerated name that begins with "__DynamicModule_" and is followed by a GUID that s
pecifies the path to the dynamic module.

Required? true
Position? 1
Default value "__DynamicModule_" + GUID
Accept pipeline input? true (ByValue)
Accept wildcard characters? false

-ReturnResult []
Runs the script block and returns the script block results instead of returning a module object.

Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false

-ScriptBlock
Specifies the contents of the dynamic module. Enclose the contents in braces ( { } ) to create a script block.
This parameter is required.

Required? true
Position? 1
Default value None
Accept pipeline input? false
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS
System.String
You can pipe a module name string to New-Module.


OUTPUTS
System.Management.Automation.PSModuleInfo, System.Management.Automation.PSCustomObject, or None
By default, New-Module generates a PSModuleInfo object. If you use the AsCustomObject parameter, it generates a
PSCustomObject object. If you use the ReturnResult parameter, it returns the result of evaluating the script b
lock in the dynamic module.


NOTES


You can also refer to New-Module by its alias, "nmo". For more information, see about_Aliases.


-------------------------- EXAMPLE 1 --------------------------

C:\PS>new-module -scriptblock {function Hello {"Hello!"}}

Name : __DynamicModule_2ceb1d0a-990f-45e4-9fe4-89f0f6ead0e5
Path : 2ceb1d0a-990f-45e4-9fe4-89f0f6ead0e5
Description :
Guid : 00000000-0000-0000-0000-000000000000
Version : 0.0
ModuleBase :
ModuleType : Script
PrivateData :
AccessMode : ReadWrite
ExportedAliases : {}
ExportedCmdlets : {}
ExportedFunctions : {[Hello, Hello]}
ExportedVariables : {}
NestedModules : {}


Description
-----------
This command creates a new dynamic module with a function called "Hello". The command returns a module object that
represents the new dynamic module.





-------------------------- EXAMPLE 2 --------------------------

C:\PS>new-module -scriptblock {function Hello {"Hello!"}}

Name : __DynamicModule_2ceb1d0a-990f-45e4-9fe4-89f0f6ead0e5
Path : 2ceb1d0a-990f-45e4-9fe4-89f0f6ead0e5
Description :
Guid : 00000000-0000-0000-0000-000000000000
Version : 0.0
ModuleBase :
ModuleType : Script
PrivateData :
AccessMode : ReadWrite
ExportedAliases : {}
ExportedCmdlets : {}
ExportedFunctions : {[Hello, Hello]}
ExportedVariables : {}
NestedModules : {}

C:\PS> get-module
C:\PS>

C:\PS> get-command Hello

CommandType Name Definition
----------- ---- ----------
Function Hello "Hello!"


Description
-----------
This example demonstrates that dynamic modules are not returned by the Get-Module cmdlet, but the members that they
export are returned by the Get-Command cmdlet.





-------------------------- EXAMPLE 3 --------------------------

C:\PS>New-Module -scriptblock {$SayHelloHelp="Type 'SayHello', a space, and a name."; function SayHello ($name) { "
Hello, $name" }; Export-ModuleMember -function SayHello -Variable SayHelloHelp}

C:\PS> $SayHelloHelp
Type 'SayHello', a space, and a name.

C:\PS> SayHello Jeffrey
Hello, Jeffrey


Description
-----------
This command 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.





-------------------------- EXAMPLE 4 --------------------------

C:\PS>new-module -scriptblock {function Hello {"Hello!"}} -name GreetingModule | import-module

C:\PS> get-module


Name : GreetingModule
Path : d54dfdac-4531-4db2-9dec-0b4b9c57a1e5
Description :
Guid : 00000000-0000-0000-0000-000000000000
Version : 0.0
ModuleBase :
ModuleType : Script
PrivateData :
AccessMode : ReadWrite
ExportedAliases : {}
ExportedCmdlets : {}
ExportedFunctions : {[Hello, Hello]}
ExportedVariables : {}
NestedModules : {}


C:\PS> get-command hello

CommandType Name Definition
----------- ---- ----------
Function Hello "Hello!"


Description
-----------
This command demonstrates that you can make a dynamic module available to the Get-Module cmdlet by piping the dynam
ic module to the Import-Module cmdlet.

The first command uses a pipeline operator (|) to send the module object that New-Module generates to the Import-Mo
dule cmdlet. The command uses the Name parameter of New-Module to assign a friendly name to the module. Because Imp
ort-Module does not return any objects by default, there is no output from this command.

The second command uses the Get-Module cmdlet to get the modules in the session. The result shows that Get-Module c
an get the new dynamic module.

The third command uses the Get-Command cmdlet to get the Hello function that the dynamic module exports.





-------------------------- EXAMPLE 5 --------------------------

C:\PS>$m = new-module -scriptblock {function Hello ($name) {"Hello, $name"}; function Goodbye ($name) {"Goodbye, $n
ame"}} -AsCustomObject

C:\PS> $m

C:\PS> $m | get-member

TypeName: System.Management.Automation.PSCustomObject

Name MemberType Definition
---- ---------- ----------
Equals Method bool Equals(System.Object obj)
GetHashCode Method int GetHashCode()
GetType Method type GetType()
ToString Method string ToString()
Goodbye ScriptMethod System.Object Goodbye();
Hello ScriptMethod System.Object Hello();

PS C:\ps-test> $m.goodbye("Jane")
Goodbye, Jane

PS C:\ps-test> $m.hello("Manoj")
Hello, Manoj

PS C:\ps-test> goodbye Jane
Goodbye, Jane

PS C:\ps-test> hello Manoj
Hello, Manoj


Description
-----------
This example shows how to use the AsCustomObject parameter of New-Module to generate a custom object with script me
thods that represent the exported functions.

The first command uses the New-Module cmdlet to generate a dynamic module with two functions, Hello and Goodbye. Th
e command uses the AsCustomObject parameter to generate a custom object instead of the PSModuleInfo object that New
-Module generates by default. The command saves the custom object in the $m variable.

The second command attempts to display the value of the $m variable. No content appears.

The third command uses a pipeline operator (|) to send the custom object to the Get-Member cmdlet, which displays t
he properties and methods of the custom object. The output shows that the object has script methods that represent
the Hello and Goodbye functions.

The fourth and fifth commands use the script method format to call the Hello and Goodbye functions.

The sixth and seventh commands call the functions by specifying the function name and parameter value.





-------------------------- EXAMPLE 6 --------------------------

C:\PS>new-module -scriptblock {function SayHello {"Hello, World!"}; SayHello} -returnResult

Hello, World!


Description
-----------
This command uses the ReturnResult parameter to request the results of running the script block instead of requesti
ng a module object.

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






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=141554
Get-Module
Import-Module
Remove-Module
Export-ModuleMember
about_Modules