Tag Archives: PassThru

Remove-PSSnapin

February 26, 2014 Adam

SYNOPSIS
Removes Windows PowerShell snap-ins from the current session.

SYNTAX
Remove-PSSnapin [-Name] <string[]> [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Remove-PSSnapin cmdlet removes a Windows PowerShell snap-in from the current session. You can use it to remove snap-ins that you have added to Windows PowerShell, but you cannot use it to remove the snap-ins that are installed with Windows PowerShell.

After a snap-in is removed from the current session, it is still loaded, but the cmdlets and providers in the snap-in are no longer available in the session.

PARAMETERS
-Name <string[]>
Specifies the names of Windows PowerShell snap-ins to remove from the current session. The parameter name (“Name”) is optional, and wildcard characters (*) are permitted in the value.

        Required?                    true
        Position?                    1
        Default value                None
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? true

-PassThru [<SwitchParameter>]
Returns an object representing the snap-in. By default, this cmdlet does not generate any output.

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

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

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

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

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

    <CommonParameters>
        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.Management.Automation.PSSnapInInfo
You can pipe a snap-in object to Remove-PSSnapin.

OUTPUTS
None or System.Management.Automation.PSSnapInInfo
By default, Remove-PSSnapin does not generate any output. However, if you use the PassThru parameter, it generates a System.Management.Automation.PSSnapInInfo object representing the snap-in.

NOTES

You can also refer to Remove-PSSnapin by its built-in Alias, “rsnp”. For more information, see about_aliases.

Remove-PSSnapin does not check the version of Windows PowerShell before removing a snap-in from the session. If a snap-in cannot be removed, a warning appears and the command fails.

Remove-PSSnapin affects only the current session. If you have added an Add-PSSnapin command to your Windows PowerShell profile, you should delete the command to remove the snap-in from future sessions. For instructions, see about_profiles.

————————– EXAMPLE 1 ————————–

C:\PS>Remove-PSSnapin -Name Microsoft.Exchange

    Description
    ———–
    This command removes the Microsoft.Exchange snap-in from the current session. When the command is complete, the cmdlets and providers that the snap-in supported are not available in the session.

————————– EXAMPLE 2 ————————–

C:\PS>Get-PSSnapin smp* | Remove-PSSnapin

    Description
    ———–
    This command removes the Windows PowerShell snap-ins that have names beginning with “smp” from the current session.

The command uses the Get-PSSnapin cmdlet to get objects representing the snap-ins. The pipeline operator (|) sends the results to the Remove-PSSnapin cmdlet, which removes them from the session. The providers and cmdlets that this snap-in supports are no longer available in the session.

When you pipe objects to Remove-PSSnapin, the names of the objects are associated with the Name parameter, which accepts objects from the pipeline that have a Name property.

————————– EXAMPLE 3 ————————–

C:\PS>Remove-PSSnapin -Name *event*

    Description
    ———–
    This command removes all Windows PowerShell snap-ins that have names that include “event”. This command specifies the “Name” parameter name, but the parameter name can be omitted because it is optional.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113378
    Add-PSSnapin
    Get-PSSnapin
    about_profiles

cmdlet, Location, Pop

Pop-Location

February 26, 2014 Adam

NAME
Pop-Location

SYNOPSIS
Changes the current location to the location most recently pushed onto the stack. You can pop the location from the default stack or from a stack that you create by using the Push-Location cmdlet.

SYNTAX
Pop-Location [-PassThru] [-StackName <string>] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
The Pop-Location cmdlet changes the current location to the location most recently pushed onto the stack by using the Push-Location cmdlet. You can pop a location from the default stack or from a stack that you create by using a Push-Location command.

PARAMETERS
-PassThru [<SwitchParameter>]
Passes an object representing the location to the pipeline. By default, this cmdlet does not generate any output.

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

-StackName <string>
Specifies an alternate stack. Pop-Location pops the most recently added location from this stack. This stack then becomes the current stack.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_transactions.

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

INPUTS
None
You cannot pipe input to Pop-Location.

OUTPUTS
None or System.Management.Automation.PathInfo
When you use the PassThru parameter, Pop-Location generates a System.Management.Automation.PathInfo object that represents the location. Otherwise, this cmdlet does not generate any output.

NOTES

You can also refer to Pop-Location by its built-in Alias, “popd”. For more information, see about_aliases.

The Pop-Location cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type “Get-PSProvider“. For more information, see about_providers.

————————– EXAMPLE 1 ————————–

C:\PS>Pop-Location

    Description
    ———–
    This command changes your location to the location most recently added to the current stack.

————————– EXAMPLE 2 ————————–

C:\PS>Pop-Location -StackName Stack2

    Description
    ———–
    This command changes your location to the location most recently added to the Stack2 stack.

————————– EXAMPLE 3 ————————–

C:\PS>pushd HKLM:\Software\Microsoft\PowerShell

pushd Cert:\LocalMachine\TrustedPublisher

popd

PS C:\> Push-Location HKLM:\Software\Microsoft\PowerShell

PS HKLM:\Software\Microsoft\PowerShell> Push-Location Cert:\LocalMachine\TrustedPublisher

PS cert:\LocalMachine\TrustedPublisher> popd

PS HKLM:\Software\Microsoft\PowerShell> popd

PS C:\ps-test>

    Description
    ———–
    These commands use the Push-Location and Pop-Location cmdlets to move between locations supported by different Windows PowerShell providers. The commands use the “pushd” Alias for Push-Location and the “popd” Alias for Pop-Location.

The first command pushes the current file system location onto the stack and moves to the HKLM drive supported by the Windows PowerShell Registry provider. The second command pushes the Registry location onto the stack and moves to a location supported by the Windows PowerShell Certificate provider.

The last two commands pop those locations off the stack. The first “popd” command returns to the Registry: drive, and the second command returns to the file system drive.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113369
    about_providers
    Push-Location
    Set-Location
    Get-Location

cmdlet, Location, Push

Push-Location

February 26, 2014 Adam

NAME
Push-Location

SYNOPSIS
Adds the current location to the top of a list of locations (a “stack”).

SYNTAX
Push-Location [[-LiteralPath] <string>] [-PassThru] [-StackName <string>] [-UseTransaction] [<CommonParameters>]

Push-Location [[-Path] <string>] [-PassThru] [-StackName <string>] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
The Push-Location cmdlet adds (“pushes”) the current location to the top of a list of locations, called a “stack.” You can push the current location onto a default stack or onto a stack that you create. If you specify a path, Push-Location pushes the current location onto the stack and then changes the current location to the location specified by the path. You cannot push a location onto the stack unless it is the current location.

PARAMETERS
-LiteralPath <string>
Specifies the path to the new location. Unlike the Path parameter, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.

        Required?                    false
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-PassThru [<SwitchParameter>]
Passes an object representing the location to the pipeline. By default, this cmdlet does not generate any output.

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

-Path <string>
Changes your location to the location specified by this path after it adds (pushes) the current location onto the top of the stack. Enter a path to any location whose provider supports this cmdlet. Wildcards are permitted. The parameter name (“Path”) is optional.

        Required?                    false
        Position?                    1
        Default value
        Accept pipeline input?     true (ByValue, ByPropertyName)
        Accept wildcard characters? false

-StackName <string>
Specifies the name of a stack. The current location is pushed onto this stack, and this stack becomes the current stack. If the stack does not yet exist, it is created.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_transactions.

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

INPUTS
System.String
You can pipe a string that contains a path (but not a literal path) to Push-Location.

OUTPUTS
None or System.Management.Automation.PathInfo
When you use the PassThru parameter, Push-Location generates a System.Management.Automation.PathInfo object that represents the location. Otherwise, this cmdlet does not generate any output.

NOTES

You can also refer to Push-Location by its built-in Alias, “pushd”. For more information, see about_aliases.

A “stack” is a “last-in, first-out” (LIFO) data structure. It is like a vertical list in which only the top item is accessible. You can add (“push”) items only to the top of the stack, and you can retrieve (“pop”) items only from the top of the stack. To get to items below the top, you must retrieve all the items above.

The Push-Location cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type “Get-PSProvider“. For more information, see about_providers.

————————– EXAMPLE 1 ————————–

C:\PS>Push-Location C:\Windows

    Description
    ———–
    This command pushes the current location onto the default stack and then changes the location to C:\Windows.

————————– EXAMPLE 2 ————————–

C:\PS>Push-Location HKLM:\Software\Policies -StackName RegFunction

    Description
    ———–
    This command pushes the current location onto the RegFunction stack and changes the current location to the HKLM:\Software\Policies location. This command shows that you can use Push-Location with the Windows PowerShell Registry provider.

————————– EXAMPLE 3 ————————–

C:\PS>Push-Location

    Description
    ———–
    This command pushes the current location onto the default stack.

————————– EXAMPLE 4 ————————–

C:\PS>Push-Location ~ -StackName Stack2

    Description
    ———–
    This command pushes the current location onto a new stack named Stack2 and then changes the current location to the home directory (%USERPROFILE%), which is represented in the command by the tilde symbol (~) or $home. The Stack2 stack then becomes the current stack.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113370
    about_providers
    Pop-Location
    Set-Location
    Get-Location

cmdlet, New, Variable

New-Variable

February 26, 2014 Adam

NAME
New-Variable

SYNOPSIS
Creates a new Variable.

SYNTAX
New-Variable [-Name] <string> [[-Value] <Object>] [-Description <string>] [-Force] [-Option {None | ReadOnly | Constant | Private | AllScope}] [-PassThru] [-Scope <string>] [-Visibility {Public | Private}] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The New-Variable cmdlet creates a new Variable in Windows PowerShell. You can assign a value to the Variable while creating it or assign or change the value after it is created.

You can use the parameters of New-Variable to set the properties of the Variable (such as those that create read-only or constant Variables), set the scope of a Variable, and determine whether Variables are public or private.

Typically, you create a new Variable by typing the Variable name and its value, such as “$var = 3”, but you can use the New-Variable cmdlet to use its parameters.

PARAMETERS
-Description <string>
Specifies a description of the Variable.

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

-Force [<SwitchParameter>]
Allows you to create a new Variable with the same name as an existing read-only Variable.

By default, you can overwrite a Variable unless the Variable has an option value of ReadOnly or Constant. For more information, see the Option parameter.

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

-Name <string>
Specifies a name for the new Variable.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Option <ScopedItemOptions>
Sets the value of the Options property of the new Variable.

Valid values are:

— None: Sets no options. (“None” is the default.)

— ReadOnly: The value of the Variable cannot be changed except by using the Force parameter. You can use Remove-Variable to delete the Variable.

— Constant: The Variable cannot be deleted, and its properties cannot be changed. “Constant” is available only when you are creating an Alias. You cannot change the option of an existing Variable to “Constant”.

— Private: The Variable is available only within the scope specified by the Scope parameter. It is inherited by child scopes. (This value is not related to the “Private” value of the Visibility parameter.)

— AllScope: The Variable is copied to any new scopes that are created.

To see the Options property of the Variables, type “Get-Variable| Format-Table -property name, options -autosize”.

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

-PassThru [<SwitchParameter>]
Returns an object representing the new Variable. By default, this cmdlet does not generate any output.

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

-Scope <string>
Determines the scope of the new Variable. Valid values are “Global”, “Local”, or “Script”, or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). “Local” is the default. For more information, see about_scopes.

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

-Value <Object>
Specifies the initial value of the Variable.

        Required?                    false
        Position?                    2
        Default value
        Accept pipeline input?     true (ByValue, ByPropertyName)
        Accept wildcard characters? false

-Visibility <SessionStateEntryVisibility>
Determines whether the Variable is visible outside of the session in which it was created. This parameter is designed for use in scripts and commands that will be delivered to other users.

Valid values are:

— Public: The Variable is visible. (“Public” is the default.)
— Private: The Variable is not visible.

When a Variable is private, it does not appear in lists of Variables, such as those returned by Get-Variable, or in displays of the Variable: drive. Commands to read or change the value of a private Variable return an error. However, the user can run commands that use a private Variable if the commands were written in the session in which the Variable was defined.

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

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

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

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

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

INPUTS
System.Object
You can pipe a value to New-Variable.

OUTPUTS
None or System.Management.Automation.PSVariable
When you use the PassThru parameter, New-Variable generates a System.Management.Automation.PSVariable object representing the new Variable. Otherwise, this cmdlet does not generate any output.

NOTES

————————– EXAMPLE 1 ————————–

C:\PS>New-Variable days

    Description
    ———–
    This command creates a new Variable named “days”. It has no value immediately following the command.

————————– EXAMPLE 2 ————————–

C:\PS>New-Variable zipcode -Value 98033

    Description
    ———–
    This command creates a Variable named “zipcode” and assigns it the value “98033”.

————————– EXAMPLE 3 ————————–

C:\PS>New-Variable -Name max -Value 256 -Option readonly

New-Variable -Name max -Value 1024

New-Variable -Name max -Value 1024 -Force

C:\PS> New-Variable -Name max -Value 256 -Option readonly

    C:\PS> New-Variable -Name max -Value 1024
    New-Variable : A Variable with name ‘max’ already exists.
    At line:1 char:13
    + New-Variable <<<< -Name max -Value 1024

C:\PS> New-Variable -Name max -Value 1024 -Force

    Description
    ———–
    This example shows how to use the ReadOnly option of New-Variable to protect a Variable from being overwritten.

The first command creates a new Variable named Max and sets its value to “256”. It uses the Option parameter with a value of ReadOnly.

The second command tries to create a second Variable with the same name. This command returns an error, because the read-only option is set on the Variable.

The third command uses the Force parameter to override the read-only protection on the Variable. In this case, the command to create a new Variable with the same name succeeds.

————————– EXAMPLE 4 ————————–

C:\PS>New-Variable -Name counter -Visibility private

#Effect of private Variable in a module.

C:\PS> Get-Variable c*

    Name                         Value
    —-                         —–
    Culture                        en-US
    ConsoleFileName
    ConfirmPreference             High
    CommandLineParameters         {}

C:\PS> $counter
“Cannot access the Variable ‘$counter’ because it is a private Variable”

    C:\PS> Get-Counter
    Name         Value
    —-         —–
    Counter1     3.1415
    …

    Description
    ———–
    This command demonstrates the behavior of a private Variable in a module. The module contains the Get-Counter cmdlet, which has a private Variable named “Counter”. The command uses the Visibility parameter with a value of “Private” to create the Variable.

The sample output shows the behavior of a private Variable. The user who has loaded the module cannot view or change the value of the Counter Variable, but the Counter Variable can be read and changed by the commands in the module.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113361
    Get-Variable
    Set-Variable
    Remove-Variable
    Clear-Variable

cmdlet, Item, Move

Move-Item

February 26, 2014 Adam

NAME
Move-Item

SYNOPSIS
Moves an item from one location to another.

SYNTAX
Move-Item [-LiteralPath] <string[]> [[-Destination] <string>] [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

Move-Item [-Path] <string[]> [[-Destination] <string>] [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
The Move-Item cmdlet moves an item, including its properties, contents, and child items, from one location to another location. The locations must be supported by the same provider. For example, it can move a file or subdirectory from one directory to another or move a Registry subkey from one key to another. When you move an item, it is added to the new location and deleted from its original location.

PARAMETERS
-Credential <PSCredential>
Specifies a user account that has permission to perform this action. The default is the current user.

Type a user name, such as “User01” or “Domain01\User01”, or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.

This parameter is not supported by any providers installed with Windows PowerShell.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Destination <string>
Specifies the path to the location where the items are being moved. The default is the current directory. Wildcards are permitted, but the result must specify a single location.

To rename the item being moved, specify a new name in the value of the Destination parameter.

        Required?                    false
        Position?                    2
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Exclude <string[]>
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as “*.txt”. Wildcards are permitted.

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

-Filter <string>
Specifies a filter in the provider’s format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.

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

-Force [<SwitchParameter>]
Allows the cmdlet to move an item that writes over an existing read-only item. Implementation varies from provider to provider. For more information, see about_providers. Even using the Force parameter, the cmdlet cannot override security restrictions.

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

-Include <string[]>
Moves only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as “*.txt”. Wildcards are permitted.

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

-LiteralPath <string[]>
Specifies the path to the current location of the items. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-PassThru [<SwitchParameter>]
Passes an object representing the item to the pipeline. By default, this cmdlet does not generate any output.

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

-Path <string[]>
Specifies the path to the current location of the items. The default is the current directory. Wildcards are permitted.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByValue, ByPropertyName)
        Accept wildcard characters? false

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

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

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

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

-UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_transactions.

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

INPUTS
System.String
You can pipe a string that contains a path to Move-Item.

OUTPUTS
None or an object representing the moved item.
When you use the Passthru parameter, Move-Item generates an object representing the moved item. Otherwise, this cmdlet does not generate any output.

NOTES

Move-Item will move files between drives that are supported by the same provider, but it will move directories only within the same drive.

Because a Move-Item command moves the properties, contents, and child items of an item, all moves are recursive by default.

You can also refer to Move-Item by its built-in Aliases, “move”, “mv”, and “mi”. For more information, see about_aliases.

The Move-Item cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type “Get-PSProvider“. For more information, see about_providers.

————————– EXAMPLE 1 ————————–

C:\PS>Move-Item -Path C:\test.txt -Destination E:\Temp\tst.txt

    Description
    ———–
    This command moves the Test.txt file from the C: drive to the E:\Temp directory and renames it from “test.txt” to “tst.txt”.

————————– EXAMPLE 2 ————————–

C:\PS>Move-Item -Path C:\Temp -Destination C:\Logs

    Description
    ———–
    This command moves the C:\Temp directory and its contents to the C:\Logs directory. The Temp directory, and all of its subdirectories and files, then appear in the Logs directory.

————————– EXAMPLE 3 ————————–

C:\PS>Move-Item -Path .\*.txt -Destination C:\Logs

    Description
    ———–
    This command moves all of the text files (*.txt) in the current directory (represented by a dot (.)) to the C:\Logs directory.

————————– EXAMPLE 4 ————————–

C:\PS>Get-ChildItem -Path . -recurse -Include *.txt | Move-Item -Destination C:\TextFiles

    Description
    ———–
    This command moves all of the text files from the current directory and all subdirectories, recursively, to the C:\TextFiles directory.

The command uses the Get-ChildItem cmdlet to get all of the child items in the current directory (represented by the dot [.]) and its subdirectories that have a *.txt file name extension. It uses the Recurse parameter to make the retrieval recursive and the Include parameter to limit the retrieval to *.txt files.

The pipeline operator (|) sends the results of this command to Move-Item, which moves the text files to the TextFiles directory.

If files being moved to C:\Textfiles have the same name, Move-Item displays an error and continues, but it moves only one file with each name to C:\Textfiles. The other files remain in their original directories.

If the Textfiles directory (or any other element of the destination path) does not exist, the command fails. The missing directory is not created for you, even if you use the Force parameter. Move-Item moves the first item to a file called “Textfiles” and then displays an error explaining that the file already exists.

Also, by default, Get-ChildItem does not move hidden files. To move hidden files, use the Force parameter with Get-ChildItem.

————————– EXAMPLE 5 ————————–

C:\PS>Move-Item hklm:\software\mycompany\* hklm:\software\mynewcompany

    Description
    ———–
    This command moves the Registry keys and values within the MyCompany Registry key in HKLM\Software to the MyNewCompany key. The wildcard character (*) indicates that the contents of the MyCompany key should be moved, not the key itself. In this command, the optional Path and Destination parameter names are omitted.

————————– EXAMPLE 6 ————————–

C:\PS>Move-Item -literalpath ‘Logs[Sept`06]’ -Destination ‘Logs[2006]’

    Description
    ———–
    This command moves the Logs[Sept`06] directory (and its contents) into the Logs[2006] directory.

The LiteralPath parameter is used instead of Path, because the original directory name includes left bracket and right bracket characters (“[” and “]”). The path is also enclosed in single quotation marks (‘ ‘), so that the backtick symbol (`) is not misinterpreted.

The Destination parameter does not require a literal path, because the Destination Variable also must be enclosed in single quotation marks, because it includes brackets that can be misinterpreted.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113350
    about_providers
    Clear-Item
    Get-Item
    Invoke-Item
    Set-Item
    New-Item
    Remove-Item
    Rename-Item
    Copy-Item

cmdlet, ItemProperty, Move

Move-ItemProperty

February 26, 2014 Adam

NAME
Move-ItemProperty

SYNOPSIS
Moves a property from one location to another.

SYNTAX
Move-ItemProperty [-LiteralPath] <string[]> [-Destination] <string> [-Name] <string[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

Move-ItemProperty [-Path] <string[]> [-Destination] <string> [-Name] <string[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
The Move-ItemProperty cmdlet moves a property of an item from one item to another item. For example, it can move a Registry entry from one Registry key to another Registry key. When you move an item property, it is added to the new location and deleted from its original location.

PARAMETERS
-Credential <PSCredential>
Specifies a user account that has permission to perform this action. The default is the current user.

This parameter is not supported by any providers installed with Windows PowerShell.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Destination <string>
Specifies the path to the destination location.

        Required?                    true
        Position?                    2
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Exclude <string[]>
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as “*.txt”. Wildcards are permitted.

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

-Filter <string>
Specifies a filter in the provider’s format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having Windows PowerShell filter the objects after they are retrieved.

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

-Force [<SwitchParameter>]
Allows the cmdlet to move properties to or from items that cannot otherwise be accessed by the user. Implementation varies from provider to provider. For more information, see about_providers.

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

-Include <string[]>
Moves only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as “*.txt”. Wildcards are permitted.

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

-LiteralPath <string[]>
Specifies the path to the current location of the property. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Name <string[]>
Specifies the name of the property to be moved.

        Required?                    true
        Position?                    3
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-PassThru [<SwitchParameter>]
Passes an object representing the item property. By default, this cmdlet does not generate any output.

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

-Path <string[]>
Specifies the path to the current location of the property. Wildcards are permitted.

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

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

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

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

-UseTransaction [<SwitchParameter>]
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_transactions.

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

INPUTS
System.String
You can pipe a string that contains a path to Move-ItemProperty.

OUTPUTS
None or System.Management.Automation.PSCustomObject
When you use the PassThru parameter, Move-ItemProperty generates a PSCustomObject representing the moved item property. Otherwise, this cmdlet does not generate any output.

NOTES

The names of the Path, Destination, and Name parameters are optional. If you omit the parameter names, the unnamed parameter values must appear in this order: Path, Destination, Name. If you include the parameter names, the parameters can appear in any order.

You can also refer to Move-ItemProperty by its built-in Alias, “mp”. For more information, see about_aliases.

The Move-ItemProperty cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type “Get-PSProvider“. For more information, see about_providers.

————————– EXAMPLE 1 ————————–

C:\PS>Move-Itemproperty HKLM:\Software\MyCompany\MyApp -Name `
Version -Destination HKLM:\Software\MyCompany\NewApp

    Description
    ———–
    This command moves the “Version” Registry value, and its data, from the MyApp subkey to the NewApp subkey of the HKLM\Software\MyCompany Registry key.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113351
    about_providers
    Clear-ItemProperty
    New-ItemProperty
    Copy-ItemProperty
    Rename-ItemProperty
    Get-ItemProperty
    Set-ItemProperty
    Remove-ItemProperty

Alias, cmdlet, New

New-Alias

February 26, 2014 Adam

NAME
New-Alias

SYNOPSIS
Creates a new Alias.

SYNTAX
New-Alias [-Name] <string> [-Value] <string> [-Description <string>] [-Force] [-Option {None | ReadOnly | Constant | Private | AllScope}] [-PassThru] [-Scope <string>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The New-Alias cmdlet creates a new Alias in the current Windows PowerShell session. Aliases created by using New-Alias are not saved after you exit the session or close Windows PowerShell. You can use the Export-Alias cmdlet to save your Alias information to a file. You can later use Import-Alias to retrieve that saved Alias information.

PARAMETERS
-Description <string>
Specifies a description of the Alias. You can type any string. If the description includes spaces, enclose it in quotation marks.

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

-Force [<SwitchParameter>]
If set, act like Set-Alias if the Alias named already exists.

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

-Name <string>
Specifies the new Alias. You can use any alphanumeric characters in an Alias, but the first character cannot be a number.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Option <ScopedItemOptions>
Sets one or more optional properties of the Alias. Valid values are:

— None: Sets no options. (default)

— ReadOnly: The Alias cannot be changed unless you use the Force parameter.

— Constant: The Alias cannot be changed, even by using the Force parameter.

— Private: The Alias is available only within the scope specified by the Scope parameter. It is invisible in all other scopes.

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

-PassThru [<SwitchParameter>]
Returns an object representing the new Alias. By default, this cmdlet does not generate any output.

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

-Scope <string>
Specifies the scope of the new Alias. Valid values are “Global”, “Local”, or “Script”, or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). “Local” is the default. For more information, see about_scopes.

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

-Value <string>
Specifies the name of the cmdlet or command element that is being Aliased.

        Required?                    true
        Position?                    2
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

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

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

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

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
None or System.Management.Automation.AliasInfo
When you use the Passthru parameter, New-Alias generates a System.Management.Automation.AliasInfo object representing the new Alias. Otherwise, this cmdlet does not generate any output.

NOTES

To create a new Alias, use Set-Alias or New-Alias. To change an Alias, use Set-Alias. To delete an Alias, use Remove-Item.

————————– EXAMPLE 1 ————————–

C:\PS>New-Alias list Get-ChildItem

    Description
    ———–
    This command creates an Alias named “list” to represent the Get-ChildItem cmdlet.

————————– EXAMPLE 2 ————————–

C:\PS>New-Alias -Name w -Value Get-WmiObject -Description “quick wmi Alias” -Option ReadOnly

C:\PS> Get-Alias -Name w | Format-List *

    Description
    ———–
    This command creates an Alias named “w” to represent the Get-WmiObject cmdlet. It creates a description, “quick wmi Alias“, for the Alias and makes it read only. The last line of the command uses Get-Alias to get the new Alias and pipes it to Format-List to display all of the information about it.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113352
    Set-Alias
    Get-Alias
    Export-Alias
    Import-Alias

cmdlet, ModuleManifest, New

New-ModuleManifest

February 26, 2014 Adam

NAME
New-ModuleManifest

SYNOPSIS
Creates a new module manifest.

SYNTAX
New-ModuleManifest [-Path] <string> -Author <string> -CompanyName <string> -Copyright <string> -Description <string> -FileList <string[]> -FormatsToProcess <string[]> -ModuleToProcess <string> -NestedModules <string[]> -RequiredAssemblies <string[]> -TypesToProcess <string[]> [-AliasesToExport <string[]>] [-ClrVersion <Version>] [-CmdletsToExport <string[]>] [-DotNetFrameworkVersion <Version>] [-FunctionsToExport <string[]>] [-Guid <Guid>] [-ModuleList <Object[]>] [-ModuleVersion <Version>] [-PassThru] [-PowerShellHostName <string>] [-PowerShellHostVersion <Version>] [-PowerShellVersion <Version>] [-PrivateData <Object>] [-ProcessorArchitecture {None | MSIL | X86 | IA64 | Amd64}] [-RequiredModules <Object[]>] [-ScriptsToProcess <string[]>] [-VariablesToExport <string[]>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The New-ModuleManifest cmdlet creates a new module manifest (.psd1) file, populates its values, and saves the manifest file in the specified path.

Module authors can use this cmdlet to create a manifest for their module. A module manifest is a .psd1 file that contains a hash table. The keys and values in the hash table describe the contents and attributes of the module, define the prerequisites, and determine how the components are processed. Manifests are not required for a module.

New-ModuleManifest creates a manifest that includes all of the commonly used manifest keys, so you can use the default output as a manifest template. To add or change values, or to add module keys that this cmdlet does not add, open the resulting file in a text editor.

Each parameter of this cmdlet (except for Path and PassThru) creates a module manifest key and its value. In a module manifest, only the ModuleVersion key is required. However, several other parameters of this cmdlet are mandatory. As a result, you can type a “New-ModuleManifest” command without parameters and the cmdlet will prompt you for values for other commonly used keys. To leave the value empty, press ENTER.

For a complete description of the format, effects, and requirements of a module manifest, see “How to Write a Module Manifest” in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143613.

PARAMETERS
-AliasesToExport <string[]>
Specifies the Aliases that the module exports. Wildcards are permitted.

You can use this parameter to restrict the Aliases that are exported by the module. It can remove Aliases from the list of exported Aliases, but it cannot add Aliases to the list.

If you omit this parameter, New-ModuleManifest creates an AliasesToExport key with a value of * (all), meaning that all Aliases that are exported by the module are exported by the manifest.

        Required?                    false
        Position?                    named
        Default value                * (all)
        Accept pipeline input?     false
        Accept wildcard characters? true

-Author <string>
Specifies the module author.

This parameter is required by the cmdlet, but the Author key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates an Author key with the name of the current user.

        Required?                    true
        Position?                    named
        Default value                Name of the current user
        Accept pipeline input?     false
        Accept wildcard characters? false

-ClrVersion <Version>
Specifies the version of the Common Language Runtime (CLR) of the Microsoft .NET Framework that the module requires.

If you omit this parameter, New-ModuleManifest creates a CLRVersion key with an empty string value.

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

-CmdletsToExport <string[]>
Specifies the cmdlets that the module exports. Wildcards are permitted.

You can use this parameter to restrict the cmdlets that are exported by the module. It can remove cmdlets from the list of exported cmdlets, but it cannot add cmdlets to the list.

If you omit this parameter, New-ModuleManifest creates a CmdletsToExport key with a value of * (all), meaning that all cmdlets that are exported by the module are exported by the manifest.

-CompanyName <string>
Identifies the company or vendor who created the module.

This parameter is required by the cmdlet, but the CompanyName key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a CompanyName key with a value of “Unknown”.

        Required?                    true
        Position?                    named
        Default value                “Unknown”
        Accept pipeline input?     false
        Accept wildcard characters? false

-Copyright <string>
Specifies a copyright statement for the module.

This parameter is required by the cmdlet, but the Copyright key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a Copyright key with a value of “(c) <year> <username>. All rights reserved.” where <year> is the current year and <username> is the value of the Author key (if one is specified) or the name of the current user.

        Required?                    true
        Position?                    named
        Default value                (c) <year> <username>. All rights reserved.
        Accept pipeline input?     false
        Accept wildcard characters? false

-Description <string>
Describes the contents of the module.

This parameter is required by the cmdlet, but the Description key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a Description key with an empty string value.

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

-DotNetFrameworkVersion <Version>
Specifies the version of the Microsoft .NET Framework that the module requires.

If you omit this parameter, New-ModuleManifest creates a DotNetFrameWorkVersion key with an empty string value.

-FileList <string[]>
Specifies all items that are included in the module.

This key is designed to act as a module inventory. These files are not automatically exported with the module.

This parameter is required by the cmdlet, but the FileList key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a FileList key with an empty array value.

-FormatsToProcess <string[]>
Specifies the formatting files (.ps1xml) that run when the module is imported.

When you import a module, Windows PowerShell runs the Update-FormatData cmdlet with the specified files. Because formatting files are not scoped, they affect all session states in the session.

This parameter is required by the cmdlet, but the FormatsToProcess key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a FormatsToProcess key with an empty array value.

-FunctionsToExport <string[]>
Specifies the Functions that the module exports. Wildcards are permitted.

You can use this parameter to restrict the Functions that are exported by the module. It can remove Functions from the list of exported Aliases, but it cannot add Functions to the list.

If you omit this parameter, New-ModuleManifest creates an FunctionsToExport key with a value of * (all), meaning that all Functions that are exported by the module are exported by the manifest.

-Guid <Guid>
Specifies a unique identifier for the module. The GUID can be used to distinguish among modules with the same name.

If you omit this parameter, New-ModuleManifest creates a GUID key in the manifest and generates a GUID for the value.

To create a new GUID in Windows PowerShell, type “[guid]::NewGuid()”.

        Required?                    false
        Position?                    named
        Default value                A GUID generated for the module
        Accept pipeline input?     false
        Accept wildcard characters? false

-ModuleList <Object[]>
Lists all modules that are packaged with this module.

Enter each module name as a string or enter a hash table with ModuleName and GUID keys. The hash table can also have an optional ModuleVersion key.

This key is designed to act as a module inventory. These modules are not automatically processed.

If you omit this parameter, New-ModuleManifest creates a ModuleList key in the manifest with an empty array value.

-ModuleToProcess <string>
Specifies the primary or “root” file of the module. When the module is imported, the members that are exported from the root module file are imported into the caller’s session state. Enter the file name of one script module (.psm1) or binary module (.dll).

If a module has a manifest file and no root file has been designated in the ModuleToProcess key, the manifest becomes the primary file for the module, and the module becomes a “manifest module” (ModuleType = Manifest).

To export members from .psm1 or .dll files in a module that has a manifest, the names of those files must be specified in the values of the ModuleToProcess or NestedModules keys in the manifest. Otherwise, their members are not exported.

This parameter is required by the cmdlet, but the ModuleToProcess key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a ModuleToProcess key with an empty string value.

-ModuleVersion <Version>
Specifies the version of the module.

This parameter is not required by the cmdlet, but a ModuleVersion key is required in the manifest. If you omit this parameter, New-ModuleManifest creates a ModuleVersion key with a value of “1.0”.

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

-NestedModules <string[]>
Specifies script modules (.psm1) and binary modules (.dll) that are imported into the module’s session state. The files in the NestedModules key run in the order in which they are listed in the value.

Typically, nested modules contain commands that the root module needs for its internal processing. By default, the commands in nested modules are exported from the module’s session state into the caller’s session state, but the root module can restrict the commands that it exports (for example, by using an Export-Module command).

Nested modules in the module session state are available to the root module, but they are not returned by a Get-Module command in the caller’s session state.

Scripts (.ps1) that are listed in the NestedModules key are run in the module’s session state, not in the caller’s session state. To run a script in the caller’s session state, list the script file name in the value of the ScriptsToProcess key in the manifest.

This parameter is required by the cmdlet, but the NestedModules key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a NestedModules key with an empty array value.

-PassThru [<SwitchParameter>]
Writes the resulting module manifest to the console, in addition to creating a .psd1 file. By default, this cmdlet does not generate any output.

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

-Path <string>
Specifies the path and file name of the new module manifest. Enter a path and file name with a .psd1 file name extension, such as “$pshome\Modules\MyModule\MyModule.psd1”. This parameter is required.

If you specify the path to an existing file, New-ModuleManifest replaces the file without warning unless the file has the read-only attribute.

The manifest should be located in the module’s directory, and the manifest file name should be the same as the module directory name, but with a .psd1 file name extension.

Note: You cannot use Variables, such as $pshome or $home, in response to a prompt for a Path parameter value. To use a Variable, include the Path parameter in the command.

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

-PowerShellHostName <string>
Specifies the name of the Windows PowerShell host program that the module requires. Enter the name of the host program, such as “Windows PowerShell ISE Host” or “ConsoleHost”. Wildcards are not permitted.

To find the name of a host program, in the program, type “$host.name”.

If you omit this parameter, New-ModuleManifest creates a PowerShellHostName key with an empty string value.

-PowerShellHostVersion <Version>
Specifies the minimum version of the Windows PowerShell host program that works with the module. Enter a version number, such as 1.1.

If you omit this parameter, New-ModuleManifest creates a PowerShellHostName key with an empty string value.

-PowerShellVersion <Version>
Specifies the minimum version of Windows PowerShell that will work with this module. Enter 1.0 or 2.0. Requirements for versions greater than 2.0 are not enforced.

If you omit this parameter, New-ModuleManifest creates a PowerShellVersion key with an empty string value.

-PrivateData <Object>
Specifies data that is passed to the module when it is imported.

If you omit this parameter, New-ModuleManifest creates a PrivateData key with an empty string value.

-ProcessorArchitecture <ProcessorArchitecture>
Specifies the processor architecture that the module requires. Valid values are x86, AMD64, IA64, and None (unknown or unspecified).

If you omit this parameter, New-ModuleManifest creates a ProcessorArchitecture key with an empty string value.

-RequiredAssemblies <string[]>
Specifies the assembly (.dll) files that the module requires. Windows PowerShell loads the specified assemblies before updating types or formats, importing nested modules, or importing the module file that is specified in the value of the ModuleToProcess key.

Use this parameter to list all the assemblies that the module requires, including assemblies that must be loaded to update any formatting or type files that are listed in the FormatsToProcess or TypesToProcess keys, even if those assemblies are also listed as binary modules in the NestedModules key.

This parameter is required by the cmdlet, but the RequiredAssemblies key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a RequiredAssemblies key with an empty array value.

-RequiredModules <Object[]>
Specifies modules that must be in the global session state. If the required modules are not in the global session state, attempts to import this module will fail.

Enter each module name as a string or enter a hash table with the ModuleName and GUID keys. The hash table can also have an optional ModuleVersion key. For more information, see the examples.

Windows PowerShell does not import required modules automatically. It verifies only that the required modules are present. However, modules can include scripts (.ps1) that import the required modules into the global session state.

If you omit this parameter, New-ModuleManifest creates a RequiredModules key with an empty array value.

-ScriptsToProcess <string[]>
Specifies script (.ps1) files that run in the caller’s session state when the module is imported. You can use these scripts to prepare an Environment, just as you might use a login script.

To specify scripts that run in the module’s session state, use the NestedModules key.

If you omit this parameter, New-ModuleManifest creates a ScriptsToProcess key with an empty array value.

-TypesToProcess <string[]>
Specifies the type files (.ps1xml) that run when the module is imported.

When you import the module, Windows PowerShell runs the Update-TypeData cmdlet with the specified files. Because type files are not scoped, they affect all session states in the session.

This parameter is required by the cmdlet, but the TypesToProcess key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a TypesToProcess key with an empty array value.

-VariablesToExport <string[]>
Specifies the Variables that the module exports. Wildcards are permitted.

You can use this parameter to restrict the Variables that are exported by the module. It can remove Variables from the list of exported Variables, but it cannot add Variables to the list.

If you omit this parameter, New-ModuleManifest creates a VariablesToExport key with a value of * (all), meaning that all Variables that are exported by the module are exported by the manifest.

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

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

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

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

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
None or System.String
By default, New-ModuleManifest does not generate any output. However, if you use the PassThru parameter, it generates a System.String object representing the module manifest..

NOTES

Module manifests are usually optional. However, a module manifest is required to export an assembly that is installed in the global assembly cache.

To add or change files in the $pshome\Modules directory (%Windir%\System32\WindowsPowerShell\v1.0\Modules), start Windows PowerShell with the “Run as administrator” option.

A “session” is an instance of the Windows PowerShell execution Environment. A session can have one or more session state. By default, a session has only a global session state, but each imported module has its own session state. Session states allow the commands in a module to run without affecting the global session state.

The “caller’s session state” is the session state into which a module is imported. Typically, it refers to the global session state, but when a module imports nested modules, the “caller” is the module and the “caller’s session state” is the module’s session state.

————————– EXAMPLE 1 ————————–

C:\PS>New-ModuleManifest

    Path: C:\Users\User01\Documents\WindowsPowerShell\Modules\Test-Module\Test-Module.psd1
    NestedModules[0]: BackgroundModule.psm1
    Author: Jinghao Liu
    CompanyName: Fabrikam, Inc.
    Copyright: Copyright © 2009 Liu Jinghao. All rights reserved.
    ModuleToProcess: TestModule.psm1
    Description: Cmdlets to find common errors in scripts.
    TypesToProcess[0]: TestTypes.ps1xml
    FormatsToProcess[0]: TestFormat.ps1xml
    RequiredAssemblies[0]: Test.dll
    FileList[0]: Test-Module.psd1
    FileList[1]: Test-Module.psm1
    FileList[2]: BackgroundModule.psm1
    FileList[3]: TestTypes.ps1xml
    FileList[4]: TestFormat.ps1xml
    FileList[5]: Test.dll
    FileList[6]: TestIcon.ico

    Description
    ———–
    This command creates a new module manifest. The cmdlet prompts you for the parameters that it requires, including the Path parameter, and creates a manifest file in the specified location.

The output of this command shows sample responses to the prompts. To use default values, press ENTER.

The actual prompt, and its handling of quoted and non-quoted phrases, depends on the host program in which Windows PowerShell is running.

————————– EXAMPLE 2 ————————–

C:\PS>New-ModuleManifest -PowerShellVersion 1.0 -AliasesToExport JKBC, DRC, TAC

    Description
    ———–
    This command creates a new module manifest. The command includes parameters that the cmdlet does not require (or prompt for). You can include other manifest key values at the prompt.

————————– EXAMPLE 3 ————————–

C:\PS>New-ModuleManifest -RequiredModules FileTransfer,@{ModuleName=”BackgroundModule”;GUID=”486569a2-2784-48bf-af15-70ba837a64d0″;ModuleVersion=”3.5″}

    Description
    ———–
    This example shows how to use the string and hash table formats of the RequiredModules parameter value. Strings and hash tables can be used in the same command.

This command commands creates a module manifest for a module that requires the FileTransfer module and a (fictitious) module named “BackgroundModule”.

The command uses a string format to specify the name of the FileTransfer module and the hash table format to specify the name, a GUID, and a version of the BackgroundModule.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=141555
    Import-Module
    Get-Module
    New-Module
    Remove-Module
    Export-ModuleMember
    Test-ModuleManifest
    about_modules

Alias, cmdlet, Import

Import-Alias

February 26, 2014 Adam

NAME
Import-Alias

SYNOPSIS
Imports an Alias list from a file.

SYNTAX
Import-Alias [-Path] <string> [-Force] [-PassThru] [-Scope <string>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Import-Alias cmdlet imports an Alias list from a file.

PARAMETERS
-Force [<SwitchParameter>]
Allows the cmdlet to import an Alias that is already defined and is read only. You can use the following command to display information about the currently-defined Aliases:

Get-Alias | Select-Object name,Options
The value of the Options property will include “ReadOnly” if the corresponding Alias is read only.

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

-PassThru [<SwitchParameter>]
Returns an object representing the Alias. By default, this cmdlet does not generate any output.

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

-Path <string>
Specifies the path to a file that includes exported Alias information. Wildcards are allowed but they must resolve to a single name.

-Scope <string>
Specifies the scope into which the Aliases are imported. Valid values are “Global”, “Local”, or “Script”, or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). “Local” is the default. For more information, see about_scopes.

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

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

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

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

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

INPUTS
System.String
You can pipe a string that contains a path to Import-Alias.

OUTPUTS
None or System.Management.Automation.AliasInfo
When you use the Passthru parameter, Import-Alias returns a System.Management.Automation.AliasInfo object that represents the Alias. Otherwise, this cmdlet does not generate any output.

NOTES

————————– EXAMPLE 1 ————————–

C:\PS>Import-Alias test.txt

    Description
    ———–
    This command imports Alias information from a file named test.txt.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113339
    Export-Alias
    Get-Alias
    New-Alias
    Set-Alias

cmdlet, Import, Module

Import-Module

February 26, 2014 Adam

NAME
Import-Module

SYNOPSIS
Adds modules to the current session.

SYNTAX
Import-Module [-Name] <string[]> [-Alias <string[]>] [-ArgumentList <Object[]>] [-AsCustomObject] [-Cmdlet <string[]>] [-Force] [-Function <string[]>] [-Global] [-PassThru] [-Prefix <string>] [-Variable <string[]>] [-Version <Version>] [<CommonParameters>]

Import-Module [-Assembly] <Assembly[]> [-Alias <string[]>] [-ArgumentList <Object[]>] [-AsCustomObject] [-Cmdlet <string[]>] [-Force] [-Function <string[]>] [-Global] [-PassThru] [-Prefix <string>] [-Variable <string[]>] [-Version <Version>] [<CommonParameters>]

Import-Module [-ModuleInfo] <PSModuleInfo[]> [-Alias <string[]>] [-ArgumentList <Object[]>] [-AsCustomObject] [-Cmdlet <string[]>] [-Force] [-Function <string[]>] [-Global] [-PassThru] [-Prefix <string>] [-Variable <string[]>] [-Version <Version>] [<CommonParameters>]

DESCRIPTION
The Import-Module cmdlet adds one or more modules to the current session.

A module is a package that contains members (such as cmdlets, providers, scripts, Functions, Variables, and other tools and files) that can be used in Windows PowerShell. After a module is imported, you can use the module members in your session.

To import a module, use the Name, Assembly, or ModuleInfo parameter to identify the module to import. By default, Import-Module imports all members that the module exports, but you can use the Alias, Function, Cmdlet, and Variable parameters to restrict the members that are imported.

Import-Module imports a module only into the current session. To import the module into all sessions, add an Import-Module command to your Windows PowerShell profile. For more information about profiles, see about_profiles.

For more information about modules, see about_modules.

PARAMETERS
-Alias <string[]>
Imports only the specified Aliases from the module into the current session. Enter a comma-separated list of Aliases. Wildcard characters are permitted.

Some modules automatically export selected Aliases into your session when you import the module. This parameter lets you select from among the exported Aliases.

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

-ArgumentList <Object[]>
Specifies arguments (parameter values) that are passed to a script module during the Import-Module command. This parameter is valid only when you are importing a script module.

You can also refer to ArgumentList by its Alias, “args”. For more information, see about_aliases.

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

-AsCustomObject [<SwitchParameter>]
Returns a custom object with members that represent the imported module members. This parameter is valid only for script modules.

When you use the AsCustomObject parameter, Import-Module imports the module members into the 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.

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

-Assembly <Assembly[]>
Imports the cmdlets and providers implemented in the specified assembly objects. Enter a Variable that contains assembly objects or a command that creates assembly objects. You can also pipe an assembly object to Import-Module.

When you use this parameter, only the cmdlets and providers implemented by the specified assemblies are imported. If the module contains other files, they are not imported, and you might be missing important members of the module. Use this parameter for debugging and testing the module, or when you are instructed to use it by the module author.

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

-Cmdlet <string[]>
Imports only the specified cmdlets from the module into the current session. Enter a list of cmdlets. Wildcard characters are permitted.

Some modules automatically export selected cmdlets into your session when you import the module. This parameter lets you select from among the exported cmdlets.

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

-Force [<SwitchParameter>]
Re-imports a module and its members, even if the module or its members have an access mode of read-only.

-Function <string[]>
Imports only the specified Functions from the module into the current session. Enter a list of Functions. Wildcard characters are permitted.

Some modules automatically export selected Functions into your session when you import the module. This parameter lets you select from among the exported Functions.

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

-Global [<SwitchParameter>]
When used in a script module (.psm1), this parameter imports modules into the global session state.

This parameter is effective only when it appears in a script module. Otherwise, it is ignored.

By default, the commands in a script module, including commands from nested modules, are imported into the caller’s session state. To restrict the commands that a module exports, use an Export-ModuleMember command in the script module.

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

-ModuleInfo <PSModuleInfo[]>
Specifies module objects to import. Enter a Variable that contains the module objects, or a command that gets the module objects, such as a “Get-Module -listavailable” command. You can also pipe module objects to Import-Module.

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

-Name <string[]>
Specifies the names of the modules to import. Enter the name of the module or the name of a file in the module, such as a .psd1, .psm1, .dll, or ps1 file. File paths are optional. Wildcards are not permitted. You can also pipe module names and file names to Import-Module.

If you omit a path, Import-Module looks for the module in the paths saved in the PSModulePath Environment Variable ($env:PSModulePath).

Specify only the module name whenever possible. When you specify a file name, only the members that are implemented in that file are imported. If the module contains other files, they are not imported, and you might be missing important members of the module.

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

-PassThru [<SwitchParameter>]
Returns objects that represent the modules that were imported. By default, this cmdlet does not generate any output.

Notes
— When you pipe the output of a “Get-Module -listavailable” command to an Import-Module command with the PassThru parameter, Import-Module returns the object that Get-Module passed to it without updating the object. As a result, the Exported and NestedModules properties are not yet populated.

— When you use the Prefix parameter to specify a prefix for the member, the prefix does not appear in the member names in the properties of the module object. The object records what was exported before the prefix was applied.

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

-Prefix <string>
Adds the specified prefix to the nouns in the names of imported module members.

Use this parameter to avoid name conflicts that might occur when different members in the session have the same name. This parameter does not change the module, and it does not affect files that the module imports for its own use (known as “nested modules”). It affects only the names of members in the current session.

For example, if you specify the prefix “UTC” and then import a Get-Date cmdlet, the cmdlet is known in the session as Get-UTCDate, and it is not confused with the original Get-Date cmdlet.

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

-Variable <string[]>
Imports only the specified Variables from the module into the current session. Enter a list of Variables. Wildcard characters are permitted.

Some modules automatically export selected Variables into your session when you import the module. This parameter lets you select from among the exported Variables.

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

-Version <Version>
Specifies the version of the module to import. Use this parameter when you have different versions of the same module on your system.

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

INPUTS
System.String, System.Management.Automation.PSModuleInfo, System.Reflection.Assembly
You can pipe a module name, module object, or assembly object to Import-Module.

OUTPUTS
None, System.Management.Automation.PSModuleInfo, or System.Management.Automation.PSCustomObject
By default, Import-Module does not generate any output. If you use the PassThru parameter, it generates a System.Management.Automation.PSModuleInfo object that represents the module. If you use the AsCustomObject parameter, it generates a PSCustomObject object.

NOTES

You can also refer to Import-Module by its Alias, “ipmo”. For more information, see about_aliases.

Before you can import a module, the module directory must be copied to a directory that is accessible to your local computer. For more information, see about_modules.

Module members run in their own private module session state, so the commands that they use for internal processing do not affect your session state.

If you import members with the same name and the same type into your session, Windows PowerShell uses the member imported last by default. Variables and Aliases are replaced, and the originals are not accessible. Functions, cmdlets and providers are merely “shadowed” by the new members, and they can be accessed by qualifying the command name with the name of its snap-in, module, or Function path.

To update the formatting data for commands that have been imported from a module, use the Update-FormatData cmdlet. Update-FormatData also updates the formatting data for commands in the session that were imported from modules. If the formatting file for a module changes, you can run an Update-FormatData command to update the formatting data for imported commands. You do not need to import the module again.

To import a module that is created by Import-PSSession or Export-PSSession, the execution policy in the current session cannot be Restricted or AllSigned, because the modules that Import-PSSession and Export-PSSession create contains unsigned script files that are prohibited by these policies. To use Import-Module without changing the execution policy for the local computer, use the Scope parameter of Set-ExecutionPolicy to set a less restrictive execution policy for a single process.

————————– EXAMPLE 1 ————————–

C:\PS>Import-Module -Name BitsTransfer

    Description
    ———–
    This command imports the members of the BitsTransfer module into the current session.

The Name parameter name (-Name) is optional and can be omitted.

By default, Import-Module does not generate any output when it imports a module. To request output, use the PassThru or AsCustomObject parameter, or the Verbose common parameter.

————————– EXAMPLE 2 ————————–

C:\PS>Get-Module -listAvailable | Import-Module

    Description
    ———–
    This command imports all available modules in the path specified by the PSModulePath Environment Variable ($env:psmodulepath) into the current session.

————————– EXAMPLE 3 ————————–

C:\PS>$m = Get-Module -ListAvailable BitsTransfer, ServerBackup

C:\PS> Import-Module -moduleInfo $m

    Description
    ———–
    These commands import the members of the BitsTransfer and ServerBackup modules into the current session.

The first command uses the Get-Module cmdlet to get PSModuleInfo objects that represent the BitsTransfer and ServerBackup modules. It saves the objects in the $m Variable. The ListAvailable parameter is required when you are getting modules that are not yet imported into the session.

The second command uses the ModuleInfo parameter of Import-Module to import the modules into the current session.

These commands are equivalent to using a pipeline operator (|) to send the output of a Get-Module command to Import-Module.

————————– EXAMPLE 4 ————————–

C:\PS>Import-Module -Name c:\ps-test\modules\test -Verbose

    VERBOSE: Loading module from path ‘C:\ps-test\modules\Test\Test.psm1’.
    VERBOSE: Exporting Function ‘my-parm’.
    VERBOSE: Exporting Function ‘get-parm’.
    VERBOSE: Exporting Function ‘get-spec’.
    VERBOSE: Exporting Function ‘get-specDetails’.

    Description
    ———–
    This command uses an explicit path to identify the module to import.

It also uses the Verbose common parameter to get a list of the items imported from the module. Without the Verbose, PassThru, or AsCustomObject parameter, Import-Module does not generate any output when it imports a module.

————————– EXAMPLE 5 ————————–

C:\PS>Import-Module BitsTransfer -Cmdlet Add-BitsTransferFile, Get-BitsTransfer

C:\PS> Get-Module BitsTransfer

    Name             : BitsTransfer
    Path             : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\BitsTransfer\BitsTransfer.psd1
    Description     :
    Guid             : 8fa5064b-8479-4c5c-86ea-0d311fe48875
    Version         : 1.0.0.0
    ModuleBase        : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\BitsTransfer
    ModuleType        : Manifest
    PrivateData     :
    AccessMode        : ReadWrite
    ExportedAliases : {}
    ExportedCmdlets : {[Add-BitsTransfer, Add-BitsTransfer], [Complete-BitsTransfer, Complete-BitsTransfer], [Get-BitsTransfer, Get-BitsTransfer], [Rem
                        ove-BitsTransfer, Remove-BitsTransfer]…}
    ExportedFunctions : {}
    ExportedVariables : {}
    NestedModules     : {Microsoft.BackgroundIntelligentTransfer.Management}

C:\PS> Get-Command -module BitsTransfer

    CommandType Name                Definition
    ———– —-                ———-
    Cmdlet     Add-BitsTransfer    Add-BitsTransfer [-BitsJob] <BitsJob[]> [-Source] <String[]> [[-Destination] <String[]>] [-Verbose] [-Debug] [-ErrorA…
    Cmdlet     Get-BitsTransfer    Get-BitsTransfer [[-Name] <String[]>] [-AllUsers] [-Verbose] [-Debug] [-ErrorAction <ActionPreference>] [-WarningActi…

    Description
    ———–
    This example shows how to restrict the module members that are imported into the session and the effect of this command on the session.

The first command imports only the Add-BitsTransfer and Get-BitsTransfer cmdlets from the BitsTransfer module. The command uses the Cmdlet parameter to restrict the cmdlets that the module imports. You can also use the Alias, Variable, and Function parameters to restrict other members that a module imports.

The second command uses the Get-Module cmdlet to get the object that represents the BitsTransfer module. The ExportedCmdlets property lists all of the cmdlets that the module exports, even when they were not all imported.

The third command uses the Module parameter of the Get-Command cmdlet to get the commands that were imported from the BitsTransfer module. The results confirm that only the Add-BitsTransfer and Get-BitsTransfer cmdlets were imported.

————————– EXAMPLE 6 ————————–

C:\PS>Import-Module BitsTransfer -Prefix PS -PassThru

    Name             : bitstransfer
    Path             : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\bitstransfer\bitstransfer.psd1
    Description     :
    Guid             : 8fa5064b-8479-4c5c-86ea-0d311fe48875
    Version         : 1.0.0.0
    ModuleBase        : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\bitstransfer
    ModuleType        : Manifest
    PrivateData     :
    AccessMode        : ReadWrite
    ExportedAliases : {}
    ExportedCmdlets : {[Add-BitsTransfer, Add-BitsTransfer], [Remove-BitsTransfer, Remove-BitsTransfer], [Complete-BitsTransfer, Complete-BitsTransfer]
                        , [Get-BitsTransfer, Get-BitsTransfer]…}
    ExportedFunctions : {}
    ExportedVariables : {}
    NestedModules     : {Microsoft.BackgroundIntelligentTransfer.Management}

C:\PS> Get-Command -module bitstransfer

    CommandType     Name                        Definition
    ———–     —-                        ———-
    Cmdlet         Add-PSBitsTransfer         Add-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Source] <String[]> …
    Cmdlet         Complete-PSBitsTransfer     Complete-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Verbose] [-Deb…
    Cmdlet         Get-PSBitsTransfer         Get-PSBitsTransfer [[-Name] <String[]>] [-AllUsers] [-Verbose] …
    Cmdlet         Remove-PSBitsTransfer     Remove-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Verbose] [-Debug…
    Cmdlet         Resume-PSBitsTransfer     Resume-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Asynchronous] [-…
    Cmdlet         Set-PSBitsTransfer         Set-PSBitsTransfer [-BitsJob] <BitsJob[]> [-DisplayName <String…
    Cmdlet         Start-PSBitsTransfer        Start-PSBitsTransfer [[-Source] <String[]>] [[-Destination] <St…
    Cmdlet         Suspend-PSBitsTransfer     Suspend-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Verbose] [-Debu…

    Description
    ———–
    These commands import the BitsTransfer module into the current session, add a prefix to the member names, and then display the prefixed member names.

The first command uses the Import-Module cmdlet to import the BitsTransfer module. It uses the Prefix parameter to add the PS prefix to all members that are imported from the module and the PassThru parameter to return a module object that represents the imported module.

The module object that the command returns has an ExportedCmdlets property that lists the exported members. The prefix does not appear in the cmdlet names, because it is applied after the members are exported (but before they are imported).

The second command uses the Get-Command cmdlet to get the members that have been imported from the module. It uses the Module parameter to specify the module. The output shows that the module members were correctly prefixed.

The prefix that you use applies only to the members in the current session. It does not change the module.

————————– EXAMPLE 7 ————————–

C:\PS>Get-Module -list | Format-Table -property name, moduletype -auto

    Name         ModuleType
    —-         ———-
    Show-Calendar     Script
    BitsTransfer    Manifest
    PSDiagnostics Manifest
    TestCmdlets     Script

C:\PS> $a = Import-Module -Name Show-Calendar -AsCustomObject

C:\PS> $a | 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()
    Show-Calendar ScriptMethod System.Object Show-Calendar();

C:\PS> $a.”show-calendar”()

    Description
    ———–
    These commands demonstrate how to get and use the custom object that Import-Module returns.

Custom objects include synthetic members that represent each of the imported module members. For example, the cmdlets and Functions in a module are converted to script methods of the custom object.

Custom objects are very useful in scripting. They are also useful when several imported objects have the same names. Using the script method of an object is equivalent to specifying the fully qualified name of an imported member, including its module name.

The AsCustomObject parameter can be used only with a script module, so the first task is to determine which of the available modules is a script module.

The first command uses the Get-Module cmdlet to get the available modules. The command uses a pipeline operator (|) to pass the module objects to the Format-Table cmdlet, which lists the Name and ModuleType of each module in a table.

The second command uses the Import-Module cmdlet to import the Show-Calendar script module. The command uses the AsCustomObject parameter to request a custom object. The command saves the resulting custom object in the $a Variable.

The third command uses a pipeline operator to send the $a Variable to the Get-Member cmdlet, which gets the properties and methods of the PSCustomObject in $a. The output shows a Show-Calendar script method.

The last command uses the Show-Calendar script method. The method name must be enclosed in quotation marks, because it includes a hyphen.

————————– EXAMPLE 8 ————————–

C:\PS>Import-Module BitsTransfer

C:\PS> Import-Module BitsTransfer -Force -Prefix PS

    Description
    ———–
    This example shows how to use the Force parameter of Import-Module when you are re-importing a module into the same session.

The first command imports the BitsTransfer module. The second command imports the module again, this time using the Prefix parameter.

The second command also includes the Force parameter, which removes the module and then imports it again. Without this parameter, the session would include two copies of each BitsTransfer cmdlet, one with the standard name and one with the prefixed name.

————————– EXAMPLE 9 ————————–

C:\PS>Get-Date

Saturday, September 12, 2009 6:47:04 PM

C:\PS> Import-Module TestModule

C:\PS> Get-Date
09255

C:\PS> Get-Command Get-Date | Format-Table -property commandtype, name, pssnapin, module -auto

    CommandType Name     pssnapin                     Module
    ———– —-     ——–                     ——
     Function Get-Date                                 TestModule
         Cmdlet Get-Date Microsoft.PowerShell.Utility

C:\PS> Microsoft.PowerShell.Utility\Get-Date

Saturday, September 12, 2009 6:33:23 PM

    Description
    ———–
    This example shows how to run commands that have been hidden by imported commands.

The first command run the Get-Date cmdlet that comes with Windows PowerShell. It returns a DateTime object with the current date.

The second command imports the TestModule module. This module includes a Function named Get-Date that returns the Julian date.

The third command runs the Get-Date command again. Because Functions take precedence over cmdlets, the Get-Date Function from the TestModule module ran, instead of the Get-Date cmdlet.

The fourth command shows that there are two Get-Date commands in the session, a Function from the TestModule module and a cmdlet from the Microsoft.PowerShell.Utility snap-in.

The fifth command runs the hidden cmdlet by qualifying the command name with the snap-in name.

For more information about command precedence in Windows PowerShell, see about_command_precedence.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=141553
    Get-Module
    New-Module
    Remove-Module
    Export-ModuleMember
    about_modules